@junghanacs/entwurf 0.13.1 → 0.14.0

package/mcp/entwurf-bridge/dist/pi-extensions/lib/mux-placement.js

@@ -0,0 +1,289 @@
+/**
+ * mux-placement — where a new sibling runtime is OPENED, and nothing else.
+ *
+ * The operating contract (2026-08-04, GLG): a caller that asks entwurf to open a new
+ * runtime is ALWAYS inside tmux. Outside tmux there is no fallback session, no
+ * `new-session`, no guess — the request is refused. The window is appended to exactly the
+ * server/session the caller's own inherited `TMUX`/`TMUX_PANE` names, because that is the
+ * session the operator is looking at. Inheriting the environment IS the addressing: this
+ * module never takes a socket path or a session name from a caller.
+ *
+ * Three actions, deliberately not four:
+ *
+ *   inspectPlacement()   the caller's own $session/@window/%pane, or a named refusal
+ *   appendWindow()       one default-shell window at the end of that same session
+ *   closeWindow()        that window, by stable id, in the context it was opened in
+ *
+ * What this module is NOT: a delivery transport, an address, a liveness fact, a launcher.
+ * It opens a place. `entwurf_v2` still owns delivery (`V2-DELIVERY-EXCLUDES-MUX`), and
+ * nothing here mints a garden id.
+ *
+ * Beside those three actions, `runTmux` and `requireSameContext` are exported as a NARROW
+ * INTERNAL SEAM for the T1-a launch composition to build on — not a fourth action and not a
+ * public operator surface. Say the risk plainly: `runTmux` takes argv this module did not
+ * author, so boundary 2 below does not protect it. The grammar is enforced by the `build*Args`
+ * builders, and anything reaching for `runTmux` owes its own argv the same validation. Its two
+ * production consumers are the launch and fresh-call compositions (`docs/mux-launch-rail.md`
+ * §11); the shipped delivery path calls neither.
+ *
+ * ── Four boundaries, each of which was a real way to touch the wrong thing ──
+ *
+ * 1. CONTEXT. Both `TMUX` and `TMUX_PANE` must be present and non-empty before anything
+ *    runs. `TMUX_PANE` alone is not enough: tmux invoked without `TMUX` in the environment
+ *    resolves to the DEFAULT server, so a caller carrying a stale pane id from a dead
+ *    server would have mutated the operator's live one. `TMUX` is checked for presence
+ *    only — never parsed. The socket and session inside that string are tmux's to report,
+ *    not ours to extract.
+ *
+ * 2. GRAMMAR. Every selector handed to `-t` is a native id and is validated against its
+ *    grammar BEFORE tmux is invoked. T0-a measured that tmux's own parser reinterprets
+ *    values (a trailing `;` can split a command; `#{…}`/`#(…)` expand), so "we used argv,
+ *    not a shell" is not by itself a safety argument. `%12`, `$3`, `@7` and decimal
+ *    pids/indices are the entire accepted vocabulary; anything else is refused unrun.
+ *
+ * 3. FAILURE. `display-message` returning rc=0 is not proof that a pane exists — it answers
+ *    rc=0 for a nonexistent target (filling only the SERVER fields) and rc=0 for an EMPTY
+ *    target while silently describing the current pane. That is why the echo-back exists.
+ *    But the converse does not follow: a NONZERO exit (no server, EACCES, a usage error) is
+ *    an operational failure and is raised, never laundered into "the anchor did not
+ *    resolve". Only an rc=0 row is ever parsed.
+ *
+ * 4. BINDING. A `Placement` is a fact about one server and one session, and the environment
+ *    passed to a later call could name a different — or restarted — server where the same
+ *    `$3`/`@7` mean something else entirely. Every mutation re-reads the caller's placement
+ *    and refuses unless the server pid and session id still match the ones the handle was
+ *    born in.
+ *
+ * The machine-readable rows carry ONLY native ids and decimal numbers, joined by `|`. The
+ * free-form fields tmux could also report (`socket_path`, `session_name`) are deliberately
+ * absent: a session legitimately named `a|b` would otherwise split the row. A display name
+ * is a later, separate concern, and nothing here needs one.
+ *
+ * ── Two more facts measured in T0-a (private tmux 3.6a) ──
+ *
+ * `renumber-windows on` (GLG's shipped setting) renumbers surviving windows when one in the
+ * middle disappears, so the human index is a keybinding affordance and never a handle.
+ * `remain-on-exit off` (the default) destroys a window when its pane process ends, so a
+ * window can vanish through a path this module never called; see `CloseOutcome`.
+ */
+import { spawnSync } from "node:child_process";
+// ── Native id grammar (boundary 2) ─────────────────────────────────────────
+const PANE_ID = /^%[0-9]+$/;
+const SESSION_ID = /^\$[0-9]+$/;
+const WINDOW_ID = /^@[0-9]+$/;
+const DECIMAL = /^[0-9]+$/;
+/** True only for tmux's own native pane id. */
+export function isPaneId(value) {
+    return PANE_ID.test(value);
+}
+/** True only for tmux's own native session id. */
+export function isSessionId(value) {
+    return SESSION_ID.test(value);
+}
+/** True only for tmux's own native window id. */
+export function isWindowId(value) {
+    return WINDOW_ID.test(value);
+}
+/** True only for a bare decimal (pids, window indices). */
+export function isDecimal(value) {
+    return DECIMAL.test(value);
+}
+/**
+ * Refuse a selector before it reaches tmux. The throw is deliberate and unconditional: a
+ * selector that is not a native id is either a bug or an injection attempt, and neither is
+ * something to route into tmux's parser to find out.
+ */
+export function assertSelector(kind, value) {
+    const okShape = kind === "pane" ? isPaneId(value) : kind === "session" ? isSessionId(value) : isWindowId(value);
+    if (!okShape) {
+        throw new Error(`mux-placement: refusing a non-native ${kind} selector ${JSON.stringify(value)}`);
+    }
+}
+// ── Pure argv / parsing (the half a deterministic gate can pin) ─────────────
+/** Field order of `INSPECT_FORMAT`. Parsing and formatting share this list. */
+export const PLACEMENT_FIELDS = ["pid", "session_id", "window_id", "window_index", "pane_id", "pane_pid"];
+const SEP = "|";
+/** tmux format string for a placement query — tmux's own facts, never string surgery on `$TMUX`. */
+export const INSPECT_FORMAT = PLACEMENT_FIELDS.map((f) => `#{${f}}`).join(SEP);
+/** Field order of `APPEND_FORMAT` — what `new-window -P -F` prints for the window it created. */
+export const WINDOW_FIELDS = ["window_id", "window_index", "pane_id", "pane_pid"];
+export const APPEND_FORMAT = WINDOW_FIELDS.map((f) => `#{${f}}`).join(SEP);
+/**
+ * Read the caller's anchor. BOTH `TMUX` and `TMUX_PANE` must be present and non-empty:
+ * `TMUX_PANE` names which pane, `TMUX` is what makes a bare `tmux` resolve to the caller's
+ * server instead of the default one. `TMUX` is checked for presence only — parsing the
+ * socket/session out of it is the guess this rail forbids.
+ */
+export function readAnchor(env) {
+    const server = env.TMUX;
+    const anchor = env.TMUX_PANE;
+    if (typeof server !== "string" || server.length === 0)
+        return { ok: false, reason: "no-tmux-context" };
+    if (typeof anchor !== "string" || anchor.length === 0)
+        return { ok: false, reason: "no-tmux-context" };
+    if (!isPaneId(anchor))
+        return { ok: false, reason: "anchor-malformed" };
+    return { ok: true, anchor };
+}
+export function buildInspectArgs(anchor) {
+    assertSelector("pane", anchor);
+    return ["display-message", "-p", "-t", anchor, INSPECT_FORMAT];
+}
+/**
+ * Append at the END of the caller's own session. `{end}` is the append semantics we want
+ * literally; the lowest-free-index behaviour of a bare `new-window` is a different verb and
+ * is not this contract. Targeting by `session_id` (`$0`) rather than name keeps a renamed or
+ * duplicate-named session from redirecting the append.
+ *
+ * `-d` keeps the caller's focus. No `-n`, no `-c`, no shell-command: default shell only.
+ */
+export function buildAppendArgs(sessionId) {
+    assertSelector("session", sessionId);
+    return ["new-window", "-d", "-a", "-t", `${sessionId}:{end}`, "-P", "-F", APPEND_FORMAT];
+}
+export function buildCloseArgs(windowId) {
+    assertSelector("window", windowId);
+    return ["kill-window", "-t", windowId];
+}
+/** Every window on the server, for the positive absence proof an `already-gone` needs. */
+export function buildListWindowIdsArgs() {
+    return ["list-windows", "-a", "-F", "#{window_id}"];
+}
+/**
+ * Turn an rc=0 placement row into facts — with the echo-back check that tmux's exit status
+ * cannot provide, and a grammar check on every field. A nonexistent target still fills the
+ * server fields and leaves the rest empty, so "the row was non-empty" proves nothing; an
+ * empty pane id means no pane resolved at all, which is unresolved rather than an answer
+ * about some other pane.
+ */
+export function parsePlacement(anchor, stdout) {
+    const line = stdout.split("\n", 1)[0]?.trim() ?? "";
+    if (line.length === 0)
+        return { ok: false, reason: "anchor-unresolved" };
+    const parts = line.split(SEP);
+    if (parts.length !== PLACEMENT_FIELDS.length)
+        return { ok: false, reason: "anchor-unresolved" };
+    const [serverPid, sessionId, windowId, windowIndex, paneId, panePid] = parts;
+    if (paneId.length === 0)
+        return { ok: false, reason: "anchor-unresolved" };
+    if (paneId !== anchor)
+        return { ok: false, reason: "anchor-mismatch" };
+    const wellFormed = isDecimal(serverPid) &&
+        isSessionId(sessionId) &&
+        isWindowId(windowId) &&
+        isDecimal(windowIndex) &&
+        isPaneId(paneId) &&
+        isDecimal(panePid);
+    if (!wellFormed)
+        return { ok: false, reason: "anchor-unresolved" };
+    return { ok: true, placement: { serverPid, sessionId, windowId, windowIndex, paneId, panePid } };
+}
+export function parseWindowFields(stdout) {
+    const line = stdout.split("\n", 1)[0]?.trim() ?? "";
+    const parts = line.split(SEP);
+    if (line.length === 0 || parts.length !== WINDOW_FIELDS.length) {
+        throw new Error(`mux-placement: new-window did not report a window handle (got ${JSON.stringify(line)})`);
+    }
+    const [windowId, windowIndex, paneId, panePid] = parts;
+    if (!isWindowId(windowId) || !isDecimal(windowIndex) || !isPaneId(paneId) || !isDecimal(panePid)) {
+        throw new Error(`mux-placement: new-window reported a non-native handle (got ${JSON.stringify(line)})`);
+    }
+    return { windowId, windowIndex, paneId, panePid };
+}
+/**
+ * Classify a FAILED `kill-window` against a fresh window inventory. Absent → `already-gone`
+ * (positive proof). Present → `null`, and the caller must fail loud: the window is still
+ * there and we did not close it.
+ */
+export function classifyCloseFailure(windowId, listStdout) {
+    const ids = listStdout
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+    return ids.includes(windowId) ? null : "already-gone";
+}
+/**
+ * An rc=0 run is the ONLY kind whose stdout may be parsed. A nonzero status (no server,
+ * EACCES, a usage error) or a null status (killed by a signal) is an operational failure of
+ * the tmux call itself — laundering it into "the anchor did not resolve" would report a
+ * missing pane when the truth is that tmux never answered.
+ */
+export function assertTmuxOk(label, run) {
+    if (run.status === 0)
+        return;
+    const how = run.status === null ? "terminated by signal" : `exit ${run.status}`;
+    throw new Error(`mux-placement: tmux ${label} failed (${how})${run.stderr.trim() ? `: ${run.stderr.trim()}` : ""}`);
+}
+/**
+ * Run tmux with the caller's environment INHERITED. No `-S`, no `-L`: the server is whichever
+ * one `TMUX` already names, which is the only server this module is allowed to touch — and
+ * `readAnchor` has already refused an environment where `TMUX` is absent, which is what would
+ * otherwise silently resolve to the default server.
+ */
+export function runTmux(args, env) {
+    const res = spawnSync("tmux", args, { env, encoding: "utf8" });
+    if (res.error)
+        throw res.error;
+    return { status: res.status, stdout: res.stdout ?? "", stderr: res.stderr ?? "" };
+}
+/** The caller's own placement, or a named refusal. Never guesses, never creates a session. */
+export function inspectPlacement(env = process.env) {
+    const anchor = readAnchor(env);
+    if (!anchor.ok)
+        return anchor;
+    const run = runTmux(buildInspectArgs(anchor.anchor), env);
+    assertTmuxOk("display-message", run);
+    return parsePlacement(anchor.anchor, run.stdout);
+}
+/**
+ * Same server AND same session. Either half alone is insufficient: a restarted tmux server
+ * hands out `$0` again, and one server holds many sessions — so matching only the session id
+ * would accept a different server, and matching only the server pid would accept a different
+ * session on the right one.
+ */
+export function isSameContext(origin, now) {
+    return origin.serverPid === now.serverPid && origin.sessionId === now.sessionId;
+}
+/**
+ * Re-read the caller's placement and refuse unless it is still the server and session the
+ * handle/placement was born in. Called before every mutation: `$3` on a restarted server is
+ * a different session, and an env naming another server would otherwise redirect the whole
+ * operation somewhere the caller never looked.
+ */
+export function requireSameContext(label, origin, env) {
+    const now = inspectPlacement(env);
+    if (!now.ok) {
+        throw new Error(`mux-placement: ${label} refused — the caller's placement is not resolvable (${now.reason})`);
+    }
+    if (!isSameContext(origin, now.placement)) {
+        throw new Error(`mux-placement: ${label} refused — context changed (expected server ${origin.serverPid} session ${origin.sessionId}, ` +
+            `now server ${now.placement.serverPid} session ${now.placement.sessionId})`);
+    }
+}
+/** One detached default-shell window at the end of the caller's own session. */
+export function appendWindow(placement, env = process.env) {
+    requireSameContext("appendWindow", placement, env);
+    const run = runTmux(buildAppendArgs(placement.sessionId), env);
+    assertTmuxOk("new-window", run);
+    return { serverPid: placement.serverPid, sessionId: placement.sessionId, ...parseWindowFields(run.stdout) };
+}
+/**
+ * Close one window by stable id, in the context it was opened in. Reports whether it was
+ * closed or had already gone.
+ */
+export function closeWindow(handle, env = process.env) {
+    requireSameContext("closeWindow", handle, env);
+    const run = runTmux(buildCloseArgs(handle.windowId), env);
+    if (run.status === 0)
+        return "closed";
+    // A signal kill is not a "tmux said no" — it is the call failing, and it carries no
+    // information about the window at all.
+    if (run.status === null)
+        assertTmuxOk("kill-window", run);
+    const list = runTmux(buildListWindowIdsArgs(), env);
+    assertTmuxOk("list-windows", list);
+    const verdict = classifyCloseFailure(handle.windowId, list.stdout);
+    if (verdict)
+        return verdict;
+    throw new Error(`mux-placement: kill-window ${handle.windowId} failed (exit ${run.status}) and the window is still listed: ${run.stderr.trim()}`);
+}

