gentle-pi 4.3.0 → 4.5.0

package/tests/design-sources.test.ts

@@ -0,0 +1,132 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import test, { type TestContext } from "node:test";
+import { DESIGN_SOURCE_LIMITS, detectDesignSources, staleDesignSources } from "../lib/design-sources.ts";
+
+// S13: the design sources a project has, found by a bounded deterministic
+// walk, and the ones changed after design/system.md was written.
+
+function scratch(t: TestContext): string {
+	const dir = mkdtempSync(join(tmpdir(), "gentle-design-sources-"));
+	t.after(() => rmSync(dir, { recursive: true, force: true }));
+	return dir;
+}
+
+function write(root: string, path: string, content = ""): void {
+	mkdirSync(dirname(join(root, path)), { recursive: true });
+	writeFileSync(join(root, path), content);
+}
+
+test("each design source kind is detected, sorted, and plain files are not", (t) => {
+	const cwd = scratch(t);
+	write(cwd, "tailwind.config.ts", "export default {}");
+	write(cwd, "web/tailwind.config.cjs", "module.exports = {}");
+	write(cwd, "src/styles/globals.css", ":root {\n  --brand: #0a84ff;\n}\n");
+	write(cwd, "src/styles/dark.scss", "[data-theme='dark'] { --surface: #111; }");
+	write(cwd, "src/app.pcss", "@import 'tailwindcss';\n@theme {\n  --color-ink: oklch(20% 0 0);\n}\n");
+	write(cwd, "src/theme-entry.css", "@theme inline;");
+	write(cwd, "src/design-tokens.json", "{}");
+	write(cwd, "src/tokens/Tokens.ts", "export const x = 1;");
+	write(cwd, "src/theme.ts", "export const theme = { colors: { primary: '#000' } };");
+	write(cwd, "src/plain.css", ".btn { color: red; background: var(--brand); }");
+	write(cwd, "src/commented.css", "/* :root { --x: 1px; } */\n.a { margin: 0; }");
+	write(cwd, "src/nested.css", ".card { --pad: 4px; }");
+	write(cwd, "src/theme.js", "export const spacing = { sm: 4 };");
+	write(cwd, "src/tokens.md", "# tokens");
+	write(cwd, "tailwind.config.json", "{}");
+	assert.deepEqual(detectDesignSources(cwd), [
+		"src/app.pcss",
+		"src/design-tokens.json",
+		"src/styles/dark.scss",
+		"src/styles/globals.css",
+		"src/theme-entry.css",
+		"src/theme.ts",
+		"src/tokens/Tokens.ts",
+		"tailwind.config.ts",
+		"web/tailwind.config.cjs",
+	]);
+});
+
+test("token files count only when named as design tokens, never auth or tokenizer files", (t) => {
+	const cwd = scratch(t);
+	write(cwd, "src/theme.tokens.css", ".a { margin: 0; }");
+	write(cwd, "src/tokens_v2.js", "export {};");
+	for (const path of ["src/auth/token.ts", "src/auth/refreshToken.ts", "src/csrf-token.js", "src/tokenizer.ts", "src/jwt-token.test.ts", "src/tokens.test.ts", "src/design-tokens.spec.js"]) write(cwd, path, "export {};");
+	assert.deepEqual(detectDesignSources(cwd), ["src/theme.tokens.css", "src/tokens_v2.js"]);
+});
+
+test("a project without design sources, or a missing cwd, has none", (t) => {
+	const cwd = scratch(t);
+	write(cwd, "src/index.ts", "export {};");
+	write(cwd, "src/plain.css", "body { margin: 0; }");
+	assert.deepEqual(detectDesignSources(cwd), []);
+	assert.deepEqual(detectDesignSources(join(cwd, "missing")), []);
+});
+
+test("the walk skips dependency, build, VCS, design and dot directories", (t) => {
+	const cwd = scratch(t);
+	const css = ":root { --x: 1px; }";
+	for (const dir of ["node_modules/pkg", ".git", "dist", "build", "out", "coverage", ".next", ".worktrees/other", "design", ".cache", "src/.hidden"]) {
+		write(cwd, `${dir}/tokens.json`, "{}");
+		write(cwd, `${dir}/vars.css`, css);
+	}
+	write(cwd, "packages/ui/design/tokens.json", "{}");
+	assert.deepEqual(detectDesignSources(cwd), ["packages/ui/design/tokens.json"], "only the root design/ is the design output");
+});
+
+test("symlinks are not followed, to files or directories", (t) => {
+	const cwd = scratch(t);
+	const outside = scratch(t);
+	write(outside, "shared/tokens.json", "{}");
+	write(outside, "vars.css", ":root { --x: 1px; }");
+	write(cwd, "src/index.ts", "");
+	symlinkSync(join(outside, "shared"), join(cwd, "src", "shared"));
+	symlinkSync(join(outside, "vars.css"), join(cwd, "src", "vars.css"));
+	symlinkSync(join(outside, "shared", "tokens.json"), join(cwd, "tokens.json"));
+	assert.deepEqual(detectDesignSources(cwd), []);
+});
+
+test("the depth cap holds: six directory levels are walked, the seventh is not", (t) => {
+	const cwd = scratch(t);
+	assert.equal(DESIGN_SOURCE_LIMITS.maxDepth, 6);
+	write(cwd, "a/b/c/d/e/f/tokens.json", "{}");
+	write(cwd, "a/b/c/d/e/f/g/tokens.json", "{}");
+	assert.deepEqual(detectDesignSources(cwd), ["a/b/c/d/e/f/tokens.json"]);
+});
+
+test("the file cap holds: the walk stops after 5000 files in name order", (t) => {
+	const cwd = scratch(t);
+	assert.equal(DESIGN_SOURCE_LIMITS.maxFiles, 5000);
+	for (let index = 0; index < 4999; index++) write(cwd, `a${String(index).padStart(4, "0")}.txt`);
+	write(cwd, "z-tokens.json", "{}");
+	assert.deepEqual(detectDesignSources(cwd), ["z-tokens.json"], "the 5000th file is still read");
+	write(cwd, "a4999.txt");
+	assert.deepEqual(detectDesignSources(cwd), [], "the 5001st file is not");
+});
+
+test("only the first 256 KiB of a stylesheet is read", (t) => {
+	const cwd = scratch(t);
+	assert.equal(DESIGN_SOURCE_LIMITS.maxBytes, 256 * 1024);
+	const filler = `/*${"x".repeat(256 * 1024)}*/\n`;
+	write(cwd, "late.css", `.a{}\n${filler}:root { --x: 1px; }`);
+	write(cwd, "early.css", `:root { --x: 1px; }\n${filler}`);
+	assert.deepEqual(detectDesignSources(cwd), ["early.css"]);
+});
+
+test("stale sources are the ones modified after design/system.md", (t) => {
+	const cwd = scratch(t);
+	write(cwd, "tailwind.config.js", "module.exports = {}");
+	write(cwd, "src/tokens.json", "{}");
+	const sources = detectDesignSources(cwd);
+	assert.deepEqual(staleDesignSources(cwd, sources), [], "no design/system.md, nothing is stale");
+	write(cwd, "design/system.md", "# Tokens");
+	utimesSync(join(cwd, "design", "system.md"), 2000, 2000);
+	utimesSync(join(cwd, "tailwind.config.js"), 1000, 1000);
+	utimesSync(join(cwd, "src", "tokens.json"), 3000, 3000);
+	assert.deepEqual(staleDesignSources(cwd, sources), ["src/tokens.json"]);
+	utimesSync(join(cwd, "src", "tokens.json"), 2000, 2000);
+	assert.deepEqual(staleDesignSources(cwd, sources), [], "an equal mtime is not newer");
+	assert.deepEqual(staleDesignSources(cwd, [...sources, "gone.css"]), [], "a source that vanished is skipped");
+});

