@junghanacs/entwurf 0.41.2 → 0.50.0

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

@@ -360,9 +360,12 @@ export interface MetaIdentity {
 	 * arm-capable event and writes in the SAME atomic upsert as that attach, then copies into
 	 * the receiver marker it writes under the record-arm lock. A dead marker carrying the
 	 * value the record still carries is evidence that no later arm-capable attach happened;
-	 * one that does not carry it is not. `null` means no binding was ever observed — every
-	 * other backend, a record no arm has touched since this field existed, a create — and
-	 * is never filled by inference. Every writer that does not mint PRESERVES it.
+	 * one that does not carry it is not. The pi-durable birth (#157 B3 C4) mints it the same way
+	 * under the same lock and copies it into its location evidence (`pi-durable-location.ts`)
+	 * instead of a marker; there it binds a location, never a dormancy verdict. `null` means no
+	 * binding was ever observed — every other backend, a pi-durable record no birth has bound,
+	 * a record no arm has touched since this field existed, a create — and is never filled by
+	 * inference. Every writer that does not mint PRESERVES it.
 	 */
 	attachIncarnation: string | null;
 }
@@ -614,10 +617,10 @@ export interface MetaIdentityMintInput {
 	model?: string | null;
 	transcriptPath?: string | null;
 	/**
-	 * The arm binding to commit with this write. ONLY the Claude Code hook passes it, and
-	 * only on an arm-capable event under the record-arm lock; `undefined` (every other
-	 * writer, every UserPromptSubmit) keeps the existing value, and a create without it is
-	 * `null`.
+	 * The arm binding to commit with this write. ONLY the Claude Code hook (on an arm-capable
+	 * event) and the pi-durable birth (#157 B3 C4) pass it, each under the record-arm lock;
+	 * `undefined` (every other writer, every UserPromptSubmit) keeps the existing value, and a
+	 * create without it is `null`.
 	 */
 	attachIncarnation?: string;
 }
@@ -1471,7 +1474,9 @@ export function defaultMetaReceiversDir(): string {
  * sandboxed receivers root sandboxes it too and no new environment carrier exists. It is
  * deliberately NOT the v2 dispatch lock dir — visible resume holds that per-gid lock across
  * its whole launch + observation window, and the relaunched session's own arm must not wait
- * on it. Only the Claude Code hook takes this lock; nothing else reads or writes here.
+ * on it. The Claude Code hook and the pi-durable birth (`pi-durable-location.ts`, #157 B3 C4)
+ * take this lock, each around the upsert that mints `attachIncarnation`; nothing else reads or
+ * writes here.
  */
 export function defaultMetaRecordArmLocksDir(receiversDir: string = defaultMetaReceiversDir()): string {
 	return path.join(path.dirname(receiversDir), "meta-record-arm-locks");

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

@@ -87,6 +87,7 @@
  */
 
 import { ACP_MODEL_NOT_CURATED_HINT } from "./acp/model-ids.js";
+import { ENTWURF_FRESH_LAUNCH_REJECT_HINTS } from "./agent-guidance.ts";
 import { callbackEnvAssignments } from "./callback-env.ts";
 import { classifyTmuxCwd, type TmuxCwdRejectReason } from "./classify-tmux-cwd.ts";
 import {
@@ -629,7 +630,9 @@ export function freshCall(
 }
 
 /** Why each refusal happened, in the caller's terms. A reason a caller cannot act on is a reason
- * they will guess about. */
+ * they will guess about. The static tmux launch-stage text is authored in root
+ * ENTWURF.json (#154 C1-D) and bound key by key, never spread, so a duplicate or missing reason
+ * still fails typecheck; slot-bearing, ACP and preflight-leaf hints stay code-owned. */
 const REJECT_HINT: Record<FreshCallRejectReason, string> = {
 	// The Copilot capability reasons keep their repair text on the leaf that decides them, so
 	// the sentence an operator reads cannot drift away from the predicate that produced it.
@@ -641,34 +644,28 @@ const REJECT_HINT: Record<FreshCallRejectReason, string> = {
 	...CODEX_CALLER_PREFLIGHT_HINT,
 	...CODEX_CALLER_SEAT_HINT,
 	...FRESH_CALL_PROVIDER_HINT,
-	"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",
-	"cwd-not-absolute":
-		"the requested cwd is not an absolute path (the value is taken literally — nothing trims or resolves it)",
-	"cwd-format-token":
-		"the requested cwd contains '#', which tmux expands as a format inside -c — it would silently rewrite the path or run a command",
-	"cwd-missing":
-		"the requested cwd does not exist; tmux would not report this, it would open the window in $HOME and look successful",
-	"cwd-not-directory": "the requested cwd exists but is not a directory",
-	"tmux-session-name-invalid":
-		"the requested tmux session name is outside the shape this rail addresses (start with a letter or digit, then letters, digits, '_' or '-') — some other shapes tmux cannot resolve at all ('#' is expanded when the name is stored; '.' and ':' are its own pane/window separators inside a target; a name like '$0' loses to the session id '$0'), and the rest are declined to keep one narrow grammar, so rename the session or open one whose name fits",
-	"tmux-session-missing":
-		"no session with that exact name answers on this agent's tmux server (or that server stopped answering) — nothing was created, so open the session yourself and call again",
-	"model-empty": "model is empty after trimming; fresh calls require an explicit model",
+	"no-tmux-context": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["no-tmux-context"],
+	"anchor-malformed": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["anchor-malformed"],
+	"anchor-unresolved": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["anchor-unresolved"],
+	"anchor-mismatch": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["anchor-mismatch"],
+	"caller-identity-unavailable": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["caller-identity-unavailable"],
+	"cwd-not-absolute": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["cwd-not-absolute"],
+	"cwd-format-token": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["cwd-format-token"],
+	"cwd-missing": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["cwd-missing"],
+	"cwd-not-directory": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["cwd-not-directory"],
+	"tmux-session-name-invalid": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["tmux-session-name-invalid"],
+	"tmux-session-missing": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["tmux-session-missing"],
+	"model-empty": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["model-empty"],
 	"model-invalid": `model must be one ${MODEL_MAX_CHARS}-character argv-safe id/alias without whitespace or tmux syntax`,
 	"acp-model-not-curated": ACP_MODEL_NOT_CURATED_HINT,
-	"task-empty": "task is empty after trimming",
+	"task-empty": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["task-empty"],
 	"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",
+	"runtime-unresolved": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["runtime-unresolved"],
+	"runtime-not-absolute": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["runtime-not-absolute"],
+	"runtime-path-whitespace": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["runtime-path-whitespace"],
+	"runtime-missing": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["runtime-missing"],
+	"runtime-not-regular-file": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["runtime-not-regular-file"],
+	"runtime-not-executable": ENTWURF_FRESH_LAUNCH_REJECT_HINTS["runtime-not-executable"],
 };
 
 /**

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

@@ -23,7 +23,11 @@
  * This is the tmux rail. A caller inside herdr (`HERDR_ENV=1`, herdr's own marker, read for its
  * exact value as `fresh-call-dispatch` does) is refused by name before anything else: herdr owns
  * placement there, and an ambient `TMUX` that happens to be set would otherwise put the window in
- * a session the operator is not looking at. There is no herdr resume rail yet and no fallback.
+ * a session the operator is not looking at. Since #157 G1a the shared rail root (`fresh-call-dispatch`)
+ * hands a resume inside herdr to the separate herdr rail (`herdr-resume-call.ts`) and never reaches
+ * this leaf there;
+ * this guard stays so that a direct caller still cannot open a tmux window from inside herdr. No
+ * fallback in either direction.
  *
  * ── The cwd is the whole reason this module owns its own tmux argv ──
  *
@@ -49,6 +53,7 @@
  * to acceptance, not to the product's launch receipt.
  */
 
+import { ENTWURF_RESUME_LAUNCH_REJECT_HINTS } from "./agent-guidance.ts";
 import { classifyTmuxCwd, type TmuxCwdRejectReason } from "./classify-tmux-cwd.ts";
 import {
 	assertLaunchTarget,
@@ -76,6 +81,49 @@ import {
 export const RESUME_CALL_RUNTIME = { pi: "pi", "claude-code": "claude" } as const;
 export type ResumeCallBackend = keyof typeof RESUME_CALL_RUNTIME;
 
+/**
+ * #157 B3: a pi-durable resume reopens through the MANAGED verb, exactly as its fresh call does —
+ * `entwurf pi-durable` verifies this package's carrier and its SDK set before anything runs, and the
+ * durable app is never started bare. It is its own entry (`resumePiDurableCall`) rather than a row of
+ * the table above, because it is the one resume whose launch also carries an environment.
+ */
+export const RESUME_CALL_PI_DURABLE_RUNTIME = "entwurf";
+
+/**
+ * The pi-durable adopt launch projection (#157 B3, L3-A1 §1): EXACTLY these five names, each read by
+ * name and emitted in this order — the SDK's own profile input, and the standard children of ONE meta
+ * root. It is a fixed projection of two coordinates the caller derived, not an environment dictionary:
+ * no other name can be expressed through it. The launched child checks the four roots it actually
+ * received against its closed adopt context, and its raw profile against the reservation, before
+ * anything opens, so a value this module mangled would refuse there rather than open something else.
+ */
+export interface ResumeCallPiDurableAdoptEnv {
+	readonly PI_CODING_AGENT_DIR: string;
+	readonly ENTWURF_META_SESSIONS_DIR: string;
+	readonly ENTWURF_META_MAILBOX_DIR: string;
+	readonly ENTWURF_META_SENDERS_DIR: string;
+	readonly ENTWURF_META_RECEIVERS_DIR: string;
+}
+
+/** The five `NAME=value` assignments, in the fixed order, or none. Every value must be an absolute
+ * path: a relative one would resolve against whatever directory the child starts in. */
+function adoptEnvAssignments(adoptEnv: ResumeCallPiDurableAdoptEnv | undefined): string[] {
+	if (adoptEnv === undefined) return [];
+	const pairs: readonly (readonly [string, string])[] = [
+		["PI_CODING_AGENT_DIR", adoptEnv.PI_CODING_AGENT_DIR],
+		["ENTWURF_META_SESSIONS_DIR", adoptEnv.ENTWURF_META_SESSIONS_DIR],
+		["ENTWURF_META_MAILBOX_DIR", adoptEnv.ENTWURF_META_MAILBOX_DIR],
+		["ENTWURF_META_SENDERS_DIR", adoptEnv.ENTWURF_META_SENDERS_DIR],
+		["ENTWURF_META_RECEIVERS_DIR", adoptEnv.ENTWURF_META_RECEIVERS_DIR],
+	];
+	for (const [name, value] of pairs) {
+		if (typeof value !== "string" || !value.startsWith("/")) {
+			throw new Error(`mux-resume-call: refusing to build argv with a non-absolute ${name}: ${JSON.stringify(value)}`);
+		}
+	}
+	return pairs.map(([name, value]) => `${name}=${value}`);
+}
+
 /** Why a resume window could not be opened. Every value is a NAMED refusal; this module has no
  * fallback launch and no fallback directory. The cwd members come from the shared classification
  * leaf and their string values are stable contract. */
@@ -96,7 +144,8 @@ export type ResumeCallResult = { ok: true; receipt: ResumeCallReceipt } | { ok:
 
 /**
  * Launch argv: the leaf's detached-append shape, the fixed identity scrub (`SCRUBBED_INHERITED_ENV`,
- * the same two assignments every fresh window carries), `-c`, the runtime, then the caller's flags.
+ * the same two assignments every fresh window carries), for a pi-durable adoption the five fixed
+ * projection assignments after it (#157 B3), `-c`, the runtime, then the caller's flags.
  * `--` is what keeps tmux from reading the runtime or its flags as tmux options. The scrub is not a
  * carrier: it only empties identity a tmux server may have inherited, and a resumed Claude Code
  * (which, unlike pi, never re-exports its own) would otherwise present a stale one to its bridge.
@@ -106,16 +155,19 @@ export function buildResumeCallArgs(
 	cwd: string,
 	runtimePath: string,
 	runtimeArgs: readonly string[],
+	adoptEnv?: ResumeCallPiDurableAdoptEnv,
 ): string[] {
 	assertSelector("session", placement.sessionId);
 	assertLaunchTarget(runtimePath);
 	const bad = classifyTmuxCwd(cwd);
 	if (bad) throw new Error(`mux-resume-call: refusing to build argv with an unusable cwd (${bad}): ${cwd}`);
+	const adoptAssignments = adoptEnvAssignments(adoptEnv);
 	return [
 		"new-window",
 		"-d",
 		"-a",
 		...SCRUBBED_INHERITED_ENV.flatMap((assignment) => ["-e", assignment]),
+		...adoptAssignments.flatMap((assignment) => ["-e", assignment]),
 		"-t",
 		`${placement.sessionId}:{end}`,
 		"-c",
@@ -139,6 +191,28 @@ export function buildResumeCallArgs(
 export function resumeCall(
 	params: { backend: ResumeCallBackend; cwd: string; runtimeArgs: readonly string[] },
 	env: NodeJS.ProcessEnv = process.env,
+): ResumeCallResult {
+	return openResumeWindow(RESUME_CALL_RUNTIME[params.backend], params, undefined, env);
+}
+
+/**
+ * #157 B3: the pi-durable resume window. The same order, refusals and receipt as `resumeCall` — the
+ * runtime is the managed `entwurf`, and the window additionally carries the fixed adopt projection.
+ * `runtimeArgs` (the managed verb and its closed adopt context) is passed through untouched; this
+ * module never decodes it.
+ */
+export function resumePiDurableCall(
+	params: { cwd: string; runtimeArgs: readonly string[]; adoptEnv: ResumeCallPiDurableAdoptEnv },
+	env: NodeJS.ProcessEnv = process.env,
+): ResumeCallResult {
+	return openResumeWindow(RESUME_CALL_PI_DURABLE_RUNTIME, params, params.adoptEnv, env);
+}
+
+function openResumeWindow(
+	runtime: string,
+	params: { cwd: string; runtimeArgs: readonly string[] },
+	adoptEnv: ResumeCallPiDurableAdoptEnv | undefined,
+	env: NodeJS.ProcessEnv,
 ): ResumeCallResult {
 	if (env.HERDR_ENV === "1") return { ok: false, reason: "herdr-resume-unsupported" };
 	const badCwd = classifyTmuxCwd(params.cwd);
@@ -146,7 +220,7 @@ export function resumeCall(
 
 	let runtimePath: string;
 	try {
-		runtimePath = resolveRuntimeOnPath(RESUME_CALL_RUNTIME[params.backend], env);
+		runtimePath = resolveRuntimeOnPath(runtime, env);
 	} catch (err) {
 		if (err instanceof LaunchPreconditionError) return { ok: false, reason: err.reason };
 		throw err;
@@ -157,7 +231,7 @@ export function resumeCall(
 	const placement = inspected.placement;
 	requireSameContext("resumeCall", placement, env);
 
-	const run = runTmux(buildResumeCallArgs(placement, params.cwd, runtimePath, params.runtimeArgs), env);
+	const run = runTmux(buildResumeCallArgs(placement, params.cwd, runtimePath, params.runtimeArgs, adoptEnv), env);
 	assertTmuxOk("new-window", run);
 
 	let fields: ReturnType<typeof parseWindowFields>;
@@ -187,24 +261,22 @@ export function resumeCall(
 }
 
 /** Why each refusal happened, in the caller's terms. A reason a caller cannot act on is a reason
- * they will guess about. */
+ * they will guess about. The text is authored in root ENTWURF.json (#154 C1-D); each
+ * key is bound explicitly so the reason union stays exhaustive here. */
 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",
-	"herdr-resume-unsupported":
-		"this agent runs inside herdr, and same-id resume has only a tmux rail — nothing was opened in any ambient tmux session",
-	"runtime-unresolved": "the citizen's runtime (pi or claude) 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",
+	"no-tmux-context": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["no-tmux-context"],
+	"anchor-malformed": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["anchor-malformed"],
+	"anchor-unresolved": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["anchor-unresolved"],
+	"anchor-mismatch": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["anchor-mismatch"],
+	"cwd-not-absolute": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["cwd-not-absolute"],
+	"cwd-format-token": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["cwd-format-token"],
+	"cwd-missing": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["cwd-missing"],
+	"cwd-not-directory": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["cwd-not-directory"],
+	"herdr-resume-unsupported": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["herdr-resume-unsupported"],
+	"runtime-unresolved": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["runtime-unresolved"],
+	"runtime-not-absolute": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["runtime-not-absolute"],
+	"runtime-path-whitespace": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["runtime-path-whitespace"],
+	"runtime-missing": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["runtime-missing"],
+	"runtime-not-regular-file": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["runtime-not-regular-file"],
+	"runtime-not-executable": ENTWURF_RESUME_LAUNCH_REJECT_HINTS["runtime-not-executable"],
 };

package/pi-extensions/lib/pi-durable-fresh-preflight.ts

@@ -19,7 +19,7 @@
  *                 `{v:2,task}` payload, whose decoder caps `task` at 16000 characters. A framed
  *                 task over that cap would open a window whose bootstrap refuses its own argv.
  *
- * ── Then the carrier, then the four units ──
+ * ── Then the carrier, then the five units ──
  *
  *   carrier          the package's own pi-durable carrier and its declared SDK set, verified
  *                    (`pi-durable-runtime.ts`); passed in as that check's verdict.
@@ -29,6 +29,9 @@
  *                    it every dispatch to the citizen is the honest `mailbox-undeliverable`.
  *   visible identity the packaged bootstrap — the one that hands the TUI the view whose conversation
  *                    labels carry the garden id.
+ *   owner fence      the compiled owner fence in the same closure — the packaged bootstrap imports it,
+ *                    so without it the bootstrap cannot load. Asked here as a file this package must
+ *                    ship, nothing more; the carrier verdict above does not cover it.
  *
  * ── What this deliberately does NOT claim ──
  *
@@ -52,7 +55,8 @@ export type PiDurablePreflightRejectReason =
 	| "pi-durable-birth-unit-missing"
 	| "pi-durable-mcp-hand-missing"
 	| "pi-durable-receive-unit-missing"
-	| "pi-durable-visible-identity-missing";
+	| "pi-durable-visible-identity-missing"
+	| "pi-durable-owner-fence-missing";
 
 /** `<provider>/<model id>` at the FIRST `/`, or `null` when either side is empty. */
 export function splitPiDurableModel(model: string): { provider: string; model: string } | null {
@@ -89,6 +93,7 @@ export function piDurableFreshPreflight(params: {
 	if (!existsSync(layout.bridgeEntry)) return "pi-durable-mcp-hand-missing";
 	if (!ownerJoinAdmitsDurableHost(layout.deliverability)) return "pi-durable-receive-unit-missing";
 	if (!existsSync(layout.bootstrap)) return "pi-durable-visible-identity-missing";
+	if (!existsSync(layout.ownerFence)) return "pi-durable-owner-fence-missing";
 	return null;
 }
 
@@ -110,4 +115,6 @@ export const PI_DURABLE_PREFLIGHT_HINT: Record<
 		"this Entwurf package's compiled owner join does not admit pi-durable-host, so nothing could ever be delivered to the sibling — reinstall or rebuild Entwurf",
 	"pi-durable-visible-identity-missing":
 		"this Entwurf package has no packaged pi-durable bootstrap (pi/pi-durable/bootstrap.mjs), so no TUI would carry the garden id — reinstall Entwurf",
+	"pi-durable-owner-fence-missing":
+		"this Entwurf package has no compiled pi-durable owner fence (mcp/entwurf-bridge/dist/pi-extensions/lib/pi-durable-owner-fence.js), which its packaged bootstrap imports — reinstall or rebuild Entwurf",
 };