Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 100 additions & 0 deletions docs/specs/2026-11-10-interface-audit.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
# Interface regression audit — 2026-11-10

Baseline: `62b1ac1d3597bbbf23c60065b3e6ac2e6f38d9b6` (v2026.11.1-alpha).

## Scope and acceptance

Exercise shipping interfaces and follow confirmed failures through reproduction,
regression tests, fixes and independent review. Preserve capture policies,
provider isolation, confirmation requirements and wire compatibility. Tests must
use disposable state and fixture assistants; never signal real workloads or run
real assistant turns. Existing functionality should behave consistently across
its supported interfaces. This is a bounded audit, not proof of absence of bugs.

## Confirmed defects

| Interface | Before | Required result | Regression |
| --- | --- | --- | --- |
| macOS service | Sequential launchctl pipe reads hang status and installer postflight when stdout fills. | Drain both streams concurrently with bounded capture, deadline and owned-child cleanup. Start must use the repaired query. | `TestLaunchdStatus*`, `TestLaunchdStartUsesBoundedStatusQuery` |
| TUI | Global navigation hides an armed stop confirmation; later Enter can stop the old selection. | Cancel stop before navigation; subsequent Enter cannot confirm it. Mouse navigation cancels too. | `interface_audit_test.go` |
| TUI | Lowercase k is swallowed on ordinary tables. | j/k navigate down/up while process-specific actions retain their meaning. | `TestAuditTableVimUpNavigation` |
| Desktop | Back/Forward do not restore page/dashboard selection; a deleted-dashboard fallback can trap Back on the missing entry. | Browser history and selected page stay synchronized; 404 fallback replaces the invalid entry. | `App.audit.test.tsx`, App stories |
| Desktop Chat | Header/pane close bypasses mode reset; loading or pending elevation can leave Full Auto enabled. | All close paths reset mode before accepting close; unresolved state blocks close and failed reset restores the pane. | App audit tests and browser close stories |
| Desktop Search | Missing clipboard API silently drops the resume command. | Show a usable fallback command when clipboard is absent or rejects. | `Search.audit.test.tsx`, Search stories |
| Desktop dashboard | Transient loading errors discard saved-dashboard selection. | Only a confirmed 404 returns Home; retryable errors retain selection. | dashboard refresh tests and App stories |

The large-output service test failed before its fix within two seconds. TUI and
desktop regressions likewise failed against baseline behavior. The repaired
read-only native service query returned `running` outside the macOS sandbox,
using disposable application state. No production service was restarted for
this audit.

## Coverage and limits

| Area | Evidence | Remaining live coverage |
| --- | --- | --- |
| CLI | Full Go suite; parsing, scopes, JSON, confirmations and action fixtures | Real destructive reclamation intentionally excluded |
| TUI | Full Go suite, app-update key/mouse regressions and fake action seams | Interactive native terminal rendering and terminal jumps |
| Desktop/browser UI | Unit tests, shipping-component Storybook plays, typecheck and production build | Installed native window, menus, tray, dialogs and OS notifications |
| MCP and web API | Tool/schema/envelope, capture, origin/identity and confirmation fixtures | Third-party live MCP hosts |
| Chat | Selection, pinned resumes, streaming, approvals, queue/history and reconnect fixture runners | Real Claude/Codex/Copilot authentication and model turns |
| CPU/memory/reclaim | Canonical process placement, current identity, exclusion and stale-data fixtures; derive/reclaim suites | Linux/Windows native process APIs and real reclamation |
| Fleet | Machine-scoped paths/readers, freshness and protocol fixtures | Live multi-machine transport |
| Hooks, intake, store and collectors | Full Go suite and targeted provider/self-exclusion/accounting checks | Real vendor configuration and histories intentionally excluded |
| Packaging/platform | Native build, native and Windows vet | New signed release and Windows runtime not exercised here |

Project-summary actions remain Claude-specific by existing design; provider
selection does not imply every provider has Claude's native tool catalog.
Documentation now describes capture/vendor history for the selected assistant
and the actual sixteen-metric header limit.

## Verification and review

Passed on macOS with disposable HOME/data through `scripts/isolated.sh`:

