bug(acp): session/new fails with "lost exact Router authority" when cwd is a symlink (e.g. macOS /tmp)

[lotgood]

Summary

session/new over ACP fails whenever the client passes a symlinked cwd. The session host spawns and becomes ready, but the ACP attach path never resolves a Router attachment and the request fails with:

-32603 Internal error: ACP session <id> lost exact Router authority.   (data.code = "unavailable")

The same request with the canonical path succeeds. On macOS this hits any client whose working directory is /tmp, /var, or a symlinked repo/worktree path.

A second problem makes it hard to diagnose: the original error is discarded and replaced by a cleanup failure from the discard path (see "Error masking" below).

Environment

• gjc/0.14.0 (compiled binary), macOS 27.0.0 arm64
• ACP client: local stdio probe (gjc acp, JSON-RPC over stdio), also reproducible through Paseo
• /tmp -> /private/tmp (standard macOS symlink)

Reproduction

initialize {protocolVersion: 1, clientCapabilities: {fs: {readTextFile: true, writeTextFile: true}}}
  -> ok

session/new {"cwd": "/tmp", "mcpServers": []}
  -> {"code": -32603,
      "message": "Internal error: ACP session 4e58a8d8-957a-4081-9218-477a64646201 lost exact Router authority.",
      "data": {"code": "unavailable",
               "details": "ACP session 4e58a8d8-957a-4081-9218-477a64646201 lost exact Router authority."}}

session/new {"cwd": "/private/tmp", "mcpServers": []}
  -> ok  (sessionId 7ea0b6d6-…, configOptions/modes/models all present)

Same binary, same broker, back to back; the only difference is realpath(cwd) !== cwd.

The spawned host is healthy in the failing case — it logs its endpoint normally:

02:12:0x info  pid=… notifications: serving session 4e58a8d8-… at ws://127.0.0.1:56282

and the state root under /tmp/.gjc/state/sdk (== /private/tmp/.gjc/state/sdk) contains a complete endpoint + lifecycle.json + lifecycle.ready.json triple. So this is a locator/identity mismatch on the attach side, not a startup failure. The failed attempt also leaves the host process behind.

Suspected cause

The host canonicalizes and validates with realpath (packages/coding-agent/src/commands/sdk.ts, session-host startup):

if ((await fs.realpath(request.cwd)) !== (await fs.realpath(cwd)))
    throw new Error(`Lifecycle worktree mismatch: expected ${request.cwd}, got ${cwd}.`);

