feat: add bounded TTY command execution

[yattdev]

Overview

codex-acp maps Codex App Server commands and terminal output into ACP, but integrations that need terminal semantics cannot currently request a bounded one-shot TTY execution while preserving the active session context.

This contribution adds a narrow, versioned extension that dispatches one command through the already-running App Server with tty: true. It is implemented entirely inside codex-acp and has no dependency on an external orchestration service.

Why this is useful

Some command-line programs change behavior when no pseudo-terminal is present. Reusing the active Codex session gives the adapter an authoritative working directory and sandbox policy while avoiding a second executor or a caller-controlled security context.

The proposed bridge complements the existing command and terminal-event mapping:

• one bounded argv request instead of an interactive terminal lifecycle;
• active-session cwd and sandbox policy instead of caller-controlled values;
• streamed App Server output correlated by a generated process ID;
• deterministic cancellation, timeout, overflow, and stale-session handling;
• no change to ordinary non-TTY command execution.

Changes

• Advertise guarded-TTY capability version 1.
• Register the provisional extension methods:
  • _kandev/guarded_tty/capability
  • _kandev/guarded_tty/exec
• Accept only { sessionId, argv } with strict argument-count, per-argument, total-byte, and NUL bounds.
• Derive cwd and sandboxPolicy from the trusted active session.
• Generate the process ID in the adapter and dispatch App Server command/exec with TTY and streaming enabled.
• Validate base64 output, preserve split UTF-8 sequences, and enforce a 64 KiB aggregate cap.
• Return a stable receipt containing capability, session, process, cwd, TTY, output, exit, and timestamp evidence.
• Terminate the process best-effort and idempotently on cancellation, stale session, timeout, overflow, invalid output, or App Server rejection.

The current method prefix is retained from the originating implementation for compatibility. It does not introduce a runtime dependency; I am happy to rename it to an upstream-preferred experimental namespace during review.

Security boundaries

The request cannot control cwd, sandbox policy, permission profile, process ID, TTY flags, environment, stdin, resize, attach, or an interactive lifecycle. The change does not create a host executor, mutate Codex configuration, alter mounts or credentials, or enable unrelated execution surfaces.

Testing

• npx vitest run src/__tests__/CodexACPAgent/guarded-tty-exec.test.ts src/__tests__/CodexACPAgent/terminal-output-events.test.ts --no-file-parallelism — 28 passed
• npm run typecheck — passed
• npm run build — passed
• npm test — 495 passed, 26 skipped
• git diff --check origin/main...HEAD — passed

Credentialed npm run test:e2e was not rerun because the required API keys are unavailable. Prior authenticated App Server probes verified TTY stdin/stdout, stty, trusted-worktree pwd, and exit code 0. Bun-only release bundling was not run because Bun is unavailable; the production build passed.

Compatibility

No existing ACP or codex-acp behavior changes. Clients that do not negotiate and call this versioned extension continue using the existing command path.

Screenshots

N/A — no UI-visible changes.

[yattdev]

@nikita-ashihmin This first-time fork PR is ready to run CI at exact head 1a5d8b9cf1f70a8677ead500088a8e022cdc65bb, but GitHub stopped both workflows at the fork-approval gate with zero jobs: CI run 33305349645 and Conventional PRs run 33305349647. Could you approve those workflow runs? This is only a workflow-approval request; I will wait for terminal green checks before requesting code review.

[yattdev]

@benbrandt could you please give a review on this PR.
I revised the title and description to present the change in codex-acp terms: a bounded one-shot TTY execution improvement that reuses the active session context, with explicit security and compatibility boundaries. The current extension prefix is called out as provisional and can be renamed to the namespace you prefer.

Could you approve those workflows and review the contribution shape? No existing ACP behavior changes for clients that do not negotiate/call the extension.

[yattdev]

@AlexandrSuhinin @Rizzen The merge conflict with upstream main has been resolved and pushed at exact head 5bc15a7826249029b613b91c7d1acb607e6363c6. Please review the updated PR when convenient.

[yattdev]

@benbrandt @AlexandrSuhinin @Rizzen The current head is ed40f14abd4ea5a90196611dc1c0cedaf4402ba2, including guarded-TTY cancellation and ACP-disconnect termination cleanup. Verification on this head: focused tests 30/30, typecheck, build, and full unit suite 784 passed / 32 skipped. Credentialed e2e was not run because no API key is available. Please review when convenient.

[yattdev]

@Ololoshechkin Could you review the current head fd6780abab10a596c2c8cf6bc0c9aa26a5bd5729 when convenient? It is clean against current main bf37821; focused tests (30/30), typecheck, build, and the full unit suite (791 passed, 32 skipped) pass. Credentialed e2e was not run because no API key is available, and local bundle:all could not run because Bun is absent. GitHub currently shows no check rollup. No functional review comments are outstanding.

[yattdev]

@nikita-ashihmin The current fork-workflow runs for exact head fd6780abab10a596c2c8cf6bc0c9aa26a5bd5729 are awaiting maintainer approval with no jobs: CI run 36218442116 and Conventional PRs run 36218442127. Could you approve these runs? This is a CI-only approval request; the existing maintainer review request remains separate.