package/mcp/entwurf-bridge/dist/pi-extensions/lib/mux-resume-call.js

@@ -0,0 +1,170 @@
+/**
+ * mux-resume-call — open ONE window in the caller's own tmux session at a cwd this module did
+ * not choose, and hand it argv this module did not author.
+ *
+ * ── Why this is a module and not a parameter on fresh-call ──
+ *
+ * `mux-fresh-call` carries a TASK to a runtime it names; the sibling starts wherever the caller
+ * happens to be. A resume carries neither: the argv comes from the record (`entwurf-v2-visible-
+ * resume` builds it) and the cwd comes from the record too — it is the directory the citizen's
+ * own transcript header remembers. Those are different inputs with a different risk, so they get
+ * a different module rather than a fourth parameter on a composition whose contract is
+ * "identity is an OUTPUT".
+ *
+ *   visible-resume composition → resume-call → placement leaf (unchanged, carrier-free)
+ *   resume-call               -X-> garden identity, records, locks, delivery
+ *
+ * This module never learns which citizen it is reopening. It sees a cwd and an argv tail.
+ *
+ * ── The cwd is the whole reason this module owns its own tmux argv ──
+ *
+ * `mux-placement`'s `buildAppendArgs` deliberately emits no `-c` ("default shell only"), and it
+ * stays that way — a resume must not widen the leaf's grammar for the three other callers. So
+ * the `-c` shape lives here, with the three refusals MEASURED on tmux 3.6a (2026-08-06, private
+ * server):
+ *
+ *   1. a NONEXISTENT `-c` is silent. tmux exits 0, opens the window, and the child falls back to
+ *      `$HOME`. A resume whose recorded cwd has been deleted would therefore open a visible
+ *      window in the wrong project and look successful. Nothing downstream can catch that: the
+ *      launch receipt would be perfectly well-formed.
+ *   2. `-c` is FORMAT-EXPANDED. `#{pane_id}` inside the value silently rewrote the path
+ *      (`<dir>/#{pane_id}` → `<dir>/%0`), and a `#(…)` value was observed running its command.
+ *      A path is data; tmux reads it as a format. So `#` is refused outright.
+ *   3. whitespace is SAFE — argv is an array and nothing re-splits. A dir named `with space`
+ *      arrived intact. So there is no quoting grammar here, and none is owed. `|` is fine too:
+ *      the cwd never enters the `-F` row (see `APPEND_FORMAT` below).
+ *
+ * That is the entire defence: one existence check and one character. No escaping layer, no
+ * sanitiser, no symlink policy — a symlinked project dir is a normal thing to work in.
+ *
+ * ── What the receipt does NOT say ──
+ *
+ * The handle carries the shared `APPEND_FORMAT` fields only — native ids and decimals. The cwd
+ * is reported as what tmux was ASKED for, exactly as `runtimePath` is: `-P -F` prints its row
+ * BEFORE the child has chdir'd (measured — `#{pane_current_path}` in that row still reports the
+ * client's cwd), so a start-path field there would be a free-form path that is also racy. Proving
+ * where the pane actually landed is a separate query against the stable pane id, and it belongs
+ * to acceptance, not to the product's launch receipt.
+ */
+import { statSync } from "node:fs";
+import path from "node:path";
+import { assertLaunchTarget, LaunchPreconditionError, resolveRuntimeOnPath, } from "./mux-launch.js";
+import { APPEND_FORMAT, assertSelector, assertTmuxOk, inspectPlacement, parseWindowFields, requireSameContext, runTmux, } from "./mux-placement.js";
+/** The fixed runtime a resume reopens. Only pi stands a control socket up, so only pi has a
+ * same-id resume at all — the backend boundary is enforced upstream by
+ * `resolveResumeLaunchIdentity`, and this constant is the mux half of the same fact. */
+export const RESUME_CALL_RUNTIME = "pi";
+/**
+ * Classify a candidate start directory. Split into three reasons rather than one because the
+ * operator's next move differs: an absolute-path bug is a caller defect, a missing directory is
+ * a moved/deleted project, and a `#` is a path tmux would rewrite under us.
+ */
+export function classifyResumeCwd(cwd) {
+    if (!path.isAbsolute(cwd))
+        return "cwd-not-absolute";
+    // tmux expands formats inside the `-c` VALUE. `#{…}` rewrote the path silently and `#(…)`
+    // was observed executing; neither is something to escape our way out of.
+    if (cwd.includes("#"))
+        return "cwd-format-token";
+    let st;
+    try {
+        st = statSync(cwd);
+    }
+    catch {
+        // tmux would NOT report this — it opens the window and lands the child in $HOME.
+        return "cwd-missing";
+    }
+    return st.isDirectory() ? null : "cwd-not-directory";
+}
+/**
+ * Launch argv: the leaf's detached-append shape plus `-c`, the runtime, then the caller's flags.
+ * `--` is what keeps tmux from reading the runtime or its flags as tmux options.
+ */
+export function buildResumeCallArgs(placement, cwd, runtimePath, runtimeArgs) {
+    assertSelector("session", placement.sessionId);
+    assertLaunchTarget(runtimePath);
+    const bad = classifyResumeCwd(cwd);
+    if (bad)
+        throw new Error(`mux-resume-call: refusing to build argv with an unusable cwd (${bad}): ${cwd}`);
+    return [
+        "new-window",
+        "-d",
+        "-a",
+        "-t",
+        `${placement.sessionId}:{end}`,
+        "-c",
+        cwd,
+        "-P",
+        "-F",
+        APPEND_FORMAT,
+        "--",
+        runtimePath,
+        ...runtimeArgs,
+    ];
+}
+/**
+ * Open the window. Order is the safety argument, same as `freshCall`: classify the cwd, resolve
+ * and prove the runtime, re-read the caller's placement and refuse a changed context — and only
+ * then mutate. Nothing above can leave a window behind.
+ *
+ * `runtimeArgs` is passed through untouched. This module does not know what `--session` means.
+ */
+export function resumeCall(params, env = process.env) {
+    const badCwd = classifyResumeCwd(params.cwd);
+    if (badCwd)
+        return { ok: false, reason: badCwd };
+    let runtimePath;
+    try {
+        runtimePath = resolveRuntimeOnPath(RESUME_CALL_RUNTIME, env);
+    }
+    catch (err) {
+        if (err instanceof LaunchPreconditionError)
+            return { ok: false, reason: err.reason };
+        throw err;
+    }
+    const inspected = inspectPlacement(env);
+    if (!inspected.ok)
+        return { ok: false, reason: inspected.reason };
+    const placement = inspected.placement;
+    requireSameContext("resumeCall", placement, env);
+    const run = runTmux(buildResumeCallArgs(placement, params.cwd, runtimePath, params.runtimeArgs), env);
+    assertTmuxOk("new-window", run);
+    let fields;
+    try {
+        fields = parseWindowFields(run.stdout);
+    }
+    catch (err) {
+        // The window exists and its id is precisely what could not be read. Diffing the inventory
+        // to find "the new one" is the guess this rail forbids everywhere else, so name the orphan.
+        throw new Error(`mux-resume-call: launched ${runtimePath} but could not read the window handle tmux printed — a window may ` +
+            `be open in session ${placement.sessionId} that this call cannot identify or close: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return {
+        ok: true,
+        receipt: {
+            serverPid: placement.serverPid,
+            sessionId: placement.sessionId,
+            ...fields,
+            runtimePath,
+            cwd: params.cwd,
+        },
+    };
+}
+/** Why each refusal happened, in the caller's terms. A reason a caller cannot act on is a reason
+ * they will guess about. */
+export const RESUME_CALL_REJECT_HINT = {
+    "no-tmux-context": "this agent is not running inside tmux, so there is no session to reopen the citizen in",
+    "anchor-malformed": "TMUX_PANE is not a native pane id",
+    "anchor-unresolved": "tmux resolved no pane for this agent's anchor",
+    "anchor-mismatch": "tmux answered about a different pane than the one asked about",
+    "cwd-not-absolute": "the recorded cwd is not an absolute path",
+    "cwd-format-token": "the recorded cwd contains '#', which tmux expands as a format inside -c — it would silently rewrite the path or run a command",
+    "cwd-missing": "the recorded cwd no longer exists; tmux would not report this, it would open the window in $HOME and look successful",
+    "cwd-not-directory": "the recorded cwd exists but is not a directory",
+    "runtime-unresolved": "pi is not installed on PATH",
+    "runtime-not-absolute": "the resolved runtime path is not absolute",
+    "runtime-path-whitespace": "the resolved runtime path contains whitespace, which tmux would re-split",
+    "runtime-missing": "nothing exists at the resolved runtime path",
+    "runtime-not-regular-file": "the resolved runtime path is not a regular file",
+    "runtime-not-executable": "the resolved runtime path is not executable",
+};

package/mcp/entwurf-bridge/dist/pi-extensions/lib/resume-launch-identity.js

@@ -0,0 +1,136 @@
+/**
+ * resume-launch-identity — the RECORD-AUTHORITATIVE half of resuming a pi citizen,
+ * kept after the visible-first cut removed everything that used to call it.
+ *
+ * It was the preamble of the `spawn-bg` watcher's `spawnChild` (entwurf-v2-spawn-production.ts,
+ * deleted with that transport): garden id → the meta-record → the transcript that record
+ * claims → the provider/model/cwd that transcript's own header carries. None of that is
+ * about being hidden or visible. It is the answer to "which being is this, and which
+ * conversation is theirs", and it is the same answer a VISIBLE resume will need.
+ *
+ * So this leaf is preserved deliberately, with no consumer in the shipped tree today.
+ * `check-resume-launch-identity` holds its contract so the record-integrity rules below —
+ * the transcript header id must equal `record.nativeSessionId`, an addressable read
+ * (#52) rather than a plain targeted one, a recorded ACP provider must resolve its
+ * bridge — cannot rot while they wait.
+ *
+ * It takes a bare garden id, not a plan: the plan type it used to destructure belonged to
+ * the removed transport, and the identity question never needed the rest of it.
+ */
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { getEntwurfExplicitExtensions, readSessionIdentity } from "./entwurf-core.js";
+import { readAddressableMetaIdentity } from "./meta-session.js";
+/**
+ * The ONE expected refusal on this leaf: the target is a citizen of a backend that has no
+ * same-id resume at all.
+ *
+ * Everything else this function throws is a defect in the record, the transcript or the
+ * environment — a stale path, a foreign session file, an unrecorded model, an unresolvable
+ * bridge — and those keep their bare cause-rich `Error`, because a caller cannot act on them
+ * except by looking. A Claude Code or agy garden id is different in kind: nothing is broken,
+ * the operator simply asked a capability boundary to do something it does not cover, and the
+ * honest answer is a named refusal rather than an error report about a store that is fine.
+ *
+ * It carries a `reason` so the caller matches on a FIELD. Parsing the message string would make
+ * the wording load-bearing, and re-reading the record to ask "was it pi?" would read an address
+ * twice and could answer differently the second time.
+ */
+export class ResumeBackendUnsupportedError extends Error {
+    reason = "target-not-pi";
+    backend;
+    constructor(gardenId, backend) {
+        super(`resume-launch-identity: ${gardenId} is a ${backend} citizen — same-id resume is a host-adapter relaunch ` +
+            `capability, and its domain currently contains backend pi only (only pi stands a control socket up). ` +
+            `This is a capability boundary, not the control-socket rail and not citizen rank.`);
+        this.name = "ResumeBackendUnsupportedError";
+        this.backend = backend;
+    }
+}
+/**
+ * Resolve launch identity for a resume. The TARGET is now resolved through the
+ * meta-record (#50 C2): `gardenId → record.transcriptPath`. It used to be a global
+ * header scan for a JSONL whose header id equalled the garden id — which only worked
+ * while entwurf forced pi's session id to BE the garden id. With the record minting the
+ * address, that scan cannot find anything (a citizen's header carries pi's own uuid), so
+ * keeping it would not have been a "smaller change", it would have been a broken one.
+ *
+ * The record is also the AUTHORIZATION now (#50 C3). The old gates — `requireEntwurf`
+ * (an `entwurf` tag in the session NAME, planted by a name mirror that no longer
+ * exists) and the sessionId-bound resume-marker env — are deleted. Record-backed pi
+ * citizens are all siblings (LOCKED PROTOCOL 6), so "this garden id names a pi citizen
+ * with a recorded transcript" is the whole test, PLUS one integrity check: the resumed
+ * file's header id must equal `record.nativeSessionId` (pi owns the transcript, the
+ * record remembers whose it is — a mismatch means the transcriptPath is stale or
+ * foreign, and resuming it would put a turn into a different being's session).
+ *
+ * That check is per-record, and per-record is not enough: the v2 lock domain is keyed on
+ * GARDEN ID, so two records sharing one `nativeSessionId` would each pass their own
+ * integrity check and resume the SAME transcript concurrently under two different locks.
+ * Hence {@link readAddressableMetaIdentity} rather than the plain targeted read (#52) —
+ * a resume is exactly the moment a record stops being data and becomes an address.
+ *
+ * Everything else is unchanged authority: readSessionIdentity (first model_change) for
+ * provider/model/cwd, getEntwurfExplicitExtensions for bridge re-injection (#29 fail-fast).
+ * Throws on anything that makes a resume impossible — a stale/foreign transcript, a
+ * deleted session file, an unrecorded model, an unresolvable ACP bridge. Every throw
+ * names its own cause; none of them degrades into a silent no-op.
+ */
+export function resolveResumeLaunchIdentity(gardenId) {
+    const record = readAddressableMetaIdentity(gardenId);
+    if (record.backend !== "pi") {
+        throw new ResumeBackendUnsupportedError(gardenId, record.backend);
+    }
+    const sessionFile = record.transcriptPath;
+    if (!sessionFile) {
+        throw new Error(`resume-launch-identity: ${gardenId} has no recorded transcriptPath — ` +
+            `the citizen never wrote a session file (no turn yet), so there is nothing to resume.`);
+    }
+    // A recorded path is only a resume target while it names ONE file from everywhere. The record
+    // schema types transcriptPath as a nullable string and does not require an absolute path, and
+    // `existsSync` below would happily resolve a relative one against THIS process's cwd — while
+    // the launch resolves `--session <relative>` inside the window's own `-c <record cwd>`. Those
+    // are two different files whenever the two directories differ, and the resume would open the
+    // wrong transcript with a receipt that looks correct. This is a bad record, not an expected
+    // refusal, so it throws with its own cause like every other integrity failure here.
+    if (!path.isAbsolute(sessionFile)) {
+        throw new Error(`resume-launch-identity: ${gardenId} recorded a RELATIVE transcriptPath ${JSON.stringify(sessionFile)} — ` +
+            `a resume resolves --session inside the window's own working directory, so a relative path would name a ` +
+            `different file than the one checked here; refusing rather than resuming an unknown transcript.`);
+    }
+    // A recorded path is only a resume target while the file is actually on disk.
+    // Without this check a missing transcript falls through readSessionIdentity's
+    // ENOENT swallow and surfaces as "no recorded model" — the wrong cause (F7):
+    // the transcript was deleted, or the record carries a phantom path minted
+    // before birth guarded on file existence.
+    if (!existsSync(sessionFile)) {
+        throw new Error(`resume-launch-identity: ${gardenId} recorded transcriptPath "${sessionFile}" ` +
+            `does not exist on disk — the transcript was deleted, or the record carries a phantom ` +
+            `path from a pre-guard birth; nothing to resume.`);
+    }
+    const identity = readSessionIdentity(sessionFile);
+    const resumeModel = identity?.modelId ?? null;
+    if (!identity || !resumeModel) {
+        throw new Error(`resume-launch-identity: ${gardenId} has no recorded model — cannot resume.`);
+    }
+    if (identity.sessionId !== record.nativeSessionId) {
+        throw new Error(`resume-launch-identity: ${gardenId} transcript header id "${identity.sessionId ?? "(none)"}" ` +
+            `does not match the record's nativeSessionId "${record.nativeSessionId}" — the recorded transcriptPath ` +
+            `is stale or points at a foreign session file; refusing to resume another being's transcript.`);
+    }
+    const explicitExtensions = getEntwurfExplicitExtensions(resumeModel, false, identity.provider);
+    if (explicitExtensions.unresolvedAcpIntent) {
+        throw new Error(`resume-launch-identity: ${gardenId} recorded provider=entwurf but the bridge ` +
+            `extension could not be resolved — refusing to resume with an unknown provider (#29).`);
+    }
+    if (!identity.cwd) {
+        throw new Error(`resume-launch-identity: ${gardenId} header has no cwd (the cold-resume authority, #9).`);
+    }
+    return {
+        sessionFile,
+        cwd: identity.cwd,
+        explicitExtensionArgs: explicitExtensions.args,
+        provider: explicitExtensions.provider ?? identity.provider,
+        model: explicitExtensions.modelOverride ?? resumeModel,
+    };
+}

