gentle-pi 4.0.0 → 4.2.0

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

@@ -0,0 +1,129 @@
+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 { createQuietToolRenderer } from "../extensions/quiet-tools.ts";
+import { CARD_STYLE, cardStyle, setCardStyle } from "../lib/shell-card.ts";
+
+initTheme("dark");
+const pi = { getThinkingLevel: () => "high" } as unknown as ExtensionAPI;
+const footer = { getGitBranch: () => "main", getExtensionStatuses: () => new Map() } as unknown as ShellFooterData;
+
+function sessionFixture() {
+	let reads = 0;
+	let projections = 0;
+	let sessionId = "session-1";
+	let leaf = "leaf-1";
+	const entries = [{ type: "message", message: { role: "assistant", usage: { cost: { total: 1 } } } }];
+	const ctx = {
+		model: { id: "model", contextWindow: 1000 },
+		getContextUsage() { projections++; return { percent: 10, contextWindow: this.model.contextWindow }; },
+		modelRegistry: { isUsingOAuth: () => false },
+		sessionManager: {
+			getEntries() { reads++; return [...entries]; },
+			getEntryCount: () => entries.length,
+			getSessionId: () => sessionId,
+			getLeafId: () => leaf,
+			getCwd: () => "/repo",
+			getSessionName: () => "session",
+		},
+	};
+	return {
+		ctx, entries,
+		build: () => buildShellBarModel(pi, ctx as unknown as ExtensionContext, footer),
+		counts: () => [reads, projections],
+		branch: () => { leaf = "other-leaf"; },
+		switchSession: () => { sessionId = "session-2"; },
+	};
+}
+
+test("settled shell chrome scans stats once while presentation stays live", () => {
+	const fixture = sessionFixture();
+	assert.equal(fixture.build().costTotal, 1);
+	for (let frame = 0; frame < 20; frame++) fixture.build();
+	assert.deepEqual(fixture.counts(), [1, 1]);
+	fixture.ctx.sessionManager.getSessionName = () => "renamed";
+	assert.equal(fixture.build().sessionName, "renamed");
+	assert.deepEqual(fixture.counts(), [1, 1]);
+	fixture.entries.push(fixture.entries[0]!);
+	assert.equal(fixture.build().costTotal, 2);
+	fixture.branch(); fixture.build();
+	fixture.switchSession(); fixture.build();
+	fixture.ctx.model = { ...fixture.ctx.model, id: "new-model" }; fixture.build();
+	fixture.ctx.model.contextWindow = 2000;
+	assert.equal(fixture.build().contextWindow, 2000);
+	assert.deepEqual(fixture.counts(), [6, 6]);
+	const other = sessionFixture(); other.build();
+	assert.deepEqual(other.counts(), [1, 1], "manager identities do not share statistics");
+});
+
+test("leaf-based stats work on read-only hosts without an entry-count method", () => {
+	const fixture = sessionFixture();
+	Reflect.deleteProperty(fixture.ctx.sessionManager, "getEntryCount");
+	fixture.build(); fixture.build();
+	assert.deepEqual(fixture.counts(), [1, 1]);
+	fixture.branch(); fixture.build();
+	assert.deepEqual(fixture.counts(), [2, 2]);
+});
+
+function countingTheme() {
+	let calls = 0;
+	let prefix = "";
+	return {
+		theme: {
+			fg: (_color: string, text: string) => { calls++; return prefix + text; },
+			bg: (_color: string, text: string) => { calls++; return `\x1b[48;5;235m${text}\x1b[49m`; },
+			bold: (text: string) => text,
+		},
+		calls: () => calls,
+		change: () => { prefix += "!"; },
+	};
+}
+
+for (const expanded of [false, true]) test(`settled tool cards cache complete rows (expanded=${expanded})`, () => {
+	const previous = cardStyle();
+	try {
+		setCardStyle(CARD_STYLE.NEON);
+		const { theme, calls, change } = countingTheme();
+		const renderer = createQuietToolRenderer("read");
+		const context = { args: { path: "src/example.ts" }, state: {}, isPartial: false, executionStarted: true };
+		const result = { content: [{ type: "text" as const, text: "first line\nsecond line" }], details: {} };
+		const cards = [renderer.renderCall!(context.args, theme as never, context as never),
+			renderer.renderResult!(result, { expanded, isPartial: false }, theme as never, context as never)];
+		for (const card of cards) {
+			const rows = card.render(80);
+			const warm = calls();
+			for (let frame = 0; frame < 20; frame++) assert.deepEqual(card.render(80), rows);
+			assert.equal(calls(), warm, "warm frames do not rebuild decorated lines");
+			assert.notDeepEqual(card.render(40), rows, "width invalidates layout");
+			setCardStyle(CARD_STYLE.FLOAT);
+			assert.notDeepEqual(card.render(80), rows, "style changes apply without host invalidation");
+			setCardStyle(CARD_STYLE.NEON);
+			card.render(80);
+			change(); card.invalidate();
+			assert.notDeepEqual(card.render(80), rows, "theme invalidation rebuilds colored content");
+		}
+	} finally { setCardStyle(previous); }
+});
+
+test("cached call chrome observes a result mark on its shared row state", () => {
+	const { theme } = countingTheme();
+	const renderer = createQuietToolRenderer("read");
+	const context = { args: { path: "file.ts" }, state: {}, isPartial: true, executionStarted: true };
+	const call = renderer.renderCall!(context.args, theme as never, context as never);
+	const running = call.render(80);
+	assert.ok(running.join("\n").includes("running"));
+	renderer.renderResult!({ content: [], details: {} }, { expanded: false, isPartial: false }, theme as never, context as never);
+	assert.ok(!call.render(80).join("\n").includes("running"), "result arrival removes the call's running/closing rows");
+});
+
+test("image renderers keep their live geometry instead of caching opaque components", () => {
+	const { theme } = countingTheme();
+	let renders = 0;
+	const renderer = createQuietToolRenderer("read", undefined, undefined, () => ({
+		render: () => [`image geometry ${++renders}`], invalidate() {},
+	}));
+	const card = renderer.renderResult!({ content: [{ type: "image", data: "", mimeType: "image/png" }], details: {} },
+		{ expanded: true, isPartial: false }, theme as never, {} as never);
+	assert.notDeepEqual(card.render(80), card.render(80));
+});

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

