@junghanacs/entwurf 0.13.0 → 0.14.0

package/pi-extensions/lib/meta-session.ts

@@ -514,7 +514,7 @@ export function parseMetaIdentity(json: string): MetaIdentity {
 // `wakeMode` describes the last centimetre, not citizen rank. The control-socket
 // adapter injects the body into a pi turn, so backend `pi` is `direct-inject`;
 // Claude's mailbox is `self-fetch`; native-push adapters are direct injection.
-// Dormant spawn-bg resume is a separate transport/ownership decision and does not
+// Resuming a dormant citizen is a separate lifecycle capability and does not
 // turn the pi record into a mailbox citizen.
 // ---------------------------------------------------------------------------
 
@@ -1090,6 +1090,22 @@ export function listAllMetaIdentities(
 	return { identities, errors };
 }
 
+/**
+ * The fs-bound listing — the same binding shape {@link certifyActiveStoreDir} gives the
+ * certification: one resolved dir, kind-carrying entries, the fd-guarded record reader.
+ * Exists so an in-repo facts surface (`meta-facts`, #65) reuses THE listing contract
+ * instead of re-binding readdir/read by hand — the exact drift that made external
+ * consumers carry a decaying copy of the certification. No semantics of its own:
+ * everything it returns is {@link listAllMetaIdentities} over the real store.
+ */
+export function listAllMetaIdentitiesDir(dir: string): ListIdentitiesResult & { dir: string } {
+	const resolved = path.resolve(expandTilde(dir));
+	return {
+		dir: resolved,
+		...listAllMetaIdentities(readActiveStoreEntries(resolved), makeStoreRecordReader(resolved)),
+	};
+}
+
 export type UpsertAction = "create" | "attach";
 
 export interface UpsertDecision {
@@ -1747,8 +1763,13 @@ export interface UpsertMetaSessionResult {
  * A narrower scan is not a smaller version of this: asking only about MY
  * `nativeSessionId` writes happily beside a drifted or duplicated record that the
  * doctor refuses, which is how a host ends up certified by one surface and not
- * the other. The write is tmp-file + rename so a crash never leaves a
- * half-written record (#30 crash-safety).
+ * the other.
+ *
+ * The write is split by ACTION (#66): ATTACH rewrites its OWN record atomically
+ * in place (tmp + rename, #30 crash-safety); CREATE publishes exclusively
+ * (tmp + link) and fails loud if the minted garden id's final path already
+ * exists — certification cannot see a future minted gid, so replacement-free
+ * publish is the only collision safety a create has.
  */
 export function upsertMetaSession(opts: UpsertMetaSessionOptions): UpsertMetaSessionResult {
 	const dir = path.resolve(expandTilde(opts.dir ?? defaultMetaSessionsDir()));
@@ -1759,17 +1780,84 @@ export function upsertMetaSession(opts: UpsertMetaSessionOptions): UpsertMetaSes
 	const existing = cert.records.find((record) => record.identity.nativeSessionId === target)?.identity ?? null;
 	const decision = decideUpsert(existing, opts.input, opts.now);
 	const file = path.join(dir, metaRecordFilename(decision.record));
-	atomicWriteIdentity(file, decision.record);
+	if (decision.action === "create") publishExclusiveIdentity(file, decision.record);
+	else atomicWriteIdentity(file, decision.record);
 	return { action: decision.action, record: decision.record, dir, path: file };
 }
 
-/** tmp-file + rename so a crash never leaves a half-written record (v3 identity write). */
+/**
+ * ATTACH replace primitive: tmp-file + rename so a crash never leaves a
+ * half-written record (#30 crash-safety). rename(2) REPLACES an existing final
+ * path, which is exactly right for attach (the record being rewritten is the
+ * caller's own) and exactly wrong for create — a freshly minted garden id must
+ * never land on this path (#66).
+ */
 function atomicWriteIdentity(file: string, identity: MetaIdentity): void {
 	const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
 	fs.writeFileSync(tmp, serializeMetaIdentity(identity), { mode: 0o600 });
 	fs.renameSync(tmp, file);
 }
 
+/**
+ * CREATE publish primitive: same-directory tmp + `link(2)` to the final path.
+ * link fails with EEXIST when the final path already exists — the kernel makes
+ * the existence check and the publish one atomic step, so there is no
+ * check-then-rename TOCTOU window and a same-second 24-bit garden-id suffix
+ * collision can never silently replace whatever already holds the final path
+ * (#66). The occupied entry's bytes are untouched on refusal; tmp cleanup is
+ * attempted on every path, and a published-with-residue state fails loud.
+ *
+ * @internal Exported only as the production subject for the meta-session gate's
+ * deterministic collision oracle (the minted suffix is random, so the public
+ * upsert seam cannot force a collision deterministically). Not an
+ * operator/package API.
+ */
+export function publishExclusiveIdentity(file: string, identity: MetaIdentity): void {
+	const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+	fs.writeFileSync(tmp, serializeMetaIdentity(identity), { mode: 0o600 });
+	try {
+		fs.linkSync(tmp, file);
+	} catch (err) {
+		try {
+			fs.unlinkSync(tmp);
+		} catch (cleanupErr) {
+			// The primary link error stays the truth of this publish; a cleanup errno
+			// never masks it. ENOENT is silent (no residue = desired state); any other
+			// cleanup failure is an operator diagnostic on stderr, then the primary throws.
+			if ((cleanupErr as { code?: unknown }).code !== "ENOENT") {
+				process.stderr.write(
+					`[meta-session] tmp cleanup after a failed CREATE publish also failed (${tmp}): ` +
+						`${(cleanupErr as Error).message}\n`,
+				);
+			}
+		}
+		if ((err as { code?: unknown }).code === "EEXIST") {
+			throw new MetaRecordError(
+				`meta-record CREATE collision: garden id "${identity.gardenId}" already has an entry at ` +
+					`${file}. Exclusive publish refused to replace it — the occupied final-path entry was ` +
+					`not modified and no ACTIVE record was published for nativeSessionId ` +
+					`"${identity.nativeSessionId}".`,
+			);
+		}
+		throw err;
+	}
+	try {
+		fs.unlinkSync(tmp);
+	} catch (err) {
+		// ENOENT is the goal state, not a failure: the record is published and no
+		// tmp remains, so there is nothing left to clean.
+		if ((err as { code?: unknown }).code === "ENOENT") return;
+		// Never roll the final back: the record IS published (link succeeded).
+		throw new MetaRecordError(
+			`meta-record CREATE for garden id "${identity.gardenId}" is already published at ${file}, ` +
+				`but temp cleanup failed (${tmp}): ${(err as Error).message}. The caller aborts here, so ` +
+				`it received no successful birth/registration receipt; remove the temp file and retry — ` +
+				`a retry with the same nativeSessionId will ATTACH to the published record, not mint a ` +
+				`second identity.`,
+		);
+	}
+}
+
 // ---------------------------------------------------------------------------
 // Mailbox delivery (step 6) — addressed by GARDEN ID. The record store is the
 // authority (a sender may only deliver to a known garden citizen); the mailbox

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

@@ -0,0 +1,328 @@
+/**
+ * mux-fresh-call — open ONE visible sibling in the caller's own tmux session, hand it its first
+ * task in the launch argv, and let it name itself back to the caller.
+ *
+ * ── Why this is a third module and not a parameter on the leaf ──
+ *
+ * `mux-placement` owns place and only place; `mux-launch` owns "start the fixed official pi in
+ * a window I placed" and refuses a command carrier (docs §11). Both stay that way. The carrier
+ * lives HERE, one layer up, because the thing being carried is not a command in the shell sense
+ * — it is a TASK plus the instruction that makes the new citizen announce itself. Putting it on
+ * the leaf would make every future placement caller inherit a prompt argument it has no use for.
+ *
+ *   caller agent → fresh-call → fixed backend runtime + first-turn framing
+ *   fresh-call   → placement leaf (unchanged, carrier-free)
+ *   fresh-call  -X-> identity minting, delivery transport, task planning
+ *
+ * ── Invariants ──
+ *
+ *   1. The first turn does not MINT the garden id — record and socket exist from session start.
+ *      It exists to SAY that id to the caller, who is the one who cannot see it. (rail §6-a)
+ *   2. Correlation is what the DELIVERY layer stamps on the callback, never what the sibling
+ *      says about itself — asked directly, a fresh cell answers with a uuidv7. (rail §6-b)
+ *   3. The two receipts are separate objects and stay that way: `freshCall` returns tmux
+ *      coordinates synchronously and nothing else; the correlation receipt arrives later on the
+ *      caller's own inbound surface. Merging them would claim knowledge this module cannot have.
+ *   4. A launch with no callback is a REAL outcome, not an error to retry. No watcher, no poll,
+ *      no timeout supervisor. The window is visible; the operator can look.
+ */
+
+import { randomBytes } from "node:crypto";
+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 two backends this rail can open. Fixed set, not a profile — a third one is a decision,
+ * not a config entry. */
+export const FRESH_CALL_BACKENDS = ["pi", "claude-code"] as const;
+export type FreshCallBackend = (typeof FRESH_CALL_BACKENDS)[number];
+
+/** The fixed runtime each backend resolves on PATH. Same reason `mux-launch` uses PATH rather
+ * than a compiled-in location: the official binary is whatever the operator's environment gives
+ * when they type the name. */
+export const FRESH_CALL_RUNTIME: Record<FreshCallBackend, string> = {
+	pi: "pi",
+	"claude-code": "claude",
+};
+
+/**
+ * The callback tool NAME differs per backend and that is not cosmetic: native pi exposes the
+ * capability directly (`entwurf_v2`), while a Claude Code session reaches it through the MCP
+ * bridge under its namespaced name. Naming the wrong one costs the whole first turn.
+ */
+export const FRESH_CALL_CALLBACK_TOOL: Record<FreshCallBackend, string> = {
+	pi: "entwurf_v2",
+	"claude-code": "mcp__entwurf-bridge__entwurf_v2",
+};
+
+/** Mirrors the `entwurf_v2` message bound. This is an INTERFACE cap for symmetry with the
+ * delivery surface, not a claim that a task of this size was measured through tmux. An argv
+ * that the OS refuses is a launch failure and fails loud — it never reads as a delivered task. */
+export const TASK_MAX_CHARS = 16000;
+export const MODEL_MAX_CHARS = 200;
+const MODEL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._/:\[\]-]*$/;
+
+/** A model is an explicit launch input, not ambient process state. The grammar admits canonical
+ * pi provider/model ids, Claude model ids/aliases, and bracketed context variants, while refusing
+ * whitespace and tmux control syntax. It is passed without a shell using each runtime's measured
+ * CLI dialect: Pi takes `--model`, value; Claude Code takes `--model=value`. */
+export function isSafeFreshCallModel(model: string): boolean {
+	return model.length > 0 && model.length <= MODEL_MAX_CHARS && MODEL_PATTERN.test(model);
+}
+
+/**
+ * Backend argv AFTER the runtime path. Both orders are MEASURED, and both were measured by
+ * getting them wrong first (rail §6-a):
+ *
+ *   pi          — prompt BEFORE `--entwurf-control`, then `--model`, value as TWO tokens.
+ *                 Flag-first submitted no message; Pi rejects the equals form for `--model`.
+ *   claude-code — prompt, then `--allowedTools=` and `--model=` as ONE token each. The space form
+ *                 for allowedTools is variadic and eats the prompt as an option value.
+ *
+ * Both failures looked identical from outside: window open, record and socket minted, no turn.
+ *
+ * The equals form is NOT a permission guarantee — on the measured host the tool was already
+ * permitted, so the option's effect was unobservable. What was observed is that it does no harm
+ * to the argv. Permission stays a documented host precondition.
+ */
+export function buildBackendArgs(backend: FreshCallBackend, prompt: string, model: string): string[] {
+	switch (backend) {
+		case "pi":
+			return [prompt, "--entwurf-control", "--model", model];
+		case "claude-code":
+			return [prompt, `--allowedTools=${FRESH_CALL_CALLBACK_TOOL["claude-code"]}`, `--model=${model}`];
+	}
+}
+
+/**
+ * The first-turn framing. Order is the contract: the callback is the FIRST action and the task
+ * follows it, so a sibling that gets stuck in the task has already told the caller who it is.
+ *
+ * The three prohibitions are not politeness. Each names a detour that was measured to produce a
+ * confidently wrong answer or a wasted turn.
+ */
+export function buildFreshCallPrompt(params: {
+	backend: FreshCallBackend;
+	task: string;
+	callerGardenId: string;
+	nonce: string;
+}): string {
+	const tool = FRESH_CALL_CALLBACK_TOOL[params.backend];
+	return [
+		"You are a fresh visible citizen that entwurf opened in the operator's tmux session.",
+		"",
+		`FIRST ACTION, before reading files or anything else: call ${tool} with ` +
+			`target=${params.callerGardenId}, intent=fire-and-forget, wants_reply=false, and ` +
+			`message set to exactly ${params.nonce} — that string alone, nothing added.`,
+		"That call is how the agent that opened you learns your address. Do not skip it, do not",
+		"defer it until the task is done, and do not reword the message.",
+		"",
+		"Do not inspect environment variables, do not call entwurf_self, and do not start an MCP",
+		"server yourself. Your own report of your identity is not the address anyone needs.",
+		"",
+		"After the tool receipt, carry out this task:",
+		"",
+		params.task,
+	].join("\n");
+}
+
+/** A launch that was refused, or a placement that could not be established. Every value is a
+ * NAMED refusal — this module has no fallback launch. */
+export type FreshCallRejectReason =
+	| PlacementRejectReason
+	| LaunchRejectReason
+	| "caller-identity-unavailable"
+	| "model-empty"
+	| "model-invalid"
+	| "task-empty"
+	| "task-too-long";
+
+/** Coordinates plus what was handed to tmux. Read `runtimePath` as "what we asked to start".
+ * There is deliberately NO field here for the callback, the nonce's arrival, or the sibling's
+ * garden id — see the module header. */
+export interface FreshCallReceipt extends WindowHandle {
+	backend: FreshCallBackend;
+	model: string;
+	runtimePath: string;
+	nonce: string;
+}
+
+export type FreshCallResult = { ok: true; receipt: FreshCallReceipt } | { ok: false; reason: FreshCallRejectReason };
+
+/** Correlation tag only. Random, never derived from time, cwd or a peer listing — a nonce that
+ * encoded any of those would invite exactly the guessing this rail exists to refuse. */
+export function mintNonce(randomHex: () => string = defaultRandomHex): string {
+	return `mux-fresh-call-${randomHex()}`;
+}
+
+function defaultRandomHex(): string {
+	return randomBytes(12).toString("hex");
+}
+
+/** Launch argv: the leaf's detached-append shape, the runtime, then the backend's dialect. */
+export function buildFreshCallArgs(
+	placement: Placement,
+	runtimePath: string,
+	backendArgs: readonly string[],
+): string[] {
+	assertSelector("session", placement.sessionId);
+	assertLaunchTarget(runtimePath);
+	return [
+		"new-window",
+		"-d",
+		"-a",
+		"-t",
+		`${placement.sessionId}:{end}`,
+		"-P",
+		"-F",
+		APPEND_FORMAT,
+		"--",
+		runtimePath,
+		...backendArgs,
+	];
+}
+
+/**
+ * Open the sibling. Order is the safety argument, same as `launchPi`: validate the caller's
+ * identity and task, 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.
+ *
+ * `callerGardenId` is supplied by the SURFACE that registered this tool, from its own
+ * record-backed context. It is not a tool parameter and this module never derives, validates
+ * against a store, or guesses it: an empty value is a named refusal, not a lookup.
+ */
+export function freshCall(
+	params: { backend: FreshCallBackend; model: string; task: string; callerGardenId: string | null },
+	env: NodeJS.ProcessEnv = process.env,
+	nonce: string = mintNonce(),
+): FreshCallResult {
+	if (typeof params.callerGardenId !== "string" || params.callerGardenId.length === 0) {
+		return { ok: false, reason: "caller-identity-unavailable" };
+	}
+	const model = params.model.trim();
+	if (model.length === 0) return { ok: false, reason: "model-empty" };
+	if (!isSafeFreshCallModel(model)) return { ok: false, reason: "model-invalid" };
+	const task = params.task.trim();
+	if (task.length === 0) return { ok: false, reason: "task-empty" };
+	if (task.length > TASK_MAX_CHARS) return { ok: false, reason: "task-too-long" };
+
+	let runtimePath: string;
+	try {
+		runtimePath = resolveRuntimeOnPath(FRESH_CALL_RUNTIME[params.backend], 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("freshCall", placement, env);
+
+	const prompt = buildFreshCallPrompt({
+		backend: params.backend,
+		task,
+		callerGardenId: params.callerGardenId,
+		nonce,
+	});
+	const run = runTmux(buildFreshCallArgs(placement, runtimePath, buildBackendArgs(params.backend, prompt, model)), 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-fresh-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,
+			backend: params.backend,
+			model,
+			runtimePath,
+			nonce,
+		},
+	};
+}
+
+/** Why each refusal happened, in the caller's terms. A reason a caller cannot act on is a reason
+ * they will guess about. */
+const REJECT_HINT: Record<FreshCallRejectReason, string> = {
+	"no-tmux-context": "this agent is not running inside tmux, so there is no session to open a sibling beside",
+	"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",
+	"caller-identity-unavailable":
+		"this surface has no record-backed garden id for the caller, so the sibling would have no address to call back to",
+	"model-empty": "model is empty after trimming; fresh calls require an explicit model",
+	"model-invalid": `model must be one ${MODEL_MAX_CHARS}-character argv-safe id/alias without whitespace or tmux syntax`,
+	"task-empty": "task is empty after trimming",
+	"task-too-long": `task exceeds ${TASK_MAX_CHARS} characters`,
+	"runtime-unresolved": "the backend's runtime 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",
+};
+
+/**
+ * ONE renderer for both surfaces. Not a convenience: the two registrations are separate literals
+ * (that is this repo's shape), so a shared renderer is what keeps the operator-visible answer
+ * from drifting apart between native pi and the MCP bridge.
+ *
+ * The success text states the boundary out loud. A caller that reads "launched" and assumes
+ * "delivered" is the exact confusion the two-receipt split exists to prevent, so the text refuses
+ * to imply it.
+ */
+export function renderFreshCall(result: FreshCallResult): { text: string; isError: boolean } {
+	if (!result.ok) {
+		return {
+			text: `entwurf_fresh_call rejected: ${result.reason} — ${REJECT_HINT[result.reason]}. No window was opened.`,
+			isError: true,
+		};
+	}
+	const r = result.receipt;
+	return {
+		text:
+			`[entwurf fresh call →]\n` +
+			`  backend:  ${r.backend} (${r.runtimePath})\n` +
+			`  model:    ${r.model} (requested on the runtime CLI)\n` +
+			`  window:   ${r.windowId} (index ${r.windowIndex}) in session ${r.sessionId}\n` +
+			`  pane:     ${r.paneId} pid ${r.panePid}\n` +
+			`  nonce:    ${r.nonce}\n` +
+			`\n` +
+			`This is a LAUNCH receipt: tmux created that window and was asked to start the runtime with the model above. It does ` +
+			`NOT mean the sibling is running, that its first turn ran, or that the task was delivered.\n` +
+			`The sibling's garden id arrives separately — it calls entwurf_v2 back with the nonce above as its ` +
+			`first action, and the sender envelope of THAT message is the address. Nothing is polling for it; ` +
+			`if it never comes, the window is visible and can be read directly.`,
+		isError: false,
+	};
+}