@junghanacs/entwurf 0.45.0 → 0.51.0

package/pi/pi-durable/bootstrap.mjs

@@ -14,7 +14,9 @@
 //   fails and closes itself retires that doorbell at once;
 // - a launcher's first input, when given, is admitted to the root ONCE, after that birth;
 // - the TUI is handed the native view with the garden id on every conversation label
-//   (`withGardenIdentity`).
+//   (`withGardenIdentity`);
+// - every open takes the owner fence (#157 B3) — built once here from the compiled closure — inside
+//   the session directory before its native lease; a refusal opens nothing.
 // Nothing of the native registry, controller or TUI is rebuilt here.
 //
 // The durable app itself is this package's CARRIER (./carrier/, emitted from Entwurf's owned source
@@ -27,6 +29,8 @@
 //        <entwurf>/pi/pi-durable/bootstrap.mjs \
 //        --provider <provider> --model <model id> --width task-wide [--entwurf-bootstrap <json>]
 //   ... bootstrap.mjs --continue
+//   ... bootstrap.mjs --resume
+//   ... bootstrap.mjs --session <native id>
 //
 // Explicit means the native API, not a vendor argv: upstream's durable main takes only
 // `--continue`, so `--provider`/`--model` reach pi's own `findInitialAgentModel` through the
@@ -45,9 +49,17 @@
 // address rides the process env only.
 // `--continue` opens the newest session for this directory as upstream does (not a chosen
 // record), so every flag that only a new session can honour is refused beside it by name.
+// `--session <native id>` (#157 G3 B-L1) reopens exactly that native session of this directory as it
+// was saved, through the owned runtime's `session` option, with no interactive session picker or
+// picker-specific TTY check; the normal TUI still runs. The id is the native session directory name, never a garden id: a native CLI selector, not an address. It is
+// held to the owned `isSessionName` grammar before operator-native module evaluation, TUI load, open
+// or birth; that scope is lexical (the selection stays under this cwd's session root by name), not
+// physical symlink confinement. A well-formed id this directory does not hold is the runtime's own
+// refusal, after the TUI module loads and before any TUI runs. `--continue`, `--resume` and
+// `--session` are mutually exclusive, and every new-session flag is refused beside each of them.
 //
-// `--native-module <absolute file>` (#130 P2) names ONE operator module, for a new or a continued
-// session. It is an ordinary ES module: its own top-level evaluation (top-level await included) is
+// `--native-module <absolute file>` (#130 P2) names ONE operator module, for a new, a continued, a
+// resumed or a named session. It is an ordinary ES module: its own top-level evaluation (top-level await included) is
 // its initialization, and its default export is a native durable Extension, handed to `openDurable`
 // by reference after the contact. Initialization runs before the TUI or the runtime is imported —
 // the runtime creates the provider runtime before it installs any extension (carrier/runtime.js
@@ -68,16 +80,28 @@
 // REPLACE the first extension or keep both tools. A refusal at module k leaves modules before it
 // evaluated: nothing is rolled back. No watch, no recursion, nothing persisted.
 //
