gentle-pi 4.1.0 → 4.3.0

package/tests/run-test-suite.test.ts

@@ -123,6 +123,8 @@ console.log("ENV_PROBE=" + JSON.stringify({
   home,
   files: home && existsSync(home) ? readdirSync(home) : null,
   sentinel: process.env.TEST_ENV_SENTINEL,
+  tmp: process.env.TMPDIR ?? null,
+  tmpExists: process.env.TMPDIR ? existsSync(process.env.TMPDIR) : null,
 }));
 `);
 	writeFileSync(stagesPath, JSON.stringify([
@@ -200,3 +202,16 @@ test("direct invocation rejects a malformed stages file with a non-zero exit", (
 	assert.equal(result.status, 1);
 	assert.match(result.stderr ?? "", /stages file must be an array/);
 });
+
+// Harness roadmap T3: each subagent gets its own TMPDIR, and unit fixtures that
+// leave a fake child unfinished would leave it behind; the stage owns them all.
+test("unit stage gets a private TMPDIR removed after the stage; later stages keep the inherited one", (t) => {
+	const inherited = mkdtempSync(join(tmpdir(), "gentle-pi-caller-tmp-"));
+	t.after(() => rmSync(inherited, { recursive: true, force: true }));
+	const [unit, provider] = probeStageEnvironment(t, { TMPDIR: inherited });
+	assert.notEqual(unit.tmp, inherited);
+	assert.match(unit.tmp, /gentle-pi-unit-tmp-/);
+	assert.equal(unit.tmpExists, true, "the private TMPDIR exists while the stage runs");
+	assert.equal(existsSync(unit.tmp), false, "the private TMPDIR is removed after the stage");
+	assert.equal(provider.tmp, inherited);
+});

package/tests/runtime-harness.mjs

@@ -604,9 +604,19 @@ async function run() {
 			assert.equal(writerDispatch.task, task, "writer guard must not mutate child input");
 		}
 
+		// S16: generic writers are admitted only for a task of an existing feature document (or at the measured
+		// context backstop); the accepted cases below name one, and an undocumented launch is told to work inline.
+		await mkdir(join(toolCwd, "odd", "tasks"), { recursive: true });
+		await writeFile(join(toolCwd, "odd", "tasks", "harness.md"), "# Harness\n");
+		const undocumentedWriter = await toolHook(
+			{ toolName: "subagent_run", input: { agent: "gentle-ai-worker", task: "Implement the requested change.\n\n## Allowed edit surfaces\nextensions/gentle-ai.ts", mode: "task" } },
+			createCtx(toolCwd),
+		);
+		assert.equal(undocumentedWriter?.block, true, "an undocumented writer must be blocked before dispatch");
+		assert.match(undocumentedWriter?.reason ?? "", /write this unit inline yourself/);
 		const scopedWriterDispatch = {
 			agent: "gentle-ai-worker",
-			task: "Implement the requested change.\n\n## Allowed edit surfaces\nextensions/gentle-ai.ts\ntests/runtime-harness.mjs",
+			task: "Spec: odd/tasks/harness.md, T1. Implement the requested change.\n\n## Allowed edit surfaces\nextensions/gentle-ai.ts\ntests/runtime-harness.mjs",
 			mode: "task",
 		};
 		assert.equal(
@@ -620,7 +630,7 @@ async function run() {
 					toolName: "subagent_run",
 					input: {
 						agent: "worker",
-						task: "Implement the requested change.",
+						task: "Spec: odd/tasks/harness.md, T2. Implement the requested change.",
 						context: "## Allowed edit surfaces\n- assets/orchestrator.md",
 						mode: "task",
 					},
@@ -717,7 +727,7 @@ async function run() {
 				"valid scope followed by a repository-root scope",
 				{
 					agent: "gentle-ai-worker",
-					task: "## Allowed edit surfaces\nextensions/gentle-ai.ts\n\n## Allowed edit surfaces\n.",
+					task: "Spec: odd/tasks/harness.md, T4.\n\n## Allowed edit surfaces\nextensions/gentle-ai.ts\n\n## Allowed edit surfaces\n.",
 					mode: "task",
 				},
 			],
@@ -725,7 +735,7 @@ async function run() {
 				"valid task scope plus invalid context scope",
 				{
 					agent: "gentle-ai-worker",
-					task: "## Allowed edit surfaces\nextensions/gentle-ai.ts",
+					task: "Spec: odd/tasks/harness.md, T5.\n\n## Allowed edit surfaces\nextensions/gentle-ai.ts",
 					context: "## Allowed edit surfaces\n.",
 					mode: "task",
 				},
@@ -734,7 +744,7 @@ async function run() {
 				"conflicting valid task and context scopes",
 				{
 					agent: "gentle-ai-worker",
-					task: "## Allowed edit surfaces\nextensions/gentle-ai.ts",
+					task: "Spec: odd/tasks/harness.md, T6.\n\n## Allowed edit surfaces\nextensions/gentle-ai.ts",
 					context: "## Allowed edit surfaces\ntests/runtime-harness.mjs",
 					mode: "task",
 				},
@@ -749,7 +759,7 @@ async function run() {
 					toolName: "subagent_run",
 					input: {
 						agent: "gentle-ai-worker",
-						task: "## Allowed edit surfaces\nextensions/gentle-ai.ts\ntests/runtime-harness.mjs\n\n## Allowed edit surfaces\n- `tests/runtime-harness.mjs`\n- `extensions/gentle-ai.ts`",
+						task: "Spec: odd/tasks/harness.md, T3.\n\n## Allowed edit surfaces\nextensions/gentle-ai.ts\ntests/runtime-harness.mjs\n\n## Allowed edit surfaces\n- `tests/runtime-harness.mjs`\n- `extensions/gentle-ai.ts`",
 						mode: "task",
 					},
 				},

package/tests/selection-engine.test.ts

@@ -2,11 +2,16 @@ import assert from "node:assert/strict";
 import test from "node:test";
 import { CustomEditor } from "@earendil-works/pi-coding-agent";
 import { GentlePromptEditor } from "../extensions/gentle-shell.ts";
-import { SelectionEngine } from "../lib/selection-engine.ts";
+import { SelectionEngine, withReverseSpan } from "../lib/selection-engine.ts";
 import { decodePrintableKey } from "../lib/pi-tui-keys.ts";
-import { CURSOR_MARKER, visibleWidth, type TuiMouseEvent } from "@earendil-works/pi-tui";
+import { CURSOR_MARKER, stripTerminalSequences as stripAnsi, TuiMainScreen, visibleWidth, type TuiMouseEvent } from "@earendil-works/pi-tui";
 import { CARD_STYLE, cardStyle, setCardStyle } from "../lib/shell-card.ts";
-import { stripAnsi } from "../lib/terminal-theme.ts";
+import { withPromptHint } from "../lib/shell-prompt.ts";
+
+function resolveFakeCursors(rows: string[], hardware = false): string[] {
+	const host = TuiMainScreen.prototype as unknown as { resolveFakeCursors(rows: string[]): string[] };
+	return host.resolveFakeCursors.call({ showHardwareCursor: hardware }, rows);
+}
 
 // Native selection engine tests: drive a real CustomEditor through the
 // SelectionEngine the same way GentlePromptEditor wires it — engine.handleInput
@@ -45,6 +50,30 @@ const click = (x: number, y: number, width: number): TuiMouseEvent => ({
 	type: "click", button: "left", x, y, width, height: 30, screenX: x, screenY: y, shift: false, alt: false, ctrl: false,
 });
 
+test("legacy and APC cursors preserve native selection and empty hints", () => {
+	const legacy = `${CURSOR_MARKER}\x1b[7ma\x1b[0mbc`;
+	assert.equal(withReverseSpan(legacy, 0, 3), `\x1b[7m${CURSOR_MARKER}\x1b[7ma\x1b[0m\x1b[7mbc\x1b[27m`);
+	const apc = `${CURSOR_MARKER}\x1b_pi:fc\x07a\x1b_pi:/fc\x07bc`;
+	const selected = withReverseSpan(apc, 0, 3);
+	assert.ok(selected.includes(`${CURSOR_MARKER}\x1b_pi:fc\x07`));
+	for (const hardware of [false, true]) {
+		const resolved = resolveFakeCursors([selected], hardware)[0];
+		assert.ok(resolved.includes("\x1b[7mbc\x1b[27m"));
+		assert.equal(stripAnsi(resolved), "abc");
+	}
+	// Outside selection the host still suppresses only the focused fake cursor.
+	assert.equal(resolveFakeCursors([apc], true)[0], `${CURSOR_MARKER}abc`);
+	assert.ok(resolveFakeCursors([apc.replace(CURSOR_MARKER, "")], true)[0].includes("\x1b[7ma\x1b[27m"));
+	for (const cursor of ["\x1b[7m \x1b[0m", "\x1b_pi:fc\x07 \x1b_pi:/fc\x07"]) {
+		const row = `${CURSOR_MARKER}${cursor}${" ".repeat(30)}`;
+		const hinted = withPromptHint(row, "type here", (_role, text) => text);
+		assert.ok(hinted.startsWith(`${CURSOR_MARKER}${cursor}`));
+		assert.ok(hinted.includes("type here"));
+		assert.equal(visibleWidth(hinted), visibleWidth(row));
+		assert.equal(withPromptHint(row + "draft", "type here", (_role, text) => text), row + "draft");
+	}
+});
+
 test("T2 float prompt native cursor, selection, replacement and mouse share geometry", () => {
 	const previous = cardStyle();
 	setCardStyle(CARD_STYLE.FLOAT);
@@ -56,11 +85,12 @@ test("T2 float prompt native cursor, selection, replacement and mouse share geom
 		let rows = editor.render(80);
 		assert.match(rows[0], /\x1b\[35m▎\x1b\[39m/);
 		assert.equal(visibleWidth(rows[1].split(CURSOR_MARKER)[0]), 6);
-		assert.ok(rows[1].includes(`${CURSOR_MARKER}\x1b[7md\x1b[0m\x1b[44m`));
+		assert.ok(rows[1].includes(`${CURSOR_MARKER}\x1b_pi:fc\x07d\x1b_pi:/fc\x07`));
+		assert.ok(resolveFakeCursors(rows)[1].includes(`${CURSOR_MARKER}\x1b[7md\x1b[27m`));
 		editor.handleInput("\x1b[1;2H");
 		rows = editor.render(80);
 		assert.equal(stripAnsi(rows[1].replaceAll(CURSOR_MARKER, "")).trim(), "▎ abcd");
-		assert.ok(rows[1].includes(`${CURSOR_MARKER}\x1b[7ma\x1b[0m\x1b[44m\x1b[7mbc\x1b[27md`), "native selection inversion survives the software cursor reset");
+		assert.ok(rows[1].includes(`${CURSOR_MARKER}\x1b_pi:fc\x07a\x1b_pi:/fc\x07\x1b[7mbc\x1b[27md`), "native selection inversion survives the deferred software cursor reset");
 		assert.match(rows[2], /3 chars selected/);
 		assert.doesNotMatch(rows[2], /╯/);
 		assert.ok(rows[2].includes("\x1b[44m"));

package/tests/session-changes-shell.test.ts

@@ -39,7 +39,7 @@ function fixture(entries: any[] = [], options: { root?: string; sessionId?: stri
 		for(let i=0;i<200&&!overlay.view;i++){ if(await Promise.race([opened.then(()=>true),new Promise(r=>setTimeout(()=>r(false),5))])) break; }
 		if(!overlay.view) return undefined;
 		const text=overlay.view.render(200).join("\n");
-		const trees=(overlay.view.trees as any[]).map(tree=>({root:tree.root as string,branch:tree.branch as string|undefined,files:tree.model.files.map((file:any)=>file.path) as string[],added:tree.model.added as number,deleted:tree.model.deleted as number}));
+		const trees=(overlay.view.children[0].trees as any[]).map(tree=>({root:tree.root as string,branch:tree.branch as string|undefined,files:tree.model.files.map((file:any)=>file.path) as string[],added:tree.model.added as number,deleted:tree.model.deleted as number}));
 		overlay.close!(); await opened;
 		return {text,trees,files:trees.flatMap(tree=>tree.files)};
 	};

package/tests/session-profile-freeze.test.ts

@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test, { after, beforeEach } from "node:test";
 import { createProfile, emptyProfilesFile, profilesFilePath, setActiveProfile, writeProfilesFileSync } from "../lib/agent-profiles.ts";
-import { clearProfilePinSync, localProfilePinPath, repoProfileDeclarationPath, writeProfilePinSync } from "../lib/agent-profile-pin.ts";
+import { clearProfilePinSync, localProfilePinPath, repoProfileDeclarationPath, setProfilePinWorktreeResolverForTesting, writeProfilePinSync } from "../lib/agent-profile-pin.ts";
 import type { AgentModelConfig } from "../lib/model-routing-authority.ts";
 import { bindSessionProfile, resetSessionProfileBindingsForTesting } from "../lib/session-profile-binding.ts";
 import {
@@ -120,6 +120,19 @@ test("resolveInheritedProfile falls to the global active profile in profiles.jso
 	});
 });
 
+test("resolveInheritedProfile asks the default worktree resolver once when no resolver is passed", (t) => {
+	const f = fixture();
+	f.setActive("local");
+	let lookups = 0;
+	setProfilePinWorktreeResolverForTesting(() => { lookups++; return f.identity; });
+	t.after(() => setProfilePinWorktreeResolverForTesting());
+	assert.equal(resolveInheritedProfile({ cwd: f.cwd, configHome: f.configHome })?.name, "local");
+	assert.equal(lookups, 1, "the no-pin path reuses one worktree lookup");
+	f.pinLocal("frontier");
+	assert.equal(resolveInheritedProfile({ cwd: f.cwd, configHome: f.configHome })?.origin, "local");
+	assert.equal(lookups, 2);
+});
+
 test("resolveInheritedProfile returns undefined when no layer has a profile", () => {
 	const f = fixture();
 	assert.equal(resolveInheritedProfile({ cwd: f.cwd, configHome: f.configHome, resolveWorktree: f.resolveWorktree }), undefined);
@@ -282,6 +295,29 @@ test("drift notice: shown once per distinct change of the defaults", () => {
 	assert.equal(readFrozenInheritedProfile("session-a")?.profile?.name, "frontier", "the notice never adopts the new default");
 });
 
+test("drift notice: an explicit binding learns its profile definition changed in profiles.json", () => {
+	const f = fixture({ team: { worker: { model: "openai/old" } } });
+	const opts = options(f, "session-a");
+	bindSessionProfile("session-a", "team", { worker: { model: "openai/old" } });
+	assert.equal(inheritedProfileDriftNotice(opts), undefined, "no drift while the definition matches the binding");
+
+	f.editProfile("team", { worker: { model: "openai/new" } });
+	const notice = inheritedProfileDriftNotice(opts);
+	assert.match(notice ?? "", /the profile definition changed to "team"/);
+	assert.match(notice ?? "", /this session keeps the binding from selection/);
+	assert.equal(inheritedProfileDriftNotice(opts), undefined, "the same change is not repeated");
+
+	f.editProfile("team", { worker: { model: "openai/older" } });
+	assert.match(inheritedProfileDriftNotice(opts) ?? "", /the profile definition changed to "team"/, "a different edit is a distinct change");
+	assert.equal(inheritedProfileDriftNotice(opts), undefined);
+	f.editProfile("team", { worker: { model: "openai/old" } });
+	assert.equal(inheritedProfileDriftNotice(opts), undefined, "reverting to the bound content is not drift");
+
+	const childOpts = options(f, "session-b", { GENTLE_PI_AGENTS_CHILD: "1" });
+	bindSessionProfile("session-b", "team", { worker: { model: "openai/old" } });
+	assert.equal(inheritedProfileDriftNotice(childOpts), undefined, "children never get the notice");
+});
+
 test("drift notice: an edit of the default profile's content counts as a change", () => {
 	const f = fixture();
 	f.setActive("frontier");

package/tests/session-profile-persistence.test.ts

@@ -0,0 +1,334 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+	SESSION_PROFILE_CUSTOM_TYPE,
+	createSessionProfileBind,
+	createSessionProfileClear,
+	readSessionProfileEntry,
+	replaySessionProfileBranch,
+} from "../lib/session-profile-persistence.ts";
+
+import { normalizeModelConfig } from "../lib/model-routing-authority.ts";
+import {
+	normalizeProfilesFile,
+	PROFILES_KIND,
+	PROFILES_VERSION,
+} from "../lib/agent-profiles.ts";
+
+const custom = (data: unknown, customType = SESSION_PROFILE_CUSTOM_TYPE) => ({
+	type: "custom",
+	customType,
+	data,
+});
+const bind = (modelProfiles: unknown = {}) => ({
+	kind: "bind",
+	origin: "user",
+	name: "work",
+	modelProfiles,
+});
+
+// These are supplied branch entries, not evidence of persistence on disk.
+test("writer emits only the v1 user binding fields and a minimal clear", () => {
+	assert.equal(SESSION_PROFILE_CUSTOM_TYPE, "gentle-pi.session-profile/v1");
+	assert.deepEqual(createSessionProfileBind("work", {}), bind());
+	assert.deepEqual(createSessionProfileClear(), { kind: "clear" });
+});
+
+test("writer accepts real normalized optional fields without persisting undefined", () => {
+	const raw = {
+		worker: "provider/model",
+		reviewer: { effort: "high" },
+		orchestrator: { model: "provider/main" },
+		inheriting: {},
+	};
+	const routes = normalizeModelConfig(raw);
+	const profiles = normalizeProfilesFile({
+		kind: PROFILES_KIND,
+		version: PROFILES_VERSION,
+		profiles: { work: raw },
+	});
+	assert.ok(routes);
+	assert.ok(profiles);
+	assert.equal(Object.hasOwn(routes.reviewer, "model"), true);
+	assert.equal(Object.hasOwn(routes.reviewer, "thinking"), true);
+	const expected = bind({
+		worker: { model: "provider/model" },
+		reviewer: { thinking: "high" },
+		orchestrator: { model: "provider/main" },
+		inheriting: {},
+	});
+	for (const config of [routes, profiles.file.profiles.work]) {
+		const payload = createSessionProfileBind("work", config);
+		assert.deepEqual(payload, expected);
+		assert.deepEqual(readSessionProfileEntry(custom(payload)), {
+			status: "bound",
+			binding: expected,
+		});
+		assert.notEqual(payload.modelProfiles.reviewer, config.reviewer);
+	}
+	assert.equal(Object.hasOwn(routes.reviewer, "model"), true);
+});
+
+test("decoder stays strict about present undefined known fields", () => {
+	for (const route of [
+		{ model: undefined },
+		{ thinking: undefined },
+		{ effort: undefined },
+	]) {
+		assert.deepEqual(readSessionProfileEntry(custom(bind({ worker: route }))), {
+			status: "invalid",
+		});
+	}
+});
+
+test("bound empty snapshot is distinct from absent and cleared", () => {
+	assert.deepEqual(readSessionProfileEntry(custom(bind())), {
+		status: "bound",
+		binding: bind(),
+	});
+	assert.deepEqual(replaySessionProfileBranch([]), { status: "absent" });
+	assert.deepEqual(readSessionProfileEntry(custom({ kind: "clear" })), {
+		status: "cleared",
+	});
+});
+
+test("reader accepts all four origins and ignores unknown payload fields", () => {
+	for (const origin of ["user", "local", "repo", "global"]) {
+		assert.deepEqual(
+			readSessionProfileEntry(
+				custom({ ...bind(), origin, extra: true, version: 99 }),
+			),
+			{
+				status: "bound",
+				binding: { ...bind(), origin },
+			},
+		);
+	}
+	assert.deepEqual(
+		readSessionProfileEntry(custom({ kind: "clear", extra: true })),
+		{ status: "cleared" },
+	);
+});
+
+test("legacy strings and effort normalize while orchestrator remains in the snapshot", () => {
+	const result = readSessionProfileEntry(
+		custom(
+			bind({
+				worker: " provider/model ",
+				reviewer: { effort: "high", ignored: true },
+				orchestrator: { model: "provider/main", thinking: "low", effort: "max" },
+				inheriting: {},
+			}),
+		),
+	);
+	assert.deepEqual(result, {
+		status: "bound",
+		binding: bind({
+			worker: { model: "provider/model" },
+			reviewer: { thinking: "high" },
+			orchestrator: { model: "provider/main", thinking: "low" },
+			inheriting: {},
+		}),
+	});
+});
+
+test("missing required fields and invalid known meanings fail closed", () => {
+	const invalid: unknown[] = [
+		null,
+		[],
+		{},
+		{ kind: "other" },
+		{ kind: "bind", name: "work", modelProfiles: {} },
+		{ ...bind(), origin: "future" },
+		{ ...bind(), name: "../work" },
+		{ ...bind(), name: "constructor" },
+		{ ...bind(), modelProfiles: undefined },
+		{ ...bind(), modelProfiles: [] },
+	];
+	for (const data of invalid) {
+		assert.deepEqual(readSessionProfileEntry(custom(data)), {
+			status: "invalid",
+		});
+	}
+});
+
+test("one invalid route invalidates the whole snapshot instead of silently dropping it", () => {
+	const routes: unknown[] = [
+		null,
+		[],
+		3,
+		"bad model",
+		{ model: "bad model", thinking: "low" },
+		{ model: "provider/good", thinking: "extreme" },
+		{ effort: "extreme" },
+		{ thinking: "low", effort: "extreme" },
+		{ model: null },
+	];
+	for (const route of routes) {
+		assert.deepEqual(readSessionProfileEntry(custom(bind({ worker: route }))), {
+			status: "invalid",
+		});
+		assert.deepEqual(
+			readSessionProfileEntry(
+				custom(bind({ good: "provider/good", worker: route })),
+			),
+			{ status: "invalid" },
+		);
+	}
+	assert.deepEqual(readSessionProfileEntry(custom(bind({ "bad role": {} }))), {
+		status: "invalid",
+	});
+});
+
+test("unknown route fields are ignored, including an unknown-only route", () => {
+	assert.deepEqual(
+		readSessionProfileEntry(custom(bind({ worker: { future: true } }))),
+		{
+			status: "bound",
+			binding: bind({ worker: {} }),
+		},
+	);
+});
+
+test("hostile record keys remain own data without changing prototypes", () => {
+	const routes = JSON.parse(
+		'{"__proto__":{"model":"provider/safe"},"constructor":{},"prototype":{}}',
+	);
+	const result = readSessionProfileEntry(custom(bind(routes)));
+	assert.equal(result.status, "bound");
+	if (result.status !== "bound") return;
+	assert.equal(
+		Object.getPrototypeOf(result.binding.modelProfiles),
+		Object.prototype,
+	);
+	assert.equal(Object.hasOwn(result.binding.modelProfiles, "__proto__"), true);
+	assert.deepEqual(result.binding.modelProfiles["__proto__"], {
+		model: "provider/safe",
+	});
+	for (const key of ["constructor", "prototype"]) {
+		assert.equal(Object.hasOwn(result.binding.modelProfiles, key), true);
+		assert.deepEqual(result.binding.modelProfiles[key], {});
+	}
+});
+
+test("required fields cannot be supplied by prototypes", () => {
+	assert.deepEqual(readSessionProfileEntry(custom(Object.create(bind()))), {
+		status: "invalid",
+	});
+});
+
+test("writer rejects invalid input rather than manufacturing an empty snapshot", () => {
+	assert.throws(() => createSessionProfileBind("../bad", {}));
+	assert.throws(() =>
+		createSessionProfileBind("work", { worker: { model: "bad model" } }),
+	);
+	for (const route of [
+		{ model: null },
+		{ model: "bad model", thinking: undefined },
+		{ model: undefined, thinking: "extreme" },
+		{ effort: undefined },
+	]) {
+		assert.throws(() =>
+			createSessionProfileBind("work", {
+				good: { model: "provider/good" },
+				worker: route,
+			} as Parameters<typeof createSessionProfileBind>[1]),
+		);
+	}
+});
+
+test("writer and reader return defensive snapshots", () => {
+	const source = { worker: { model: "provider/first" } };
+	const payload = createSessionProfileBind("work", source);
+	source.worker.model = "provider/second";
+	assert.equal(payload.modelProfiles.worker.model, "provider/first");
+	const entry = custom(payload);
+	const first = readSessionProfileEntry(entry);
+	assert.equal(first.status, "bound");
+	if (first.status !== "bound") return;
+	first.binding.modelProfiles.worker.model = "provider/third";
+	const second = readSessionProfileEntry(entry);
+	assert.equal(second.status, "bound");
+	if (second.status === "bound")
+		assert.equal(second.binding.modelProfiles.worker.model, "provider/first");
+});
+
+test("noncustom and unrelated custom entries are absent even with matching payloads", () => {
+	for (const entry of [
+		{ type: "message", customType: SESSION_PROFILE_CUSTOM_TYPE, data: bind() },
+		{ type: "message", message: { role: "user", content: "hello" } },
+		custom(bind(), "other/v1"),
+	])
+		assert.deepEqual(readSessionProfileEntry(entry), { status: "absent" });
+});
+
+test("newest family entry is terminal and retains its actual branch index", () => {
+	const old = custom(bind({ worker: "provider/old" }));
+	const message = {
+		type: "message",
+		message: { role: "user", content: "hello" },
+	};
+	for (const [entry, status] of [
+		[custom({ kind: "clear" }), "cleared"],
+		[custom({ kind: "bind" }), "invalid"],
+		[custom(bind(), "gentle-pi.session-profile/v2"), "unsupported"],
+	] as const) {
+		assert.deepEqual(
+			replaySessionProfileBranch([old, message, entry, custom({}, "other/v1")]),
+			{
+				status,
+				entryIndex: 2,
+			},
+		);
+	}
+});
+
+test("family identifier, not payload version, determines support", () => {
+	for (const customType of [
+		"gentle-pi.session-profile/v0",
+		"gentle-pi.session-profile/v99",
+		"gentle-pi.session-profile/future",
+	]) {
+		assert.deepEqual(readSessionProfileEntry(custom(null, customType)), {
+			status: "unsupported",
+		});
+	}
+	assert.deepEqual(
+		readSessionProfileEntry(custom(bind(), "gentle-pi.session-profile-other/v1")),
+		{ status: "absent" },
+	);
+});
+
+test("branch order selects latest bind; clear and bad entries can be explicitly superseded", () => {
+	const latest = custom(bind({ worker: "provider/new" }));
+	for (const earlier of [
+		custom({ kind: "clear" }),
+		custom(null),
+		custom(null, "gentle-pi.session-profile/v2"),
+	]) {
+		assert.deepEqual(replaySessionProfileBranch([earlier, latest]), {
+			status: "bound",
+			entryIndex: 1,
+			binding: bind({ worker: { model: "provider/new" } }),
+		});
+	}
+});
+
+test("replay sees only caller-supplied active branch, not siblings or later paths", () => {
+	const ancestor = custom(bind());
+	const sibling = custom({ kind: "clear" });
+	const future = custom(null, "gentle-pi.session-profile/v2");
+	assert.equal(
+		replaySessionProfileBranch([ancestor, sibling]).status,
+		"cleared",
+	);
+	assert.equal(
+		replaySessionProfileBranch([ancestor, future]).status,
+		"unsupported",
+	);
+	assert.deepEqual(replaySessionProfileBranch([ancestor, { type: "message" }]), {
+		status: "bound",
+		entryIndex: 0,
+		binding: bind(),
+	});
+});