rpc: open_session cannot accept a caller-chosen durable session id, so every embedder maintains a second identity

[code-yeongyu]

Summary

open_session gives a caller no way to choose the durable session id. The host always mints its own uuidv7, so every embedder that already has a stable record id for the conversation (a desktop thread, a server-side job row, an external tracker item) is forced to keep a SECOND identity and a translation layer between the two. Every feature that crosses the boundary — goal files, subagent/team matching, resume cursors, adoption provenance — then has to carry the mapping, and when the mapping is lost the user-visible result is a dead-end turn rather than a recoverable error.

Expected (the ideal state)

open_session accepts an optional caller-chosen durable id, negotiated by capability, validated, and refused cleanly when it would collide.

Acceptance criteria:

1. open_session accepts an optional durableSessionId. When present and the session is being CREATED, the session's durable id IS that value: the open_session reply carries state.sessionId === durableSessionId and the JSONL header records it.
2. The field is named durableSessionId, never sessionId. session-command-router.ts:250 reads "sessionId" in command generically and feeds it to drain gating (:252), active-request accounting (:256-260) and runWithSessionAttribution (:257); a caller-chosen durable id arriving under that key would be treated as a routing handle. The name also matches what list_sessions already publishes.
3. Advertised as host capability durable_session_id in get_protocol_info, so a client can detect support instead of guessing.
4. Validation: a malformed id is refused with a stable invalid_session_id code, using the existing assertValidSessionId rule.
5. Collision safety: if a LIVE session already holds that durable id, the open is refused with a stable session_id_in_use code. Two live sessions sharing one durable id would collide every per-session artifact keyed by it.
6. Resume is unaffected: when sessionPath names an existing session file, the header's id stays authoritative and durableSessionId is ignored rather than rewriting history.
7. Path reservations remain the single-writer authority; this change adds an id guard, it does not replace session_path_in_use.
8. The D1 normative table and the D6 identity notes in rpc-mode.ts document the field, the capability and both new error codes.

Actual

• open_session params are sessionPath?, cwd?, provider?, modelId?, thinkingLevel?, permissionPreset?, retain_on_disconnect?, kind?, context?, auto_title? — no id field (packages/coding-agent/src/modes/rpc/rpc-types.ts:267-313).
• The id is always host-minted: createSessionId() { return uuidv7() } (packages/coding-agent/src/core/session-manager.ts:313-315), assigned at :1031.

Evidence

• Id injection already exists in-process but is unreachable over RPC: NewSessionOptions.id (core/session-manager.ts:99-102), honored in _resetToNewSession (:1025-1031) behind assertValidSessionId (:317-322); SessionManager.create(cwd, sessionDir?, options?) already takes it (:2052).
• The RPC seam that drops it: modes/rpc/session-registry.ts:341 — sessionPath ? SessionManager.open(sessionPath, undefined, cwd) : SessionManager.create(cwd), neither call passing NewSessionOptions.
• SessionManager.open(path, sessionDir?, cwdOverride?) (:2063) has no options parameter at all. This is the branch that matters: a client that names its own session file always lands here, and a missing file falls through to _setSessionFile -> _resetToNewSession() (:1007) with no options, minting a fresh id.
• When the file already exists the header id is adopted (:991), which is why resume must stay untouched.

Root cause

The RPC surface was designed with the path as the only caller-supplied identity. Id injection was implemented one layer below (the session manager and the session repo) and never lifted to the wire.

Scope

In: the open_session field, capability advertisement, validation, the live-id collision guard, threading the id through RpcSessionLaunchProfile into both manager constructors, docs, tests.
Out: changing how ids are generated when the caller supplies none; any change to path reservation semantics; any client-side adoption (tracked separately in the desktop repo).

Related

• shared RPC host: in-process unlimited sessions, session kind/context, retain-on-disconnect, capability compat + generation handoff, senpi host CLI #1782 — shared RPC host capability-compat umbrella; durable_session_id is a sibling of session_kind / session_context / retain_on_disconnect.
• rpc in-process host: a pathless session never reserves its created file, so opening that path builds a second runtime over the same transcript #1850 — a pathless session never reserved its created file, building a second runtime over one transcript. Same family: identity/reservation bookkeeping at open.

