gentle-pi 2.7.0 → 3.0.0

package/tests/artifact-language.test.ts

@@ -152,10 +152,10 @@ test("SDD proposal questions focus on business and PRD gaps", async () => {
 test("all shipped SDD agents and chains require parent preflight transport", async () => {
 	const agents = [
 		"sdd-init", "sdd-onboard", "sdd-explore", "sdd-research", "sdd-proposal", "sdd-spec", "sdd-design",
-		"sdd-tasks", "sdd-status", "sdd-apply", "sdd-verify", "sdd-sync", "sdd-archive", "sdd-remediate",
+		"sdd-tasks", "sdd-status", "sdd-apply", "sdd-verify", "sdd-archive", "sdd-remediate",
 	];
 	const chains = ["sdd-full", "sdd-plan", "sdd-verify"];
-	assert.equal(agents.length, 14);
+	assert.equal(agents.length, 13);
 	assert.equal(chains.length, 3);
 	for (const agent of agents) {
 		const source = await readFile(join(ROOT, "assets", "agents", `${agent}.md`), "utf8");
@@ -221,7 +221,7 @@ test("persistent harness prompt assets do not hardcode Spanish SDD artifact copy
 	assert.deepEqual(failures, []);
 });
 
-test("SDD assets route completed implementation directly through verify, sync, and archive", async () => {
+test("SDD assets route completed implementation through native archive with optional verification", async () => {
 	const [tasks, apply, status, contract, chain] = await Promise.all([
 		readFile(join(ROOT, "assets/agents/sdd-tasks.md"), "utf8"),
 		readFile(join(ROOT, "assets/agents/sdd-apply.md"), "utf8"),
@@ -231,13 +231,16 @@ test("SDD assets route completed implementation directly through verify, sync, a
 	]);
 	const assets = [tasks, apply, status, contract, chain].join("\n");
 
-	assert.match(tasks, /<!-- sdd-owner: implementation -->/);
-	assert.match(apply, /next_recommended: "sdd-verify"/);
+	assert.match(tasks, /- \[ \] 1\. Implement and verify the behavior\./);
+	assert.doesNotMatch(tasks, /<!-- sdd-owner:/);
+	assert.match(apply, /fresh native recommendation/);
 	assert.match(status, /gentle-ai\.sdd-status.*v2/i);
 	assert.match(status, /read-only/i);
 	assert.match(contract, /native.*(?:apply|verify).*archive/is);
-	assert.match(contract, /Manual `sdd-sync` remains its intentional local resolver/);
-	assert.match(chain, /apply.*verification/is);
+	assert.doesNotMatch(contract, /local resolver/);
+	assert.match(contract, /verification is optional/);
+	assert.match(chain, /apply -> archive/);
+	assert.doesNotMatch(chain, /^## sdd-(verify|sync)$/m);
 	assert.doesNotMatch(assets, /<!-- sdd-owner: parent -->/);
 	assert.doesNotMatch(assets, /parent-lifecycle/);
 	assert.doesNotMatch(assets, /approved receipt|bounded review/i);

package/tests/command-palette.test.ts

@@ -0,0 +1,378 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { CommandPalette, commandsKey, rankPaletteGroups, type CommandPaletteGroup, type CommandPaletteItem, type CommandPaletteResult, type CommandPaletteTheme } from "../lib/command-palette.ts";
+import { buildCommandPaletteGroups, COMMAND_PALETTE_CATALOG } from "../lib/command-palette-catalog.ts";
+
+// Command palette: a pure, curated, grouped overlay component for
+// `/gentle:commands` and its `alt+k` shortcut. These tests drive ranking,
+// keyboard input, and rendering without any Pi extension API — the
+// component only depends on pi-tui key/width helpers and plain data
+// (groups of items) in, plain strings out.
+
+const KEY = {
+	DOWN: "\x1b[B",
+	UP: "\x1b[A",
+	CTRL_J: "\n",
+	CTRL_K: "\x0b",
+	ENTER: "\r",
+	ESCAPE: "\x1b",
+	CTRL_C: "\x03",
+	BACKSPACE: "\x7f",
+	CTRL_U: "\x15",
+} as const;
+
+function type(palette: CommandPalette, text: string): void {
+	for (const ch of text) palette.handleInput(ch);
+}
+
+function createPalette(groups: readonly CommandPaletteGroup[], theme?: CommandPaletteTheme, rows?: () => number): { palette: CommandPalette; results: CommandPaletteResult[] } {
+	const results: CommandPaletteResult[] = [];
+	const palette = new CommandPalette(groups, (result) => results.push(result), theme, rows);
+	return { palette, results };
+}
+
+// --- rankPaletteGroups -------------------------------------------------------
+
+test("rankPaletteGroups ranks label-prefix, label-contains, label-subsequence, command-contains, then description-contains", () => {
+	const group: CommandPaletteGroup = {
+		title: "G",
+		items: [
+			// rank 4: only the description contains "mod".
+			{ command: "gentle:xyz-tool", label: "xyz", description: "custom mod support" },
+			// rank 3: only the command name contains "mod".
+			{ command: "gentle:mod-tool", label: "xyz-abc" },
+			// rank 2: the label matches "mod" only as a subsequence.
+			{ command: "gentle:whatever3", label: "my-old-doc" },
+			// rank 1: the label contains "mod", but does not start with it.
+			{ command: "gentle:whatever2", label: "gentle models here" },
+			// rank 0: the label starts with "mod".
+			{ command: "gentle:whatever1", label: "Modify a thing" },
+		],
+	};
+	const ranked = rankPaletteGroups([group], "mod");
+	assert.equal(ranked.length, 1);
+	assert.deepEqual(
+		ranked[0]?.items.map((item) => item.command),
+		["gentle:whatever1", "gentle:whatever2", "gentle:whatever3", "gentle:mod-tool", "gentle:xyz-tool"],
+	);
+});
+
+test("rankPaletteGroups is case-insensitive and trims the query", () => {
+	const group: CommandPaletteGroup = { title: "G", items: [{ command: "a", label: "Alpha Mod" }, { command: "b", label: "beta" }] };
+	const lower = rankPaletteGroups([group], "mod").map((g) => g.items.map((i) => i.command));
+	assert.deepEqual(rankPaletteGroups([group], "MOD").map((g) => g.items.map((i) => i.command)), lower);
+	assert.deepEqual(rankPaletteGroups([group], "  mod  ").map((g) => g.items.map((i) => i.command)), lower);
+});
+
+test("rankPaletteGroups keeps input order within a group for tied ranks", () => {
+	const group: CommandPaletteGroup = { title: "G", items: [{ command: "mod-b", label: "mod-b" }, { command: "mod-a", label: "mod-a" }] };
+	assert.deepEqual(rankPaletteGroups([group], "mod")[0]?.items.map((i) => i.command), ["mod-b", "mod-a"]);
+});
+
+test("rankPaletteGroups returns every group unchanged for an empty or whitespace query", () => {
+	const groups: CommandPaletteGroup[] = [
+		{ title: "G1", items: [{ command: "a", label: "Alpha" }] },
+		{ title: "G2", items: [{ command: "b", label: "Beta" }] },
+	];
+	assert.deepEqual(rankPaletteGroups(groups, ""), groups);
+	assert.deepEqual(rankPaletteGroups(groups, "   "), groups);
+});
+
+test("rankPaletteGroups drops a group with no matching item, and never reorders groups", () => {
+	const groups: CommandPaletteGroup[] = [
+		{ title: "Configuration", items: [{ command: "gentle:models", label: "Assign models and effort" }, { command: "gentle:profiles", label: "Agent-model profiles" }] },
+		{ title: "Session", items: [{ command: "gentle:usage", label: "Subscription usage" }] },
+		{ title: "Diagnostics", items: [{ command: "gentle:status", label: "Gentle AI status" }] },
+	];
+	const ranked = rankPaletteGroups(groups, "model");
+	assert.deepEqual(ranked.map((g) => g.title), ["Configuration"]);
+	assert.deepEqual(ranked[0]?.items.map((i) => i.command), ["gentle:models", "gentle:profiles"]);
+});
+
+test("rankPaletteGroups returns no groups for a query that matches nothing anywhere", () => {
+	const groups: CommandPaletteGroup[] = [{ title: "G", items: [{ command: "a", label: "Alpha", description: "first letter" }] }];
+	assert.deepEqual(rankPaletteGroups(groups, "qqqqzzz"), []);
+});
+
+// --- input flow --------------------------------------------------------------
+
+const GROUPS: CommandPaletteGroup[] = [
+	{
+		title: "Configuration",
+		items: [
+			{ command: "gentle:models", label: "Assign models and effort" },
+			{ command: "gentle:profiles", label: "Agent-model profiles" },
+		],
+	},
+	{
+		title: "Session",
+		items: [{ command: "gentle:changes", label: "Browse captured changes", shortcut: "alt+g" }],
+	},
+];
+
+test("typing filters across groups and resets the selection to the first visible item", () => {
+	const { palette, results } = createPalette(GROUPS);
+	palette.handleInput(KEY.DOWN);
+	palette.handleInput(KEY.DOWN); // selection is now "gentle:changes" (index 2)
+	// "s" keeps every item (each label contains "s") in the same relative
+	// order, so this only exercises the selection reset: without it, enter
+	// would still pick "gentle:changes".
+	palette.handleInput("s");
+	palette.handleInput(KEY.ENTER);
+	assert.deepEqual(results, [{ type: "run", name: "gentle:models" }]);
+});
+
+test("backspace removes the last query character", () => {
+	const { palette, results } = createPalette(GROUPS);
+	type(palette, "changez");
+	palette.handleInput(KEY.BACKSPACE);
+	palette.handleInput(KEY.ENTER);
+	assert.deepEqual(results, [{ type: "run", name: "gentle:changes" }]);
+});
+
+test("ctrl+u clears the query", () => {
+	const { palette, results } = createPalette(GROUPS);
+	type(palette, "changes");
+	palette.handleInput(KEY.CTRL_U);
+	palette.handleInput(KEY.ENTER);
+	assert.deepEqual(results, [{ type: "run", name: "gentle:models" }]);
+});
+
+test("up and down move the selection across groups and clamp at the ends", () => {
+	const { palette, results } = createPalette(GROUPS);
+	palette.handleInput(KEY.UP); // clamps at 0, still "gentle:models"
+	palette.handleInput(KEY.DOWN); // gentle:profiles
+	palette.handleInput(KEY.DOWN); // gentle:changes (crosses into the Session group)
+	palette.handleInput(KEY.DOWN); // clamps at the last item
+	palette.handleInput(KEY.ENTER);
+	assert.deepEqual(results, [{ type: "run", name: "gentle:changes" }]);
+});
+
+test("ctrl+j and ctrl+k also move the selection", () => {
+	const { palette, results } = createPalette(GROUPS);
+	palette.handleInput(KEY.CTRL_J); // gentle:profiles
+	palette.handleInput(KEY.CTRL_K); // gentle:models
+	palette.handleInput(KEY.ENTER);
+	assert.deepEqual(results, [{ type: "run", name: "gentle:models" }]);
+});
+
+test("enter runs the highlighted item and is a no-op with no match", () => {
+	const { palette, results } = createPalette(GROUPS);
+	type(palette, "nothing-like-this");
+	palette.handleInput(KEY.ENTER);
+	assert.deepEqual(results, []);
+});
+
+test("escape and ctrl+c close without running", () => {
+	const escapePalette = createPalette(GROUPS);
+	escapePalette.palette.handleInput(KEY.ESCAPE);
+	assert.deepEqual(escapePalette.results, [{ type: "close" }]);
+
+	const ctrlCPalette = createPalette(GROUPS);
+	ctrlCPalette.palette.handleInput(KEY.CTRL_C);
+	assert.deepEqual(ctrlCPalette.results, [{ type: "close" }]);
+});
+
+test("a second input after completion is ignored", () => {
+	const { palette, results } = createPalette(GROUPS);
+	palette.handleInput(KEY.ESCAPE);
+	palette.handleInput(KEY.ENTER);
+	palette.handleInput("x");
+	assert.deepEqual(results, [{ type: "close" }]);
+});
+
+test("a key release event is ignored even when it would otherwise match a binding", () => {
+	const { palette, results } = createPalette(GROUPS);
+	// ":3B" flags a Kitty protocol key release for the down arrow.
+	palette.handleInput("\x1b[1;1:3B");
+	palette.handleInput(KEY.ENTER);
+	assert.deepEqual(results, [{ type: "run", name: "gentle:models" }]);
+});
+
+// --- rendering ---------------------------------------------------------------
+
+function render(groups: readonly CommandPaletteGroup[], query: string, width = 60, theme?: CommandPaletteTheme, rows?: () => number): string[] {
+	const { palette } = createPalette(groups, theme, rows);
+	type(palette, query);
+	return palette.render(width);
+}
+
+test("render shows the header (Commands / esc), the search hint, and the typed query", () => {
+	const lines = render(GROUPS, "");
+	const header = lines.find((line) => line.includes("Commands"));
+	assert.ok(header, "expected a header line with Commands");
+	assert.match(header!, /Commands/);
+	assert.match(header!, /esc\s*│?\s*$/);
+	assert.ok(lines.some((line) => line.includes("› Search")));
+
+	const typed = render(GROUPS, "models");
+	assert.ok(typed.some((line) => line.includes("› models")));
+});
+
+test("render shows group titles and one row per item, with the shortcut right-aligned", () => {
+	const lines = render(GROUPS, "").join("\n");
+	assert.match(lines, /Configuration/);
+	assert.match(lines, /Session/);
+	assert.match(lines, /Assign models and effort/);
+	assert.match(lines, /Agent-model profiles/);
+	const changesLine = render(GROUPS, "").find((line) => line.includes("Browse captured changes"));
+	assert.ok(changesLine, "expected a row for Browse captured changes");
+	assert.match(changesLine!, /Browse captured changes[\s\S]*alt\+g/);
+});
+
+test("render omits the shortcut column for an item without one", () => {
+	const lines = render(GROUPS, "").join("\n");
+	const modelsLine = render(GROUPS, "")
+		.filter((line) => line.includes("Assign models and effort"))
+		.join("\n");
+	assert.doesNotMatch(modelsLine, /undefined/);
+	assert.ok(lines.length > 0);
+});
+
+test("render marks the selected row with a highlighted bar when the theme provides bg", () => {
+	const bgTheme: CommandPaletteTheme = {
+		fg: (_color, text) => text,
+		bg: (color, text) => `[bg:${color}]${text}[/bg]`,
+	};
+	const lines = render(GROUPS, "", 60, bgTheme);
+	const selectedLine = lines.find((line) => line.includes("[bg:selectedBg]"));
+	assert.ok(selectedLine, "expected a bg-highlighted selected row");
+	assert.match(selectedLine!, /Assign models and effort/);
+	assert.doesNotMatch(selectedLine!, /▸/);
+});
+
+test("render falls back to a ▸ marker when the theme has no bg", () => {
+	const fgOnlyTheme: CommandPaletteTheme = { fg: (_color, text) => text };
+	const lines = render(GROUPS, "", 60, fgOnlyTheme);
+	const selectedLine = lines.find((line) => line.includes("▸"));
+	assert.ok(selectedLine, "expected a ▸ marker when bg is unavailable");
+	assert.match(selectedLine!, /Assign models and effort/);
+	assert.doesNotMatch(lines.join("\n"), /\[bg:/);
+});
+
+test("render shows a muted no-match row when nothing matches", () => {
+	const lines = render(GROUPS, "does-not-exist").join("\n");
+	assert.match(lines, /No commands match "does-not-exist"/);
+});
+
+test("render escapes control characters in labels and shortcuts", () => {
+	const groups: CommandPaletteGroup[] = [{ title: "G", items: [{ command: "gentle:evil", label: "line1\x07line2", shortcut: "alt+\x07" }] }];
+	const lines = render(groups, "").join("\n");
+	assert.doesNotMatch(lines, /\x07/);
+	assert.match(lines, /\\x07/);
+});
+
+test("render footer lists the key bindings", () => {
+	const lines = render(GROUPS, "").join("\n");
+	assert.match(lines, /type to search • ↑\/↓ move • enter run • esc close/);
+});
+
+test("render keeps the right border aligned when a label has wide characters", () => {
+	// Both labels are exactly 10 UTF-16 code units, so a length-based pad
+	// treats the two rows as equally wide and pads them by the same amount.
+	// Their display widths differ (20 columns of CJK vs. 10 ASCII columns),
+	// so only a visibleWidth-based pad keeps the right border aligned.
+	const groups: CommandPaletteGroup[] = [
+		{
+			title: "G",
+			items: [
+				{ command: "gentle:emoji", label: "中文中文中文中文中文" },
+				{ command: "gentle:plain", label: "plain desc" },
+			],
+		},
+	];
+	const lines = render(groups, "", 60);
+	const widths = new Set(lines.map((line) => visibleWidth(line)));
+	assert.equal(widths.size, 1, `expected every rendered line to share one visible width, got ${[...widths].join(", ")}`);
+});
+
+test("height follows rows() with scroll indicators when 30 items do not fit in 24 rows", () => {
+	const groups: CommandPaletteGroup[] = Array.from({ length: 3 }, (_, groupIndex) => ({
+		title: `Group ${groupIndex}`,
+		items: Array.from({ length: 10 }, (_, itemIndex) => ({ command: `cmd:${groupIndex}-${itemIndex}`, label: `Item ${groupIndex}-${itemIndex}` })),
+	}));
+	const { palette } = createPalette(groups, undefined, () => 24);
+	for (let i = 0; i < 15; i++) palette.handleInput(KEY.DOWN);
+	const lines = palette.render(80);
+	assert.ok(lines.length <= 20, `expected at most 20 total lines for rows()=24, got ${lines.length}`);
+	assert.ok(lines.some((line) => /↑ \d+ more/.test(line)));
+	assert.ok(lines.some((line) => /↓ \d+ more/.test(line)));
+});
+
+test("a small terminal still renders at least the minimum 12-line card", () => {
+	const { palette } = createPalette(GROUPS, undefined, () => 4);
+	const lines = palette.render(60);
+	assert.ok(lines.length <= 12, `expected at most 12 total lines for a tiny terminal, got ${lines.length}`);
+});
+
+// --- commandsKey ---------------------------------------------------------------
+
+test("commandsKey defaults to alt+k", () => {
+	assert.equal(commandsKey({}), "alt+k");
+});
+
+test("commandsKey honors an override", () => {
+	assert.equal(commandsKey({ GENTLE_PI_COMMANDS_KEY: "ctrl+p" }), "ctrl+p");
+});
+
+test("commandsKey is disabled by an empty value or off (case-insensitive)", () => {
+	assert.equal(commandsKey({ GENTLE_PI_COMMANDS_KEY: "" }), undefined);
+	assert.equal(commandsKey({ GENTLE_PI_COMMANDS_KEY: "off" }), undefined);
+	assert.equal(commandsKey({ GENTLE_PI_COMMANDS_KEY: "OFF" }), undefined);
+});
+
+// --- catalog -------------------------------------------------------------------
+
+test("COMMAND_PALETTE_CATALOG matches the curated command set, in order", () => {
+	assert.deepEqual(
+		COMMAND_PALETTE_CATALOG.map((group) => group.title),
+		["Configuration", "Session", "Diagnostics", "SDD", "Skills"],
+	);
+	const byTitle = (title: string) => COMMAND_PALETTE_CATALOG.find((group) => group.title === title)?.items.map((item) => item.command);
+	assert.deepEqual(byTitle("Configuration"), [
+		"gentle:models",
+		"gentle:profiles",
+		"gentle:persona",
+		"gentle:review-mode",
+		"gentle:background-subagents",
+		"gentle:telemetry",
+		"gentle:banner",
+		"gentle:banner-color",
+		"gentle:toggle-rose",
+		"gentle:toggle-text-logo",
+		"gentle:dev-binary",
+	]);
+	assert.deepEqual(byTitle("Session"), ["gentle:changes", "gentle:agents", "gentle:usage", "gentle:review-session-permission"]);
+	assert.deepEqual(byTitle("Diagnostics"), ["gentle:status", "gentle:doctor"]);
+	assert.deepEqual(byTitle("SDD"), ["gentle:sdd-preflight", "gentle-sdd-status", "gentle-sdd-continue", "gentle-sdd-init"]);
+	assert.deepEqual(byTitle("Skills"), ["skill-registry:refresh"]);
+});
+
+test("buildCommandPaletteGroups keeps only registered commands, attaches descriptions and shortcuts, drops empty groups, preserves catalog order", () => {
+	const registered = [
+		{ name: "gentle:models", description: "Configure models" },
+		{ name: "gentle:changes", description: "Browse changes" },
+		{ name: "gentle:status", description: "Show status" },
+		{ name: "skill-registry:refresh", description: "Refresh registry" },
+	];
+	const shortcuts = { "gentle:changes": "alt+g" };
+	const groups = buildCommandPaletteGroups(registered, shortcuts);
+	assert.deepEqual(
+		groups.map((group) => group.title),
+		["Configuration", "Session", "Diagnostics", "Skills"],
+	);
+	const configuration = groups.find((group) => group.title === "Configuration");
+	assert.deepEqual(configuration?.items.map((item) => item.command), ["gentle:models"]);
+	assert.equal(configuration?.items[0]?.description, "Configure models");
+	assert.equal(configuration?.items[0]?.shortcut, undefined);
+	const session = groups.find((group) => group.title === "Session");
+	assert.deepEqual(session?.items.map((item) => item.command), ["gentle:changes"]);
+	assert.equal(session?.items[0]?.shortcut, "alt+g");
+	assert.equal(groups.some((group) => group.title === "SDD"), false);
+});
+
+test("buildCommandPaletteGroups drops every group when nothing in the catalog is registered", () => {
+	const groups = buildCommandPaletteGroups([{ name: "not-in-catalog", description: "n/a" }], {});
+	assert.deepEqual(groups, []);
+});

package/tests/delegated-key-learnings-contract.test.ts

@@ -93,7 +93,7 @@ test("SDD executor coverage is exhaustive against actual agent files", () => {
 	const expected = [
 		"sdd-apply.md", "sdd-archive.md", "sdd-design.md", "sdd-explore.md",
 		"sdd-init.md", "sdd-onboard.md", "sdd-proposal.md", "sdd-remediate.md", "sdd-research.md",
-		"sdd-spec.md", "sdd-status.md", "sdd-sync.md", "sdd-tasks.md",
+		"sdd-spec.md", "sdd-status.md", "sdd-tasks.md",
 		"sdd-verify.md",
 	];
 	assert.deepEqual(actual, expected, "SDD agent set must match the known allowlist");
@@ -231,7 +231,7 @@ test("modified SDD agents are packaged and installed by the existing installer",
 		"assets/agents/sdd-init.md", "assets/agents/sdd-onboard.md",
 		"assets/agents/sdd-proposal.md", "assets/agents/sdd-research.md",
 		"assets/agents/sdd-spec.md", "assets/agents/sdd-status.md",
-		"assets/agents/sdd-sync.md", "assets/agents/sdd-tasks.md",
+		"assets/agents/sdd-tasks.md",
 		"assets/agents/sdd-verify.md",
 	];
 	for (const path of expected) {

package/tests/fixtures/agents-session-transport-process.mjs

@@ -0,0 +1,108 @@
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { ActiveSessionClient, ActiveSessionClientError, ActiveSessionListener, SessionPresenceRegistry } from "../../lib/agents-session-transport.ts";
+
+const agentHome = process.env.GENTLE_AGENT_HOME;
+const CONTROL_BYTES = 16_384;
+if (!agentHome) throw new Error("GENTLE_AGENT_HOME is required");
+
+await mkdir(join(agentHome, "gentle-agents"), { recursive: true, mode: 0o755 });
+const registry = await SessionPresenceRegistry.create(agentHome);
+let listener;
+let client;
+let blockShutdown = false;
+let blocker;
+let closed = false;
+let input = Buffer.alloc(0);
+
+const record = (value) => ({ ...value, presencePath: registry.presencePath(value) });
+const controlLine = (value) => {
+	const line = JSON.stringify(value);
+	if (Buffer.byteLength(line) > CONTROL_BYTES) throw new Error("control frame exceeds bound");
+	return `${line}\n`;
+};
+const emit = (value) => { process.stdout.write(controlLine(value)); };
+const flush = (value) => new Promise((resolveFlush, rejectFlush) => {
+	process.stdout.write(controlLine(value), (error) => error ? rejectFlush(error) : resolveFlush());
+});
+const stop = async () => {
+	const current = listener?.record;
+	client?.close();
+	client = undefined;
+	if (blocker) clearInterval(blocker);
+	blocker = undefined;
+	if (listener) await listener.close();
+	listener = undefined;
+	return current ? record(current) : {};
+};
+const reply = (requestId, ok, result, error) => emit({ requestId, ok, ...(ok ? { result } : { error }) });
+const fatal = () => {
+	if (closed) return;
+	closed = true;
+	input = Buffer.alloc(0);
+	process.stdin.off("data", onData);
+	void stop().finally(() => process.exit(2));
+};
+
+async function handle(line) {
+	let text;
+	try { text = new TextDecoder("utf-8", { fatal: true }).decode(line); }
+	catch { fatal(); return; }
+	let command;
+	try {
+		command = JSON.parse(text);
+		if (!command || typeof command !== "object" || typeof command.requestId !== "string" || typeof command.operation !== "string") throw new Error("invalid control frame");
+		let result;
+		if (command.operation === "start") {
+			await stop();
+			listener = new ActiveSessionListener(registry, command.sessionId, async (notification) => {
+				emit({ event: "callback", requestId: notification.id, pid: process.pid, ...notification });
+			});
+			await listener.start();
+			client = new ActiveSessionClient(registry, command.sessionId);
+			result = record(listener.record);
+		} else if (command.operation === "send") {
+			if (!client) throw new Error("listener is not active");
+			result = await client.sendNotification(command.recipientSessionId, command.message, { id: command.id });
+		} else if (command.operation === "resolve") result = record(await registry.resolve(command.sessionId));
+		else if (command.operation === "stop") result = await stop();
+		else if (command.operation === "delay") {
+			if (!Number.isInteger(command.delayMs) || command.delayMs < 0 || command.delayMs > 2_500) throw new Error("invalid test delay");
+			await new Promise((resolveDelay) => setTimeout(resolveDelay, command.delayMs));
+			result = { delayed: true };
+		} else if (command.operation === "exit") process.exit(23);
+		else if (command.operation === "block-shutdown") {
+			blockShutdown = true;
+			blocker ??= setInterval(() => {}, 1_000);
+			result = { armed: true };
+		}
+		else if (command.operation === "shutdown") {
+			if (blockShutdown) return;
+			result = await stop();
+			await flush({ requestId: command.requestId, ok: true, result });
+			process.exit(0);
+		} else throw new Error("unknown operation");
+		reply(command.requestId, true, result);
+	} catch (error) {
+		const message = error instanceof ActiveSessionClientError ? error.code : "fixture_error";
+		reply(typeof command?.requestId === "string" ? command.requestId : "invalid", false, undefined, message);
+	}
+}
+
+let queue = Promise.resolve();
+function onData(chunk) {
+	let start = 0;
+	while (start < chunk.length) {
+		const newline = chunk.indexOf(10, start), end = newline < 0 ? chunk.length : newline;
+		const fragment = chunk.subarray(start, end);
+		if (input.length + fragment.length > CONTROL_BYTES) { fatal(); return; }
+		if (newline < 0) { input = Buffer.concat([input, fragment]); return; }
+		const line = input.length ? Buffer.concat([input, fragment]) : fragment;
+		input = Buffer.alloc(0);
+		queue = queue.then(() => handle(line)).catch(fatal);
+		start = newline + 1;
+	}
+}
+
+process.stdin.on("data", onData);
+process.stdin.on("error", fatal);

package/tests/fixtures/legacy/sdd-research-v2.5.0.md

@@ -0,0 +1,54 @@
+---
+name: sdd-research
+description: Collect auditable external evidence for a selected SDD research lane.
+tools:
+  - read
+  - grep
+  - find
+  - edit
+  - write
+  - mem_search
+  - mem_get_observation
+  - mem_save
+---
+
+You are the SDD research executor for Gentle AI.
+
+## Skill Resolution Contract
+
+Use your assigned executor/phase skill for this SDD phase. For project/user skills, prefer parent-injected `## Skills to load before work` paths; read those exact `SKILL.md` files before work. Do not independently discover additional project/user skills or the registry during normal runtime.
+
+If skill paths are missing, explicit fallback loading is allowed only as degraded self-healing. Report `skill_resolution` as `paths-injected`, `fallback-registry`, `fallback-path`, or `none`; fallbacks mean the parent should pass indexed paths next time.
+
+- Run only when the orchestrator selects `sdd-research` and supplies the persisted research intent: the change name, the questions, the requested source classes, and the artifact store. Treat that intent as immutable; if it is absent, return `blocked` with no claims.
+- Evidence grants for this runtime are `documentation=[]; open-web=[]`. Never infer evidence capability from bash, persistence tools, or any inherited tool; persistence tools are not evidence grants. Unsupported or undeclared classes deny admission and emit no claims.
+- Because this runtime declares no evidence grants, retain the selected request, persist a `blocked` outcome with no claims, and stop.
+- Admission denial, partial evidence, invalid sources, or persistence divergence emits no unvalidated claim and blocks proposal readiness.
+- Keep evidence claims separate from non-authoritative product choices; the orchestrator owns product decisions and proposal admission.
+- Do NOT launch child subagents. Parent/orchestrator owns delegation.
+- Persist the research and pre-proposal artifacts per the Memory Contract below; never claim persistence you did not perform.
+- Keep output concise and return the SDD result contract.
+## Memory Contract
+
+Read any input artifacts directly from the active backend before doing the phase work; do not wait for the parent to inline them. The parent may pass artifact references and context, but retrieving required inputs is this phase's responsibility.
+
+Inputs to read (`engram`/`both`: use the injected Engram memory read tools for the topic key, then fetch the full observation; `openspec`: read the file under `openspec/changes/{change}/`):
+- Exploration (when it exists): `sdd/{change}/explore` (openspec: the exploration file under `openspec/changes/{change}/`).
+
+Persist this phase's artifact to the active backend before returning (mandatory):
+- `engram`/`both`: call the injected Engram save tool with title and `topic_key` `"sdd/{change}/research"`, `type: "architecture"`, `project` from context, and `capture_prompt: false` when the tool schema supports it (omit the field if an older schema rejects it).
+- `openspec`: write/update `openspec/changes/{change}/research.md`.
+- `none`: return the research record inline.
+
+The research artifact uses schema `gentle-ai.sdd-research/v1`: a positive `revision`, an explicit `done | partial | blocked` outcome, the questions, admission and the observed exact grants, sources, and validated claims where each claim maps to source IDs. For this runtime the outcome is `blocked` with an admission denial and no claims.
+
+Also update the pre-proposal state (`engram`/`both`: topic `"sdd/{change}/preproposal"`; same save conventions) using schema `gentle-ai.sdd-preproposal/v1`: a positive `revision`, the exploration reference, the research request and classes, the admission outcome, evidence references, product decisions (`pending | confirmed`), and `proposal_ready`.
+
+Hybrid (`both`) persistence means identical bytes in both stores. On hybrid mismatch or a one-sided write failure, never prefer one store: recover from the retained intent, not from a surviving store, and keep proposal readiness false for recovery.
+
+Never claim persistence you did not perform.
+
+
+## Key Learnings Closing
+
+Close your final report text with a `## Key Learnings` block (no trailing colon). Use 1–5 numbered items, each a standalone factual sentence of at least 20 characters and at least 4 words. This applies to final report text only — not intermediate tool output or saved artifact content. The Engram memory provider automatically extracts and persists these items as passive capture; you do not parse the block or invoke passive-capture tools yourself. Omit the block when there is genuinely no reusable learning; no filler or speculation. This closing block is separate from explicit `mem_save` artifact/decision persistence.