Skip to content

docs(terminal): correct the tmux env-freshness rationale to one server per drive + sweep dead test - #362

Merged
anconina merged 2 commits into
comisai:mainfrom
roeikosh:fix/terminal-tmux-stale-rationale
Jul 28, 2026
Merged

docs(terminal): correct the tmux env-freshness rationale to one server per drive + sweep dead test#362
anconina merged 2 commits into
comisai:mainfrom
roeikosh:fix/terminal-tmux-stale-rationale

Conversation

@roeikosh

Copy link
Copy Markdown
Contributor

Description

Follow-up to #358 (review of the merged branch).

#358 removed new-session -e — env values on the tmux command line are
world-readable via /proc/<pid>/cmdline. Freshness now comes from starting a
session-private tmux server with that drive's scrubbed env, so the env travels
in the server's own environ. Seven sites still gave the deleted -e
mechanism as the reason a drive sees a rotated secret:

  • docs/agent-tools/terminal-driver.mdx — the unsafeDisableSandbox
    paragraph, i.e. the text an operator reads to decide whether running without
    the jail is acceptable. It described a mechanism that no longer exists and
    that leaked env on argv.
  • terminal-worker-backend-attach.ts — the load-bearing security comment
    directly above loadTmux.spawn, plus the module header and the
    unsandboxed field doc.
  • terminal-spawn-plan.ts — all three sandbox-off sites.
  • setup-terminal-tools.ts — the create-frame comment for the operator opt-out.

Also corrects two field docs #358 invalidated: tmuxSocket (absent now means
the worker derives tmux-<sessionId>.sock, not "the legacy single-socket
default" — a wrong pointer when debugging a failed re-attach) and socketPath
(documented one stable tmux.sock; production always passes the per-session
path).

Deletes the skipped SUPERSEDED: -e test: its body still passes an env field
that no longer exists on buildTmuxSpawnArgv's parameter type, an
excess-property error hidden only because packages/skills/tsconfig.json
excludes test files. It can never be un-skipped, so it is rot.

No behavior change.

Related Issue

N/A: documentation, comments, and one dead skipped test — no runtime behavior or
security expectation changes.

Type of Change

  • Bug fix
  • New feature
  • Breaking change
  • Documentation
  • Refactor

Checklist

  • Targeted checks for the changed area pass
  • Full repository validation passes (pnpm validate) — see Additional Notes
  • New or changed behavior has a test that demonstrated the RED state before the production change
    (N/A — no behavior change)
  • Documentation updated (if applicable)
  • No secrets or credentials committed
  • Security implications considered
  • The change is focused on one concern and links the related issue, or states the allowed N/A
    reason

RED Test Proof

EXEMPT: comments, docs, and removal of one already-skipped test. No
packages//src/* behavior change.

Evidence and Residual Risk

  • Contribution path: not applicable (documentation of an existing security
    boundary; no code path changes)
  • Evidence level: code trace — each corrected comment was checked against
    the post-fix(terminal): keep drive secrets off the tmux command line via one server per session #358 call path (runOneShot(a.env) carries the env; buildTmuxSpawnArgv
    no longer accepts one)
  • Tested profile: Linux (Ubuntu 6.8), Node 22, no isolation change; docs:check,
    tsc -b packages/skills packages/daemon, terminal-driver unit tier (917 passed)
  • Residual risk: prose accuracy is not machine-checked — nothing prevents the
    same rationale drifting again after a future change to the tmux backend. This PR
    does not add such a check.

Screenshots

N/A

Additional Notes

pnpm validate on my dev box: docs:check, build:clean, cycles (0 circular
across 16 dist packages), cycles:refs, and lint:security (0 errors) all pass.
test:coverage ends 60 failed / 41114 passed across 15 files, all in the
real-bwrap / live-PTY / jsdom tier that is broken on this host
(bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted;
localStorage.removeItem is not a function in packages/web). This PR touches
no web code and changes no runtime behavior, so those cannot originate here —
but the per-package coverage floors never evaluated (the run aborted first), so
CI is the first place that gate actually runs.

…r per drive

The per-session-socket change removed `new-session -e`, but six sites still
gave per-pane `-e` re-injection as the reason a drive sees a rotated secret —
including the load-bearing security comment directly above `loadTmux.spawn`
and the `unsafeDisableSandbox` paragraph an operator reads to decide whether
running without the jail is acceptable. Freshness now comes from each drive
starting its own tmux server with that drive's scrubbed env; the env travels
in the server's `environ`, never on argv where /proc/<pid>/cmdline exposes it.

Also corrects two field docs the change invalidated (`tmuxSocket` absent now
means the worker derives `tmux-<sessionId>.sock`, not a legacy single socket;
`socketPath` is per-session, not one stable `tmux.sock`) and deletes the
skipped `-e` test, whose body still passes an `env` field that no longer
exists on the builder's parameter type — invisible only because the package
tsconfig excludes test files, so it can never be un-skipped.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@roeikosh
roeikosh requested a review from anconina as a code owner July 27, 2026 14:18
@roeikosh roeikosh changed the title fix(terminal): correct the tmux env-freshness rationale to one server per drive docs(terminal): correct the tmux env-freshness rationale to one server per drive + sweep dead test Jul 27, 2026
@anconina
anconina enabled auto-merge (squash) July 28, 2026 07:13
@anconina
anconina merged commit 4866675 into comisai:main Jul 28, 2026
13 checks passed
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.

2 participants