- `go test ./... -count=1` and `go test -race ./...`.
- Final affected TUI/service tests and TUI race tests after wheel cancellation;
launchd race tests include timeout cleanup and Start dispatch.
- `go vet ./...`, `GOOS=windows go vet ./...`, and a Linux CLI build.
- Final `go test ./internal/web ./internal/desktop -count=1` after bundle rebuild.
- `go mod tidy -diff`, generated config comparison and docgen `--check`.

UI unit suite: 219 tests across 32 files passed; all seven App audit tests passed
after the final history fix. Typecheck and both production bundles passed.
Focused App/Search browser plays passed (32), then the new deleted-dashboard
history story passed. Gitleaks found no secrets in the staged changes. Source
diff whitespace checks passed; generated bundles retain dependency license text.

The full Chromium catalogue passed: 1,266 tests across 172 files, covering both
themes and both review widths. The final history regression was added during
that run; affected history plays passed again across all four cells (16 tests
in four files) against the frozen final source, instead of relying on which
cell loaded the change during the broader run.

An early race attempt and Windows vet overlapped a bundle rebuild and failed on
temporarily absent embed files. Verification was rerun after the build; the race
suite and Windows vet passed. One UI unit attempt encountered a shared Vitest
cache import error; its serialized rerun passed. These were not product fixes.

### Standards

Independent fresh-context review found one P1: local mode could be stale while
loading or enabling Full Auto. The fix refuses closure until initialization and
mode changes settle, then requires an acknowledged Confirm reset. Rereview found
zero remaining documented-standard violations or actionable smell findings.

### Spec

Independent fresh-context review found the same pending-elevation race and a
mouse-wheel cancellation gap on the flow board. Both received failing regression
tests and fixes. The reviewer's separate real-Chat pending-elevation reproduction
changed from failing to passing. Final rereview found zero outstanding findings.

### Astra consultation

A separate Astra pass reproduced a Back-history trap after a saved dashboard
was deleted elsewhere: fallback navigation pushed Home again, causing the next
Back to hit the deleted dashboard repeatedly. The regression requires fallback
navigation to replace that invalid entry while intentional navigation pushes.
Its independent reproduction passed after the fix; Astra reported no additional
blockers. The installed signed release was not replaced with this audit build.
8 changes: 4 additions & 4 deletions docs/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -925,15 +925,15 @@ agent automatically. Clients resume from a cursor over bounded ordered events;
an expired cursor or service restart sends a replacement snapshot. The app and
TUI reload the local broker key after the Driga service restart.

Your explicitly submitted question is scrubbed and sent to Claude. Context and
Your explicitly submitted question is scrubbed and sent to the selected assistant. Context and
MCP evidence pass the capture policy before reaching the agent. Driga retains no
chat message bodies under `capture_text = "titles"`; `snippets` retains scrubbed
200-character snippets. Live conversation text and drafts are bounded in memory,
and the app stores no chat text on disk. Tool names and safe action decision metadata are retained as
metadata. Process command lines and argv require `capture_text = "snippets"` in
Chat tool responses; other policies remove both argument-bearing fields. Downgrading to titles erases retained bodies when the broker starts.
Claude's own session history is vendor-managed and enables `--resume`; driga's
capture policy does not control that vendor history. Chat tools may make network connections when approved; Claude uses its existing
The assistant's own session history is vendor-managed and enables resume; driga's
capture policy does not control that vendor history. Chat tools may make network connections when approved; the assistant uses its existing
vendor connection.

## Desktop app
Expand All @@ -951,7 +951,7 @@ port. It opens on Home, a dashboard that fills the window, with Chat docked
beside it and a row of metrics above: by default Need you, To review, Possibly
stuck, Leftover processes and Reclaimable. Click a metric to ask Chat about it.
Change the row by asking Chat ("add cost today to the header"), or remove a
metric in Edit. The header holds only single numbers, eight at most.
metric in Edit. The header holds only single numbers, sixteen at most.

Home shows the inbox with pending permission prompts (Allow or Deny), leftover
process trees, sessions that look stuck, every session, and memory. Panels take
Expand Down
13 changes: 9 additions & 4 deletions internal/service/launchd_darwin.go
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
package service

