gentle-pi 4.1.0 → 4.3.0

package/tests/test-strength-contract.test.ts

@@ -111,7 +111,7 @@ test("T31: high-risk item 3 is about unrequested breaks, not the requested chang
 	);
 });
 
-// T33 (L74): in p31 x5 both runs declared `Risk: none` after adding --year to
+// T33 (L74): in a benchmark run both cells declared `Risk: none` after adding --year to
 // the shared budget options; one shipped `budget set --year` silently saving a
 // wrong budget, the regression verify used to catch. The Risk line must check
 // shared code before claiming none.
@@ -122,3 +122,38 @@ test("T33: the Close step checks shared code before Risk: none", () => {
 		assert.ok(step?.includes(SHARED_CHECK), `${persona} Close step must check shared code before Risk: none`);
 	}
 });
+
+// C8 (benchmark finding): the PRESERVE test alone missed the `budget set
+// --year` regression in 1 of 2 runs. A differential run of every existing
+// command that shares the changed code, old code against new, caught it in
+// 2 of 2. Inline work and the worker carry the same check.
+// S15: the differential check runs in scratch and is never committed as a test (blind round 4 found tests pinning a git commit).
+const DIFFERENTIAL = "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("C8: inline test-first and the worker PRESERVE step run the differential check", () => {
+	for (const persona of ["gentleman", "neutral"] as const) {
+		const principle = __testing.buildGentlePrompt(persona).split("\n").find((line) => line.includes("use test-first by default"));
+		assert.ok(principle?.includes(`${TOUCHED}. ${DIFFERENTIAL}`), `${persona} principle must run the differential check after PRESERVE`);
+	}
+	const step = read("assets/agents/gentle-ai-worker.md").split("\n").find((line) => line.startsWith("3. PRESERVE — "));
+	assert.ok(step?.includes(DIFFERENTIAL), "worker step 3 must run the differential check");
+});
+
+// C3 (benchmark finding): parallel workers appended a shared `Fees` entry
+// inline, unsorted, instead of reusing the helper that keeps the order. The
+// worker reuses the existing function for shared state, and each writer prompt
+// names the helpers to reuse, because parallel units cannot see each other.
+test("C3: the worker reuses the existing function for shared state and keeps its invariants", () => {
+	const worker = read("assets/agents/gentle-ai-worker.md");
+	assert.ok(
+		worker.includes("- Before you create or change shared state (a record, list entry, file, or setting that other commands also create or read), find the existing function that already does it and reuse it, keeping every invariant it enforces (ordering, uniqueness, validation, normalization). Never re-implement that step inline with a different shape."),
+		"worker must reuse the existing shared-state function",
+	);
+	const invariants = read("assets/orchestrator-writer.md").split("\n").find((line) => line.startsWith("- **Invariants**"));
+	for (const clause of [
+		"each writer prompt names the existing helpers its unit must reuse for shared state",
+		"and the invariants they keep",
+		"units built in parallel cannot see each other",
+	]) {
+		assert.ok(invariants?.includes(clause), `writer module invariants reason is missing: ${clause}`);
+	}
+});

package/tests/tool-batching-contract.test.ts

