gentle-pi 4.3.0 → 4.4.0

package/tests/shell-changes.test.ts

@@ -15,6 +15,7 @@ import {
 	foreignRootBranch,
 	parseWorktrees,
 	changesSummary,
+	changesDigest,
 	emptyChanges,
 	parseNumstat,
 	parsePorcelain,
@@ -101,6 +102,36 @@ test("changesModel sorts files by path and totals the counts", () => {
 	assert.equal(model.deleted, 2);
 });
 
+// The footer Status memo reads the changes digest on every keystroke, so the
+// model stores it once per build and reading it never walks the file list.
+// The digest hashes every per-file tuple the renderer consumes (path, status,
+// counts, diffRevision, countsUnavailable); a 64-bit collision could only
+// skip one refresh until the next change moves it again -- never render a
+// wrong picture.
+test("the changes digest is stored on the model and stays equal while nothing moves", () => {
+	const files = [file("lib/a.ts", 4, 2), file("lib/b.ts", 10, 0, CHANGE_STATUS.ADDED)];
+	const model = changesModel([...files]);
+	assert.equal(Object.hasOwn(model, "digest"), true, "the digest is a stored field, not recomputed per read");
+	assert.equal(model.digest, changesDigest(model), "the stored digest matches an independently computed one");
+	assert.equal(changesModel([...files]).digest, model.digest, "an unchanged model rebuilds to the same digest");
+	assert.equal(emptyChanges().digest, emptyChanges().digest, "the empty model carries a stable digest");
+});
+
+test("the changes digest moves with every per-file detail the renderer consumes", () => {
+	const base = changesModel([file("lib/a.ts", 4, 2)]).digest;
+	const digestFor = (files: ChangedFile[]) => changesModel(files).digest!;
+	assert.notEqual(digestFor([file("lib/a.ts", 4, 2, CHANGE_STATUS.RENAMED)]), base, "a status change moves the digest even at equal counts");
+	assert.notEqual(digestFor([file("lib/a.ts", 5, 2)]), base, "an added-count change moves the digest");
+	assert.notEqual(digestFor([file("lib/a.ts", 4, 3)]), base, "a deleted-count change moves the digest");
+	assert.notEqual(digestFor([file("lib/b.ts", 4, 2)]), base, "a path change moves the digest");
+	const revised = file("lib/a.ts", 4, 2);
+	revised.diffRevision = "abc123";
+	assert.notEqual(digestFor([revised]), base, "a diffRevision change moves the digest");
+	const partial = file("lib/a.ts", 4, 2);
+	partial.countsUnavailable = "timeout";
+	assert.notEqual(digestFor([partial]), base, "countsUnavailable moves the digest");
+});
+
 test("changesSummary and the widget describe the session at a glance", () => {
 	const model = changesModel([file("extensions/gentle-shell.ts", 31, 0, CHANGE_STATUS.ADDED), file("lib/shell-bar.ts", 9, 7), file("tests/x.test.ts", 2, 0)]);
 	assert.equal(changesSummary(model), "3 files · +42 −7");
@@ -121,6 +152,14 @@ test("renderChangesWidget colors counts by direction and yields nothing when cle
 	assert.deepEqual(renderChangesWidget(emptyChanges(), plainTheme, 120), []);
 });
 
+// The unborn state (no commits yet) is silence in the idle bar: the widget
+// renders only tracked files, and /gentle:changes explains the state on demand.
+test("renderChangesWidget stays silent when nothing is tracked", () => {
+	assert.deepEqual(renderChangesWidget(emptyChanges(), plainTheme, 120), []);
+	assert.deepEqual(renderChangesWidget(emptyChanges(), taggedTheme, 400), []);
+	assert.deepEqual(renderChangesWidget(emptyChanges(), plainTheme, 12), []);
+});
+
 test("renderChangesWidget drops the file list before truncating on narrow terminals", () => {
 	const model = changesModel([file("a/very/long/path/one.ts", 1, 0), file("a/very/long/path/two.ts", 1, 0)]);
 	const [line] = renderChangesWidget(model, plainTheme, 40);
@@ -132,6 +171,67 @@ test("renderChangesWidget drops the file list before truncating on narrow termin
 	assert.match(tiny, /^✎ 2 files/);
 });
 
+// Repeated frames hit the widget from two surfaces (the sidebar part and the
+// below-input header row), but its paint depends only on what the model digest
+// already covers plus the width and the theme. A counting theme is the seam: a
+// cache hit paints nothing, so theme.fg stays silent instead of walking files.
+function countingTheme() {
+	let calls = 0;
+	return {
+		get fgCalls() {
+			return calls;
+		},
+		fg(_color: string, text: string) {
+			calls += 1;
+			return text;
+		},
+	};
+}
+
+test("renderChangesWidget memoizes a frame per digest, width and theme so an unchanged model repaints nothing", () => {
+	const model = changesModel([file("lib/a.ts", 4, 2), file("lib/b.ts", 10, 0, CHANGE_STATUS.ADDED)]);
+	const theme = countingTheme();
+	const first = renderChangesWidget(model, theme, 120);
+	assert.ok(theme.fgCalls > 0, "the first render paints");
+	const afterFirst = theme.fgCalls;
+	const second = renderChangesWidget(model, theme, 120);
+	assert.deepEqual(second, first, "an unchanged model, width and theme return the same rows");
+	assert.equal(theme.fgCalls, afterFirst, "a memo hit repaints nothing: no per-file iteration");
+});
+
+test("renderChangesWidget re-renders when the digest moves", () => {
+	const theme = countingTheme();
+	const before = changesModel([file("lib/a.ts", 4, 2)]);
+	renderChangesWidget(before, theme, 120);
+	const afterFirst = theme.fgCalls;
+	const moved = changesModel([file("lib/a.ts", 5, 2)]);
+	assert.notEqual(moved.digest, before.digest, "a count change moves the digest");
+	const lines = renderChangesWidget(moved, theme, 120);
+	assert.ok(theme.fgCalls > afterFirst, "a digest change re-renders");
+	assert.match(lines.join("\n"), /\+5/, "the re-render shows the new totals");
+});
+
+test("renderChangesWidget re-renders when the width or the theme changes", () => {
+	const model = changesModel([file("lib/a.ts", 4, 2)]);
+	const theme = countingTheme();
+	const wide = renderChangesWidget(model, theme, 400);
+	const afterWide = theme.fgCalls;
+	renderChangesWidget(model, theme, 40);
+	assert.ok(theme.fgCalls > afterWide, "a width change re-renders");
+	const otherTheme = countingTheme();
+	assert.deepEqual(renderChangesWidget(model, otherTheme, 400), wide, "a new theme object repaints the same wide frame");
+	assert.ok(otherTheme.fgCalls > 0, "the new theme did the painting");
+});
+
+test("renderChangesWidget never caches a digest-less model", () => {
+	const model = { files: [file("lib/a.ts", 4, 2)], added: 4, deleted: 2 };
+	const theme = countingTheme();
+	renderChangesWidget(model, theme, 120);
+	const afterFirst = theme.fgCalls;
+	renderChangesWidget(model, theme, 120);
+	assert.ok(theme.fgCalls > afterFirst, "a hand-built model without a digest re-renders every call");
+});
+
 function fakeGit(numstats: string[], porcelains: string[], code = 0) {
 	const calls: string[][] = [];
 	let round = 0;
@@ -336,7 +436,6 @@ test("foreignRootBranch still reports a genuine detached HEAD as undefined, not
 test("a root missing from worktree list resolves its own branch instead of defaulting to detached", async (t) => {
 	const scenarios: Array<{ name: string; symbolic: { stdout: string; code: number }; verify: { stdout: string; code: number }; expected: string | undefined }> = [
 		{ name: "a normal branch on a foreign clone", symbolic: { stdout: "feature\n", code: 0 }, verify: { stdout: "deadbeef\n", code: 0 }, expected: "feature" },
-		{ name: "an unborn branch (no commits yet)", symbolic: { stdout: "main\n", code: 0 }, verify: { stdout: "", code: 1 }, expected: "no commits yet" },
 		{ name: "a genuinely detached HEAD", symbolic: { stdout: "", code: 1 }, verify: { stdout: "deadbeef\n", code: 0 }, expected: undefined },
 	];
 	for (const scenario of scenarios) {
@@ -358,9 +457,57 @@ test("a root missing from worktree list resolves its own branch instead of defau
 			assert.deepEqual(tracker.worktrees.map((tree) => [tree.root, tree.branch]), [["/foreign", scenario.expected]]);
 			assert.ok(calls.some((args) => args[0] === "symbolic-ref"), "a root absent from worktree list must be asked directly");
 		});
+		// An unborn foreign root is a holder before it is a branch question: with
+		// no commits there is no baseline to diff against, so it is skipped --
+		// neither dirty nor failed -- before any branch lookup happens.
+		await t.test("an unborn foreign root is skipped as a holder before the branch ask", async () => {
+			const calls: string[][] = [];
+			const tracker = new WorktreeChangesTracker(
+				async () => ({ stdout: "", code: 0 }),
+				() => async (args) => {
+					calls.push(args);
+					if (args[0] === "rev-parse") return { stdout: "", code: 1 };
+					return { stdout: "", code: 0 };
+				},
+				undefined,
+				() => ["/foreign"],
+			);
+			await tracker.start();
+			assert.deepEqual(tracker.worktrees, []);
+			assert.deepEqual(tracker.unbornRoots, ["/foreign"]);
+			assert.deepEqual(tracker.failedRoots, []);
+			assert.ok(!calls.some((args) => args[0] === "symbolic-ref"), "a skipped holder is never asked for a branch");
+		});
 	}
 });
 
+// A worktree-holder repository (no commits, only linked worktrees inside) has
+// no baseline: `git diff HEAD` is meaningless and every file reports
+// untracked, so scanning it floods Changes with thousands of phantom files.
+// It is skipped as neither dirty nor failed, and its first commit starts
+// tracking it on the next scan.
+test("a root with no commits is skipped as a holder, neither dirty nor failed, and recovers on its first commit", async () => {
+	let holderHasCommits = false;
+	const tracker = new WorktreeChangesTracker(
+		async () => ({ stdout: "worktree /real\0branch refs/heads/main\0\0", code: 0 }),
+		(root) => async (args) => {
+			if (args[0] === "rev-parse") return { stdout: "", code: root === "/holder" && !holderHasCommits ? 1 : 0 };
+			return { stdout: args[0] === "status" && (root === "/real" || (root === "/holder" && holderHasCommits)) ? "?? a.ts\0" : "", code: 0 };
+		},
+		undefined,
+		() => ["/holder", "/real"],
+	);
+	await tracker.start();
+	assert.deepEqual(tracker.worktrees.map((tree) => tree.root), ["/real"], "an unborn root is skipped, not scanned");
+	assert.deepEqual(tracker.unbornRoots, ["/holder"]);
+	assert.deepEqual(tracker.failedRoots, [], "no commits is not a Git failure");
+	assert.equal(tracker.scannedRootCount, 2);
+	holderHasCommits = true;
+	await tracker.refresh();
+	assert.deepEqual(tracker.worktrees.map((tree) => tree.root), ["/holder", "/real"], "the first commit starts tracking");
+	assert.deepEqual(tracker.unbornRoots, []);
+});
+
 // The direct per-root ask (for a root missing from worktree list) can fail on
 // its own -- root gone, git unavailable -- independently of the change scan
 // that already found real files. That failure must label the root

package/tests/shell-prompt.test.ts

@@ -8,15 +8,15 @@ import {
 	PROMPT_STATE,
 	petalGlyph,
 	petalTone,
-	SHELL_PULSE_MS,
+	SHELL_PULSE_WATCHDOG_MS,
 	SHELL_SCANNER_STEPS,
 	withPromptHint,
 	type PromptFrameOptions,
 } from "../lib/shell-prompt.ts";
 
-test("scanner reflects a symmetric light wave across working text at Pi's original cadence", () => {
+test("scanner reflects a symmetric light wave across working text at the watchdog cadence", () => {
 	const fg = (role: string, char: string) => `<${role}>${char}</${role}>`;
-	assert.equal(SHELL_PULSE_MS, 80);
+	assert.equal(SHELL_PULSE_WATCHDOG_MS, 1000);
 	assert.equal(SHELL_SCANNER_STEPS, 15);
 	for (const word of ["working…", "Thinking…"]) {
 		for (let tick = 0; tick < SHELL_SCANNER_STEPS; tick++) {

package/tests/shell-render-cache.test.ts

@@ -1,7 +1,11 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 import { initTheme, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { buildShellBarModel, type ShellFooterData } from "../extensions/gentle-shell.ts";
+import { buildShellBarModel, createFooterStatusMemo, type ShellFooterData } from "../extensions/gentle-shell.ts";
+import { CHANGE_STATUS } from "../lib/shell-changes.ts";
+import type { RunningJobDisplay } from "../lib/jobs-sidebar-state.ts";
+import type { ReviewSidebarSnapshot } from "../lib/review-sidebar-state.ts";
+import type { ProviderUsage } from "../lib/shell-usage.ts";
 import { createQuietToolRenderer } from "../extensions/quiet-tools.ts";
 import { CARD_STYLE, cardStyle, setCardStyle } from "../lib/shell-card.ts";
 
@@ -127,3 +131,132 @@ test("image renderers keep their live geometry instead of caching opaque compone
 		{ expanded: true, isPartial: false }, theme as never, {} as never);
 	assert.notDeepEqual(card.render(80), card.render(80));
 });
+
+function footerMemoFixture() {
+	let reads = 0;
+	let projections = 0;
+	let leaf = "leaf-1";
+	const entries = [{ type: "message", message: { role: "assistant", usage: { cost: { total: 1 } } } }];
+	// One stable model object, replaced only by setModelId: real hosts keep the
+	// model identity stable, and sessionStatsKey compares it by identity.
+	let model: { id: string; contextWindow: number } = { id: "model", contextWindow: 1000 };
+	const ctx = {
+		get model() { return model; },
+		getContextUsage() { projections++; return { percent: 10, contextWindow: 1000 }; },
+		modelRegistry: { isUsingOAuth: () => false },
+		sessionManager: {
+			getEntries() { reads++; return [...entries]; },
+			getEntryCount: () => entries.length,
+			getSessionId: () => "session-1",
+			getLeafId: () => leaf,
+			getCwd: () => "/repo",
+			getSessionName: () => "session",
+		},
+	};
+	let branch: string | null = "main";
+	let statuses = new Map<string, string>();
+	let usage: ProviderUsage | undefined;
+	let added = 0;
+	let deleted = 0;
+	let unbornRoots = 0;
+	let review: ReviewSidebarSnapshot | undefined;
+	let jobs: RunningJobDisplay[] | undefined;
+	let settings: unknown = { statusPlacement: "auto" };
+	let style: unknown = "comfortable";
+	const footerData = { getGitBranch: () => branch, getExtensionStatuses: () => statuses } as unknown as ShellFooterData;
+	let profile: string | undefined = "team";
+	const memo = createFooterStatusMemo({
+		pi, ctx: ctx as unknown as ExtensionContext, footerData,
+		usage: () => usage,
+		profile: () => profile,
+		jobs: () => jobs,
+		review: () => review,
+		tracker: () => ({ model: { files: [{ path: "a.ts", status: CHANGE_STATUS.MODIFIED, added, deleted }], added, deleted }, unbornRoots: Array.from({ length: unbornRoots }, () => "root") }),
+		visualSettings: () => settings,
+		cardStyle: () => style,
+	});
+	return {
+		ctx: ctx as unknown as ExtensionContext & { sessionManager: { getLeafId?: () => string } },
+		memo,
+		counts: () => [reads, projections],
+		setLeaf: (value: string) => { leaf = value; },
+		spend: () => { entries[0]!.message.usage.cost.total += 1; },
+		setModelId: (value: string) => { model = { ...model, id: value }; },
+		setProfile: (value: string | undefined) => { profile = value; },
+		setBranch: (value: string | null) => { branch = value; },
+		setStatuses: (value: Map<string, string>) => { statuses = value; },
+		setUsage: (value: ProviderUsage | undefined) => { usage = value; },
+		setChangeCounts: (nextAdded: number, nextDeleted: number) => { added = nextAdded; deleted = nextDeleted; },
+		setUnbornRoots: (value: number) => { unbornRoots = value; },
+		setReview: (value: ReviewSidebarSnapshot | undefined) => { review = value; },
+		setJobs: (value: RunningJobDisplay[] | undefined) => { jobs = value; },
+		setSettings: (value: unknown) => { settings = value; },
+		setStyle: (value: unknown) => { style = value; },
+	};
+}
+
+test("the footer status memo reuses one model while live inputs hold still", () => {
+	const f = footerMemoFixture();
+	const first = f.memo.model();
+	assert.equal(first.costTotal, 1);
+	assert.deepEqual(first.changes, { files: 1, added: 0, deleted: 0 });
+	for (let frame = 0; frame < 10; frame++) assert.equal(f.memo.model(), first, "stable inputs reuse the built model");
+	assert.deepEqual(f.counts(), [1, 1], "warm frames never rescan the session");
+});
+
+test("the footer status digest key notices every live input the model reads", () => {
+	const f = footerMemoFixture();
+	const before = f.memo.key();
+	assert.equal(f.memo.key(), before, "the key is deterministic while nothing moves");
+	const mutations: Array<[string, () => void]> = [
+		["branch", () => f.setBranch("feature")],
+		["profile", () => f.setProfile("other (local)")],
+		["statuses", () => f.setStatuses(new Map([["jobs", "1 running"]]))],
+		["usage", () => f.setUsage({ provider: "p", plan: undefined, limits: [], fetchedAt: 1 })],
+		["change counts", () => f.setChangeCounts(2, 1)],
+		["unborn roots", () => f.setUnbornRoots(1)],
+		["review", () => f.setReview({ state: "open", scope: undefined } as unknown as ReviewSidebarSnapshot)],
+		["jobs", () => f.setJobs([{ id: "j", label: "l", startedAt: 0 }])],
+		["visual settings", () => f.setSettings({ statusPlacement: "bottom" })],
+		["card style", () => f.setStyle("compact")],
+		["model", () => f.setModelId("new-model")],
+		["cwd", () => (f.ctx.sessionManager as { getCwd(): string }).getCwd = () => "/other"],
+		["session name", () => (f.ctx.sessionManager as { getSessionName(): string }).getSessionName = () => "renamed"],
+		["leaf", () => f.setLeaf("leaf-2")],
+	];
+	let previous = before;
+	for (const [name, mutate] of mutations) {
+		mutate();
+		const current = f.memo.key();
+		assert.notEqual(current, previous, `a moved ${name} changes the digest key`);
+		previous = current;
+	}
+	// A branch or profile move rebuilds the model without rescanning statistics:
+	// the model object identity stays stable across those rebuilds.
+	const settled = f.memo.model();
+	const [reads, projections] = f.counts();
+	f.setBranch("release");
+	assert.notEqual(f.memo.model(), settled);
+	assert.deepEqual(f.counts(), [reads, projections]);
+});
+
+test("a moved leaf rebuilds the footer model with fresh statistics", () => {
+	const f = footerMemoFixture();
+	const first = f.memo.model();
+	f.setLeaf("leaf-2");
+	const second = f.memo.model();
+	assert.notEqual(second, first);
+	assert.deepEqual(f.counts(), [2, 2]);
+	assert.equal(f.memo.model(), second, "the fresh model is memoized again");
+});
+
+test("hosts without leaf identity stay honest through the digest key's values", () => {
+	const f = footerMemoFixture();
+	assert.equal(f.memo.key(), f.memo.key(), "the key stays deterministic on uncached hosts");
+	Reflect.deleteProperty(f.ctx.sessionManager, "getLeafId");
+	const first = f.memo.model();
+	f.spend();
+	const second = f.memo.model();
+	assert.notEqual(second, first, "a changed cost value rebuilds the model without leaf identity");
+	assert.equal(second.costTotal, 2);
+});

package/tests/shell-sidebar-layout.test.ts

@@ -589,6 +589,56 @@ test("a rail digest refreshes live state that no invalidation announces", (t) =>
 	assert.equal(todoRenders, 2, "explicit invalidation still reaches a rail without a digest");
 });
 
+test("a theme switch repaints rail sections whose digest did not change", (t) => {
+	const f = fixture();
+	// Pi hands extensions a live theme proxy and announces a switch only through
+	// ui.invalidate(), which never reaches the rail inside the layout tree.
+	let code = 31;
+	const live = { fg: (_color: string, text: string) => `\x1b[${code}m${text}\x1b[39m`, bold: (text: string) => text };
+	for (const key of ["footer", "agents", "todo"]) {
+		sidebarPart(f.tui, key, { render: () => [key], invalidate() {} }, {
+			digest: () => "stable",
+			render: () => [live.fg("accent", `${key} card`)],
+			invalidate() {},
+		});
+	}
+	t.after(installSidebar(f.tui, live));
+
+	const before = renderLayoutFrame(f.root, 140, 20, () => {}).lines.join("\n");
+	for (const key of ["footer", "agents", "todo"]) assert.ok(before.includes(`\x1b[31m${key} card`), `${key} paints with the first theme`);
+
+	code = 32;
+	const after = renderLayoutFrame(f.root, 140, 20, () => {}).lines.join("\n");
+	for (const key of ["footer", "agents", "todo"]) {
+		assert.ok(after.includes(`\x1b[32m${key} card`), `${key} repaints with the new theme`);
+		assert.ok(!after.includes(`\x1b[31m${key} card`), `${key} drops the old theme`);
+	}
+});
+
+test("structural cache misses skip the whole-rail digest pass", (t) => {
+	const f = fixture();
+	let digests = 0;
+	sidebarPart(f.tui, "todo", { render: () => ["Todo"], invalidate() {} }, {
+		digest: () => { digests++; return "stable"; },
+		render: () => [`Todo ${digests}`],
+		invalidate() {},
+	});
+	t.after(installSidebar(f.tui, theme));
+
+	// Every frame evaluates the digest exactly once: the whole-rail comparison
+	// reuses it for the section cache instead of calling each digest twice per
+	// prepare (issue #1681).
+	renderLayoutFrame(f.root, 140, 20, () => {});
+	const prepared = digests;
+	assert.equal(prepared, 1, "preparing the rail evaluates the digest once");
+	renderLayoutFrame(f.root, 140, 20, () => {});
+	assert.equal(digests, prepared + 1, "a cache hit compares the digest once");
+	renderLayoutFrame(f.root, 141, 20, () => {});
+	assert.equal(digests, prepared + 2, "a structural miss re-prepares with a single digest pass");
+	renderLayoutFrame(f.root, 140, 20, () => {});
+	assert.equal(digests, prepared + 3, "returning to the cached structure stays on a single digest pass");
+});
+
 test("reuses final sidebar presentation until a relevant invalidation", (t) => {
 	const f = fixture();
 	sidebarPart(f.tui, "todo", { render: () => Array.from({ length: 10 }, (_, index) => `Todo ${index}`), invalidate() {} });

package/tests/short-check-routing-contract.test.ts

@@ -36,7 +36,7 @@ for (const [name, text] of Object.entries({ registeredDescription: background.de
 test("inline still means the same parent, and the public background API stays asynchronous", () => {
 	assert.ok(core.includes("Small path: inline (parent; `bash_background` policy);"));
 	assert.ok(guide.includes("Inline means the same parent, not necessarily synchronous bash"));
-	assert.ok(core.includes("run the focused test and the suite inline, once each"));
+	assert.ok(core.includes("run the focused test and the suite inline in one command"));
 	assert.match(background.description, /return a job id at once/);
 	assert.match(background.description, /notified once, automatically/);
 	assert.match(background.description, /do not poll, sleep, or delegate a subagent to wait/);

package/tests/skill-collision-prefixes.test.ts

@@ -25,7 +25,9 @@ const PREFIXED_NAMES: Record<string, string> = {
 	"work-unit-commits": "gentle-ai-work-unit-commits",
 };
 
-const UNPREFIXED_DIRS = ["gentle-ai"];
+// gentle-pi-owned skills that gentle-ai does not install keep their own
+// gentle- namespace, so they need no gentle-ai- prefix to avoid a collision.
+const UNPREFIXED_DIRS = ["gentle-ai", "design"];
 
 for (const [dir, expectedName] of Object.entries(PREFIXED_NAMES)) {
 	test(`skills/${dir}/SKILL.md frontmatter name is prefixed`, () => {

package/tests/skill-registry-watcher.test.ts

@@ -16,7 +16,7 @@ for (const code of ["ENOENT", "EMFILE"]) {
 			import assert from "node:assert/strict";
 			import fs from "node:fs";
 			import { syncBuiltinESMExports } from "node:module";
-			import { join } from "node:path";
+			import { join, sep } from "node:path";
 			const root = ${JSON.stringify(root)};
 			const cwd = join(root, "workspace");
 			const home = join(root, "home");
@@ -52,6 +52,8 @@ for (const code of ["ENOENT", "EMFILE"]) {
 			});
 			const ctx = { cwd, hasUI: true, ui: { notify: (message, level) => notices.push({ message, level }) } };
 			const waitFor = async (predicate) => {
+				// Must stay well below the parent's spawnSync timeout so a missed
+				// outcome fails with this assertion instead of an opaque ETIMEDOUT.
 				const deadline = Date.now() + 5000;
 				while (!predicate() && Date.now() < deadline) await new Promise(resolve => setTimeout(resolve, 25));
 				assert.ok(predicate(), "timed out waiting for watcher outcome");
@@ -66,18 +68,28 @@ for (const code of ["ENOENT", "EMFILE"]) {
 				if (code === "ENOENT" && process.platform !== "darwin" && process.platform !== "win32") {
 					// Force the transient missing-directory race at Node's real recursive
 					// readdir boundary, after watcher creation, not in our refresh callback.
+					// Older Node rescans the parent folder; Node 24.22+ resolves new files
+					// via lstat and only readdirs a newly added directory, so trigger with
+					// a directory and fail whichever readdir lands under assets.
 					const nativeReaddir = fs.readdirSync;
 					let reachedRescan = false;
 					fs.readdirSync = function (path, options) {
-						if (path === assets) {
+						if (typeof path === "string" && (path === assets || path.startsWith(assets + sep))) {
 							fs.readdirSync = nativeReaddir;
 							reachedRescan = true;
 							throw Object.assign(new Error("ENOENT: transient skill assets disappeared"), { code, syscall: "scandir", path });
 						}
 						return nativeReaddir(path, options);
 					};
-					fs.writeFileSync(join(assets, "trigger.txt"), "trigger directory rescan");
-					await waitFor(() => reachedRescan);
+					fs.mkdirSync(join(assets, "trigger"));
+					// The rescan race needs live recursive-watch events. Where the OS
+					// cannot deliver them (an exhausted inotify budget, some WSL2
+					// setups), waiting the full waitFor budget is pointless: settle
+					// briefly for the natural race, then exercise the public error
+					// listener directly, as the manual fallback below always did.
+					const raceDeadline = Date.now() + 2000;
+					while (!reachedRescan && Date.now() < raceDeadline) await new Promise((resolve) => setTimeout(resolve, 25));
+					fs.readdirSync = nativeReaddir;
 					// Newer Node versions swallow rescan ENOENT themselves. Still
 					// exercise our public error listener without requiring Node's bug.
 					if (!notices.some(({ message, level }) => level === "warning" && message.includes(code))) {
@@ -112,7 +124,7 @@ for (const code of ["ENOENT", "EMFILE"]) {
 			timeout: 15_000,
 			env: { ...process.env, GIT_CEILING_DIRECTORIES: root },
 		});
-		assert.equal(child.error, undefined, child.error?.message);
+		assert.equal(child.error, undefined, `${child.error?.message}\n${child.stderr}`);
 		assert.equal(child.status, 0, child.stderr);
 		assert.match(child.stdout, new RegExp(`SURVIVED ${code}`));
 	});

package/tests/skill-registry.test.ts

@@ -120,28 +120,61 @@ test("uniqueExistingDirs normalizes duplicates and ignores missing roots", async
 	);
 });
 
-test("findSkillFiles scans one skill directory level only", async () => {
+test("findSkillFiles scans flat skills and category-nested skills without descending further", async () => {
 	const root = join(tmpdir(), `gentle-pi-shallow-${Date.now()}`);
 	const skillPath = join(root, "docs", "SKILL.md");
 	const nestedSkillPath = join(root, "fixtures", "nested", "SKILL.md");
+	const deeperSkillPath = join(root, "fixtures", "nested", "deeper", "SKILL.md");
 	mkdirSync(dirname(skillPath), { recursive: true });
 	mkdirSync(dirname(nestedSkillPath), { recursive: true });
+	mkdirSync(dirname(deeperSkillPath), { recursive: true });
 	writeFileSync(skillPath, "---\nname: docs\ndescription: Docs.\n---\n");
 	writeFileSync(nestedSkillPath, "---\nname: nested\ndescription: Nested fixture.\n---\n");
+	writeFileSync(deeperSkillPath, "---\nname: deeper\ndescription: Deeper fixture.\n---\n");
 
-	assert.deepEqual(await __testing.findSkillFiles(root), [skillPath]);
+	assert.deepEqual(await __testing.findSkillFiles(root), [skillPath, nestedSkillPath]);
 });
 
-test("findSkillFiles follows symlinked skill directories", async (t) => {
+test("findSkillFiles keeps direct skills ahead of alphabetically earlier nested collisions", async () => {
+	const cwd = join(tmpdir(), `gentle-pi-precedence-${Date.now()}`);
+	const directSkillPath = join(cwd, "skills", "zeta", "SKILL.md");
+	const nestedSkillPath = join(cwd, "skills", "alpha", "duplicate", "SKILL.md");
+	mkdirSync(dirname(directSkillPath), { recursive: true });
+	mkdirSync(dirname(nestedSkillPath), { recursive: true });
+	writeFileSync(directSkillPath, "---\nname: duplicate\ndescription: Direct skill.\n---\n");
+	writeFileSync(nestedSkillPath, "---\nname: duplicate\ndescription: Nested skill.\n---\n");
+
+	await __testing.regenerateRegistry(cwd, true);
+	const registry = readFileSync(join(cwd, ".atl", "skill-registry.md"), "utf8");
+	assert.match(registry, new RegExp(directSkillPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
+	assert.doesNotMatch(registry, new RegExp(nestedSkillPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
+});
+
+test("findSkillFiles does not descend into excluded categories", async () => {
+	const root = join(tmpdir(), `gentle-pi-excluded-category-${Date.now()}`);
+	for (const category of ["_shared", "skill-registry", "sdd-fixtures"]) {
+		const nestedSkillPath = join(root, category, "hidden", "SKILL.md");
+		mkdirSync(dirname(nestedSkillPath), { recursive: true });
+		writeFileSync(nestedSkillPath, "---\nname: hidden\ndescription: Hidden skill.\n---\n");
+	}
+
+	assert.deepEqual(await __testing.findSkillFiles(root), []);
+});
+
+test("findSkillFiles follows direct symlinked skills but not symlinked categories", async (t) => {
 	const root = join(tmpdir(), `gentle-pi-symlink-root-${Date.now()}`);
 	const realSkillDir = join(tmpdir(), `gentle-pi-symlink-target-${Date.now()}`);
+	const categoryTarget = join(tmpdir(), `gentle-pi-symlink-category-${Date.now()}`);
 	const linkedSkillDir = join(root, "linked");
 	const skillPath = join(linkedSkillDir, "SKILL.md");
 	mkdirSync(root, { recursive: true });
 	mkdirSync(realSkillDir, { recursive: true });
+	mkdirSync(join(categoryTarget, "nested"), { recursive: true });
 	writeFileSync(join(realSkillDir, "SKILL.md"), "---\nname: linked\ndescription: Linked skill.\n---\n");
+	writeFileSync(join(categoryTarget, "nested", "SKILL.md"), "---\nname: nested\ndescription: Nested skill.\n---\n");
 	try {
 		symlinkSync(realSkillDir, linkedSkillDir, "dir");
+		symlinkSync(categoryTarget, join(root, "category"), "dir");
 	} catch (error) {
 		t.skip(`symlink creation unavailable: ${error instanceof Error ? error.message : String(error)}`);
 		return;
@@ -150,6 +183,12 @@ test("findSkillFiles follows symlinked skill directories", async (t) => {
 	assert.deepEqual(await __testing.findSkillFiles(root), [skillPath]);
 });
 
+test("only missing skill-file errors allow category scanning", () => {
+	assert.equal(__testing.isMissingSkillFileError({ code: "ENOENT" }), true);
+	assert.equal(__testing.isMissingSkillFileError({ code: "ENOTDIR" }), true);
+	assert.equal(__testing.isMissingSkillFileError({ code: "EACCES" }), false);
+});
+
 test("skill registry watchers close on shutdown", async () => {
 	const root = join(tmpdir(), `gentle-pi-watchers-${Date.now()}`);
 	const skillPath = join(root, "skills", "docs", "SKILL.md");
@@ -453,6 +492,11 @@ test("registered watcher protects registry tracked after a cache hit", async (t)
 	while (runtime.notices.length === 0 && Date.now() < deadline) await new Promise((resolve) => setTimeout(resolve, 50));
 	assert.equal(readFileSync(fixture.registry, "utf8"), before);
 	assert.ok(runtime.notices.some(({ message, level }) => level === "warning" && message.includes("/skill-registry:refresh")));
+	// The poll re-asks the same tracked-target state every interval: the
+	// warning stays a one-shot per unchanged state instead of repeating.
+	runtime.notices.length = 0;
+	await new Promise((resolve) => setTimeout(resolve, 3000));
+	assert.deepEqual(runtime.notices, []);
 	assert.ok(!runtime.notices.some(({ message }) => message.includes("refreshed")));
 });
 

package/tests/task-size-routing-contract.test.ts

@@ -61,7 +61,7 @@ test("AC2: counts never classify, and the step-count classifier is gone", () =>
 test("AC3: small work runs its checks inline and keeps test-first", () => {
 	const size = sectionOf(core, "## Task Size");
 	for (const clause of [
-		"run the focused test and the suite inline, once each",
+		"run the focused test and the suite inline in one command",
 		"observe RED inline before the fix",
 		"No explore, worker, or verifier",
 		"no feature document, mirror, or commits unless the user asks",

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

@@ -128,7 +128,7 @@ test("T33: the Close step checks shared code before Risk: none", () => {
 // 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.";
+const DIFFERENTIAL = "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("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"));

package/tests/verifier-admission.test.ts

@@ -47,6 +47,23 @@ test("S3: a Risk line naming a Task Size high-risk item admits the verifier", (t
 	assert.equal(rejectUnriskedVerifierLaunch(viaContext, { root, contextUsage: quiet }), undefined, "the context carries the line");
 });
 
+// gentle-shell-bench model-economy L9: a DeepSeek verifier launch was refused twice because its valid declaration
+// opened a sentence mid-paragraph ("... on top of commit ebf3f35). Risk: item 1 (...)"), not a line.
+test("S3: a Risk declaration that opens a sentence admits the verifier", (t) => {
+	const root = workspace(false);
+	t.after(() => rmSync(root, { recursive: true, force: true }));
+	for (const task of [
+		"Independently verify an ODD change on top of commit ebf3f35. Risk: item 1 (schema migration of stored data).",
+		"Verify the parser change! Risk: item 3 (shared parser)",
+		"Is the guard still sound? Risk: item 2",
+	]) {
+		assert.equal(rejectUnriskedVerifierLaunch({ agent: "gentle-ai-verify", task }, { root, contextUsage: quiet }), undefined, task);
+	}
+	for (const task of ["Verify it. Risk: none (local rename)", "Verify it. Do not write Risk: item 3 here.", "Verify it.Risk: item 3"]) {
+		assert.ok(rejectUnriskedVerifierLaunch({ agent: "gentle-ai-verify", task }, { root, contextUsage: quiet })?.block, task);
+	}
+});
+
 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 }));
@@ -128,7 +145,7 @@ test("S3/S5: the orchestrator tool_call hook gates only primary verifier launche
 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");
+	assert.ok(read("assets/orchestrator-verification.md").includes("(runtime admits its launch on a `Risk: item N` line or sentence, 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");