+// `--entwurf-adopt <json>` (#157 B3 I-3) opens the one native session a parent reserved for this process. The
+// payload is closed: exactly `{v:1, gardenId, metaRoot, sourceGeneration}`, and any other key or value is refused. It
+// is exclusive with `--continue`, `--resume`, `--session` and every new-session flag. The garden record under
+// `metaRoot` is the address. Its native session id is the session, held to the same grammar as `--session`.
+// Before anything loads, the four `ENTWURF_META_*_DIR` values this process actually received must be `metaRoot`'s
+// standard children (the launch's fixed projection). The contact's roots are those four, whatever a seam passes.
+// The open takes the adoption fence of that context, which re-reads the record and its location inside its own
+// holds. The selection read here is never handed to the fence as evidence.
+//
 // Without that resolver the carrier's first pi-coding-agent internal import fails by name (an
 // unsupported entwurf-pi-dist: URL scheme), and that failure is the honest one.
 import { readdirSync, realpathSync, statSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { readAddressableMetaIdentity } from "../../mcp/entwurf-bridge/dist/pi-extensions/lib/meta-session.js";
+import { createPiDurableOwnerFence } from "../../mcp/entwurf-bridge/dist/pi-extensions/lib/pi-durable-owner-fence.js";
 import { decodeOmpBootstrapPayload } from "../../mcp/entwurf-bridge/dist/pi-extensions/meta-bridge-omp.js";
 import {
 	closeAll,
 	createPiDurableContact,
 	failAfterCleanup,
+	PI_DURABLE_BACKEND,
 	PI_DURABLE_EXTENSION_NAME,
 	PI_DURABLE_TOOL_NAMES,
 	piDurableGardenIds,
@@ -87,6 +111,14 @@ import {
 const RUNTIME = "./carrier/runtime.js";
 const TUI = "./carrier/tui.js";
 const SESSIONS = "./carrier/sessions.js";
+/** The session-name grammar alone: no imports and no I/O, so reading it loads nothing an operator module may prepare. */
+const SESSION_NAME = "./carrier/session-name.js";
+
+/**
+ * The owner fence every ordinary open of this process hands the runtime (#157 B3); an adoption hands its own (below).
+ * Building it reads and writes nothing.
+ */
+const OWNER_FENCE = createPiDurableOwnerFence();
 
 /** The entwurf-bridge of THIS package closure: the one the contact spawns as its MCP hand. */
 export const PACKAGED_BRIDGE_ENTRY = fileURLToPath(
@@ -102,9 +134,20 @@ const VALUE_FLAGS = [
 	"--entwurf-bootstrap",
 	"--native-module",
 	"--native-module-dir",
+	"--session",
+	"--entwurf-adopt",
 ];
 /** Flags only a NEW session can honour. */
 const FRESH_ONLY_FLAGS = ["--provider", "--model", "--width", "--entwurf-bootstrap"];
+/** The closed adopt context's keys, sorted: nothing else rides it (#157 B3 I-3). */
+const ADOPT_KEYS = ["gardenId", "metaRoot", "sourceGeneration", "v"];
+/** Each contact root of an adoption: the env name its launch carries it in, and its standard child of `metaRoot`. */
+const ADOPT_ROOTS = {
+	sessionsDir: ["ENTWURF_META_SESSIONS_DIR", "meta-sessions"],
+	mailboxDir: ["ENTWURF_META_MAILBOX_DIR", "meta-mailbox"],
+	sendersDir: ["ENTWURF_META_SENDERS_DIR", "meta-senders"],
+	receiversDir: ["ENTWURF_META_RECEIVERS_DIR", "meta-receivers"],
+};
 
 /**
  * Extension names the durable app installs itself — the contact, then the carrier's own
@@ -124,6 +167,68 @@ function refuse(reason, detail) {
 
 const nonEmpty = (value) => typeof value === "string" && value.trim().length > 0;
 
+const messageOf = (error) => (error instanceof Error ? error.message : String(error));
+
+/**
+ * `--entwurf-adopt`'s closed context, decoded before anything loads. The key set and `v` are this grammar's own.
+ * The garden id, the generation and the absolute root are the adoption fence's checks, run here by building the
+ * fence, which reads and writes nothing.
+ */
+function decodeAdoptContext(text) {
+	let value;
+	try {
+		value = JSON.parse(text);
+	} catch (error) {
+		throw Object.assign(refuse("adopt-context-invalid", "--entwurf-adopt is not JSON"), { cause: error });
+	}
+	if (
+		typeof value !== "object" ||
+		value === null ||
+		Array.isArray(value) ||
+		Object.keys(value).sort().join(",") !== ADOPT_KEYS.join(",")
+	) {
+		throw refuse("adopt-context-invalid", "--entwurf-adopt is exactly {v, gardenId, metaRoot, sourceGeneration}");
+	}
+	if (value.v !== 1) throw refuse("adopt-context-invalid", "--entwurf-adopt is version 1");
+	const { gardenId, metaRoot, sourceGeneration } = value;
+	let fence;
+	try {
+		fence = createPiDurableOwnerFence({ adoption: { gardenId, metaRoot, sourceGeneration } });
+	} catch (error) {
+		throw Object.assign(refuse("adopt-context-invalid", messageOf(error)), { cause: error });
+	}
+	return { gardenId, metaRoot, sourceGeneration, fence };
+}
+
+/** An adoption's contact roots: the standard children of its `metaRoot`, the shape the parent's reserve required. */
+function adoptRoots(metaRoot) {
+	return Object.fromEntries(Object.entries(ADOPT_ROOTS).map(([key, [, child]]) => [key, join(metaRoot, child)]));
+}
+
+/** The four meta roots this process actually received must be the context's; no ambient root stands in for them. */
+function requireAdoptRootEnv(metaRoot) {
+	const mismatched = Object.values(ADOPT_ROOTS)
+		.filter(([name, child]) => process.env[name] !== join(metaRoot, child))
+		.map(([name]) => name);
+	if (mismatched.length > 0) {
+		throw refuse("adopt-root-mismatch", `${mismatched.join(", ")} must be the standard children of ${metaRoot}`);
+	}
+}
+
+/** The native session the garden record names. The record is the address, read through the addressable reader. */
+function adoptedSession({ gardenId, metaRoot }) {
+	let record;
+	try {
+		record = readAddressableMetaIdentity(gardenId, join(metaRoot, ADOPT_ROOTS.sessionsDir[1]));
+	} catch (error) {
+		throw Object.assign(refuse("adopt-record-unaddressable", `${gardenId}: ${messageOf(error)}`), { cause: error });
+	}
+	if (record.backend !== PI_DURABLE_BACKEND) {
+		throw refuse("adopt-record-not-pi-durable", `${gardenId} is a ${record.backend} record`);
+	}
+	return record.nativeSessionId;
+}
+
 /** The identity carriers present now: names and values, compared in memory and never printed. */
 function identitySnapshot() {
 	return Object.fromEntries(
@@ -291,6 +396,8 @@ async function loadNativeModules(files) {
  * checkout-only gates, which drive a private bundle) passes another one — never the launch argv.
  * `extensions` are the operator's native extensions (`--native-module` or `--native-module-dir`),
  * installed after the contact, by reference.
+ * `adopt` is a decoded `--entwurf-adopt` context (#157 B3 I-3). Its fence admits the open, in place of the ordinary
+ * one, and its `metaRoot`'s four standard roots are the contact's, spread last so no seam replaces them.
  *
  * @param {{
  *   bridgeEntry?: string,
@@ -301,7 +408,8 @@ async function loadNativeModules(files) {
  *   firstInput?: string,
  *   extensions?: readonly object[],
  *   contact?: Record<string, unknown>,
- *   open?: (options: { cwd: string, continueSession: boolean, session?: string, extensions: readonly object[], model?: { provider: string, model: string } }) => Promise<any>,
+ *   adopt?: { gardenId: string, metaRoot: string, sourceGeneration: string, fence: object },
+ *   open?: (options: { cwd: string, continueSession: boolean, session?: string, extensions: readonly object[], model?: { provider: string, model: string }, fence: object }) => 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
@@ -316,6 +424,7 @@ export async function openDurableCitizen({
 	firstInput,
 	extensions = [],
 	contact: contactOptions = {},
+	adopt,
 	open,
 }) {
 	if (continueSession && (model !== undefined || firstInput !== undefined)) {
@@ -337,7 +446,12 @@ export async function openDurableCitizen({
 		throw refuse("first-input-empty", "a first input is a non-empty task");
 	}
 	const openDurable = open ?? (await import(RUNTIME)).openDurable;
-	const contact = createPiDurableContact({ ...contactOptions, bridgeEntry });
+	const fence = adopt === undefined ? OWNER_FENCE : adopt.fence;
+	const contact = createPiDurableContact({
+		...contactOptions,
+		bridgeEntry,
+		...(adopt === undefined ? {} : adoptRoots(adopt.metaRoot)),
+	});
 	let durable;
 	try {
 		durable = await openDurable({
@@ -346,6 +460,7 @@ export async function openDurableCitizen({
 			...(session === undefined ? {} : { session }),
 			extensions: [contact.extension, ...extensions],
 			...(model === undefined ? {} : { model }),
+			fence,
 		});
 	} catch (error) {
 		contact.fail(error);
@@ -426,7 +541,42 @@ function parseArgs(argv) {
 			"--resume chooses a session and --continue opens the newest one; give one of them",
 		);
 	}
+	const session = values.get("--session");
+	if (session !== undefined && continueSession) {
+		throw refuse(
+			"session-continue-exclusive",
+			"--session names the session to reopen and --continue opens the newest one; give one of them",
+		);
+	}
+	if (session !== undefined && resume) {
+		throw refuse(
+			"session-resume-exclusive",
+			"--session names the session to reopen and --resume chooses one from a list; give one of them",
+		);
+	}
 	const fresh = FRESH_ONLY_FLAGS.filter((flag) => values.has(flag));
+	const adoptArg = values.get("--entwurf-adopt");
+	if (adoptArg !== undefined) {
+		const others = [
+			...(continueSession ? ["--continue"] : []),
+			...(resume ? ["--resume"] : []),
+			...(session === undefined ? [] : ["--session"]),
+			...fresh,
+		];
+		if (others.length > 0) {
+			throw refuse(
+				"adopt-exclusive",
+				`${others.join(", ")} cannot be given with --entwurf-adopt: an adoption opens exactly the reserved session`,
+			);
+		}
+	}
+	const adopt = adoptArg === undefined ? undefined : decodeAdoptContext(adoptArg);
+	if (session !== undefined && fresh.length > 0) {
+		throw refuse(
+			"fresh-only-argument-with-session",
+			`${fresh.join(", ")} apply only to a new session; --session reopens the named session as it was saved`,
+		);
+	}
 	if (resume && fresh.length > 0) {
 		throw refuse(
 			"fresh-only-argument-with-resume",
@@ -455,6 +605,8 @@ function parseArgs(argv) {
 				: {};
 	if (continueSession) return { continueSession, ...nativeModule };
 	if (resume) return { resume, ...nativeModule };
+	if (session !== undefined) return { session, ...nativeModule };
+	if (adopt !== undefined) return { adopt, ...nativeModule };
 	const provider = values.get("--provider");
 	if (provider === undefined) {
 		throw refuse(
@@ -543,8 +695,29 @@ async function chooseSession(cwd, sessionsDir, pick) {
  * }} [seams]
  */
 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.
+	// Every argument refusal but the `--session` grammar is decided here, before any module, the TUI or
+	// the app loads.
 	const { nativeModules = [], resume = false, ...args } = parseArgs(argv);
+	// `--entwurf-adopt` (#157 B3 I-3): the roots this process received are checked against the context before
+	// anything else is read. The session is the one the garden record names, under the `--session` grammar below.
+	if (args.adopt !== undefined) {
+		requireAdoptRootEnv(args.adopt.metaRoot);
+		args.session = adoptedSession(args.adopt);
+	}
+	// `--session` is held to the owned session-name grammar the runtime selects by, before operator-native
+	// module evaluation, TUI load, open or birth. Only the import-free grammar file is read for it — never
+	// the session store, whose SDK config import fixes package state from the environment an operator
+	// module may still prepare. The shape is lexical — it names a directory under this cwd's session root
+	// by name only, which is not physical symlink confinement.
+	if (args.session !== undefined) {
+		const { isSessionName } = await import(SESSION_NAME);
+		if (!isSessionName(args.session)) {
+			throw refuse(
+				"session-id-malformed",
+				`${JSON.stringify(args.session)} is not a durable session id (<13-digit ms>-<uuid>)`,
+			);
+		}
+	}
 	// 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);