@@ -0,0 +1,64 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+
+// Pain-point iteration S13 (C9/C10, from the S12 session analysis): subagents
+// spent 78% of their turns on a single tool call, and 31% of their turns were
+// consecutive read-only calls one turn could batch; the parent read repo files
+// and then delegated, and 69% of the files it read were read again by the
+// worker. Codex reads 8 files with one command. These are instruction-delivery
+// contracts, not proof of model adherence.
+
+const ROOT = join(import.meta.dirname, "..");
+const read = (path: string): string => readFileSync(join(ROOT, path), "utf8");
+
+function containsAll(text: string, clauses: readonly string[], label: string): void {
+	for (const clause of clauses) assert.ok(text.includes(clause), `${label} is missing: ${clause}`);
+}
+
+function declaredTools(prompt: string): string[] {
+	const frontmatter = prompt.split("\n---\n")[0];
+	return [...frontmatter.matchAll(/^\s+- (\S+)$/gm)].map((match) => match[1]);
+}
+
+test("S13 C9: every generic subagent prompt batches independent tool calls in one turn", () => {
+	for (const agent of ["gentle-ai-worker", "gentle-ai-verify", "gentle-ai-explore"]) {
+		const prompt = read(`assets/agents/${agent}.md`);
+		const rule = prompt.split("\n").find((line) => line.includes("**Batch tool calls:**"));
+		assert.ok(rule, `${agent} must carry the batch tool calls rule`);
+		containsAll(rule, [
+			"issue independent calls together in the same turn (parallel tool calls)",
+			"read each relevant file whole once instead of many small ranges",
+		], agent);
+		const tools = declaredTools(prompt);
+		// A shell-less agent must not be told to read files or run tests with a command it cannot run.
+		if (tools.includes("bash")) {
+			containsAll(rule, ["read several files with one command", "the focused test and the suite without status-only turns"], agent);
+		} else {
+			assert.doesNotMatch(rule, /one command|the suite/, `${agent} has no shell, so its rule must not name a command`);
+		}
+		if (tools.includes("edit")) containsAll(rule, ["all edits to one file in one `edit` call"], agent);
+	}
+});
+
+test("S13 C10: the delegation card keeps the parent from reading what the worker will read", () => {
+	const card = read("assets/orchestrator-delegation.md");
+	const rule = card.split("\n").find((line) => line.startsWith("**Preparation trigger:**"));
+	assert.ok(rule, "the delegation card must carry the Preparation trigger");
+	containsAll(rule, [
+		"When delegating, read only what decides the route",
+		"never the files the worker will read",
+		"pass paths, the spec reference, and what to change, not file contents",
+	], "delegation card preparation trigger");
+});
+
+// S13 C9 parent: 95 of 389 parent turns did only coordination (todo 55, orchestrator_session_id 17,
+// gentle_review assess 14, subagent_list_agents 8) and parent multi-tool turns were ~0.
+test("S13 C9: the always-on orchestrator batches independent calls and never spends a turn only on coordination", () => {
+	const core = read("assets/orchestrator.md");
+	containsAll(core, [
+		"Batch independent tool calls in one turn (parallel calls or one multi-file command).",
+		"Never spend a turn only on a `todo` or status update.",
+	], "orchestrator core");
+});

package/tests/verification-proportionality.test.ts

@@ -0,0 +1,46 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+
+const read = (path: string) => readFileSync(new URL(`../${path}`, import.meta.url), "utf8");
+const verify = read("assets/agents/gentle-ai-verify.md");
+const policy = read("assets/orchestrator-verification.md");
+const parent = read("assets/orchestrator.md");
+
+// Instruction-delivery checks, not evidence of model adherence or delivery time.
+test("unit verification keeps whole-feature context without blocking on future work", () => {
+  for (const text of [verify, policy]) {
+    assert.ok(text.includes("out of scope, not unmet"));
+    assert.ok(text.includes("affected interactions"));
+  }
+  assert.ok(!verify.includes("no partial-scope carve-out"));
+  assert.ok(verify.includes("At final feature verification, cover every requirement"));
+  assert.ok(policy.includes("final feature verification covers every `S#`"));
+  assert.ok(verify.includes("met, unmet, not implemented, or out of scope"));
+  assert.ok(verify.includes("unrelated future work must not block that unit"));
+});
+
+test("observed writer evidence is reusable but does not replace independent probes", () => {
+  assert.ok(verify.includes("Reuse observed writer checks when their candidate and scope remain valid"));
+  assert.ok(verify.includes("independent probes"));
+  assert.ok(!verify.includes("never evidence of correctness"));
+});
+
+test("auxiliary gates must protect a concrete requirement or threat", () => {
+  assert.ok(parent.includes("gates/overengineering: `orchestrator-verification.md`"));
+  assert.ok(policy.includes("acceptance criterion, concrete threat, or authoritative contract"));
+  assert.ok(policy.includes("must not become a delivery blocker"));
+  assert.ok(policy.includes("Do not build a framework for a bounded capability probe"));
+});
+
+test("overengineering warnings visibly simplify the plan without weakening safeguards", () => {
+  assert.ok(policy.includes("remove or collapse optional artifacts and checks"));
+  assert.ok(policy.includes("State what was removed, what remains indispensable, and the next application outcome"));
+  assert.ok(policy.includes("Keep required functional checks, security controls, and native review authority intact"));
+});
+
+test("existing verification isolation and bounded correction remain required", () => {
+  assert.ok(verify.includes("run it only against isolated state"));
+  assert.ok(verify.includes("one correction batch and one recheck limited to the reported blockers"));
+  assert.ok(policy.includes("Advisories never start a correction"));
+});

