@junghanacs/entwurf 0.36.0 → 0.37.0

package/pi/pi-durable/bootstrap.mjs

@@ -80,19 +80,21 @@ import {
 	failAfterCleanup,
 	PI_DURABLE_EXTENSION_NAME,
 	PI_DURABLE_TOOL_NAMES,
+	piDurableGardenIds,
 	withGardenIdentity,
 } from "../../mcp/entwurf-bridge/dist/pi-extensions/meta-bridge-pi-durable.js";
 
 const RUNTIME = "./carrier/runtime.js";
 const TUI = "./carrier/tui.js";
+const SESSIONS = "./carrier/sessions.js";
 
 /** The entwurf-bridge of THIS package closure: the one the contact spawns as its MCP hand. */
 export const PACKAGED_BRIDGE_ENTRY = fileURLToPath(
 	new URL("../../mcp/entwurf-bridge/dist/mcp/entwurf-bridge/src/index.js", import.meta.url),
 );
 
-/** Flags that take a value. Anything else but `--continue`/`-c` is an unknown argument — a bridge
- * entry included: the launch argv cannot point the contact at another bridge. */
+/** Flags that take a value. Anything else but `--continue`/`-c` and `--resume` is an unknown argument — a
+ * bridge entry included: the launch argv cannot point the contact at another bridge. */
 const VALUE_FLAGS = [
 	"--provider",
 	"--model",
@@ -293,12 +295,13 @@ async function loadNativeModules(files) {
  * @param {{
  *   bridgeEntry?: string,
  *   continueSession?: boolean,
+ *   session?: string,
  *   cwd?: string,
  *   model?: { provider: string, model: string },
  *   firstInput?: string,
  *   extensions?: readonly object[],
  *   contact?: Record<string, unknown>,
- *   open?: (options: { cwd: string, continueSession: boolean, extensions: readonly object[], model?: { provider: string, model: string } }) => Promise<any>,
+ *   open?: (options: { cwd: string, continueSession: boolean, session?: string, extensions: readonly object[], model?: { provider: string, model: string } }) => Promise<any>,
  * }} options
  * @returns {Promise<{ durable: any, contact: any, attachment: { gardenId: string } & Record<string, any>, firstInput?: any, close(): Promise<void> }>}
  *   (stated, because the compiled closure carries no declarations: a cleanup path that rethrows
@@ -307,6 +310,7 @@ async function loadNativeModules(files) {
 export async function openDurableCitizen({
 	bridgeEntry = PACKAGED_BRIDGE_ENTRY,
 	continueSession = false,
+	session,
 	cwd = process.cwd(),
 	model,
 	firstInput,
@@ -320,6 +324,12 @@ export async function openDurableCitizen({
 			"an explicit model and a first input apply only to a new session; a continued session is reopened as it was saved",
 		);
 	}
+	if (session !== undefined && (continueSession || model !== undefined || firstInput !== undefined)) {
+		throw refuse(
+			"fresh-only-argument-with-resume",
+			"a chosen session is reopened as it was saved: no --continue, explicit model or first input",
+		);
+	}
 	if (model !== undefined && !(nonEmpty(model.provider) && nonEmpty(model.model))) {
 		throw refuse("explicit-model-incomplete", "an explicit model names both its provider and its model id");
 	}
@@ -333,6 +343,7 @@ export async function openDurableCitizen({
 		durable = await openDurable({
 			cwd,
 			continueSession,
+			...(session === undefined ? {} : { session }),
 			extensions: [contact.extension, ...extensions],
 			...(model === undefined ? {} : { model }),
 		});
@@ -389,6 +400,7 @@ export async function openDurableCitizen({
 
 function parseArgs(argv) {
 	let continueSession = false;
+	let resume = false;
 	const values = new Map();
 	for (let i = 0; i < argv.length; i++) {
 		const arg = argv[i];
@@ -396,6 +408,10 @@ function parseArgs(argv) {
 			continueSession = true;
 			continue;
 		}
+		if (arg === "--resume") {
+			resume = true;
+			continue;
+		}
 		if (!VALUE_FLAGS.includes(arg)) throw new Error(`Unknown argument: ${arg}`);
 		if (values.has(arg)) throw refuse("argument-repeated", `${arg} is given more than once`);
 		const value = argv[++i];
@@ -404,7 +420,19 @@ function parseArgs(argv) {
 		}
 		values.set(arg, value);
 	}
+	if (resume && continueSession) {
+		throw refuse(
+			"resume-continue-exclusive",
+			"--resume chooses a session and --continue opens the newest one; give one of them",
+		);
+	}
 	const fresh = FRESH_ONLY_FLAGS.filter((flag) => values.has(flag));
+	if (resume && fresh.length > 0) {
+		throw refuse(
+			"fresh-only-argument-with-resume",
+			`${fresh.join(", ")} apply only to a new session; --resume reopens the chosen session as it was saved`,
+		);
+	}
 	if (continueSession && fresh.length > 0) {
 		throw refuse(
 			"fresh-only-argument-with-continue",
@@ -426,6 +454,7 @@ function parseArgs(argv) {
 				? { nativeModules: nativeModuleDirFiles(dirArg) }
 				: {};
 	if (continueSession) return { continueSession, ...nativeModule };
+	if (resume) return { resume, ...nativeModule };
 	const provider = values.get("--provider");
 	if (provider === undefined) {
 		throw refuse(
@@ -457,29 +486,102 @@ function parseArgs(argv) {
 	};
 }
 
+/** A local `YYYY-MM-DD HH:MM` for a list line. */
+function localTime(ms) {
+	const date = new Date(ms);
+	const two = (n) => String(n).padStart(2, "0");
+	return `${date.getFullYear()}-${two(date.getMonth() + 1)}-${two(date.getDate())} ${two(date.getHours())}:${two(date.getMinutes())}`;
+}
+
 /**
- * Parse, initialize the operator's module, load the TUI, open, run, close. `loadTui`, `open` and
- * `contact` are test seams; `bridgeEntry` is the checkout-only gates' private bundle, as in
- * `openDurableCitizen` — never the launch argv.
+ * `--resume` (#143): this directory's durable sessions, most recently written first, each by what its files and
+ * the record store already say — creation time, garden id, last write, whether another process holds it. No
+ * session database is opened to list them, and nothing is named that the store does not hold. Resolves the
+ * chosen session's id, or undefined when the choice was cancelled; never a fallback to another session.
+ */
+async function chooseSession(cwd, sessionsDir, pick) {
+	const { listSessions } = await import(SESSIONS);
+	const sessions = await listSessions(cwd);
+	if (sessions.length === 0) throw refuse("resume-no-session", `no durable session exists for ${cwd}`);
+	const { gardens, unreadable } = piDurableGardenIds(
+		sessions.map((session) => session.id),
+		sessionsDir,
+	);
+	const items = sessions.map((session) => ({
+		value: session.id,
+		label: `${localTime(session.createdAt)}  ${gardens.get(session.id) ?? "no record"}`,
+		description: [
+			session.lastWriteAt === undefined ? "never written" : `last write ${localTime(session.lastWriteAt)}`,
+			session.id,
+			...(session.openElsewhere ? ["open elsewhere"] : []),
+		].join(" · "),
+	}));
+	const title =
+		unreadable === 0 ? "Resume durable session:" : `Resume durable session (${unreadable} unreadable record(s)):`;
+	const id = await pick(title, items);
+	if (id === undefined) return undefined;
+	const chosen = sessions.find((session) => session.id === id);
+	if (chosen === undefined) throw refuse("session-not-found", `${id} is not one of the listed sessions`);
+	if (chosen.openElsewhere) {
+		throw refuse("session-open-elsewhere", `${id} is open in another process; close it there first`);
+	}
+	return chosen.id;
+}
+
+/**
+ * Parse, initialize the operator's module, load the TUI, open, run, close. `loadTui`, `open`,
+ * `contact` and `pick` (the `--resume` list's choice) are test seams; `bridgeEntry` is the
+ * checkout-only gates' private bundle, as in `openDurableCitizen` — never the launch argv.
  *
  * @param {readonly string[]} argv
  * @param {{
- *   loadTui?: () => Promise<{ runDurableTui: (...args: any[]) => Promise<void> }>,
+ *   loadTui?: () => Promise<{ runDurableTui: (...args: any[]) => Promise<void>, pickDurableSession?: (title: string, items: object[]) => Promise<string | undefined> }>,
  *   open?: (options: any) => Promise<any>,
  *   contact?: Record<string, unknown>,
  *   bridgeEntry?: string,
+ *   pick?: (title: string, items: { value: string, label: string, description: string }[]) => Promise<string | undefined>,
  * }} [seams]
  */
-export async function main(argv, { loadTui = () => import(TUI), open, contact, bridgeEntry } = {}) {
+export async function main(argv, { loadTui = () => import(TUI), open, contact, bridgeEntry, pick } = {}) {
 	// Every argument refusal is decided here, before any module, the TUI or the app loads.
-	const { nativeModules = [], ...args } = parseArgs(argv);
+	const { nativeModules = [], resume = false, ...args } = parseArgs(argv);
 	// The caller's directory, fixed before any operator code runs and handed to the app explicitly.
 	const cwd = process.cwd();
 	const extensions = await loadNativeModules(nativeModules);
 	// Loaded before anything opens, as upstream main.ts imports it statically: a TUI that cannot
 	// load opens no session, mints no citizen and leaves nothing to clean up.
-	const { runDurableTui } = await loadTui();
-	const citizen = await openDurableCitizen({ ...args, cwd, extensions, bridgeEntry, open, contact });
+	const tui = await loadTui();
+	const { runDurableTui } = tui;
+	let session;
+	if (resume) {
+		session = await chooseSession(
+			cwd,
+			contact?.sessionsDir,
+			pick ??
+				((title, items) => {
+					if (!process.stdin.isTTY || !process.stdout.isTTY) {
+						throw refuse(
+							"resume-needs-terminal",
+							"--resume lists the sessions to choose from in an interactive terminal",
+						);
+					}
+					return tui.pickDurableSession(title, items);
+				}),
+		);
+		if (session === undefined) {
+			process.stderr.write("[pi-durable] resume-cancelled: nothing was opened\n");
+			return;
+		}
+	}
+	const citizen = await openDurableCitizen({
+		...args,
+		...(session === undefined ? {} : { session }),
+		cwd,
+		extensions,
+		bridgeEntry,
+		open,
+		contact,
+	});
 	try {
 		await runDurableTui(
 			withGardenIdentity(citizen.durable.view, citizen.attachment.gardenId),

package/pi/pi-durable/carrier/harness-setup.js

@@ -28,13 +28,16 @@ export function createHarnessSettings(settingsManager                 )
 			const provider = settingsManager.getProviderRetrySettings();
 			const idle = settingsManager.getHttpIdleTimeoutMs();
 			return {
+				transport: settingsManager.getTransport(),
 				timeoutMs: provider.timeoutMs ?? (idle === 0 ? 2147483647 : idle),
 				maxRetryDelayMs: provider.maxRetryDelayMs,
 				...(provider.maxRetries === undefined ? {} : { maxRetries: provider.maxRetries }),
 			};
 		},
+		// The reference app waits for a compaction instead of summarizing beside the running turn (#143): no background
+		// compaction. Threshold, manual and overflow compaction stay the SDK's, on pi's own compaction settings.
 		get compaction() {
-			return settingsManager.getCompactionSettings();
+			return { ...settingsManager.getCompactionSettings(), backgroundTokens: 0 };
 		},
 		get retry() {
 			return settingsManager.getRetrySettings();

package/pi/pi-durable/carrier/prompt.js

@@ -1,5 +1,6 @@
+import { isAbsolute, join, resolve } from "node:path";
 import { defineExtension,                   section } from "@earendil-works/pi-durable";
-import { getAgentDir } from "entwurf-pi-dist:config.js";
+import { CONFIG_DIR_NAME, getAgentDir } from "entwurf-pi-dist:config.js";
 import { loadProjectContextFiles } from "entwurf-pi-dist:core/resource-loader.js";
                                                                       
 import { loadSkills,            } from "entwurf-pi-dist:core/skills.js";
@@ -19,6 +20,29 @@ const CONTRIBUTIONS = {
 /** pi's section order; `buildSystemPromptSections()` omits the ones without content. */
 const KEYS = ["preamble", "tools", "rules", "docs", "project_context", "skills", "cwd"]         ;
 
+/** An entry pi reads as a pattern, not a path: an override or a glob. */
+const PATTERN = /^[!+-]|[*?]/u;
+
+/**
+ * The `skills` setting with each scope's relative entries read against that scope's own directory, as pi resolves
+ * them: the project's against the session directory's `.pi`, the global ones against the agent directory, the
+ * project's first. Read against the conversation's directory, a relative entry names another place. Absolute, `~`
+ * and pattern entries go on unchanged.
+ */
+function scopedSkillPaths(settings                 , agentDir        , projectCwd        )           {
+	const against = (entries                               , base        )           =>
+		(entries ?? []).map((entry) => {
+			const path = entry.trim();
+			return path === "" || isAbsolute(path) || path === "~" || path.startsWith("~/") || PATTERN.test(path)
+				? entry
+				: resolve(base, path);
+		});
+	return [
+		...against(settings.getProjectSettings().skills, join(projectCwd, CONFIG_DIR_NAME)),
+		...against(settings.getGlobalSettings().skills, agentDir),
+	];
+}
+
 /**
  * pi's system prompt as one extension: the sections of `buildSystemPromptSections()` for the request's tools and the
  * conversation's directory. Context files and skills load once per directory, like pi at startup.
@@ -31,7 +55,12 @@ export function createPiPrompt(settings                 , fallbackCwd        ) {
 			const agentDir = getAgentDir();
 			found = {
 				contextFiles: loadProjectContextFiles({ cwd, agentDir }),
-				skills: loadSkills({ cwd, agentDir, skillPaths: settings.getSkillPaths(), includeDefaults: true }).skills,
+				skills: loadSkills({
+					cwd,
+					agentDir,
+					skillPaths: scopedSkillPaths(settings, agentDir, fallbackCwd),
+					includeDefaults: true,
+				}).skills,
 			};
 			resources.set(cwd, found);
 		}

package/pi/pi-durable/carrier/runtime.js

@@ -90,6 +90,8 @@ const context = BACKGROUND_CONTEXT;
                                      
 	                      
 	                                   
+	                                                                                         
+	                          
 	                                                                                                                 
 	                                           
 	                                                                                                           
@@ -143,10 +145,17 @@ function titleOf(entry                         )                     {
 }
 
 export async function openDurable(options                     = {})                             {
-	if (options.model !== undefined && options.continueSession) {
+	if (options.model !== undefined && (options.continueSession || options.session !== undefined)) {
 		throw new Error("An explicit model applies only to a new session, not to a continued one");
 	}
-	const location = await selectSession(options.cwd ?? process.cwd(), options.continueSession ?? false);
+	if (options.continueSession && options.session !== undefined) {
+		throw new Error("A chosen session and the newest one are two different sessions; name one");
+	}
+	const location = await selectSession(
+		options.cwd ?? process.cwd(),
+		options.continueSession ?? false,
+		options.session,
+	);
 	const envs = new ExecutionEnvs(location.cwd);
 	let harness                     ;
 	try {

package/pi/pi-durable/carrier/sessions.js

@@ -1,5 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
-import { mkdir, readdir, realpath } from "node:fs/promises";
+                                             
+import { mkdir, readdir, realpath, stat } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
 import lockfile from "proper-lockfile";
 import { getAgentDir } from "entwurf-pi-dist:config.js";
@@ -14,8 +15,31 @@ import { getAgentDir } from "entwurf-pi-dist:config.js";
 	                         
  
 
-/** A new session for `cwd`, or its newest one with `continueSession`. */
-export async function selectSession(cwdInput        , continueSession         )                           {
+/** One session of a directory as its files show it (#143): nothing in it is opened. */
+                               
+	           
+	                  
+	                                        
+	                  
+	                                                                                          
+	                     
+	                                                
+	                       
+ 
+
+const SESSION_NAME = /^\d{13}-[0-9a-f-]{36}$/u;
+
+/** A path's stat, or undefined when nothing is there; any other failure is thrown, never read as absence. */
+async function statIfPresent(path        )                             {
+	try {
+		return await stat(path);
+	} catch (error) {
+		if ((error                         ).code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+async function sessionRoot(cwdInput        )                                         {
 	const cwd = await realpath(resolve(cwdInput));
 	const root = join(
 		getAgentDir(),
@@ -23,14 +47,60 @@ export async function selectSession(cwdInput        , continueSession         )
 		"durable-sessions",
 		createHash("sha256").update(cwd).digest("hex").slice(0, 24),
 	);
+	return { cwd, root };
+}
+
+/** The sessions of `cwd`, most recently written first. Reads names, file times and locks; creates nothing. */
+export async function listSessions(cwdInput        )                          {
+	const { root } = await sessionRoot(cwdInput);
+	let entries          ;
+	try {
+		entries = await readdir(root, { withFileTypes: true });
+	} catch (error) {
+		if ((error                         ).code === "ENOENT") return [];
+		throw error;
+	}
+	const sessions                 = [];
+	for (const entry of entries) {
+		if (!entry.isDirectory() || !SESSION_NAME.test(entry.name)) continue;
+		const directory = join(root, entry.name);
+		let lastWriteAt                    ;
+		for (const file of ["session.sqlite", "session.sqlite-wal"]) {
+			const mtime = (await statIfPresent(join(directory, file)))?.mtimeMs;
+			if (mtime !== undefined && (lastWriteAt === undefined || mtime > lastWriteAt)) lastWriteAt = mtime;
+		}
+		sessions.push({
+			id: entry.name,
+			directory,
+			createdAt: Number(entry.name.slice(0, 13)),
+			...(lastWriteAt === undefined ? {} : { lastWriteAt }),
+			openElsewhere: await lockfile.check(directory, { realpath: false }),
+		});
+	}
+	return sessions.sort((a, b) => (b.lastWriteAt ?? b.createdAt) - (a.lastWriteAt ?? a.createdAt));
+}
+
+/** A new session for `cwd`, its newest one with `continueSession`, or the existing one named by `sessionId`. */
+export async function selectSession(
+	cwdInput        ,
+	continueSession         ,
+	sessionId         ,
+)                           {
+	const { cwd, root } = await sessionRoot(cwdInput);
 	await mkdir(root, { recursive: true });
 
 	let directory        ;
 	let created = false;
-	if (continueSession) {
+	if (sessionId !== undefined) {
+		const chosen = SESSION_NAME.test(sessionId) ? join(root, sessionId) : undefined;
+		if (chosen === undefined || !(await statIfPresent(chosen))?.isDirectory()) {
+			throw new Error(`No durable session ${sessionId} exists for ${cwd}`);
+		}
+		directory = chosen;
+	} else if (continueSession) {
 		const entries = await readdir(root, { withFileTypes: true });
 		const newest = entries
-			.filter((entry) => entry.isDirectory() && /^\d{13}-[0-9a-f-]{36}$/u.test(entry.name))
+			.filter((entry) => entry.isDirectory() && SESSION_NAME.test(entry.name))
 			.map((entry) => entry.name)
 			.sort()
 			.at(-1);

package/pi/pi-durable/carrier/tui.js

@@ -113,6 +113,29 @@ class ListSelector extends Container                      {
 	}
 }
 
+/**
+ * Choose one of the sessions `--resume` lists (#143) before any of them opens: the /agents list on a screen of its
+ * own, stopped before the session's TUI starts. Resolves the chosen value, or undefined when cancelled.
+ */
+export function pickDurableSession(title        , items              )                              {
+	initTheme();
+	const ui = new TuiAltScreen(new ProcessTerminal(), false, getAgentDir());
+	setKeybindings(KeybindingsManager.create());
+	return new Promise((resolve) => {
+		let done = false;
+		const finish = (value                    )       => {
+			if (done) return;
+			done = true;
+			ui.stop();
+			resolve(value);
+		};
+		const selector = new ListSelector(title, items, finish, () => finish(undefined));
+		ui.addChild(selector);
+		ui.setFocus(selector);
+		ui.start();
+	});
+}
+
 /** The summary that replaced earlier context: collapsed to one line until expanded. */
 class CompactionComponent extends Box {
 	         #summary        ;

package/pi/pi-durable/overlay/upstream-pin.json

@@ -70,32 +70,32 @@
 			{
 				"name": "runtime.js",
 				"source": "pi/pi-durable/src/experimental/durable/runtime.ts",
-				"blob": "36c352291620ab86184172a1b4a0df4562ab9581",
-				"sha256": "60c2965eadbdbbe78fce1b7eeb89d97eb3104a30b7d58ebca87009d2e9118403"
+				"blob": "75d7bf2b4fdc36aa775f73f9d7f3de8659f19187",
+				"sha256": "725757156580ad2a2d170c790440763371bb8035052a0c6caae6af5159d4718f"
 			},
 			{
 				"name": "tui.js",
 				"source": "pi/pi-durable/src/experimental/durable/tui.ts",
-				"blob": "dab99cd4778ae1db7f062e64db2d0c068f7e342d",
-				"sha256": "0f9ebaf8fbb2a532ccd1a7198e1a25533a99720b5fedbf03f42d5c381db3abc5"
+				"blob": "eb5e2ec4e98919cd3ff4f81f166eb52afe6555af",
+				"sha256": "a1b0d9d9358c5b54ac0974de84068b7792669171917ebd7b7351374ed625c9c5"
 			},
 			{
 				"name": "harness-setup.js",
 				"source": "pi/pi-durable/src/experimental/durable/harness-setup.ts",
-				"blob": "4d6a4be5333ebb8e0f17eac1987f18ea35a91fc7",
-				"sha256": "712b630145dc6f5c655a85b01b1e20299c962542e63c5494d2202bb7bf414a15"
+				"blob": "36a622ec6d5dccda828ffaceaf74ce8ec241e39d",
+				"sha256": "efb06ae25258fbbab5b28f8a9bbb50956c7ebfd77a5ed23b065706f662e70ba3"
 			},
 			{
 				"name": "prompt.js",
 				"source": "pi/pi-durable/src/experimental/durable/prompt.ts",
-				"blob": "8e2f5d5273fba58da8b314766956ed62951c3814",
-				"sha256": "ff1ff765fa313e5cb1c3d7537c901c23adb0562ee433bd050fd35eb3d892134c"
+				"blob": "0e99ff64214c44986c1c2259490e401898659fd5",
+				"sha256": "15870ea4c9cb465395d70189be4f1480c48544d724bd9fc3b0e6650f17226c0f"
 			},
 			{
 				"name": "sessions.js",
 				"source": "pi/pi-durable/src/experimental/durable/sessions.ts",
-				"blob": "34f9ceeeaeaf874f7478d56115da2e4f726c6a85",
-				"sha256": "1bd1a04ece66f5ab3ca22860c64dba9abc848334d11a27a9afe543f1365c7254"
+				"blob": "eed4b3ca51c6f5a3bab8106adaf0062f3f7d5b56",
+				"sha256": "668373feadabcf13bd4dd7431e5429b7d7376c47c367e4b15353c57cb8711892"
 			},
 			{
 				"name": "subagent.js",

package/pi-extensions/meta-bridge-pi-durable.ts

@@ -113,6 +113,7 @@ import {
 	defaultMetaReceiversDir,
 	defaultMetaSendersDir,
 	defaultMetaSessionsDir,
+	listAllMetaIdentitiesDir,
 	readAddressableMetaIdentity,
 	readMetaReceiverMarker,
 	readMetaSenderMarker,
@@ -125,6 +126,25 @@ import {
 /** The backend id this contact mints under. */
 export const PI_DURABLE_BACKEND = "pi-durable" as const;
 
+/**
+ * The garden ids the record store holds for these durable sessions (#143 `--resume`), read only: a session no record
+ * names is absent, and an unreadable record is counted, never guessed.
+ */
+export function piDurableGardenIds(
+	nativeSessionIds: readonly string[],
+	sessionsDir: string = defaultMetaSessionsDir(),
+): { gardens: Map<string, string>; unreadable: number } {
+	const wanted = new Set(nativeSessionIds);
+	const { identities, errors } = listAllMetaIdentitiesDir(sessionsDir);
+	const gardens = new Map<string, string>();
+	for (const identity of identities) {
+		if (identity.backend === PI_DURABLE_BACKEND && wanted.has(identity.nativeSessionId)) {
+			gardens.set(identity.nativeSessionId, identity.gardenId);
+		}
+	}
+	return { gardens, unreadable: errors.length };
+}
+
 /** The durable Extension's name, owned exactly. */
 export const PI_DURABLE_EXTENSION_NAME = "entwurf";
 

package/run.sh

@@ -273,7 +273,7 @@ Usage:
   ./run.sh uninstall-meta-bridge      # 1.0.0 meta-bridge Phase 2: stateful GLOBAL uninstall (restore only keys/items captured in install-state)
   ./run.sh doctor-meta-bridge         # THE RELEASE ORACLE (#51, Linux-certified repair axis). exit 0 = every required layer was MEASURED on this Linux host: toolchain + state + plugin/MCP + resolved-artifact launch-form classification (all 3 owner hooks + doorbell static contract) + synthetic owner join + store scan + hook errors + SessionStart evidence + REQUIRED live MCP↔marker join + writer-version parity. Missing live evidence is NOT CERTIFIED (open a Claude session and re-run), never a pass; Darwin is NOT CERTIFIED and stays nonzero, on ONE narrowed reason — start-key and ppid are portable there (`ps` fallback, same string the TS core mints), so what holds the lane closed is per-process environment DISCOVERY alone, pending physical-host evidence. Detection power is held by check-meta-doctor-oracle
   ./run.sh copilot [args...]          # #82 RAIL 7: the MANAGED Copilot launch. exec()s the vendor CLI in THIS terminal (cwd/pid/exit preserved) with COPILOT_CLI_ENABLED_FEATURE_FLAGS=EXTENSIONS set for that one invocation — entwurf owns no part of your shell and writes nothing to it, but it owns the process it is about to become. Without that flag Copilot skips the extension scan SILENTLY. Refuses to launch unless the receiver unit is actually installed. Injects `--model auto` when no --model was given and `--yolo` when no explicit permission/surface policy flag was given, both BEFORE any `--`; every argument you pass is forwarded byte-identical. RUNNING THIS IS YOUR CONSENT to that profile — use plain `copilot` for stock vendor behaviour. Not tmux, not fresh-call, mints no citizen (birth is still the first prompt)
-  ./run.sh pi-durable [args...]       # #129/#130: the MANAGED durable launch. Verifies this package's pi-durable CARRIER (pi/pi-durable/carrier/, emitted deterministically from Entwurf's owned source pi/pi-durable/src) and the pi SDK set it resolves — every declared member/direct edge at exactly the pinned version — refusing by name (package-incomplete / carrier-drift / sdk-absent / sdk-mismatch, exit 3), then exec()s node under the carrier resolver with the packaged bootstrap (pi/pi-durable/bootstrap.mjs) in this terminal. A new session needs --provider <p> --model <exact catalog id> --width task-wide [--entwurf-bootstrap <{v:2,task}>]; --continue takes none of them. Nothing outside the package is located, installed or repaired
+  ./run.sh pi-durable [args...]       # #129/#130: the MANAGED durable launch. Verifies this package's pi-durable CARRIER (pi/pi-durable/carrier/, emitted deterministically from Entwurf's owned source pi/pi-durable/src) and the pi SDK set it resolves — every declared member/direct edge at exactly the pinned version — refusing by name (package-incomplete / carrier-drift / sdk-absent / sdk-mismatch, exit 3), then exec()s node under the carrier resolver with the packaged bootstrap (pi/pi-durable/bootstrap.mjs) in this terminal. A new session needs --provider <p> --model <exact catalog id> --width task-wide [--entwurf-bootstrap <{v:2,task}>]; --continue (this directory's newest session) and --resume (choose one of its sessions) take none of them. Nothing outside the package is located, installed or repaired
   ./run.sh install-copilot-bridge     # #82: GLOBAL install of the Copilot BIRTH plugin (own marketplace root; node+entry baked into the no-argv exec string). MCP wiring and the RECEIVER extension are separate install surfaces (install-copilot-mcp, install-copilot-receive). Also retires the stale Claude unit (--keep-stale-claude-unit opts out)
   ./run.sh uninstall-copilot-bridge   # #86 C3a: honest inverse of install-copilot-bridge from the package-owned install-state (exact qualified id + exact marketplace name/path + recorded assembly only; state deleted LAST; a failing vendor list is UNKNOWN and refuses; never --force, never the stale Claude unit)
   ./run.sh doctor-copilot-bridge      # #82/#86: fail-loud surface for that unit — runtime axis (red = a hook that RAN and failed, or a broken/unbaked artifact; "installed with zero records" is NOT red and is reported as NOT-YET: a Copilot session is born on its FIRST PROMPT, not when the window opens, measured) + ownership axis (install-state shape/binding, marketplace path drift, UNKNOWN vendor lists; legacy no-state install = named non-green, repair = install-copilot-bridge adoption). Either axis red = red
@@ -1596,7 +1596,10 @@ check_mux_fresh_call() {
   # pi-durable-fresh-live-receipts rides here for tmux-coordinate-row's reason: it is the
   # deterministic half of a LIVE sibling (smoke-pi-durable-fresh-live, #129) — the oracles that judge
   # that gate's receipts, proven on inline rows, so no model turn and no durable host is needed.
-  run_vitest test/mux-fresh-call.test.ts test/fresh-call-composition.contract.test.ts test/copilot-fresh-preflight.test.ts test/codex-fresh-preflight.test.ts test/fresh-call-surfaces.contract.test.ts test/fresh-call-provider.contract.test.ts test/omp-fresh-bootstrap.contract.test.ts test/tmux-coordinate-row.test.ts test/codex-fresh-live-protocol.test.ts test/codex-caller-seat.test.ts test/pi-durable-fresh-live-receipts.test.ts
+  # codex-socket-listener rides here for the same reason (#128): it is the ownership precondition
+  # of smoke-codex-fresh-live, judged on synthetic wrapper/self shapes and observed on a throwaway
+  # wrapper → listener pair of its own, so no Codex, no app-server and no model turn is needed.
+  run_vitest test/mux-fresh-call.test.ts test/fresh-call-composition.contract.test.ts test/copilot-fresh-preflight.test.ts test/codex-fresh-preflight.test.ts test/fresh-call-surfaces.contract.test.ts test/fresh-call-provider.contract.test.ts test/omp-fresh-bootstrap.contract.test.ts test/tmux-coordinate-row.test.ts test/codex-fresh-live-protocol.test.ts test/codex-caller-seat.test.ts test/pi-durable-fresh-live-receipts.test.ts test/codex-socket-listener.test.ts
 }
 
 check_pi_durable_beside() {

package/scripts/check-acp-prompt-lifecycle.ts

@@ -39,6 +39,7 @@ import { pathToFileURL } from "node:url";
 import type { Api, AssistantMessageEvent, Message, Model, TranscriptContext } from "@earendil-works/pi-ai";
 import { normalizeContext } from "@earendil-works/pi-ai";
 import { isRetryableAssistantError } from "@earendil-works/pi-ai/compat";
+import { assertOverlayInSandbox, sandboxAcpGateHome } from "./lib/acp-gate-home.ts";
 
 const sonnet = { id: "claude-sonnet-5-5" } as unknown as Model<Api>;
 
@@ -196,8 +197,6 @@ function makeHarness(recordDir: string) {
 			await notifier?.({ sessionUpdate: "agent_message_chunk", content: { type: "text", text } });
 		},
 		deps: {
-			resolveLaunch: () => ({ command: "node", args: ["fake"] }),
-			ensureOverlay: () => {},
 			spawnChild: () => {
 				const c = makeFakeChild();
 				children.push(c);
@@ -279,6 +278,7 @@ function reuseCtx(prior: string, latest: string): TranscriptContext {
 const TMP_EMIT = ".tmp-verify/acp-prompt-lifecycle";
 rmSync(TMP_EMIT, { recursive: true, force: true });
 const recordDir = mkdtempSync(resolve(tmpdir(), "acp-prompt-life-"));
+const gateHome = sandboxAcpGateHome("acp-prompt-lifecycle-home-");
 
 try {
 	execFileSync("node_modules/.bin/tsc", ["--outDir", TMP_EMIT, "--rootDir", ".", "--noEmit", "false"], {
@@ -288,6 +288,7 @@ try {
 	mkdirSync(promptsOut, { recursive: true });
 	copyFileSync("pi-extensions/lib/acp/prompts/engraving.md", resolve(promptsOut, "engraving.md"));
 	const backend = (await import(pathToFileURL(resolve(TMP_EMIT, "pi-extensions/lib/acp/backend.js")).href)) as any;
+	await assertOverlayInSandbox(TMP_EMIT, gateHome);
 
 	// ----------------------------------------------------------------------
 	// CELL 1 — a long / quiet turn is NOT killed.
@@ -918,6 +919,7 @@ try {
 		// non-empty or already gone — fine either way
 	}
 	rmSync(recordDir, { recursive: true, force: true });
+	gateHome.restore();
 }
 
 console.log(

package/scripts/check-acp-session-reuse.ts

@@ -32,6 +32,7 @@ import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import type { Api, AssistantMessageEvent, Context, Message, Model, TranscriptContext } from "@earendil-works/pi-ai";
 import { normalizeContext } from "@earendil-works/pi-ai";
+import { assertOverlayInSandbox, sandboxAcpGateHome } from "./lib/acp-gate-home.ts";
 
 // The pi built-ins the Claude child also exposes natively. pi declares its tool
 // surface on every turn; since 0.86 that declaration reaches a provider as the
@@ -175,8 +176,6 @@ function makeHarness(recordDir: string, config: any = DEFAULT_RESOLVED_CONFIG, e
 	});
 
 	const deps = {
-		resolveLaunch: () => ({ command: "node", args: ["fake"] }),
-		ensureOverlay: () => {},
 		spawnChild: () => {
 			const c = makeFakeChild();
 			children.push(c);
@@ -268,6 +267,7 @@ function reuseCtx(prior: string, latest: string): TranscriptContext {
 const TMP_EMIT = ".tmp-verify/acp-session-reuse";
 rmSync(TMP_EMIT, { recursive: true, force: true });
 const recordDir = mkdtempSync(resolve(tmpdir(), "acp-reuse-rec-"));
+const gateHome = sandboxAcpGateHome("acp-session-reuse-home-");
 
 try {
 	execFileSync("node_modules/.bin/tsc", ["--outDir", TMP_EMIT, "--rootDir", ".", "--noEmit", "false"], {
@@ -283,6 +283,7 @@ try {
 	const backendUrl = pathToFileURL(resolve(TMP_EMIT, "pi-extensions/lib/acp/backend.js")).href;
 	const storeUrl = pathToFileURL(resolve(TMP_EMIT, "pi-extensions/lib/acp/session-store.js")).href;
 	const backend = (await import(backendUrl)) as any;
+	await assertOverlayInSandbox(TMP_EMIT, gateHome);
 	const store = (await import(storeUrl)) as any;
 	const configUrl = pathToFileURL(resolve(TMP_EMIT, "pi-extensions/lib/acp/config.js")).href;
 	const configMod = (await import(configUrl)) as any;
@@ -814,6 +815,7 @@ try {
 		// non-empty or already gone — fine either way
 	}
 	rmSync(recordDir, { recursive: true, force: true });
+	gateHome.restore();
 }
 
 console.log(