@@ -49,7 +49,7 @@ test("grouped Status preserves structured fields and opaque integration text", (
 		const lines = renderShellSidebarBar({
 			cwd: "/project", branch: "main", dirty: 2, sessionName: "session",
 			modelId: "model", effort: "high", contextPercent: 45, contextWindow: 1000,
-			costTotal: 1, subscription: false, statuses: ["opaque integration"],
+			costTotal: 1, subscription: false, usage: undefined, statuses: ["opaque integration"],
 		}, painted, 46);
 		const text = lines.join("\n");
 		let previous = -1;
@@ -365,6 +365,31 @@ test("wheel scrolls the rail and is consumed at both boundaries and blank space"
 	assert.equal(scroll.scrollTop, 0);
 });
 
+test("wheel over a bounded Todo viewport scrolls the section before the surrounding rail", (t) => {
+	const f = fixture();
+	const received: TuiMouseEvent[] = [];
+	let consumes = true;
+	sidebarPart(f.tui, "todo", {
+		render: () => ["Todo viewport", "Todo body"], invalidate() {},
+		handleMouse(event: TuiMouseEvent) {
+			received.push(event);
+			return consumes && event.type === "wheel" ? { handled: true, render: true } : undefined;
+		},
+	});
+	t.after(installSidebar(f.tui, theme));
+	const scroll = rail(f);
+	const content = scroll.render(50);
+	scroll.updateLayout(content.length + 20, content.length, () => {});
+	const y = content.findIndex((line) => line.includes("Todo body"));
+	const event: TuiMouseEvent = { type: "wheel", button: "none", wheelDelta: 2, x: 3, y, screenX: 93, screenY: y, width: 50, height: content.length, shift: false, alt: false, ctrl: false };
+	assert.equal(scroll.handleMouse(event)?.handled, true);
+	assert.equal(scroll.scrollTop, 0, "inner viewport consumes wheel without moving the rail");
+	assert.equal(received.at(-1)?.y, 1, "section coordinates are local");
+	consumes = false;
+	assert.equal(scroll.handleMouse(event)?.handled, true);
+	assert.equal(scroll.scrollTop, 2, "unbounded/collapsed sections fall back to rail scrolling");
+});
+
 test("rail dispatches a clipped, scroll-translated left click to only the matching sidebar part", (t) => {
 	const f = fixture();
 	let clicks = 0;
@@ -427,7 +452,7 @@ test("rail rejects removed or replaced parts before cached geometry is prepared
 			return { handled: true };
 		},
 	};
-	const mounted = sidebarPart(f.tui, "todo", { render: () => ["Todo bottom"], invalidate() {} }, original);
+	const mounted = sidebarPart(f.tui, "todo", { render: () => ["Todo bottom"], invalidate() {}, dispose() {} }, original);
 	const dispose = installSidebar(f.tui, theme);
 	t.after(dispose);
 	const scroll = rail(f);

package/tests/shell-todo.test.ts

@@ -9,6 +9,7 @@ import {
 	staleTurns,
 	TODO_STATUS,
 	todoPromptBlock,
+	todoStateMessage,
 	todoSummary,
 	type TodoState,
 } from "../lib/shell-todo.ts";
@@ -152,19 +153,49 @@ test("replayTodo rebuilds the latest state from Gentle and rpiv tool results ali
 	assert.deepEqual(replayTodo([]), emptyTodo());
 });
 
-test("todoPromptBlock lists open work with the rules, and stays silent when there is nothing open", () => {
-	const block = todoPromptBlock(seeded(), 0);
-	assert.ok(block);
+test("todoPromptBlock is the byte-stable rules block; todoStateMessage carries the open work (#1662)", () => {
+	const block = todoPromptBlock();
 	assert.match(block, /^## Todo list/m);
 	assert.match(block, /mark a task in_progress before starting/);
-	assert.match(block, /1\. \[done\] Add quiet tool rendering/);
-	assert.match(block, /2\. \[in_progress\] Fix quiet tools conflict — fixing conflict/);
-	assert.match(block, /3\. \[pending\] Show git bash tails/);
 	assert.doesNotMatch(block, /stale/);
-	assert.match(todoPromptBlock(seeded(), 2) ?? "", /stale: 2 turns without an update/);
-	assert.equal(todoPromptBlock(emptyTodo(), 0), undefined);
+	assert.doesNotMatch(block, /Add quiet tool rendering/, "the rules block never contains task content");
+	const message = todoStateMessage(seeded());
+	assert.ok(message);
+	assert.match(message, /1\. \[done\] Add quiet tool rendering/);
+	assert.match(message, /2\. \[in_progress\] Fix quiet tools conflict — fixing conflict/);
+	assert.match(message, /3\. \[pending\] Show git bash tails/);
+	assert.doesNotMatch(message, /stale/);
+	assert.equal(todoStateMessage(emptyTodo()), undefined);
 	const allDone = applyTodo(seeded(), { action: "write", tasks: [{ title: "A", status: "done" }] }, 1).state;
-	assert.equal(todoPromptBlock(allDone, 0), undefined);
+	assert.equal(todoStateMessage(allDone), undefined);
+});
+
+test("collapsed long tasks occupy one body line, including stale state, without losing task data", (t) => {
+	const title = "界🙂 long title ".repeat(100);
+	const note = "long description ".repeat(100);
+	for (const style of [CARD_STYLE.NEON, CARD_STYLE.FLOAT]) {
+		useCardStyle(t, style);
+		for (const status of ["in_progress", "pending", "blocked"]) {
+			const state = applyTodo(emptyTodo(), { action: "write", tasks: [{ title, note, status }] }, 1).state;
+			const snapshot = structuredClone(state);
+			for (const width of [16, 40, 70]) {
+				for (const staleTurns of [0, 4]) {
+					const rows = renderTodoCard(state, withBackground(plainTheme), width, { collapsed: true, staleTurns, scrollable: true });
+					assert.equal(rows.length, style === CARD_STYLE.FLOAT ? 5 : 3);
+					assert.ok(rows.some((row) => stripAnsi(row).includes("…")), "long text signals truncation");
+					for (const row of rows) assert.equal(visibleWidth(row), width);
+				}
+			}
+			assert.deepEqual(state, snapshot);
+		}
+	}
+});
+
+test("non-scrollable Todo caps physical wrapped rows, not task count", () => {
+	const state = applyTodo(emptyTodo(), { action: "write", tasks: [{ title: "long title ".repeat(300), status: "in_progress", note: "long note ".repeat(300) }] }, 1).state;
+	const rows = renderTodoCard(state, plainTheme, 40, { collapsed: false, staleTurns: 4 });
+	assert.ok(rows.length <= 14);
+	assert.match(stripAnsi(rows.at(-2)!), /…/);
 });
 
 test("renderTodoCard draws the framed list with status glyphs and keeps every line at width", () => {
@@ -209,8 +240,8 @@ test("renderTodoCard keeps the configured collapse shortcut in the header while
 
 	const staleCollapsed = renderTodoCard(seeded(), plainTheme, 70, { collapsed: true, staleTurns: 2, collapseKey: "ctrl+shift+t" }).map(stripAnsi);
 	assert.match(staleCollapsed[0], /^╭─ ❀ Todos ▸ Expand · 1 of 3 ─+ ctrl\+shift\+t expand ╮$/);
-	assert.match(staleCollapsed[1], /^│ stale · 2 turns +│$/);
-	assert.match(staleCollapsed[2], /^│ ◐ Fix quiet tools conflict · fixing conflict +│$/);
+	assert.equal(staleCollapsed.length, 3, "staleness stays in the single collapsed body row");
+	assert.match(staleCollapsed[1], /^│ stale · 2 turns · ◐ Fix quiet tools conflict · fixing conflict +│$/);
 
 	const fallback = applyTodo(emptyTodo(), { action: "write", tasks: [{ title: "Finished first", status: "done" }, { title: "First pending" }, { title: "Later pending" }] }, 1).state;
 	assert.match(renderTodoCard(fallback, plainTheme, 70, { collapsed: true, staleTurns: 0 }).map(stripAnsi)[1], /^│ ○ First pending +│$/);
@@ -379,3 +410,93 @@ test("a done todo wraps to the float body so the strikethrough never re-wraps",
 	assertFloatRows(lines, 40);
 	for (const row of lines.slice(3, -1)) assert.match(stripAnsi(row), /^ ▎ [✓ ] ~[^~]+~ +$/u, "each physical row closes its own strikethrough");
 });
+
+// #1814 dropped: terminal, never counts as open, reads apart from done.
+// #1820 blocked: open but not actionable, always carries its reason.
+
+test("applyTodo accepts dropped and blocked, maps cancel vocabulary to dropped, and names every status on an unknown one", () => {
+	const { state, error } = applyTodo(
+		emptyTodo(),
+		{ action: "write", tasks: [{ title: "Old plan", status: "dropped" }, { title: "Deploy", status: "blocked", note: "waiting for an admin" }, { title: "A", status: "cancelled" }, { title: "B", status: "canceled" }, { title: "C", status: "abandoned" }] },
+		1,
+	);
+	assert.equal(error, undefined);
+	assert.deepEqual(state.tasks.map((task) => task.status), [TODO_STATUS.DROPPED, TODO_STATUS.BLOCKED, TODO_STATUS.DROPPED, TODO_STATUS.DROPPED, TODO_STATUS.DROPPED]);
+	assert.equal(state.tasks[1].note, "waiting for an admin");
+	const bad = applyTodo(emptyTodo(), { action: "write", tasks: [{ title: "X", status: "later" }] }, 1);
+	assert.equal(bad.error, 'unknown status "later" (use pending, in_progress, blocked, done, or dropped)');
+});
+
+test("applyTodo rejects blocked without a note and leaves the list unchanged", () => {
+	const before = seeded();
+	for (const params of [
+		{ action: "add", title: "Deploy", status: "blocked" },
+		{ action: "update", id: 3, status: "blocked" },
+		{ action: "write", tasks: [{ title: "Deploy", status: "blocked", note: "   " }] },
+	]) {
+		const result = applyTodo(before, params, 9);
+		assert.equal(result.error, "blocked needs a note naming what it waits for");
+		assert.equal(result.text, "Error: blocked needs a note naming what it waits for");
+		assert.strictEqual(result.state, before, `${params.action} must not change the list`);
+	}
+	const blocked = applyTodo(before, { action: "update", id: 3, status: "blocked", note: "waiting for the API contract" }, 9);
+	assert.equal(blocked.error, undefined);
+	assert.equal(blocked.text, "#3 Show git bash tails → blocked");
+	const unblocked = applyTodo(blocked.state, { action: "update", id: 3, status: "pending" }, 10);
+	assert.equal(unblocked.state.tasks[2].status, TODO_STATUS.PENDING);
+});
+
+test("dropped tasks never count as open: a list of done and dropped is finished, silent, and never stale", () => {
+	const state = applyTodo(emptyTodo(), { action: "write", tasks: [{ title: "A", status: "done" }, { title: "B", status: "dropped" }, { title: "C", status: "dropped" }] }, 1).state;
+	assert.deepEqual(todoSummary(state), { done: 1, total: 3, open: 0 });
+	assert.equal(todoStateMessage(state), undefined);
+	assert.equal(staleTurns(state, 9), 0);
+});
+
+test("blocked tasks stay open but alone never make the list stale; an actionable task still does", () => {
+	const blockedOnly = applyTodo(emptyTodo(), { action: "write", tasks: [{ title: "A", status: "done" }, { title: "Deploy", status: "blocked", note: "waiting for an admin" }] }, 1).state;
+	assert.deepEqual(todoSummary(blockedOnly), { done: 1, total: 2, open: 1 });
+	assert.equal(staleTurns(blockedOnly, 9), 0);
+	assert.match(todoStateMessage(blockedOnly) ?? "", /2\. \[blocked\] Deploy — waiting for an admin/);
+	const block = todoPromptBlock();
+	assert.match(block, /A blocked task waits on something outside the list: do not work on it until its condition holds/);
+	assert.match(block, /mark the tasks it made obsolete dropped instead of leaving them pending or marking them done/);
+	const mixed = applyTodo(blockedOnly, { action: "add", title: "Write docs" }, 1).state;
+	assert.equal(staleTurns(mixed, 3), 2);
+});
+
+test("renderTodoCard draws blocked with its reason and dropped dim without strikethrough, excluding dropped from the count", () => {
+	const state = applyTodo(
+		emptyTodo(),
+		{ action: "write", tasks: [{ title: "Ship", status: "done" }, { title: "Old plan", status: "dropped" }, { title: "Deploy", status: "blocked", note: "waiting for an admin" }, { title: "Docs" }] },
+		1,
+	).state;
+	const plain = renderTodoCard(state, plainTheme, 60, { collapsed: false, staleTurns: 0 }).map(stripAnsi);
+	assert.match(plain[0], /Todos ▾ Collapse · 1 of 3/);
+	assert.match(plain[2], /^│ ✕ Old plan +│$/);
+	assert.match(plain[3], /^│ ⊘ Deploy · waiting for an admin +│$/);
+	const roles: string[] = [];
+	const spy = { ...plainTheme, fg(color: string, text: string) { roles.push(`${color}:${text}`); return text; } };
+	renderTodoCard(state, spy, 60, { collapsed: false, staleTurns: 0 });
+	assert.ok(roles.includes("muted:✕") && roles.includes("dim:Old plan"), "dropped: muted glyph, dim title");
+	assert.ok(roles.includes("warning:⊘"), "blocked: warning glyph");
+});
+
+test("the collapsed card skips blocked tasks for the next one, and shows a blocked task only when nothing else is open", () => {
+	const state = applyTodo(emptyTodo(), { action: "write", tasks: [{ title: "Deploy", status: "blocked", note: "waiting for an admin" }, { title: "Docs" }] }, 1).state;
+	assert.match(renderTodoCard(state, plainTheme, 60, { collapsed: true, staleTurns: 0 }).map(stripAnsi)[1], /^│ ○ Docs +│$/);
+	const onlyBlocked = applyTodo(state, { action: "update", id: 2, status: "done" }, 2).state;
+	assert.match(renderTodoCard(onlyBlocked, plainTheme, 60, { collapsed: true, staleTurns: 0 }).map(stripAnsi)[1], /^│ ⊘ Deploy · waiting for an admin +│$/);
+});
+
+test("renderTodoCard folds dropped tasks next to done ones in a long list", () => {
+	const tasks = Array.from({ length: 20 }, (_, index) => ({ title: `Task ${index + 1}`, status: index < 5 ? "done" : index < 8 ? "dropped" : "pending" }));
+	const state = applyTodo(emptyTodo(), { action: "write", tasks }, 1).state;
+	const plain = renderTodoCard(state, plainTheme, 60, { collapsed: false, staleTurns: 0 }).map(stripAnsi);
+	assert.equal(plain.length, 14);
+	assert.match(plain[0], /Todos ▾ Collapse · 5 of 17/);
+	assert.match(plain[1], /^│ ✓ 5 done +│$/);
+	assert.match(plain[2], /^│ ✕ 3 dropped +│$/);
+	assert.match(plain[3], /^│ ○ Task 9 +│$/);
+	assert.match(plain[12], /^│ … 3 more +│$/);
+});

package/tests/shell-usage-view.test.ts

@@ -22,7 +22,7 @@ function payload(percent: number) {
 test("UsageView frames the panel, keeps every line at width, and shows the empty state", () => {
 	const store = new UsageStore();
 	const events: string[] = [];
-	const view = new UsageView(store, { theme: plainTheme, now: () => NOW, active: () => undefined, onRefresh: async () => events.push("refresh"), onClose: () => events.push("close"), requestRender: () => events.push("render") });
+	const view = new UsageView(store, { theme: plainTheme, now: () => NOW, active: () => undefined, onRefresh: async () => { events.push("refresh"); }, onClose: () => events.push("close"), requestRender: () => events.push("render") });
 	const empty = view.render(90).map(stripAnsi);
 	assert.match(empty[0], /^╭─ ✿ Subscriptions ─+╮$/);
 	assert.match(empty[1], /No subscription usage yet/);

package/tests/shell-usage.test.ts

@@ -122,6 +122,41 @@ test("parseCodexHeaders reads the SSE rate-limit headers when a provider sends t
 	assert.equal(parseCodexHeaders({ "content-type": "text/event-stream" }, NOW), undefined);
 });
 
+test("parseCodexHeaders ignores windows without a valid duration instead of inventing 0m", () => {
+	for (const minutes of [undefined, "", " ", "0", "-1", "invalid", "300oops", "Infinity", "1e309"]) {
+		const headers: Record<string, string> = { "x-codex-primary-used-percent": "0" };
+		if (minutes !== undefined) headers["x-codex-primary-window-minutes"] = minutes;
+		assert.equal(parseCodexHeaders(headers, NOW), undefined, `minutes: ${String(minutes)}`);
+	}
+});
+
+test("parseCodexHeaders keeps genuine zero usage and only the valid provider windows", () => {
+	const usage = parseCodexHeaders({
+		"x-codex-primary-used-percent": "0",
+		"x-codex-primary-window-minutes": "0",
+		"x-codex-secondary-used-percent": "0",
+		"x-codex-secondary-window-minutes": "10080",
+	}, NOW);
+	assert.ok(usage);
+	assert.deepEqual(usage.limits[0].windows.map((w) => `${w.label}:${w.usedPercent}`), ["week:0"]);
+	assert.equal(renderUsageBar(usage, plainTheme), "codex week ▱▱▱▱▱▱▱▱ 0%");
+	assert.doesNotMatch(renderUsageBar(usage, plainTheme)!, /0m|5h/);
+});
+
+test("parseCodexUsage filters invalid numeric windows without inventing a five-hour quota", () => {
+	for (const seconds of [undefined, 0, -1, Number.NaN, Number.POSITIVE_INFINITY, "18000"]) {
+		const usage = parseCodexUsage({ rate_limit: {
+			primary_window: { used_percent: 0, limit_window_seconds: seconds },
+			secondary_window: { used_percent: 0, limit_window_seconds: 604_800 },
+		} }, NOW);
+		assert.deepEqual(usage.limits[0].windows.map((w) => `${w.label}:${w.usedPercent}`), ["week:0"], `seconds: ${String(seconds)}`);
+	}
+	for (const used of [undefined, Number.NaN, Number.POSITIVE_INFINITY]) {
+		assert.deepEqual(parseCodexUsage({ rate_limit: { primary_window: { used_percent: used, limit_window_seconds: 604_800 } } }, NOW).limits, []);
+	}
+	assert.deepEqual(parseCodexUsage({ rate_limit: { primary_window: { used_percent: 0, limit_window_seconds: 0 } } }, NOW).limits, []);
+});
+
 test("accountIdFromToken decodes the chatgpt account claim from an OAuth JWT", () => {
 	const claims = Buffer.from(JSON.stringify({ "https://api.openai.com/auth": { chatgpt_account_id: "acct-123" } })).toString("base64url");
 	assert.equal(accountIdFromToken(`header.${claims}.sig`), "acct-123");

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

@@ -0,0 +1,49 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createJobRegistry } from "../lib/background-jobs.ts";
+import { registerBackgroundJobTools } from "../lib/background-jobs-tools.ts";
+
+// Guidance contract, not runtime routing or a performance guarantee.
+const tools: Array<{ name: string; description: string; parameters: unknown }> = [];
+registerBackgroundJobTools({ registerTool: (tool) => tools.push(tool), registerMessageRenderer: () => {} } as unknown as ExtensionAPI, {
+	registry: createJobRegistry({
+		outputDir: () => { throw new Error("Guidance contracts must not write job logs"); },
+		now: () => 0,
+		shell: () => { throw new Error("Guidance contracts must not execute jobs"); },
+		onSettled: () => {},
+	}),
+	sessionId: () => "contract", now: () => 0,
+});
+const background = tools.find((tool) => tool.name === "bash_background")!;
+const core = readFileSync(new URL("../assets/orchestrator.md", import.meta.url), "utf8");
+const guide = readFileSync(new URL("../docs/gentle-shell.md", import.meta.url), "utf8");
+
+for (const [name, text] of Object.entries({ registeredDescription: background.description, guide })) {
+	test(`${name}: synchronous checks have an inclusive explicit 30-second limit and safe fallback`, () => {
+		for (const clause of [
+			"local, finite, deterministic checks", "reasonably expected to finish within 30 seconds",
+			"explicit timeout <= 30 seconds (30 included)",
+			"longer or unknown duration, external waits, CI, builds, and servers",
+			"Report a timeout as failure; never automatically retry, restart, or migrate it to background",
+			"Preserve RED/GREEN and public-check exit codes, stdout, and stderr",
+			"Engram bugfix saves and session summaries", "RDD", "not a performance guarantee",
+		]) assert.ok(text.includes(clause), `${name} missing: ${clause}`);
+	});
+}
+
+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.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/);
+	assert.deepEqual(background.parameters, {
+		type: "object", additionalProperties: false, required: ["command"], properties: {
+			command: { type: "string", description: "Shell command to run in the background, in the session working directory." },
+			label: { type: "string", maxLength: 80, description: "Short human-readable label, e.g. 'CI for PR 1834'." },
+		},
+	});
+});

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

@@ -0,0 +1,119 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { pathToFileURL } from "node:url";
+
+const extensionUrl = pathToFileURL(join(import.meta.dirname, "..", "extensions", "skill-registry.ts")).href;
+
+for (const code of ["ENOENT", "EMFILE"]) {
+	test(`registered skill watcher survives asynchronous ${code} and preserves other roots`, (t) => {
+		const root = mkdtempSync(join(tmpdir(), "gentle-skill-watch-error-"));
+		t.after(() => rmSync(root, { recursive: true, force: true }));
+		const child = spawnSync(process.execPath, ["--experimental-strip-types", "--input-type=module", "-e", `
+			import assert from "node:assert/strict";
+			import fs from "node:fs";
+			import { syncBuiltinESMExports } from "node:module";
+			import { join } from "node:path";
+			const root = ${JSON.stringify(root)};
+			const cwd = join(root, "workspace");
+			const home = join(root, "home");
+			process.env.HOME = home;
+			process.env.USERPROFILE = home;
+			delete process.env.GENTLE_PI_AGENTS_CHILD;
+			delete process.env.GENTLE_PI_NO_SKILL_REGISTRY;
+			const userRoot = join(home, ".codex", "skills");
+			const assets = join(userRoot, "imagegen", "assets");
+			const projectSkill = join(cwd, "skills", "local", "SKILL.md");
+			const userSkill = join(userRoot, "imagegen", "SKILL.md");
+			fs.mkdirSync(assets, { recursive: true });
+			fs.mkdirSync(join(cwd, "skills", "local"), { recursive: true });
+			fs.writeFileSync(projectSkill, "---\\nname: local\\ndescription: Initial project skill.\\n---\\n");
+			fs.writeFileSync(userSkill, "---\\nname: imagegen\\ndescription: Initial user skill.\\n---\\n");
+			const nativeWatch = fs.watch;
+			let userWatcher;
+			fs.watch = function (path, options, listener) {
+				const watcher = nativeWatch(path, options, listener);
+				if (path === userRoot && options?.recursive) userWatcher = watcher;
+				return watcher;
+			};
+			syncBuiltinESMExports();
+			const { default: skillRegistry, __testing } = await import(${JSON.stringify(extensionUrl)});
+			const events = new Map();
+			const commands = new Map();
+			const notices = [];
+			skillRegistry({
+				on: (name, handler) => events.set(name, handler),
+				registerCommand: (name, command) => commands.set(name, command),
+				registerFlag: () => {},
+				getFlag: () => false,
+			});
+			const ctx = { cwd, hasUI: true, ui: { notify: (message, level) => notices.push({ message, level }) } };
+			const waitFor = async (predicate) => {
+				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");
+			};
+			try {
+				await events.get("session_start")(undefined, ctx);
+				await __testing.startupSettled(); // Startup regeneration runs after session_start returns.
+				assert.ok(userWatcher, "fixture must start the real recursive user watcher");
+				const initialWatchers = __testing.activeWatcherCount();
+				assert.equal(initialWatchers, 2);
+				const code = ${JSON.stringify(code)};
+				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.
+					const nativeReaddir = fs.readdirSync;
+					let reachedRescan = false;
+					fs.readdirSync = function (path, options) {
+						if (path === assets) {
+							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);
+					// 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))) {
+						userWatcher.emit("error", Object.assign(new Error("ENOENT: skill watcher failed"), { code }));
+					}
+				} else {
+					// Native Darwin/Windows recursion has no JS readdir boundary;
+					// inject its public error event, as for asynchronous resource errors.
+					setImmediate(() => userWatcher.emit("error", Object.assign(new Error(code + ": skill watcher failed"), { code })));
+				}
+				await waitFor(() => notices.some(({ message, level }) => level === "warning" && message.includes(code)));
+				assert.equal(__testing.activeWatcherCount(), initialWatchers - 1, "only the failed root must stop");
+				assert.ok(notices.some(({ message }) => message.includes("/skill-registry:refresh")));
+				fs.writeFileSync(projectSkill, "---\\nname: local\\ndescription: Changed project skill.\\n---\\n");
+				const registry = join(cwd, ".atl", "skill-registry.md");
+				await waitFor(() => fs.readFileSync(registry, "utf8").includes("Changed project skill"));
+				fs.writeFileSync(userSkill, "---\\nname: imagegen\\ndescription: Manually changed user skill.\\n---\\n");
+				await commands.get("skill-registry:refresh").handler("", ctx);
+				assert.match(fs.readFileSync(registry, "utf8"), /Manually changed user skill/);
+			} finally {
+				await events.get("session_shutdown")(undefined, ctx);
+			}
+			assert.equal(__testing.activeWatcherCount(), 0);
+			await events.get("session_start")(undefined, ctx);
+			await __testing.startupSettled();
+			assert.equal(__testing.activeWatcherCount(), 2, "a later session must rewatch the failed root");
+			await events.get("session_shutdown")(undefined, ctx);
+			assert.equal(__testing.activeWatcherCount(), 0);
+			console.log("SURVIVED ${code}");
+		`], {
+			encoding: "utf8",
+			timeout: 15_000,
+			env: { ...process.env, GIT_CEILING_DIRECTORIES: root },
+		});
+		assert.equal(child.error, undefined, child.error?.message);
+		assert.equal(child.status, 0, child.stderr);
+		assert.match(child.stdout, new RegExp(`SURVIVED ${code}`));
+	});
+}