import (
"context"
"errors"
"fmt"
"log/slog"
Expand All @@ -15,14 +16,18 @@ import (

type launchdController struct {
Controller
binPath string
plistPath string
register func(string) error
binPath string
plistPath string
register func(string) error
statusCommand func(context.Context, ...string) *exec.Cmd
}

func newLaunchdController(controller Controller, binPath string) *launchdController {
return &launchdController{Controller: controller, binPath: binPath,
plistPath: filepath.Join(config.ExpandHome("~"), "Library", "LaunchAgents", Label("darwin")+".plist"),
statusCommand: func(ctx context.Context, args ...string) *exec.Cmd {
return exec.CommandContext(ctx, "/bin/launchctl", args...)
},
register: func(app string) error {
// Apple requires Launch Services to know the associated bundle,
// wherever Driga.app was installed.
Expand All @@ -42,7 +47,7 @@ func (s *launchdController) recordedDataDir() (string, error) {

// Start makes repeating service install harmless when launchd already runs it.
func (s *launchdController) Start() error {
status, err := s.Controller.Status()
status, err := s.Status()
if err == nil && status == ks.StatusRunning {
return nil
}
Expand Down
89 changes: 89 additions & 0 deletions internal/service/launchd_status_darwin.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
package service

import (
"bytes"
"context"
"errors"
"fmt"
"os"
"os/exec"
"regexp"
"strconv"
"strings"
"time"

ks "github.com/kardianos/service"
"github.com/labstack/driga/internal/platform"
)

const launchdStatusTimeout = 5 * time.Second

var launchdStatusPID = regexp.MustCompile(`(?m)^\s*"PID"\s*=\s*([0-9]+);`)

// launchdCapture drains both pipes without retaining unbounded job metadata.
type launchdCapture struct {
bytes.Buffer
limit int
truncated bool
}

func (b *launchdCapture) Write(p []byte) (int, error) {
n := len(p)
remaining := b.limit - b.Len()
if len(p) > remaining {
p = p[:remaining]
b.truncated = true
}
_, _ = b.Buffer.Write(p)
return n, nil
}

// Status avoids the upstream sequential stderr/stdout reader. A full stdout
// pipe otherwise prevents launchctl exiting and stderr ever reaching EOF.
func (s *launchdController) Status() (ks.Status, error) {
// In-memory controllers used by the lifecycle model supply their own status.
if s.statusCommand == nil {
return s.Controller.Status()
}
ctx, cancel := context.WithTimeout(context.Background(), launchdStatusTimeout)
defer cancel()
cmd := s.statusCommand(ctx, "list", Label("darwin"))
stdout := launchdCapture{limit: 1 << 20}
stderr := launchdCapture{limit: 64 << 10}
cmd.Stdout, cmd.Stderr = &stdout, &stderr
err := platform.RunChild(cmd)
if ctx.Err() != nil {
return ks.StatusUnknown, fmt.Errorf("query Driga launch agent: %w", ctx.Err())
}
if stdout.truncated || stderr.truncated {
return ks.StatusUnknown, errors.New("launchctl status response exceeds limit")
}
if err != nil {
var exit *exec.ExitError
if errors.As(err, &exit) && (exit.ExitCode() == 3 || exit.ExitCode() == 113) {
if _, statErr := os.Stat(s.plistPath); statErr == nil {
return ks.StatusStopped, nil
} else if errors.Is(statErr, os.ErrNotExist) {
return ks.StatusUnknown, ks.ErrNotInstalled
} else {
return ks.StatusUnknown, statErr
}
}
// Job output can contain environment values; never include it in errors.
return ks.StatusUnknown, fmt.Errorf("query Driga launch agent: %w", err)
}
response := strings.TrimSpace(stdout.String())
if !strings.HasPrefix(response, "{") || !strings.HasSuffix(response, "};") {
return ks.StatusUnknown, errors.New("unexpected launchctl status response")
}
if match := launchdStatusPID.FindStringSubmatch(response); len(match) == 2 {
pid, err := strconv.Atoi(match[1])
if err != nil {
return ks.StatusUnknown, errors.New("invalid launchctl service PID")
}
if pid > 0 {
return ks.StatusRunning, nil
}
}
return ks.StatusStopped, nil
}
Loading
Loading