package/tests/verifier-admission.test.ts

@@ -0,0 +1,137 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { createGentleAiExtension } from "../extensions/gentle-ai.ts";
+import { rejectUnriskedVerifierLaunch } from "../lib/verifier-admission.ts";
+
+// odd/tasks/verifier-admission.md S2: a bench gate run launched `gentle-ai-verify` on a small, not high-risk task
+// although the prompt's Verification rule reserves the independent verifier for a named high-risk item. The runtime
+// now admits a primary-session verifier launch only with a `Risk: item N` line, a feature-document task, or a
+// measured context at the backstop.
+
+const quiet = { tokens: 20_000, contextWindow: 400_000 };
+
+function workspace(withDocument: boolean): string {
+	const root = mkdtempSync(join(tmpdir(), "verifier-admission-"));
+	if (withDocument) {
+		mkdirSync(join(root, "odd", "tasks"), { recursive: true });
+		writeFileSync(join(root, "odd", "tasks", "ledger.md"), "# Ledger\n");
+	}
+	return root;
+}
+
+test("S3/S4: a verifier launch without a high-risk line is rejected with an inline instruction", (t) => {
+	const root = workspace(false);
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	for (const task of ["Verify the annual budget change.", "Verify it.\nRisk: none", "Verify it.\nRisk: none (local rename)"]) {
+		const denied = rejectUnriskedVerifierLaunch({ agent: "gentle-ai-verify", task }, { root, contextUsage: quiet });
+		assert.ok(denied?.block, `${JSON.stringify(task)} must be blocked`);
+		assert.match(denied.reason, /independent verifier runs only for a change that declares a named high-risk item/);
+		assert.match(denied.reason, /focused test and suite inline/);
+		assert.match(denied.reason, /do not retry the launch/);
+		assert.match(denied.reason, /never add a Risk line or create a feature document only to get a verifier admitted/);
+		assert.doesNotMatch(denied.reason, /claude|gpt|openai|anthropic|gemini|sonnet|opus/i, "the message stays generic");
+	}
+});
+
+test("S3: a Risk line naming a Task Size high-risk item admits the verifier", (t) => {
+	const root = workspace(false);
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	for (const line of ["Risk: item 3 (shared parser)", "- Risk: item 2, item 3 (auth and parser)", "Risk: item 6", "  Risk:item 1"]) {
+		assert.equal(rejectUnriskedVerifierLaunch({ agent: "gentle-ai-verify", task: `Verify the change.\n${line}\n` }, { root, contextUsage: quiet }), undefined, line);
+	}
+	const viaContext = { agent: "gentle-ai-verify", task: "Verify the change.", context: "Risk: item 4 (migration)" };
+	assert.equal(rejectUnriskedVerifierLaunch(viaContext, { root, contextUsage: quiet }), undefined, "the context carries the line");
+});
+
+test("S3: an item outside 1-6, a Risk mention inside prose, or none first is rejected", (t) => {
+	const root = workspace(false);
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	for (const line of ["Risk: item 7", "Risk: item 0", "Risk: item 12", "Do not write Risk: item 3 here.", "Risk: none; item 3 does not apply", "Risk: items"]) {
+		assert.ok(rejectUnriskedVerifierLaunch({ agent: "gentle-ai-verify", task: `Verify it.\n${line}` }, { root, contextUsage: quiet })?.block, line);
+	}
+});
+
+test("S3: a task of an existing feature document admits the verifier; a missing document does not", (t) => {
+	const documented = workspace(true);
+	const bare = workspace(false);
+	t.after(() => { rmSync(documented, { recursive: true, force: true }); rmSync(bare, { recursive: true, force: true }); });
+	const input = { agent: "gentle-ai-verify", task: 'Spec: odd/tasks/ledger.md (read until "## Log"). Verify T2; S3.' };
+	assert.equal(rejectUnriskedVerifierLaunch(input, { root: documented, contextUsage: quiet }), undefined);
+	assert.ok(rejectUnriskedVerifierLaunch(input, { root: bare, contextUsage: quiet })?.block, "a missing document does not admit");
+});
+
+test("S3: the measured context backstop admits the verifier", (t) => {
+	const root = workspace(false);
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	const input = { agent: "gentle-ai-verify", task: "Verify the change." };
+	assert.equal(rejectUnriskedVerifierLaunch(input, { root, contextUsage: { tokens: 150_000, contextWindow: 1_000_000 } }), undefined);
+	assert.equal(rejectUnriskedVerifierLaunch(input, { root, contextUsage: { tokens: 19_200, contextWindow: 128_000 } }), undefined, "15% of a small window admits");
+	assert.ok(rejectUnriskedVerifierLaunch(input, { root, contextUsage: { tokens: 149_999, contextWindow: 1_000_000 } })?.block);
+	assert.ok(rejectUnriskedVerifierLaunch(input, { root, contextUsage: undefined })?.block, "missing context usage does not admit");
+});
+
+test("S5: other agents are not gated by the verifier admission", (t) => {
+	const root = workspace(false);
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	for (const agent of ["gentle-ai-worker", "worker", "gentle-ai-explore", "jd-fix-agent", "jd-judge-a", "jd-judge-b", "review-risk", "verify"]) {
+		assert.equal(rejectUnriskedVerifierLaunch({ agent, task: "Check src/budget.ts" }, { root, contextUsage: quiet }), undefined, agent);
+	}
+	for (const input of [undefined, null, "gentle-ai-verify", ["gentle-ai-verify"], { task: "Verify it." }]) {
+		assert.equal(rejectUnriskedVerifierLaunch(input, { root, contextUsage: quiet }), undefined, JSON.stringify(input));
+	}
+});
+
+type ToolCallHandler = (event: { toolName: string; input: unknown }, ctx: ExtensionContext) => Promise<{ block?: boolean; reason?: string } | undefined>;
+
+function toolCallThroughHook(toolName: string, input: Record<string, unknown>, cwd: string, tokens: number, processEnv: NodeJS.ProcessEnv = {}) {
+	const handlers = new Map<string, ToolCallHandler>();
+	const pi = { on(name: string, handler: ToolCallHandler) { handlers.set(name, handler); }, events: { emit() {} }, registerCommand() {}, registerTool() {} } as unknown as ExtensionAPI;
+	createGentleAiExtension({ nativeReviewCli: null, processEnv })(pi);
+	return handlers.get("tool_call")!({ toolName, input }, {
+		cwd, hasUI: false, ui: { confirm: async () => true },
+		getContextUsage: () => ({ tokens, contextWindow: 272_000, percent: Math.round((tokens / 272_000) * 100) }),
+	} as unknown as ExtensionContext);
+}
+
+test("S3/S5: the orchestrator tool_call hook gates only primary verifier launches", async (t) => {
+	const bare = workspace(false);
+	const documented = workspace(true);
+	t.after(() => { rmSync(bare, { recursive: true, force: true }); rmSync(documented, { recursive: true, force: true }); });
+	const blocked = await toolCallThroughHook("subagent_run", { agent: "gentle-ai-verify", mode: "task", task: "Verify the budget change." }, bare, 20_000);
+	assert.equal(blocked?.block, true);
+	assert.match(blocked?.reason ?? "", /focused test and suite inline/);
+	const risked = await toolCallThroughHook("subagent_run", { agent: "gentle-ai-verify", mode: "task", task: "Verify the budget change.\nRisk: item 3 (shared parser)" }, bare, 20_000);
+	assert.equal(risked?.block, undefined, "a named high-risk item admits");
+	const documentedLaunch = await toolCallThroughHook("subagent_run", { agent: "gentle-ai-verify", mode: "task", workspace_root: documented, task: "Spec: odd/tasks/ledger.md, T1. Verify it." }, bare, 20_000);
+	assert.equal(documentedLaunch?.block, undefined, "the feature document resolves under the selected workspace root");
+	const backstop = await toolCallThroughHook("subagent_run", { agent: "gentle-ai-verify", mode: "task", task: "Verify the budget change." }, bare, 136_000);
+	assert.equal(backstop?.block, undefined, "half of the measured window admits");
+	const child = await toolCallThroughHook("subagent_run", { agent: "gentle-ai-verify", mode: "task", task: "Verify it." }, bare, 0, { GENTLE_PI_AGENTS_CHILD: "1" });
+	assert.equal(child?.block, undefined, "a child session is not gated");
+	const continuation = await toolCallThroughHook("subagent_continue", { agent: "gentle-ai-verify", task_id: "t-1", task: "Recheck it." }, bare, 0);
+	assert.notEqual(continuation?.reason, blocked?.reason, "a continuation is not gated by the verifier admission");
+	for (const agent of ["gentle-ai-explore", "jd-judge-a", "jd-judge-b"]) {
+		const other = await toolCallThroughHook("subagent_run", { agent, mode: "task", task: "Map src/budget.ts" }, bare, 0);
+		assert.equal(other?.block, undefined, `${agent} is unaffected`);
+	}
+	// A native review relay keeps its own candidate-view gate, which already rejects a dispatch without a frozen view.
+	const relay = await toolCallThroughHook("subagent_run", { agent: "review-risk", mode: "task", task: "Review the candidate." }, bare, 0);
+	assert.match(relay?.reason ?? "", /^review subagent dispatch /, "review relays keep their previous gate");
+	const writer = await toolCallThroughHook("subagent_run", { agent: "gentle-ai-worker", mode: "background", task: "Implement it.\nRisk: item 3\n\n## Allowed edit surfaces\nsrc/budget.ts\n" }, bare, 0);
+	assert.match(writer?.reason ?? "", /write this unit inline yourself/, "writer admission is unchanged and ignores Risk lines");
+});
+
+test("S6: the Verification rule and the reference docs point at the runtime admission", () => {
+	const read = (path: string) => readFileSync(join(import.meta.dirname, "..", path), "utf8");
+	assert.ok(read("assets/orchestrator.md").includes("independent `gentle-ai-verify`; else inline; runtime admission, gates/overengineering"), "the core rule names the runtime check");
+	assert.ok(read("assets/orchestrator-verification.md").includes("(the runtime admits its launch on a `Risk: item N` line, a feature-document task line, or past the context backstop)"), "the normative rule names the admitted line");
+	const docs = read("docs/readme-reference.md");
+	const writer = docs.indexOf("A second admission check stops small-task delegation");
+	const verifier = docs.indexOf("A third admission check keeps the independent verifier for high-risk changes");
+	assert.ok(writer >= 0 && verifier > writer, "the verifier admission is documented right after the writer admission");
+	assert.match(docs.slice(verifier, docs.indexOf("\n\n", verifier)), /`gentle-ai-verify` launch is admitted only when[^]*`Risk: item N`[^]*context backstop/);
+});