[code-yeongyu]

Work started on feat/1951-durable-session-id.

One contract decision worth recording up front, because it is the part that is easy to get wrong:

The field is durableSessionId, not sessionId. session-command-router.ts:250 reads

const sessionId = "sessionId" in command ? command.sessionId : undefined;

generically for EVERY command, and that value drives drain gating (:252), activeRequests accounting (:256-260) and runWithSessionAttribution (:257). If open_session carried a caller-chosen durable id under the sessionId key, the router would treat it as a routing handle. list_sessions already publishes durableSessionId, so the chosen name also matches the existing vocabulary. Capability name: durable_session_id.

The plumbing detail that decides whether this works at all: the seam is session-registry.ts:341

const manager = sessionPath ? SessionManager.open(sessionPath, undefined, storedProfile.cwd) : SessionManager.create(storedProfile.cwd);

SessionManager.create already takes NewSessionOptions (session-manager.ts:2052), but SessionManager.open (:2063) does not — and open is the branch a client that names its own session file always hits. With a not-yet-existing file it falls through to _resetToNewSession() (:1007) with no options and mints a fresh uuidv7. That call is where the supplied id has to arrive.

[code-yeongyu]

Delivered in #1956 — RED → GREEN evidence

Three commits on feat/1951-durable-session-id:

• 3673214b03 feat(core): let SessionManager.open apply NewSessionOptions
• 85864910fc feat(rpc): accept a caller-chosen durable session id on open_session
• 72e0613cfd docs(rpc): record the durable-session-id contract

RED, captured before any production change — new test/rpc-open-session-durable-id.test.ts, 7 cases, 5 failed / 2 passed. The decisive failure named the defect exactly:

AssertionError: expected '01a0c719-98de-72e1-81b6-4d707754072d'
              to be '019ffec8-e1db-75fb-9da3-000000000001'

The supplied id was ignored and the host minted its own. The other four: no invalid_session_id refusal existed, no session_id_in_use refusal existed, the wire boundary let a malformed id through to runtime construction, and get_protocol_info did not advertise durable_session_id.

The 2 that passed are deliberate controls, not coverage gaps: re-opening an existing file must keep its header id (it did, because the field was ignored entirely — and must still do so afterwards), and an open with no supplied id must still mint a uuidv7.

GREEN after: 7/7. Neighbouring rpc-open-session-resume.test.ts unchanged at 15/15, so resume/create parity and close semantics did not regress. biome check clean across 71 files.

The plumbing detail worth recording

This looked like a one-line change because SessionManager.create already accepted NewSessionOptions. It was not. A client that names its own session file always lands in SessionManager.open, which had no options parameter — and with a not-yet-existing path it falls through to _resetToNewSession() (session-manager.ts:1007) with no options and mints a fresh id. So the supplied id would have been silently dropped on exactly the path every real caller uses. open now forwards options through the private constructor into _setSessionFile, which applies them at both _resetToNewSession call sites (missing file, empty file). An existing non-empty file reaches neither — that is the structural reason a supplied id cannot overwrite a header id, rather than a check that could be forgotten.

On the collision guard

Both the duplicate-id scan and the entry's own durableSessionId are taken synchronously before the first await, mirroring how the path reservation is taken, so two concurrent opens naming one id cannot both pass. Re-opening the same path is exempt: that is an attach, and the id is the file's own.

[code-yeongyu]

Follow-up: driving the REAL multi-session host over stdio (rather than the registry unit harness) exposed that the collision guard from #1956 lived only on RpcSessionRegistry, while the host instantiates WorkerSessionRegistry — and that a caller-chosen id was not written to disk until the first assistant message. Both fixed in #2010 / PR #2013, with a real-process scenario script (durable-session-id-qa.mjs, 9/9) kept in the repo so the two registries cannot drift again.