Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

docs(windows): document the agent launch dialect channel

review370c22474caa
diff --git a/CLAUDE.md b/CLAUDE.md
index 640506558..ed914c821 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -39,6 +39,14 @@ means — and what you may assume when writing a feature — is three tiers, not
platform where they cannot work they must either use a platform-appropriate mechanism or be
clearly gated off — a feature that throws `EACCES`/`EPERM` on Windows because nobody checked is a
bug, not an accepted limitation.
+- **Agent launch lines are POSIX source; a Windows-native pane never gets one typed if it can
+ be avoided.** A prompt-bearing builtin agent node carries `data.launchIntent` (bound to its exact
+ `initialCommand`, never serialized); on a local win32 session-host pane whose host recorded a
+ `pwsh`/`windows-powershell`/`cmd` dialect, the launch writer executes it via `pty:execute-launch`
+ (`core/launch-intent-execute.ts` → `prepareAgentLaunch` → `sessionHostExecuteLaunch`). Every
+ other pane answers `unsupported-shell` and keeps the typed line byte-identical. Only a
+ pre-delivery refusal may fall back to typing; `delivery-failed` never does. Details:
+ docs/windows-session-host.md, "Agent launches in a Windows-native shell".
- **New code is platform-neutral by default.** Do not hardcode POSIX assumptions. Publish files
through `renameAtomic`/`writeFileAtomic` (`src/core/fs-atomic.ts`), not a bare `fs.rename` — the
guard test (`fs-atomic.guard.test.ts`) enforces this. Resolve path separators / absolute-path
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d258adf6a..a2df6fc47 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -71,6 +71,11 @@ its terminals and refuses the extension; never restart it automatically or fall
Message dispatch publishes pending canvas edits before main resolves scope, without overwriting
an unresolved file conflict. See `docs/windows-session-host.md`.
+**Windows agent launches:** a new agent launch site that types a prompt-bearing line must go
+through the launch writer (`createLaunchWriter`) so a Windows-native pane can execute the node's
+`data.launchIntent` instead (`pty:execute-launch`). If you add a launch input the core planner does
+not model, exclude it in `heldLaunchIntentFor`, or the Windows pane launches without it.
+
Claude usage identity is scoped to the same config directory as its credentials. Read organization
metadata even when credentials already include an email, and degrade to the email-only row when
metadata cannot be read. Managed usage must never fall back to an unscoped system Keychain token:
diff --git a/docs/windows-session-host.md b/docs/windows-session-host.md
index 5abf4f1de..22b9fb1e7 100644
--- a/docs/windows-session-host.md
+++ b/docs/windows-session-host.md
@@ -114,6 +114,30 @@ exports, and inbound canvas traffic. A shared file or peer can therefore neither
select a local executable. See
[`features/terminals/windows-shell-profiles.md`](features/terminals/windows-shell-profiles.md).
+### Agent launches in a Windows-native shell (`pty:execute-launch`)
+
+The renderer's agent launch line is POSIX source (`'it'\''s'`, `"$(cat '<file>')"`). PowerShell
+breaks on the apostrophe, Windows PowerShell 5.1 drops embedded double quotes before the CLI sees
+them, and cmd.exe splits a single-quoted prompt into separate arguments. So a prompt-bearing
+builtin agent node also carries a semantic `data.launchIntent` (`shared/agents/launch-intent.ts`),
+bound to its exact typed line and never serialized. When the launch writer is about to type that
+line into a **local session-host pane on a win32 core**, it calls `pty:execute-launch` instead
+(`renderer/terminal/launch-intent.ts` → `core/launch-intent-execute.ts`): the core resolves the
+agent executable against the session's spawn PATH (native image, then `.ps1`; a `.cmd`-only
+install is refused), reads a `--prompt-file` itself (whitespace flattened to one argument, exactly
+what `"$(cat …)"` yields in PowerShell), encodes argv for the dialect the HOST recorded for that
+generation (`launchDialect` on the attach result; set at spawn only for `pwsh`/`powershell`/`cmd`),
+and delivers through the host's exactly-once launch ledger.
+
+Rules that keep this safe:
+- Every other pane (tmux, SSH, Zellij, plain shell, Git Bash/WSL, any POSIX core) answers
+ `unsupported-shell` before anything is read, and the typed line is used, byte-identical.
+- A refusal made before the host is asked falls back to the typed line; `delivery-failed` (or a
+ lost reply) does NOT — the launch stays held for an explicit Run now, never typed twice.
+- Excluded from the intent (legacy line only): resumes, custom agents, launch-command overrides,
+ per-node models, SSH nodes. A resume line holds only flag words and a validated id.
+- `pty:execute-launch` is host-only for relay peers (`shared/host-control.ts`).
+
### The IPty-shim (why the integration is this small)
`PtyManager`'s entire co-attach / flow-control / subscriber / park / reap machinery operates on