package/mcp/entwurf-bridge/dist/pi-extensions/lib/session-id.js

@@ -12,8 +12,9 @@
  * every path, so the id grammar has ONE definition instead of one-per-importer.
  *
  * Keep dependency-free except `node:crypto`. The validator/grammar here is the
- * same one the 0.9.0 resident garden guard and entwurf spawn collision pre-check
- * enforce — do NOT fork it.
+ * one every V3 record/address surface shares — do NOT fork it. Collision safety
+ * is NOT a validator/generator concern: it belongs to the record store's
+ * exclusive CREATE publish, which fails loud on an occupied final path.
  */
 import { randomBytes } from "node:crypto";
 /** `YYYYMMDDTHHMMSS-[0-9a-f]{6}`. Anchored; no surrounding slop. */
@@ -38,9 +39,11 @@ export function formatSessionTimestamp(now = new Date()) {
         `T${p(now.getHours())}${p(now.getMinutes())}${p(now.getSeconds())}`);
 }
 /**
- * Durable garden sessionId minted at the session's true birth. 6 hex suffix
- * defeats same-second parallel-spawn collision; callers that spawn still
- * header-scan pre-check (assertSessionIdAvailableForSpawn).
+ * Durable garden sessionId minted at the session's true birth. The 6-hex
+ * (24-bit) suffix makes a same-second collision unlikely, never impossible.
+ * No caller pre-checks availability: collision SAFETY is owned by the record
+ * store's exclusive CREATE publish (upsertMetaSession), which fails loud on
+ * an occupied final path instead of replacing whatever entry holds it.
  *
  * @param {Date} [now]
  * @returns {string}

package/mcp/entwurf-bridge/dist/pi-extensions/lib/socket-discovery.js

@@ -28,8 +28,8 @@
  *     The legacy bridge `getLiveSessions` guarded this (`entry.isSymbolicLink()`);
  *     deriving the listing from facts would drop that guard unless we re-assert it
  *     here. A symlinked socket is NEVER probed: a citizen owning one is forced to
- *     `dead` (→ dormant → resume a fresh process, never SEND to a hijacked
- *     listener); a record-less one is quarantined out of the listing entirely.
+ *     `dead` (→ dormant → an honest reject, never SEND to a hijacked listener);
+ *     a record-less one is quarantined out of the listing entirely.
  *     Both surface as `symlinkedGardenIds`.
  *   - MALFORMED NAME (P3): a `*.sock` whose stem is not a garden id has no citizen
  *     to correlate to and is dropped — but VISIBLY (`malformedNames`), not
@@ -85,7 +85,7 @@ export function isRecordLessSocketCandidate(inspection) {
 }
 /**
  * Inspect the EXACT control-socket path given (no gid re-derivation) and classify it by
- * lstat alone. This is the path-addressed core of the inspection: the 5c-3 spawn-bg watcher
+ * lstat alone. This is the path-addressed core of the inspection: a resume watcher
  * observes `plan.expectedSocketPath` and MUST inspect that exact path (its contract forbids
  * re-deriving a path from the gid), so the path-taking form is the SSOT and
  * `inspectTargetControlSocket` is the thin gid→path wrapper over it. `lstatFn` is injectable