Skip to content

feat(runtime): add reviewed PowerShell/Bash and Debug terminal - #97

Merged
Qiyuanqiii merged 1 commit into
mainfrom
codex/model-shell-runtime
Aug 18, 2026
Merged

Qiyuanqiii merged 1 commit into
mainfrom
codex/model-shell-runtime

Conversation

@Qiyuanqiii

Copy link
Copy Markdown
Member

Summary

  • add a real, review-gated one-shot Shell transport for Windows PowerShell and Git for Windows Bash; the model can only create an exact proposal, while the operator reviews the resolved executable path/SHA-256, canonical argv, working directory, environment digest, network boundary, and timeout before single-use execution
  • add a user-owned persistent Debug terminal: ConPTY + creation-time Job Object on Windows and Bash + PTY + owned process group on macOS/Linux; Agent input remains default-off and requires an explicit, revocable 15-second-to-15-minute Desktop lease
  • expose debug_terminal.v1 only to the root Supervisor in Code/Local/Deliver/Debug with the current runtime adapter and durable permission; every write is rechecked by Shell Policy and commands requiring separate approval are denied
  • harden the new paths with strict tagged-union payloads, process-transport interpreter rejection, fixed/trusted Shell resolution, executable hashing, pre-grant output watermarking, exact mode/root binding, untrusted-result metadata, ANSI/C1/Unicode-control stripping, bounded output, and process-local bearer handling
  • add schema v113 to admit debug_terminal to the durable Supervisor call ledger with a transactional, data-preserving v112 migration; update README, usage, architecture, OpenAPI text, macOS test guidance, and ADR 0114

PR #86 review/corrections

This branch is rebased on main after #86 merged as 13de12d. It preserves that PR's Windows/WebView2/DPI evidence and corrects integration points affected by the larger runtime surface:

  • the Wails/Desktop exported-method allowlist and TypeScript bridge validation now cover the three bounded grant/query/revoke methods without exposing the bearer
  • terminal reconciliation now closes a process if the same Workspace ID is re-registered to a different root, preventing stale authority across the mutable workspace flow
  • new Desktop and renderer tests cover the visible confirmation, stale async completion, revoke path, exact response projection, and root-drift close behavior

Security and compatibility boundaries

  • no host Shell or Debug-terminal tool is exposed on the Cyber Surface
  • Approval Shell proposals are not automatic execution and cannot use arbitrary interpreter argv; transport=process rejects PowerShell/Bash, so only the explicit canonical Shell branch can select them
  • Debug output before the operator grant is unavailable to the model; later output is bounded, sanitized, redacted, and explicitly marked untrusted
  • user keystrokes, raw PTY bytes, Workspace root path, process identity/environment, and lease bearer are not persisted or exposed to the renderer/model
  • application restart terminates process-local sessions and invalidates leases; schema v108 terminal_sessions remains a contract only and is not used to restore authority
  • ordinary POSIX background jobs share the owned process group, but deliberate daemonization/new-session creation remains a documented residual host risk

Verification

  • go test -timeout 20m -count=1 ./...
  • go vet ./...
  • go test -race ./internal/application -run "TestDebugTerminal" -count=1 -timeout 10m
  • go test -race ./internal/terminal -count=1 -timeout 10m
  • go test -tags "desktop,wv2runtime.error" -count=1 ./cmd/cyberagent-desktop ./internal/desktop ./internal/webui -timeout 10m
  • Linux and macOS amd64 cross-compilation of ./internal/terminal
  • npm test -- --run — 59 files / 243 tests passed
  • npm run typecheck, npm run check:api, npm run build
  • npm audit --audit-level=high — 0 vulnerabilities
  • go mod verify and go mod tidy -diff
  • GOTOOLCHAIN=go1.26.6 go run golang.org/x/vuln/cmd/govulncheck@v1.6.0 ./... — 0 reachable vulnerabilities (one required-module vulnerability is not called)
  • real Windows smoke: Windows PowerShell 5.1.26100.9168 with -NoLogo -NoProfile -NonInteractive -Command; Git for Windows 2.54.0.windows.1 / Bash 5.3.9 with --noprofile --norc -c
  • .\scripts\build-desktop.ps1 -SkipFrontend -VerifyReproducible — reproducible, SHA-256 6269d2a28c717e95afbc55490bef36139b5eb82cc83d41c0d302b77ba82b56ff

Manual evidence still required

The PR is intentionally Draft. macOS currently has compile coverage but still needs a real Bash/PTY run and UI evidence on macOS. The Windows reproducible build reports windows_release_ready=false only because signing/install/manual release evidence is outside this change; automated Windows checks passed.

@Qiyuanqiii
Qiyuanqiii marked this pull request as ready for review August 18, 2026 14:47
@Qiyuanqiii
Qiyuanqiii merged commit aff3d17 into main Aug 18, 2026
8 checks passed
@Qiyuanqiii
Qiyuanqiii deleted the codex/model-shell-runtime branch August 18, 2026 14:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant