@junghanacs/entwurf 0.13.0 → 0.14.0

package/pi-extensions/lib/mux-resume-call.ts

@@ -0,0 +1,221 @@
+/**
+ * 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,
+	type LaunchRejectReason,
+	resolveRuntimeOnPath,
+} from "./mux-launch.ts";
+import {
+	APPEND_FORMAT,
+	assertSelector,
+	assertTmuxOk,
+	inspectPlacement,
+	type Placement,
+	type PlacementRejectReason,
+	parseWindowFields,
+	requireSameContext,
+	runTmux,
+	type WindowHandle,
+} from "./mux-placement.ts";
+
+/** 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";
+
+/** Why a resume window could not be opened. Every value is a NAMED refusal; this module has no
+ * fallback launch and no fallback directory. */
+export type ResumeCallRejectReason =
+	| PlacementRejectReason
+	| LaunchRejectReason
+	| "cwd-not-absolute"
+	| "cwd-format-token"
+	| "cwd-missing"
+	| "cwd-not-directory";
+
+/** Coordinates plus what was handed to tmux. `cwd` is the REQUESTED start directory — the same
+ * kind of fact as `runtimePath`, namely what tmux was asked for, not an observation. */
+export interface ResumeCallReceipt extends WindowHandle {
+	runtimePath: string;
+	cwd: string;
+}
+
+export type ResumeCallResult = { ok: true; receipt: ResumeCallReceipt } | { ok: false; reason: ResumeCallRejectReason };
+
+/**
+ * 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: string): ResumeCallRejectReason | null {
+	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: ReturnType<typeof statSync>;
+	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: Placement,
+	cwd: string,
+	runtimePath: string,
+	runtimeArgs: readonly string[],
+): string[] {
+	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: { cwd: string; runtimeArgs: readonly string[] },
+	env: NodeJS.ProcessEnv = process.env,
+): ResumeCallResult {
+	const badCwd = classifyResumeCwd(params.cwd);
+	if (badCwd) return { ok: false, reason: badCwd };
+
+	let runtimePath: string;
+	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: ReturnType<typeof parseWindowFields>;
+	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: Record<ResumeCallRejectReason, string> = {
+	"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/pi-extensions/lib/resume-launch-identity.ts

@@ -0,0 +1,162 @@
+/**
+ * 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.ts";
+import { readAddressableMetaIdentity } from "./meta-session.ts";
+
+/**
+ * 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 {
+	readonly reason = "target-not-pi" as const;
+	readonly backend: string;
+	constructor(gardenId: string, backend: string) {
+		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;
+	}
+}
+
+/** The launch-time facts `buildResumePiArgs` needs, resolved from the meta-record + the
+ * recorded transcript (record authority, #50 C2/C3). */
+export interface LaunchIdentity {
+	/** The EXACT session JSONL to resume — `pi --session <path>`. */
+	sessionFile: string;
+	cwd: string;
+	explicitExtensionArgs: readonly string[];
+	provider: string | null | undefined;
+	model: string;
+}
+
+/**
+ * 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: string): LaunchIdentity {
+	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/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";
@@ -45,9 +46,11 @@ export function formatSessionTimestamp(now = new Date()) {
 }
 
 /**
- * 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/pi-extensions/lib/socket-discovery.ts

@@ -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
@@ -127,7 +127,7 @@ export interface LstatLike {
 
 /**
  * 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

package/prompts/engraving.md

@@ -1,11 +1,15 @@
 <!-- ═══════════════════════════════════════════════════════════════════════
      SAMPLE — operator engraving carrier (entwurf)
 
-     What this is: the markdown body below this comment is loaded VERBATIM
-     into the backend's identity slot (Claude `_meta.systemPrompt`). It is
-     the one place an operator stamps a short identity onto every entwurf
-     ACP turn — replacing Claude's `claude_code` preset (which also strips
-     the preset's auto-memory advertisement, the memory-containment lever).
+     What this is: the engraving file is loaded VERBATIM into the backend's
+     identity slot (Claude `_meta.systemPrompt`). It is the one place an
+     operator stamps a short identity onto every entwurf ACP turn —
+     replacing Claude's `claude_code` preset (which also strips the preset's
+     auto-memory advertisement, the memory-containment lever).
+
+     VERBATIM means the WHOLE file, this comment included — the loader does
+     not strip markdown comments. Copy this sample and delete everything you
+     do not want on the wire; do not point the runtime at it as-is.
 
      Where it loads from:
        • Runtime default = pi-extensions/lib/acp/prompts/engraving.md
@@ -22,6 +26,10 @@
          tool catalogs here — a large Claude carrier can route OAuth
          sessions to metered "extra usage" billing.
        • An empty or missing file = opt-out (no engraving). That is fine.
+       • Do NOT open the file with a blank line to separate yourself from
+         Claude's fixed SDK sentence. Your leading/trailing whitespace is
+         trimmed (it would otherwise drift the reuse signature) and the
+         loader opens the carrier with that blank line itself.
      ═══════════════════════════════════════════════════════════════════════ -->
 
 # Engraving Here