package/tests/verify-agent-contract.test.ts

@@ -23,11 +23,11 @@ function containsAll(text: string, clauses: readonly string[], label: string): v
 	for (const clause of clauses) assert.ok(text.includes(clause), `${label} is missing: ${clause}`);
 }
 
-test("T11.1: verify derives its own probes from every numbered rule and never trusts the writer's tests", () => {
-	assert.ok(verify.includes("The writer's tests and examples are never evidence of correctness"), "verify must not treat the writer's tests as evidence");
+test("T11.1: verify reuses valid evidence without replacing independent spec-derived probes", () => {
+	assert.ok(verify.includes("they are evidence, not a substitute for the independent probes required by the risk tier"));
 	containsAll(checklistItem(1), [
 		"verbatim request",
-		"every numbered rule or requirement",
+		"every in-scope numbered rule or requirement",
 		"derive your own probes",
 		"positive examples",
 		"negative and boundary cases",
@@ -54,13 +54,13 @@ test("T11.4: verify runs the typecheck or build and flags scope creep", () => {
 	containsAll(checklistItem(4), ["typecheck or build", "when the project has one", "outside the request's scope"], "build and scope item");
 });
 
-test("T11.5: verify returns a verdict for every spec item with no partial-scope carve-out", () => {
+test("T11.5: verify distinguishes unit exclusions from unmet spec items", () => {
 	containsAll(checklistItem(5), [
 		"verdict for EVERY spec item",
-		"met, unmet, or not implemented",
-		"no partial-scope carve-out",
-		"even when the parent named one task or unit",
-		"the parent resolves every unmet item before closing, with one correction batch and one recheck limited to the reported blockers",
+		"met, unmet, not implemented, or out of scope",
+		"assess only its requirements and affected interactions",
+		"unrelated future work must not block that unit",
+		"the parent resolves every in-scope unmet item before closing, with one correction batch and one recheck limited to the reported blockers",
 	], "verdict item");
 	assert.ok(verify.includes("verdict per `S#`"), "the feature-document verdict per S# must stay");
 });

package/tests/vim-editor-adapter.test.ts

@@ -5,12 +5,17 @@ import { tmpdir } from "node:os";
 import { createRequire } from "node:module";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { dirname, resolve } from "node:path";
-import { CURSOR_MARKER, Editor, visibleWidth } from "@earendil-works/pi-tui";
+import { CURSOR_MARKER, Editor, TuiMainScreen, visibleWidth } from "@earendil-works/pi-tui";
 import { AUDITED_PI_EDITOR_VERSIONS, createVimEditorAdapter, isAuditedPiEditorVersion } from "../lib/vim-editor-adapter.ts";
 import { resolveVimRuntime, VIM_AGENT_INDEX_PATTERN, VIM_CLI_ENTRY_PATTERN } from "../extensions/gentle-shell.ts";
 import { VimOperatorEngine } from "../lib/vim-operator-engine.ts";
 import { VimVisualEngine } from "../lib/vim-visual-engine.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);
+}
+
 function editor(): Editor {
   return new Editor({ terminal: { rows: 24 }, requestRender() {} } as never, { borderColor: (s: string) => s } as never);
 }
@@ -20,6 +25,8 @@ function editor(): Editor {
 function paintedCells(row: string): Array<{ char: string; inverse: boolean }> {
   const cells: Array<{ char: string; inverse: boolean }> = [];
   let inverse = false;
+  // Decode the actual host post-pass, including hardware cursor suppression.
+  row = resolveFakeCursors([row])[0]!;
   const tokens = row.match(/\x1b\[[0-9;]*m|\x1b_pi:c\x07|[^\x1b]/g) ?? [];
   assert.equal(tokens.join(""), row, "only known editor escape sequences are present");
   for (const token of tokens) {
@@ -270,12 +277,12 @@ test("resolveVimRuntime resolves local bundle cli entrypoint when provided", ()
 });
 
 test("audited Pi editor releases are one frozen exact allowlist that includes the installed TUI", () => {
-  assert.deepEqual([...AUDITED_PI_EDITOR_VERSIONS], ["0.99.1", "0.99.2", "1.0.0", "1.1.0"]);
+  assert.deepEqual([...AUDITED_PI_EDITOR_VERSIONS], ["0.99.1", "0.99.2", "1.0.0", "1.1.0", "1.2.0"]);
   assert.equal(bundledAgent.VERSION, INSTALLED_PI, "bundled and local metadata must describe the same actual installed release");
   assert.ok(Object.isFrozen(AUDITED_PI_EDITOR_VERSIONS));
   assert.throws(() => (AUDITED_PI_EDITOR_VERSIONS as unknown as string[]).push("0.99.3"), TypeError);
   assert.ok(isAuditedPiEditorVersion(INSTALLED_PI), `installed pi-tui ${INSTALLED_PI} must be audited`);
-  for (const unknown of ["0.99.3", "0.99.10", "0.99", "v0.99.2", " 0.99.2", "0.99.2-rc.1", ">=0.99.2", "1.0.1", ">=1.0.0", "v1.0.0", " 1.0.0", "1.0.0-rc.1", undefined, 99.2]) {
+  for (const unknown of ["0.99.3", "0.99.10", "0.99", "v0.99.2", " 0.99.2", "0.99.2-rc.1", ">=0.99.2", "1.0.1", ">=1.0.0", "v1.0.0", " 1.0.0", "1.0.0-rc.1", "1.2.1", "1.2.0-rc.1", "v1.2.0", ">=1.2.0", undefined, 99.2]) {
     assert.equal(isAuditedPiEditorVersion(unknown), false, String(unknown));
   }
 });
@@ -309,6 +316,8 @@ test("bundled host admits each audited release and rejects unknown or mismatched
     assert.equal(resolveVimRuntime(fabricatedPiCli(t, version), bundledAgent.CustomEditor), undefined, version);
   }
   assert.equal(resolveVimRuntime(fabricatedPiCli(t, "1.0.0", "1.0.0", "0.99.2"), bundledAgent.CustomEditor), undefined);
+  assert.equal(resolveVimRuntime(fabricatedPiCli(t, "1.2.1"), bundledAgent.CustomEditor), undefined);
+  assert.equal(resolveVimRuntime(fabricatedPiCli(t, "1.2.0", "1.2.0", "1.1.0"), bundledAgent.CustomEditor), undefined);
 });
 
 test("installed agent/TUI pair admits each audited release and skips unknown or mismatched pairs", (t) => {
@@ -343,6 +352,8 @@ test("adapter admits each verified audited release and rejects unknown or mismat
     assert.throws(() => createVimEditorAdapter(editor(), version), /unsupported/i, version);
   }
   assert.throws(() => createVimEditorAdapter(e, "1.0.0", BundledEditor, "0.99.2"), /unsupported/i);
+  assert.throws(() => createVimEditorAdapter(e, "1.2.1", BundledEditor, "1.2.1"), /unsupported/i);
+  assert.throws(() => createVimEditorAdapter(e, "1.2.0", BundledEditor, "1.1.0"), /unsupported/i);
   assert.equal(e.getText(), "untouched");
   assert.deepEqual(e.getCursor(), cursor);
   assert.deepEqual(e.render(30), frame);
@@ -638,24 +649,39 @@ test("operator insertion and registered marker guards keep one undo snapshot", (
   assert.equal(paste.getExpandedText(), "z".repeat(1001));
 });
 
+test("Pi 1.2 selection preserves fake markers and host hardware-cursor suppression", () => {
+  const e = editor();
+  e.setText("abcd");
+  e.focused = true;
+  const adapter = createVimEditorAdapter(e, INSTALLED_PI);
+  adapter.move({ line: 0, col: 1 });
+  const rows = adapter.renderSelection(20, { line: 0, col: 0 }, { line: 0, col: 4 });
+  assert.ok(rows[1]!.includes(`${CURSOR_MARKER}\x1b_pi:fc\x07`));
+  assert.ok(rows[1]!.includes("\x1b_pi:/fc\x07"));
+  for (const hardware of [false, true]) {
+    const resolved = resolveFakeCursors(rows, hardware);
+    assert.deepEqual(paintedCells(resolved[1]!).slice(0, 4), "abcd".split("").map(char => ({ char, inverse: true })));
+    assert.ok(resolved.every(row => visibleWidth(row) === 20));
+  }
+  const boundary = adapter.renderSelection(20, { line: 0, col: 0 }, { line: 0, col: 1 });
+  assert.ok(boundary[1]!.includes(`${CURSOR_MARKER}\x1b_pi:fc\x07`));
+  assert.deepEqual(selectedColumns(resolveFakeCursors(boundary, true)[1]!), [0]);
+  assert.deepEqual(selectedColumns(resolveFakeCursors(boundary, false)[1]!), [0, 1]);
+  const legacy = e.render(20);
+  legacy[1] = legacy[1]!.replaceAll("\x1b_pi:fc\x07", "\x1b[7m").replaceAll("\x1b_pi:/fc\x07", "\x1b[0m");
+  assert.deepEqual(selectedColumns(adapter.renderSelection(20, { line: 0, col: 0 }, { line: 0, col: 4 }, legacy)[1]!), [0, 1, 2, 3]);
+  const unknown = e.render(20).map(row => row.replace("\x1b_pi:fc\x07", "\x1b_pi:unknown\x07"));
+  assert.deepEqual(adapter.renderSelection(20, { line: 0, col: 0 }, { line: 0, col: 4 }, unknown), unknown);
+});
+
 test("selection survives fake cursor reset and retains surrounding color", () => {
   const e = editor();
   e.setText("abcd");
   createVimEditorAdapter(e, INSTALLED_PI).move({ line: 0, col: 1 });
   const frame = createVimEditorAdapter(e, INSTALLED_PI).renderSelection(20, { line: 0, col: 0 }, { line: 0, col: 4 });
   const row = frame.find((line) => line.includes("a")) ?? frame.join("");
-  let reverse = false;
-  const selected: string[] = [];
-  for (const token of row.matchAll(/\x1b\[[0-9;]*m|[^\x1b]/g)) {
-    const value = token[0];
-    if (value.startsWith("\x1b[")) {
-      for (const code of value.slice(2, -1).split(";").map(Number)) {
-        if (code === 0 || code === 27) reverse = false;
-        if (code === 7) reverse = true;
-      }
-    } else if ("abcd".includes(value)) selected.push(reverse ? value : `!${value}`);
-  }
-  assert.deepEqual(selected, ["a", "b", "c", "d"], "every visible cell must have effective reverse SGR");
+  assert.deepEqual(paintedCells(row).slice(0, 4), "abcd".split("").map(char => ({ char, inverse: true })),
+    "every visible cell must have effective reverse SGR after the host post-pass");
 });
 
 test("truecolor channels do not change inverse state across selected and unselected cells", () => {

package/tests/windows-hidden-processes.test.ts

@@ -37,6 +37,8 @@ function fakeGitResult(command: string, args: readonly string[], cwd: string): s
 	if (args.includes("--git-common-dir")) return `${cwd}/.git`;
 	if (args.includes("--show-object-format")) return "sha1";
 	if (args.includes("--is-shallow-repository")) return "false";
+	if (args.includes("--is-inside-work-tree")) return "true";
+	if (args.includes("info/exclude")) return join(cwd, ".git", "info", "exclude");
 	if (args.includes("--git-path")) return join(cwd, ".git", "gentle-ai", "reviews");
 	if (args.includes("--max-parents=0")) return "a".repeat(40);
 	if (args[0] === "cat-file" && args[1] === "-t") return "tree";
@@ -169,6 +171,9 @@ async function captureOwnedRoutes(t: TestContext): Promise<{ captures: Capture[]
 			{ kind: "execFileSync", command: "git", args: ["rev-parse", "--show-toplevel"] },
 			{ kind: "execFile", command: "codegraph", args: ["init", cwd] },
 			...fallbackCalls,
+			// A successful init keeps .codegraph/ out of git through the local exclude file.
+			{ kind: "execFileSync", command: "git", args: ["rev-parse", "--is-inside-work-tree"] },
+			{ kind: "execFileSync", command: "git", args: ["rev-parse", "--git-path", "info/exclude"] },
 		]);
 		const graphText = String((graphResult as { content?: Array<{ text?: string }> }).content?.[0]?.text ?? "");
 		assert.match(graphText, /indexed/, "CodeGraph must return the fixture command result");

package/tests/writer-edit-surface-scope.test.ts

@@ -54,10 +54,13 @@ function dispatchWriter(input: Record<string, unknown>) {
 	assert.equal(typeof toolCall, "function");
 	const cwd = mkdtempSync(join(tmpdir(), "gentle-pi-writer-surfaces-"));
 	scratchRoots.push(cwd);
+	// S16: these tests cover the surface rule; a measured context at the backstop admits the launch so the
+	// feature-document admission (tests/writer-feature-document-admission.test.ts) does not decide here.
 	return toolCall!({ toolName: "subagent_run", input }, {
 		cwd,
 		hasUI: false,
 		ui: { confirm: async () => true },
+		getContextUsage: () => ({ tokens: 150_000, contextWindow: 272_000, percent: 55 }),
 	} as unknown as ExtensionContext);
 }