so the registration ends up bound to the canonical path, while the ACP attach path keeps the client-supplied path as the exact locator (packages/coding-agent/src/modes/acp/acp-agent.ts, #attachEndpoint):

const attachment = lifecycleResult
    ? await this.#router.adoptLifecycleResult(lifecycleResult, { sessionId: id, cwd })
    : this.#router.attachment(id);
…
let currentAttachment = this.#router.attachment(id);
for (let attempt = 0; !currentAttachment && attempt < 40; attempt++) {
    await Bun.sleep(50);
    await this.#router.reconcile();
    currentAttachment = this.#router.attachment(id);
}
if (!currentAttachment)
    throw new AcpSdkAdapterError("unavailable", `ACP session ${id} lost exact Router authority.`);

The 40 × 50 ms reconcile loop then just burns 2 s before failing, because no amount of reconciling will make a /tmp-keyed lookup match a /private/tmp-keyed registration.

(Line references are from the v0.13.1 tree — the strings and shape are unchanged in the 0.14.0 binary.)

Expected

cwd should be canonicalized once at the ACP boundary (and/or Router locators compared by realpath) so a symlinked working directory creates a session exactly like its canonical form.

Error masking (secondary, same repro)

When #attach throws, newSession calls #discardNewSession → #teardownSession(id, "discarded", true) → broker session.close. If that close is not definitive, aggregateAcpFailure throws and replaces the original error, so the client sees a cleanup message that says nothing about what actually failed:

-32603 Internal error: ACP session cleanup is uncertain: Session did not close after SIGTERM
       and its durable process identity could not be verified for SIGKILL.

The very first failure of this bug surfaced only in that form, which sent me looking at broker termination rather than at attach. The discard path should preserve the causal error (e.g. attach it as cause / data.details) instead of overwriting it with the cleanup outcome.

Impact

Any ACP host that hands GJC a non-canonical path can never open a session — /tmp-based scratch sessions, symlinked worktrees, and homes on symlinked volumes are all affected. Each failed attempt also leaks a live session-host process.

[lotgood]

Follow-up: docs/external-control-readiness.md already acknowledges this constraint for the conformance harness —

The conformance workspace passed via --cwd must be a real path, not one reached through a symlink (on macOS /tmp links to /private/tmp): the ACP client enforces its session cwd root against the resolved path, so a symlinked workspace fails the client-authority cases. The wrapper rejects such a --cwd up front.

So the behavior may be intended. The report still stands on three points:

1. The error is opaque. A client that passes /tmp gets lost exact Router authority (or, on the first failure, the masked ACP session cleanup is uncertain: Session did not close after SIGTERM …). Neither says "cwd must be a canonical path". If symlinked roots are unsupported, session/new should reject them up front with that reason — exactly what the conformance wrapper does for its own --cwd.
2. It costs 2 s and leaks a process. The spawned session host stays alive after the failed attach, so repeated attempts accumulate idle gjc sdk session-host-internal processes.
3. Canonicalizing at the ACP boundary is cheap. The session host already compares fs.realpath(request.cwd) against fs.realpath(cwd); resolving the client-supplied cwd once before the Router lookup would make the symlinked and canonical forms behave identically instead of unsupported.

Downgrade to a docs+diagnostics issue if the canonical-path requirement is deliberate — but a silent 2 s failure with a lifecycle-flavored message is not a usable contract for third-party ACP clients.

[Yeachan-Heo]

Status for #4637: fix is being delivered through #4645 (maintainer successor of #4639, identical patch — stable patch-id c08e92a0a5109c128daea918bd560c730aa4220d, 0-byte tree diff vs dev+patch, authorship preserved for @thisisjun786).

Verification summary on successor head 7fe3f92d3a (base 6696988b6d):

• Router-authority suite 41 pass including the symlinked-cwd regression (fails on base: clients: 0)
• Adversarial authority controls 10/10 — symlinked spelling attaches; foreign state root, foreign-repo symlink target, broken symlink, lexical prefix collision, post-registration symlink swap, and stale mtime all fail closed
• Live ACP e2e over stdio: symlinked cwd session/new/session/close ok (attach published once), canonical cwd unchanged, no leaked host/broker processes; base reproduces lost exact Router authority exactly as reported

On the two asks from your follow-up comment:

1. Symlinked cwds are now supported, not rejected — the ACP boundary keeps the client-supplied path and the Router compares physical identity, so /tmp and /private/tmp behave identically. No up-front rejection is needed.
2. Process leak on failed attach — the refreshed runs show clean teardown (host unregistered, no leaked processes). The underlying masking problem remains: when cleanup itself fails, aggregateAcpFailure replaces the causal error (acp-agent.ts #discardNewSession → #teardownSession). That masking is diagnostic-only, orthogonal to the scope gate, and is not fixed by fix(sdk): resolve symlinked workspace cwd scope in SessionRouter endpoint reads (successor of #4639) #4645; it stays a legitimate separate follow-up.

#4645 will close this issue on merge.

—
[repo owner's gaebal-gajae (clawdbot) 🦞]

[Yeachan-Heo]

Resolved and integrated into dev by successor PR #4645 (fix(sdk): resolve symlinked workspace cwd scope in SessionRouter endpoint reads), merged at 2026-08-18T03:57:54Z. PR #4639 was the superseded predecessor and did not merge. Closing this issue against the merged successor evidence.

—
[repo owner's gaebal-gajae (clawdbot) 🦞]