package/tests/engram-safety.test.ts

@@ -16,7 +16,7 @@ const OTHER_ID = "fedcba9876543210fedcba9876543210";
 const READY = { revision: 1, source: "active", status: "ready", offline_automatic_opening_authorized: false, active_reuse_authorized: true,
 	instance_id: ID, runtime_id: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", capability: "startup-verified-store-v1" };
 const REFUSED: shell.EngramProbe = { kind: "refused" };
-const CORE = "3.4.0";
+const CORE = "3.5.2";
 const listening = (compatible: boolean, healthInstanceId?: string, healthVersion = CORE): shell.EngramProbe =>
 	({ kind: "listening", compatible, healthInstanceId, healthVersion: healthInstanceId === undefined ? undefined : healthVersion });
 
@@ -28,59 +28,152 @@ const clean = (extra: Record<string, string> = {}) => {
 	return env;
 };
 const classify = (input: Partial<Parameters<typeof shell.classifyEngramStartup>[0]> = {}) =>
-	shell.classifyEngramStartup({ env: {}, store: "absent", endpoint: REFUSED, core: true, coreVersion: CORE, ...input });
+	shell.classifyEngramStartup({ env: {}, endpoint: REFUSED, core: true, coreVersion: CORE, ...input });
 
-test("fresh state with a verified bundled core allows memory and marks the run as provisioning", () => {
-	assert.deepEqual(classify(), { policy: "allow", fresh: true });
+test("shared Engram environment drops only session scratch temp paths", () => {
+	for (const platform of ["win32", "linux"]) {
+		for (const prefix of ["gp", "ga"]) {
+			const scratch = platform === "win32" ? `C:\\Temp\\${prefix}Ab12Z9\\` : `/tmp/${prefix}Ab12Z9/`;
+			const base = { TEMP: scratch, TMP: scratch, TMPDIR: scratch, PATH: "keep", OTHER: scratch };
+			assert.deepEqual(shell.sharedEngramEnv(base, platform), { ...(platform === "win32" ? { TEMP: "C:\\Temp", TMP: "C:\\Temp", TMPDIR: "C:\\Temp" } : {}), PATH: "keep", OTHER: scratch, ENGRAM_NO_UPDATE_CHECK: "1" });
+			assert.equal(base.TEMP, scratch, "does not mutate parent");
+		}
+		for (const chosen of ["/tmp/custom", "/tmp/gp12345", "/tmp/ga1234567", "/tmp/gp123456/child", "/tmp/gp12-456"]) {
+			assert.equal(shell.sharedEngramEnv({ TEMP: chosen }, platform).TEMP, chosen);
+		}
+	}
+	assert.deepEqual(shell.sharedEngramEnv({ Temp: "C:\\Temp\\gp123456\\gaAb12Z9\\", tMp: "D:/custom", tmpdir: "C:/chosen" }, "win32"),
+		{ Temp: "C:\\Temp", tMp: "D:/custom", tmpdir: "C:/chosen", ENGRAM_NO_UPDATE_CHECK: "1" });
+	for (const key of ["TMP", "TMPDIR"]) {
+		assert.deepEqual(shell.sharedEngramEnv({ [key]: "C:\\Temp\\gp123456" }, "win32"),
+			{ [key]: "C:\\Temp", TEMP: "C:\\Temp", ENGRAM_NO_UPDATE_CHECK: "1" });
+		assert.equal(shell.sharedEngramEnv({ [key]: "C:\\Temp\\gp123456", Temp: "D:\\chosen" }, "win32").Temp, "D:\\chosen");
+	}
+	for (const invalid of ["gp123456", "relative\\ga123456", "C:gp123456", "\\gp123456"]) {
+		assert.throws(() => shell.sharedEngramEnv({ TEMP: invalid }, "win32"), /absolute.*scratch/i);
+	}
+	assert.equal(shell.sharedEngramEnv({ tmp: "/tmp/gp123456" }, "linux").tmp, "/tmp/gp123456");
+});
+
+test("shared Engram environment detects Windows scratch after a trailing dot", () => {
+	assert.equal(shell.sharedEngramEnv({ TEMP: "C:\\Temp\\gp123456\\." }, "win32").TEMP, "C:\\Temp");
+});
+
+test("shared Engram environment detects POSIX scratch after child/..", () => {
+	assert.deepEqual(shell.sharedEngramEnv({ TMPDIR: "/tmp/gp123456/child/.." }, "linux"), { ENGRAM_NO_UPDATE_CHECK: "1" });
 });
 
-test("a fresh state without the verified bundled core is disabled, never a PATH fallback", () => {
+test("shared Engram environment refuses original Windows .. even when normalization hides it", () => {
+	assert.throws(() => shell.sharedEngramEnv({ TEMP: "C:\\Temp\\gp123456\\child\\.." }, "win32"), /absolute.*scratch/i);
+});
+
+test("shared Engram environment refuses scratch-shaped UNC share roots without looping", () => {
+	const script = `import assert from 'node:assert/strict';
+		import { sharedEngramEnv } from './lib/gentle-shell-bundled.ts';
+		assert.throws(() => sharedEngramEnv({ TEMP: ${JSON.stringify("\\\\server\\gp123456\\")} }, 'win32'), /absolute.*scratch/i);`;
+	const result = spawnSync(process.execPath, ["--disable-warning=ExperimentalWarning", "--experimental-strip-types", "--input-type=module", "-e", script], { cwd: repository, encoding: "utf8", timeout: 3000 });
+	assert.equal(result.error, undefined);
+	assert.equal(result.status, 0);
+	assert.equal(result.stdout, "");
+	assert.equal(result.stderr, "");
+	assert.equal(shell.sharedEngramEnv({ TEMP: "\\\\server\\share\\gp123456\\gaAb12Z9\\" }, "win32").TEMP, "\\\\server\\share\\");
+	assert.equal(shell.sharedEngramEnv({ TEMP: "C:\\gp123456\\" }, "win32").TEMP, "C:\\");
+});
+
+test("shared Engram environment reaches an actual Windows Node child with explicit stable TEMP", { skip: process.platform !== "win32" }, () => {
+	const stable = "C:\\chosen-temp";
+	const scratch = `${stable}\\gp123456\\gaAb12Z9`;
+	const probe = `const os = require('node:os'); process.stdout.write(JSON.stringify({TEMP: process.env.TEMP, TMP: process.env.TMP, TMPDIR: process.env.TMPDIR, tmpdir: os.tmpdir()}));`;
+	// Set known ambient scratch only inside an isolated parent process. No files
+	// are created: neither chosen path needs to exist for this zero-write probe.
+	const script = `import { sharedEngramEnv } from './lib/gentle-shell-bundled.ts';
+		import { spawnSync } from 'node:child_process';
+		process.env.TEMP = ${JSON.stringify(scratch)};
+		const env = sharedEngramEnv({ TMPDIR: ${JSON.stringify(scratch)} });
+		const child = spawnSync(process.execPath, ['-e', ${JSON.stringify(probe)}], {env, encoding: 'utf8'});
+		process.stdout.write(child.stdout); process.stderr.write(child.stderr); process.exit(child.status ?? 99);`;
+	const result = spawnSync(process.execPath, ["--disable-warning=ExperimentalWarning", "--experimental-strip-types", "--input-type=module", "-e", script], { cwd: repository, encoding: "utf8", timeout: 10000 });
+	assert.equal(result.error, undefined);
+	assert.equal(result.status, 0);
+	assert.equal(result.stderr, "");
+	assert.equal(result.stdout, JSON.stringify({ TEMP: stable, TMPDIR: stable, tmpdir: stable }));
+});
+
+test("shared Engram environment retains sanitization and detached spawn wiring", () => {
+	assert.deepEqual(shell.sharedEngramEnv({ ENGRAM_BIN: "chosen", ENGRAM_OTHER: "value", ENGRAM_NO_UPDATE_CHECK: "0", GH_TOKEN: "token", GITHUB_TOKEN: "token", HOME: "home", TEMP: "chosen" }),
+		{ HOME: "home", TEMP: "chosen", ENGRAM_NO_UPDATE_CHECK: "1" });
+	const launcher = readFileSync(join(repository, "bin", "gentle-shell.mjs"), "utf8");
+	assert.match(launcher, /const env = sharedEngramEnv\(process\.env\);/);
+	assert.match(launcher, /spawn\(core, \["serve"\], \{ cwd: homedir\(\), env, detached: true, stdio: "ignore", windowsHide: true \}\)/);
+});
+
+test("nothing listening with a verified bundled core starts the shared server and reuses it through the default URL", () => {
+	assert.deepEqual(classify(), { policy: "allow", url: "http://127.0.0.1:7437", spawn: true });
+});
+
+test("nothing listening without the verified bundled core is disabled, never a PATH fallback", () => {
 	const result = classify({ core: false });
 	assert.equal(result.policy, "disabled");
+	assert.equal(result.spawn, undefined);
 	assert.match(result.notice!, /bundled Engram core/);
 });
 
-test("existing, unreadable or foreign stores without matching provenance are disabled", () => {
-	for (const store of ["present", "unknown"] as const) {
-		const result = classify({ store });
-		assert.equal(result.policy, "disabled", store);
+test("an existing store no longer disables memory by itself; only a newer schema header keeps the server stopped", () => {
+	for (const userVersion of [undefined, 0, 1]) {
+		assert.deepEqual(classify({ userVersion }), { policy: "allow", url: "http://127.0.0.1:7437", spawn: true }, String(userVersion));
+	}
+	const newer = classify({ userVersion: 2 });
+	assert.deepEqual([newer.policy, newer.spawn, newer.url], ["disabled", undefined, undefined]);
+	assert.equal(newer.notice, shell.ENGRAM_NEWER_SCHEMA_NOTICE);
+	assert.match(newer.notice!, /newer Engram.*Back up/s);
+	// A pin without a verified schema cannot rule out a newer store: never started.
+	assert.equal(classify({ coreVersion: "9.9.9", userVersion: 1 }).policy, "disabled");
+	assert.equal(classify({ coreVersion: "9.9.9" }).spawn, true);
+});
+
+test("a listener that does not verify keeps memory disabled and is never replaced", () => {
+	for (const endpoint of [listening(false), listening(false, ID), { kind: "unknown" } as shell.EngramProbe]) {
+		const result = classify({ endpoint });
+		assert.deepEqual([result.policy, result.spawn, result.url], ["disabled", undefined, undefined], JSON.stringify(endpoint));
 		assert.match(result.notice!, /could not verify.*compatibility.*Back up/is);
-		assert.doesNotMatch(result.notice!, /update Engram and restart/i);
 	}
-	assert.equal(classify({ store: "present", endpoint: listening(false, ID) }).policy, "disabled");
+	// Not even the bundled core version on /health stands in for /compatibility.
+	assert.equal(classify({ endpoint: listening(false, ID, CORE) }).policy, "disabled");
 });
 
 test("a running server older than the first compatibility-capable core is named in the notice, without changing the decision", () => {
 	for (const version of ["3.3.2", "v3.3.2", "2.9.0"]) {
-		const result = classify({ store: "present", endpoint: listening(false, OTHER_ID, version) });
+		const result = classify({ endpoint: listening(false, OTHER_ID, version) });
 		assert.equal(result.policy, "disabled", version);
 		assert.equal(result.url, undefined, version);
 		assert.match(result.notice!, new RegExp(`reports version ${version.replace(/^v/, "").replaceAll(".", "\\.")}`), version);
 		assert.match(result.notice!, /update that server to 3\.4\.0 or later.*restart it/s, version);
 		assert.match(result.notice!, /Back up/, version);
 	}
-	// Shell's own store behind an older server gets the same guidance and stays disabled.
-	const own = classify({ store: "present", provenance: { instanceId: ID }, endpoint: listening(false, ID, "3.3.2") });
-	assert.equal(own.policy, "disabled");
-	assert.match(own.notice!, /reports version 3\.3\.2/);
 });
 
 test("a current, unparsable or hostile server version keeps the generic notice and is never echoed", () => {
 	for (const version of ["3.4.0", "3.10.0", "4.0.0", "dev", "", "3.3.2\u001b[31m", "3.3.2 update now", "03.3.2", "3.03.2", "3.3.02", "v03.3.2"]) {
-		const result = classify({ store: "present", endpoint: listening(false, OTHER_ID, version) });
+		const result = classify({ endpoint: listening(false, OTHER_ID, version) });
 		assert.equal(result.policy, "disabled", JSON.stringify(version));
 		assert.equal(result.notice, shell.ENGRAM_RECOVERY_NOTICE, JSON.stringify(version));
 	}
-	assert.equal(classify({ store: "present", endpoint: listening(false) }).notice, shell.ENGRAM_RECOVERY_NOTICE);
+	assert.equal(classify({ endpoint: listening(false) }).notice, shell.ENGRAM_RECOVERY_NOTICE);
 });
 
 test("explicit selections and invalid policies are disabled without depending on probes", () => {
-	for (const key of ["ENGRAM_BIN", "ENGRAM_URL", "ENGRAM_DATA_DIR", "ENGRAM_PORT", "ENGRAM_DATABASE_URL"]) {
-		assert.equal(classify({ env: { [key]: "chosen" }, endpoint: listening(true) }).policy, "disabled", key);
+	for (const key of ["ENGRAM_BIN", "ENGRAM_URL", "ENGRAM_DATA_DIR", "ENGRAM_PORT", "ENGRAM_SOCKET", "ENGRAM_DATABASE_URL", "ENGRAM_SERVER_MODE"]) {
+		for (const endpoint of [listening(true), REFUSED]) {
+			const result = classify({ env: { [key]: "chosen" }, endpoint });
+			assert.deepEqual([result.policy, result.spawn], ["disabled", undefined], key);
+		}
 	}
-	assert.equal(classify({ env: { ENGRAM_STARTUP_POLICY: "allow" } }).policy, "allow");
+	assert.equal(classify({ env: { ENGRAM_STARTUP_POLICY: "allow" } }).spawn, true);
 	for (const value of ["", "disabled", "ALLOW", " allow ", "invalid"]) {
-		assert.equal(classify({ env: { ENGRAM_STARTUP_POLICY: value }, endpoint: listening(true) }).policy, "disabled", value);
+		for (const endpoint of [listening(true), REFUSED]) {
+			const result = classify({ env: { ENGRAM_STARTUP_POLICY: value }, endpoint });
+			assert.deepEqual([result.policy, result.spawn], ["disabled", undefined], value);
+		}
 	}
 	assert.equal(shell.engramProbeAllowed({ ENGRAM_URL: "https://chosen.invalid" }), false);
 	assert.equal(shell.engramProbeAllowed({ ENGRAM_STARTUP_POLICY: "" }), false);
@@ -88,25 +181,12 @@ test("explicit selections and invalid policies are disabled without depending on
 });
 
 test("a verified /compatibility contract reuses the running server through an explicit URL", () => {
-	assert.deepEqual(classify({ store: "present", endpoint: listening(true) }), { policy: "allow", url: "http://127.0.0.1:7437" });
-	for (const endpoint of [listening(false), { kind: "unknown" } as shell.EngramProbe]) {
-		assert.equal(classify({ store: "present", endpoint }).policy, "disabled");
+	// Reused unchanged, whatever the store header or the bundled core.
+	for (const input of [{}, { userVersion: 2 }, { core: false }]) {
+		assert.deepEqual(classify({ ...input, endpoint: listening(true) }), { policy: "allow", url: "http://127.0.0.1:7437" }, JSON.stringify(input));
 	}
 });
 
-test("Shell provenance allows its own store only for the same instance and the same core binary", () => {
-	const provenance = { instanceId: ID };
-	assert.deepEqual(classify({ store: "present", provenance }), { policy: "allow" });
-	assert.deepEqual(classify({ store: "present", provenance, endpoint: listening(false, ID) }), { policy: "allow", url: "http://127.0.0.1:7437" });
-	assert.equal(classify({ store: "present", provenance, endpoint: listening(false, OTHER_ID) }).policy, "disabled");
-	for (const version of ["3.3.3", "v3.4.0", "dev", ""]) {
-		assert.equal(classify({ store: "present", provenance, endpoint: listening(false, ID, version) }).policy, "disabled", version);
-	}
-	assert.equal(classify({ store: "present", provenance, endpoint: listening(false) }).policy, "disabled");
-	assert.equal(classify({ store: "present", provenance, endpoint: { kind: "unknown" } }).policy, "disabled");
-	assert.equal(classify({ store: "present", provenance, core: false }).policy, "disabled");
-});
-
 test("the compatibility contract must match exactly", () => {
 	assert.equal(shell.isReadyCompatibility(JSON.stringify(READY)), true);
 	assert.equal(shell.isReadyCompatibility(JSON.stringify({ ...READY, offline_automatic_opening_authorized: undefined })), true);
@@ -161,20 +241,11 @@ test("the SQLite header user_version is read from raw bytes and malformed header
 	}
 });
 
-test("provenance matches only the same directory, instance and core digest", () => {
-	const record = { schema: 1 as const, dataDir: "/home/ana/.engram", instanceId: ID, coreSha256: "a".repeat(64) };
-	const observed = { dataDir: record.dataDir, instanceId: ID, coreSha256: record.coreSha256 };
-	assert.equal(shell.engramProvenanceMatches(record, observed), true);
-	for (const change of [{ dataDir: "/elsewhere/.engram" }, { instanceId: OTHER_ID }, { coreSha256: "b".repeat(64) }, { instanceId: undefined }, { coreSha256: undefined }]) {
-		assert.equal(shell.engramProvenanceMatches(record, { ...observed, ...change }), false, JSON.stringify(change));
-	}
-	assert.equal(shell.engramProvenanceMatches(undefined, observed), false);
-});
-
 test("the header is a newer-schema tripwire against the verified bundled schema, never a compatibility proof", () => {
 	// v3.3.2:internal/store/store.go declares schemaVersion = 1.
 	assert.equal(shell.bundledEngramSchema("3.3.2"), 1);
 	assert.equal(shell.bundledEngramSchema("3.4.0"), 1);
+	assert.equal(shell.bundledEngramSchema("3.5.2"), 1);
 	assert.equal(shell.bundledEngramSchema("3.3.3"), undefined);
 	for (const userVersion of [0, 1]) assert.equal(shell.engramHeaderAllows(userVersion, 1), true, String(userVersion));
 	assert.equal(shell.engramHeaderAllows(2, 1), false);
@@ -241,10 +312,10 @@ test("probe reports refused for a closed port and unknown for a silent listener"
 	assert.ok(Date.now() - started < 2000);
 });
 
-const base = { node: "/node", cli: "/pi", prefix: "/prefix", engram: "/prefix/runtime/engram-3.4.0/engram", guard: GUARD };
+const base = { node: "/node", cli: "/pi", prefix: "/prefix", engram: "/prefix/runtime/engram-3.5.2/engram", guard: GUARD };
 
 test("disabled memory without explicit selections points ENGRAM_BIN at the guard and keeps the policy", () => {
-	const memory = classify({ store: "present" });
+	const memory = classify({ endpoint: listening(false) });
 	const env = shell.bundledChildEnv({ ENGRAM_STARTUP_NOTICE: "display only" }, { ...base, memory });
 	assert.equal(env.ENGRAM_BIN, GUARD);
 	assert.equal(env.ENGRAM_URL, undefined);
@@ -254,7 +325,7 @@ test("disabled memory without explicit selections points ENGRAM_BIN at the guard
 });
 
 test("explicit ENGRAM_BIN or ENGRAM_URL are never replaced or removed", () => {
-	const memory = classify({ store: "present" });
+	const memory = classify({ endpoint: listening(false) });
 	for (const selected of [{ ENGRAM_BIN: "/explicit" }, { ENGRAM_URL: "https://chosen.invalid" }, { ENGRAM_BIN: "/explicit", ENGRAM_URL: "https://chosen.invalid" }]) {
 		const before = { ...selected };
 		const env = shell.bundledChildEnv(selected, { ...base, memory });
@@ -267,11 +338,15 @@ test("explicit ENGRAM_BIN or ENGRAM_URL are never replaced or removed", () => {
 	assert.equal(shell.bundledChildEnv({ ENGRAM_URL: "https://chosen.invalid" }, { ...base, engram: undefined, memory }).ENGRAM_BIN, GUARD);
 });
 
-test("allowed modes select the core, the guard plus a reuse URL, or the guard when the core is missing", () => {
-	assert.equal(shell.bundledChildEnv({}, { ...base, memory: classify() }).ENGRAM_BIN, base.engram);
-	assert.equal(shell.bundledChildEnv({}, { ...base, memory: classify({ store: "present", provenance: { instanceId: ID } }) }).ENGRAM_BIN, base.engram);
-	const reuse = shell.bundledChildEnv({}, { ...base, memory: classify({ store: "present", endpoint: listening(true) }) });
-	assert.deepEqual([reuse.ENGRAM_URL, reuse.ENGRAM_BIN, reuse.ENGRAM_STARTUP_POLICY], ["http://127.0.0.1:7437", GUARD, "allow"]);
+test("allowed memory always reaches the shared server through the reuse URL and the guard, never a session-owned server", () => {
+	for (const memory of [classify(), classify({ endpoint: listening(true) })]) {
+		const env = shell.bundledChildEnv({}, { ...base, memory });
+		assert.deepEqual([env.ENGRAM_URL, env.ENGRAM_BIN, env.ENGRAM_STARTUP_POLICY, env.ENGRAM_SERVER_MODE], ["http://127.0.0.1:7437", GUARD, "allow", undefined]);
+		// The user's own server mode, if any, is passed through untouched.
+		assert.equal(shell.bundledChildEnv({ ENGRAM_SERVER_MODE: "shared" }, { ...base, memory }).ENGRAM_SERVER_MODE, "shared");
+	}
+	assert.equal("ENGRAM_PRIVATE_REQUIRED_NOTICE" in shell, false);
+	assert.equal("supportsEngramSessionOwned" in shell, false);
 	const missing = shell.bundledChildEnv({}, { ...base, engram: undefined, memory: classify({ core: false }) });
 	assert.equal(missing.ENGRAM_BIN, GUARD);
 	assert.throws(() => shell.bundledChildEnv({}, { ...base, guard: undefined, memory: classify() }), /guard/);
@@ -309,7 +384,7 @@ test("the guard fails non-zero, reports the notice and leaves Engram data byte-i
 });
 
 test("a provider-style instance-id spawn against the environment Shell builds fails closed", { skip: process.platform === "win32" }, () => {
-	const env = shell.bundledChildEnv(clean(), { ...base, memory: classify({ store: "present" }) });
+	const env = shell.bundledChildEnv(clean(), { ...base, memory: classify({ endpoint: listening(false) }) });
 	const result = spawnSync(env.ENGRAM_BIN!, ["instance-id"], { env, encoding: "utf8", timeout: 5000 });
 	assert.notEqual(result.status, 0);
 	assert.doesNotMatch(result.stdout, /^[a-f0-9]{32}$/m);

package/tests/external-editor.test.ts

@@ -0,0 +1,84 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { join, relative } from "node:path";
+import test from "node:test";
+import { openInExternalEditor } from "../lib/external-editor.ts";
+
+function fixture(result: Partial<ReturnType<typeof spawnSync>> = { status: 0 }) {
+	const events: string[] = [];
+	const host = { stop: () => events.push("stop"), start: () => events.push("start"), requestRender: (force?: boolean) => events.push(`render:${force}`) };
+	type Options = { cwd?: string; stdio: string; shell: boolean };
+	const calls: { command: string; args: string[]; options: Options }[] = [];
+	const spawn = ((command: string, args: string[], options: Options) => {
+		events.push("spawn");
+		calls.push({ command, args, options });
+		return result;
+	}) as typeof spawnSync;
+	return { host, spawn, calls, events };
+}
+
+test("editor paths remain single arguments without a shell", () => {
+	const f = fixture();
+	const path = "a&echo GS_2426_EXECUTED&rem tail.txt";
+	assert.equal(openInExternalEditor(f.host, path, { VISUAL: "editor.exe -w", EDITOR: "ignored" }, f.spawn, "/linked"), true);
+	assert.deepEqual(f.calls, [{ command: "editor.exe", args: ["-w", path], options: { cwd: "/linked", stdio: "inherit", shell: false } }]);
+	assert.deepEqual(f.events, ["stop", "spawn", "start", "render:true"]);
+});
+
+test("Windows batch editors are refused before spawning and name a direct executable alternative", { skip: process.platform !== "win32" }, () => {
+	for (const editor of ["editor.cmd", "editor.BAT"]) {
+		const f = fixture();
+		assert.throws(() => openInExternalEditor(f.host, "safe.txt", { EDITOR: editor }, f.spawn), /executable.*\.exe/i);
+		assert.deepEqual(f.calls, []);
+		assert.deepEqual(f.events, []);
+	}
+});
+
+test("editor launch failures are reported after restoring the TUI", () => {
+	for (const result of [{ error: new Error("ENOENT"), status: null }, { status: 7 }, { status: null, signal: "SIGTERM" as const }]) {
+		const f = fixture(result);
+		assert.throws(() => openInExternalEditor(f.host, "safe.txt", { EDITOR: "editor.exe" }, f.spawn), /Could not open editor/);
+		assert.deepEqual(f.events, ["stop", "spawn", "start", "render:true"]);
+	}
+});
+
+test("editor retains VISUAL precedence, flags, cwd, and missing-editor behavior", () => {
+	const f = fixture();
+	assert.equal(openInExternalEditor(f.host, "lib/a.ts", { VISUAL: "nvim -u none", EDITOR: "vi" }, f.spawn, "/linked"), true);
+	assert.equal(f.calls[0].command, "nvim");
+	assert.deepEqual(f.calls[0].args, ["-u", "none", "lib/a.ts"]);
+	assert.equal(f.calls[0].options.cwd, "/linked");
+	assert.equal(openInExternalEditor(f.host, "lib/a.ts", {}, f.spawn), false);
+	assert.deepEqual(f.events, ["stop", "spawn", "start", "render:true"]);
+});
+
+test("a real editor process receives a metacharacter filename unchanged", () => {
+	const root = mkdtempSync(join(process.cwd(), ".editor-test-"));
+	try {
+		const script = join(root, "editor.cjs");
+		writeFileSync(script, "process.stdout.write(JSON.stringify(process.argv.slice(2)))");
+		const path = join(root, "a&echo GS_2426_EXECUTED&rem tail.txt");
+		writeFileSync(path, "unchanged");
+		const f = fixture();
+		let child: ReturnType<typeof spawnSync> | undefined;
+		const spawn = ((command: string, args: string[], options: object) => {
+			child = spawnSync(command, args, { ...options, stdio: "pipe", encoding: "utf8", timeout: 3000 });
+			return child;
+		}) as typeof spawnSync;
+		assert.equal(openInExternalEditor(f.host, path, { EDITOR: `node ${relative(process.cwd(), script)}` }, spawn, process.cwd()), true);
+		assert.equal(child?.status, 0);
+		assert.equal(child?.stdout, JSON.stringify([path]));
+		assert.equal(child?.stderr, "");
+		assert.deepEqual(f.events, ["stop", "start", "render:true"]);
+	} finally {
+		rmSync(root, { recursive: true, force: true });
+	}
+});
+
+test("synchronous spawn exceptions restore the TUI before reporting failure", () => {
+	const f = fixture();
+	const spawn = (() => { throw new Error("spawn failed"); }) as typeof spawnSync;
+	assert.throws(() => openInExternalEditor(f.host, "safe.txt", { EDITOR: "editor.exe" }, spawn), { message: "Could not open editor: spawn failed" });
+	assert.deepEqual(f.events, ["stop", "start", "render:true"]);
+});

package/tests/fixtures/primary-session-prompt/gentleman.golden.md

@@ -46,7 +46,7 @@ Harness principles:
 - el Gentleman is not prompt engineering. It is runtime discipline around powerful agents.
 - Clarify scope, constraints, acceptance criteria, and non-goals before implementation.
 - Use subagents when available for exploration, planning, implementation, and review, while keeping one parent session responsible for orchestration.
-- For behavior changes with applicable runnable deterministic tests and a clear expected outcome, use test-first by default: observe RED, GREEN, then refactor with focused checks. Write one RED test per requested rule. For every existing command or option the change touches, add one test proving its previous behavior still holds; add no other cases. An existing behavior counts as touched when it shares the code you changed (options, parsers, helpers, validation). Before finishing, run a differential check: for each existing command that shares the code you changed, run it with the new or changed input (for example a new option passed to a sibling subcommand) against the previous code (a copy of the base commit in a `mktemp -d` scratch directory, never committed as a test; committed tests never read git history or a fixed commit) and against your change, and compare stdout, stderr, and exit code; any difference nobody asked for is a regression to fix and pin with a test. Test presence alone does not establish applicability; no chat or TUI toggle activates it. For passive documentation, non-testable changes, an unavailable runner, or no meaningful RED, explain why and run proportionate ordinary functional or structural verification. Never invent lifecycle evidence or skip checks. Follow orchestrator-delegation.md for ODD forwarding and evidence.
+- For behavior changes with applicable runnable deterministic tests and a clear expected outcome, use test-first by default: observe RED, GREEN, then refactor with focused checks. Write one RED test per requested rule. For every existing command or option the change touches, add one test proving its previous behavior still holds; add no other cases. An existing behavior counts as touched when it shares the code you changed (options, parsers, helpers, validation). Only when your diff changes shared code (options, parsers, helpers) that an existing command the request did not name also uses, run one differential check before finishing, as a single script: for each such command, run it with the new or changed input (for example a new option passed to a sibling subcommand) against the previous code (a copy of the base commit in a `mktemp -d` scratch directory, never committed as a test; committed tests never read git history or a fixed commit) and against your change, and compare stdout, stderr, and exit code; any difference nobody asked for is a regression to fix and pin with a test. Test presence alone does not establish applicability; no chat or TUI toggle activates it. For passive documentation, non-testable changes, an unavailable runner, or no meaningful RED, explain why and run proportionate ordinary functional or structural verification. Never invent lifecycle evidence or skip checks. Follow orchestrator-delegation.md for ODD forwarding and evidence.
 - Protect the human reviewer: avoid oversized changes, surface review workload risk, and ask before turning one task into a large multi-area change.
 - Never claim persistent memory is available because of this package. Memory is provided by separate packages or MCP tools when installed and callable.
 
@@ -88,9 +88,9 @@ A task is **small** when all three hold:
 
 The number of files, commands or tests, fixes, or a requested `todo` list never decides size. A task is **large** only when the resume test fails (several sessions, external waits, deliverables the user wants apart (never several features asked at once), requirements compaction could lose); large tasks get ODD tracking and workers only by the Writer rule, else inline.
 
-Small path: inline (parent; `bash_background` policy); observe RED inline before the fix; run the focused test and the suite inline, once each. No explore, worker, or verifier; no feature document, mirror, or commits unless the user asks; `todo` optional. It needs no lazy asset.
+Small path: inline (parent; `bash_background` policy); read only what you change and its helpers, in one batch; observe RED inline before the fix; run the focused test and the suite inline in one command. No explore, worker, or verifier; no feature document, mirror, or commits unless the user asks; no `todo`. It needs no lazy asset.
 
-**High risk**: a mistake would be hard to detect, hard to undo, or reaches beyond the change: (1) data or irreversible effects (migrations, rewriting or deleting stored data, format changes, writing data without validation; not saving new records); (2) security (auth, permissions, credentials, secrets, guards, sandbox); (3) changing or removing contracts others already consume (public API, CLI flags, config formats, exports, mirrored prompts; not adding a flag, command or optional field; requested changes are not; unrequested breaks in shared code are); (4) concurrency; (5) delivery or environment (installers, release, CI, deploy, dependencies); (6) no test would catch a regression in what changes. Count "unclear" as high only when a bounded look cannot tell whether (1)-(5) apply. When RDD is on and native assess returns a tier, that tier wins.
+**High risk**: a mistake would be hard to detect, hard to undo, or reaches beyond the change: (1) data or irreversible effects that cannot be rebuilt (migrations, rewriting or deleting stored data, format changes, writing data without validation; not saving new records, nor a dev or test database a seed or backup rebuilds); (2) security (auth, permissions, credentials, secrets, guards, sandbox); (3) changing or removing contracts others already consume (public API, CLI flags, config formats, exports, mirrored prompts; not adding a flag, command or optional field; requested changes are not; unrequested breaks in shared code are); (4) concurrency; (5) delivery or environment (installers, release, CI, deploy, dependencies); (6) no test would catch a regression in what changes. Count "unclear" as high only when a bounded look cannot tell whether (1)-(5) apply. When RDD is on and native assess returns a tier, that tier wins.
 
 **Risk line**: close every code change, small path or delegated, with `Risk: item N (reason)` or `Risk: none` per the list; any item → Verification rule.