gentle-pi 3.3.0 → 3.4.0

package/tests/review-host-relay.test.ts

@@ -556,6 +556,27 @@ test("the relay forwards the caller-owned selection and thinking level to the co
 	assert.equal(calls[0]!.routingKey, "review-risk");
 });
 
+// The in-process reviewer completion is an extension side-call that bypasses
+// pi's main agent loop, so the relay must forward the caller's live session id
+// into the completion request; the completion itself turns it into the
+// OpenCode attribution headers (lib/inprocess-reviewer.ts). A absent session
+// id forwards nothing and is never an error.
+test("the relay forwards the caller's reviewer session id into the completion request", async (t) => {
+	const fixture = harness(t);
+	const { runReviewer, calls } = textReviewer(REVIEWER_TEXT);
+	await runRelay(fixture, { reviewerSessionId: "ses-live-1" }, runReviewer);
+	assert.equal(calls.length, 1);
+	assert.equal(calls[0]!.sessionId, "ses-live-1");
+});
+
+test("a relay request with no reviewer session id adds no session id to the completion request", async (t) => {
+	const fixture = harness(t);
+	const { runReviewer, calls } = textReviewer(REVIEWER_TEXT);
+	await runRelay(fixture, {}, runReviewer);
+	assert.equal(calls.length, 1);
+	assert.equal(calls[0]!.sessionId, undefined);
+});
+
 test("a missing model registry is refused typed before materialize ever runs", async (t) => {
 	const fixture = harness(t);
 	const { runReviewer, calls } = textReviewer(REVIEWER_TEXT);

package/tests/review-integration-v2.test.ts

@@ -14,6 +14,7 @@ import {
 	decodeReviewProjectionV1,
 	decodeReviewRepairV2,
 	decodeReviewStartV3,
+	decodeReviewStartV4,
 	decodeReviewStatusV3,
 } from "../lib/review-integration-v2.ts";
 
@@ -349,6 +350,35 @@ test("capabilities gates and projections still enforce the required floor", () =
 	assert.throws(() => decode(missingProjection), /projections/);
 });
 
+test("START/v4 preserves provider-generated manifest evidence while retaining exact omitempty validation", () => {
+	const source = fixture<JsonObject>("start.fixture.json");
+	source.schema = "gentle-ai.review-integration.start/v4";
+	source.action = "closed";
+	source.lenses_required = false;
+	source.state = "approved";
+	source.selected_lenses = [];
+	delete source.repository_context;
+	const entry = (source.changed_path_manifest as JsonObject[])[0];
+	entry.generated = true;
+
+	const decoded = decodeReviewStartV4(source);
+	assert.equal(decoded.changedPathManifest?.[0]?.generated, true);
+
+	const omitted = clone(source);
+	delete (omitted.changed_path_manifest as JsonObject[])[0].generated;
+	assert.doesNotThrow(() => decodeReviewStartV4(omitted));
+
+	for (const generated of [false, "true"] as const) {
+		const invalid = clone(source);
+		((invalid.changed_path_manifest as JsonObject[])[0]).generated = generated;
+		assert.throws(() => decodeReviewStartV4(invalid), /generated/);
+	}
+
+	const unknown = clone(source);
+	((unknown.changed_path_manifest as JsonObject[])[0]).unrelated = true;
+	assert.throws(() => decodeReviewStartV4(unknown), /not allowed/);
+});
+
 test("START independently binds base/candidate tree and the target-mode overlay pair", () => {
 	const source = fixture<JsonObject>("start.fixture.json");
 	const decoded = decodeReviewStartV3(source);

package/tests/review-ledger-contract.test.ts

@@ -22,7 +22,6 @@ const README = "README.md";
 const TECHNICAL_REFERENCE = "docs/readme-reference.md";
 const CHAIN = "assets/chains/4r-review.chain.md";
 const SDD_WORKFLOW = "assets/sdd-orchestrator-workflow.md";
-const RELEASE_SKILL = "skills/release/SKILL.md";
 const WORKER = "assets/agents/gentle-ai-worker.md";
 const CANONICAL_LIFECYCLE_SPECS = [
 	"openspec/specs/review-orchestration/spec.md",
@@ -400,7 +399,7 @@ test("technical reference documents the dynamic runtime authority boundary witho
 });
 
 test("managed contracts retain no fresh lifecycle review directive", () => {
-	const managed = union([...ORCHESTRATOR, SDD_WORKFLOW, RELEASE_SKILL, WORKER, GENTLE_SKILL, README]);
+	const managed = union([...ORCHESTRATOR, SDD_WORKFLOW, WORKER, GENTLE_SKILL, README]);
 	for (const obsolete of [
 		"A fresh review still follows delegated implementation.",
 		"run a fresh-context review lens unless",

package/tests/review-relay-transport-agent.test.ts

@@ -8,7 +8,7 @@ import { __testing } from "../extensions/gentle-ai.ts";
 import { REVIEW_HOST_RELAY_FAILURE, ReviewHostRelayError } from "../lib/review-host-relay.ts";
 import { NativeReviewIntegrationError, type NativeReviewCli } from "../lib/native-review-cli.ts";
 import { CandidateViewRegistry } from "../lib/review-candidate-view.ts";
-import type { ReviewCollectInputV3, ReviewStatusV3 } from "../lib/review-integration-v2.ts";
+import type { ReviewArtifactSubjectV2, ReviewCollectInputV3, ReviewStatusV3 } from "../lib/review-integration-v2.ts";
 import type { ReviewHostRelayRequest } from "../lib/review-host-relay.ts";
 
 // Third field failure on the recovered-lineage defect (2026-08-16, gentle-pi
@@ -149,10 +149,11 @@ function transportAwareNative(options: { refusalCode?: string } = {}): {
 	return { native, agents };
 }
 
-async function runCapture(cwd: string, native: NativeReviewCli, lineageId: string, input: Record<string, unknown> = { reviewerRunAcknowledged: true }): Promise<Record<string, unknown>> {
+async function runCapture(cwd: string, native: NativeReviewCli, lineageId: string, input: Record<string, unknown> = { reviewerRunAcknowledged: true }, reviewerSessionId?: string): Promise<Record<string, unknown>> {
 	return await __testing.executeReviewCaptureOperation(
 		{ lineageId, collectBinding: JSON.stringify(collectInput(lineageId, true)), ...input },
 		cwd, native, undefined, new CandidateViewRegistry(),
+		undefined, undefined, undefined, reviewerSessionId,
 	) as Record<string, unknown>;
 }
 
@@ -217,6 +218,110 @@ test("capture forwards the lens's user-owned selection and thinking level to the
 	assert.equal(relayed[0]!.routingKey, "review-reliability");
 });
 
+// The live session id threads from the extension context through both
+// request builders, so an OpenCode-routed reviewer model carries its
+// attribution headers (a side-call bypasses pi's main agent loop, where pi
+// adds them itself). A absent session id adds nothing and is never an error.
+test("capture threads the caller's live session id into the relay request", async (t) => {
+	t.after(() => __testing.setReviewHostRelayRunnerForTesting());
+	const cwd = repository(t);
+	const { native } = transportAwareNative();
+	const relayed: ReviewHostRelayRequest[] = [];
+	__testing.setReviewHostRelayRunnerForTesting(async (request: ReviewHostRelayRequest) => {
+		relayed.push(request);
+		return { promptByteLength: 128, resultByteLength: 64, submission: '{"admission_decision":"completed"}' };
+	});
+
+	await runCapture(cwd, native, "session-lineage", { reviewerRunAcknowledged: true }, "ses-live-1");
+	assert.equal(relayed.length, 1);
+	assert.equal(relayed[0]!.reviewerSessionId, "ses-live-1");
+});
+
+test("capture with no live session id adds no reviewer session id to the relay request", async (t) => {
+	t.after(() => __testing.setReviewHostRelayRunnerForTesting());
+	const cwd = repository(t);
+	const { native } = transportAwareNative();
+	const relayed: ReviewHostRelayRequest[] = [];
+	__testing.setReviewHostRelayRunnerForTesting(async (request: ReviewHostRelayRequest) => {
+		relayed.push(request);
+		return { promptByteLength: 128, resultByteLength: 64, submission: '{"admission_decision":"completed"}' };
+	});
+
+	await runCapture(cwd, native, "no-session-lineage");
+	assert.equal(relayed.length, 1);
+	assert.equal(relayed[0]!.reviewerSessionId, undefined);
+});
+
+function groupInput(lineageId: string, lens: string, order: number): ReviewCollectInputV3 {
+	const subjectHash = `sha256:${String(order + 1).repeat(64)}`;
+	const base = collectInput(lineageId, true);
+	const arguments_ = base.arguments.map((argument) => {
+		if (argument.name === "lens") return { ...argument, value: lens, token: `--lens=${lens}` };
+		if (argument.name === "order") return { ...argument, value: String(order), token: `--order=${order}` };
+		if (argument.name === "subject-hash") return { ...argument, value: subjectHash, token: `--subject-hash=${subjectHash}` };
+		return argument;
+	});
+	return { ...base, arguments: arguments_, artifactSubject: { ...base.artifactSubject, subjectHash, lens: lens as ReviewArtifactSubjectV2["lens"], selectedOrder: order } };
+}
+
+function groupStatus(lineageId: string, inputs: readonly ReviewCollectInputV3[]): ReviewStatusV3 {
+	const status = recoveredStatus(lineageId, false) as ReviewStatusV3 & { repositoryContext?: Record<string, unknown>; nextTransition?: { kind: string; reasonCode: string; collect: { inputs: ReviewCollectInputV3[] } } };
+	// The reviewer group binds one repository context per slot; reuse the same
+	// opaque handle shape the finalizeStatus fixtures in the routing tests use.
+	status.repositoryContext = { capability: "review.opaque_repository_context", handle: `rctx1_${"e".repeat(64)}`, revision: SHA, targetIdentity: SHA };
+	status.nextTransition = { kind: "collect", reasonCode: "reviewer_results_required", collect: { inputs: [...inputs] } };
+	return status;
+}
+
+function queueNative(statuses: readonly ReviewStatusV3[]): { native: NativeReviewCli; agents: Array<string | undefined> } {
+	const agents: Array<string | undefined> = [];
+	const queue = [...statuses];
+	const native = {
+		targetStatus: async (request: { agent?: string }) => {
+			agents.push(request.agent);
+			const next = queue.shift();
+			if (next === undefined) throw new Error("status queue exhausted");
+			return next;
+		},
+	} as unknown as NativeReviewCli;
+	return { native, agents };
+}
+
+function prepared(request: ReviewHostRelayRequest) {
+	return { request, promptByteLength: 64, resultByteLength: 32 };
+}
+
+test("capture group threads the caller's live session id into every relay request", async (t) => {
+	t.after(() => __testing.setReviewHostRelayGroupRunnersForTesting());
+	const cwd = repository(t);
+	const lineageId = "group-session-lineage";
+	const inputs = [groupInput(lineageId, "review-risk", 0), groupInput(lineageId, "review-resilience", 1)];
+	// The final reconciliation STATUS must no longer offer the submitted
+	// reviewer suffix; a STATUS without a collect transition reconciles the
+	// drained group instead of replaying the submitted set.
+	const finalStatus = groupStatus(lineageId, []) as ReviewStatusV3 & { nextTransition?: { kind: string; reasonCode: string; collect: { inputs: ReviewCollectInputV3[] } } };
+	delete finalStatus.nextTransition;
+	const { native } = queueNative([groupStatus(lineageId, inputs), groupStatus(lineageId, inputs), groupStatus(lineageId, inputs.slice(1)), finalStatus]);
+	const relayed: ReviewHostRelayRequest[] = [];
+	__testing.setReviewHostRelayGroupRunnersForTesting(
+		async (requests: readonly ReviewHostRelayRequest[]) => {
+			relayed.push(...requests);
+			return requests.map(prepared);
+		},
+		async (result: { promptByteLength: number; resultByteLength: number }) => ({ promptByteLength: result.promptByteLength, resultByteLength: result.resultByteLength, submission: "{}" }),
+	);
+
+	const result = await __testing.executeReviewCaptureGroupOperation(
+		{ lineageId, collectBindings: inputs.map((input) => JSON.stringify(input)), reviewerRunAcknowledged: true },
+		cwd, native, undefined, new CandidateViewRegistry(),
+		undefined, undefined, undefined, "ses-live-1",
+	) as Record<string, unknown>;
+
+	assert.equal(relayed.length, 2);
+	assert.ok(relayed.every((request) => request.reviewerSessionId === "ses-live-1"), "every grouped reviewer request must carry the live session id");
+	assert.equal(result.outcome, "native-reviewer-group-status-reconciled");
+});
+
 // gentle-pi#311 P2 decision (flagged for confirmation): the in-process path
 // has no ambient default model. A routing entry with no configured model used
 // to launch the child selection-free (inheriting pi's own default); the real

package/tests/review-risk-assessment.test.ts

@@ -9,6 +9,7 @@ import {
 	NativeReviewCliV216,
 	type ExecFileAdapter,
 	type NativeReviewCli,
+	type NativeReviewAssessRequest,
 } from "../lib/native-review-cli.ts";
 import {
 	decodeReviewAssessmentV1,
@@ -573,6 +574,109 @@ function nativeClient(adapter: ExecFileAdapter): NativeReviewCliV216 {
 	return new NativeReviewCliV216(adapter, "/package/.gentle-ai/gentle-ai", 30_000, 1024 * 1024);
 }
 
+test("gentle_review assess: stderr-only refusal preserves safe actionable diagnostics and fails closed", async () => {
+	const queue = queuedAdapter([{ stdout: "", stderr: "untracked scope declaration required; use --untracked-scope=exclude or select; token=hidden-secret", exitCode: 1 }]);
+	const client = nativeClient(queue.adapter);
+	const tool = reviewControllerTool({ assess: client.assess.bind(client) });
+	const result = await tool.execute("refusal", { operation: "assess" }, undefined, undefined, ctx);
+	const details = result.details as { risk: string; reasons: { code: string; detail: string }[]; plan: { independentVerifier: boolean } };
+	assert.equal(details.risk, "unassessable");
+	assert.equal(details.plan.independentVerifier, true);
+	assert.equal(details.reasons[0].code, NATIVE_REVIEW_ERROR_CODE.EMPTY_OUTPUT);
+	assert.match(details.reasons[0].detail, /untracked scope declaration required/);
+	assert.match(details.reasons[0].detail, /--untracked-scope=exclude/);
+	assert.doesNotMatch(JSON.stringify(result), /hidden-secret/);
+});
+
+test("gentle_review assess: diagnostic projection is bounded and redacts paths and environment assignments", async () => {
+	const queue = queuedAdapter([{ stdout: "", stderr: "untracked declaration required /private/project/file C:\\private\\project\\file PRIVATE_PROJECT=hidden-project token=hidden-token " + "x".repeat(6000), exitCode: 1 }]);
+	const client = nativeClient(queue.adapter);
+	const tool = reviewControllerTool({ assess: client.assess.bind(client) });
+	const result = await tool.execute("private-refusal", { operation: "assess" }, undefined, undefined, ctx);
+	const serialized = JSON.stringify(result);
+	const detail = (result.details as { reasons: { detail: string }[] }).reasons[0].detail;
+	assert.match(detail, /untracked declaration required/);
+	assert.ok(detail.length < 4300);
+	assert.doesNotMatch(serialized, /hidden-project|hidden-token|private.project|\/package\//);
+});
+
+for (const [shape, sensitive] of [
+	["lowercase environment", "private_project=hidden-project"],
+	["quoted environment", 'private_project="hidden project value"'],
+	["credential argument", "--password hidden-credential"],
+	["quoted credential argument", '--api-key "hidden credential value"'],
+	["POSIX path with spaces", "/private/hidden project/hidden file.ts"],
+	["quoted POSIX path", '"/private/hidden project/hidden file.ts"'],
+	["Windows path with spaces", String.raw`C:\private\hidden project\hidden file.ts`],
+	["quoted Windows path", String.raw`"C:\private\hidden project\hidden file.ts"`],
+]) {
+	test(`assess diagnostic redacts ${shape} without losing provider guidance`, async () => {
+		const queue = queuedAdapter([{ stdout: "", stderr: `${sensitive}\nuntracked scope declaration required; use --untracked-scope=exclude or select`, exitCode: 1 }]);
+		const client = nativeClient(queue.adapter);
+		const result = await reviewControllerTool({ assess: client.assess.bind(client) }).execute("private-shape", { operation: "assess" }, undefined, undefined, ctx);
+		const details = result.details as { risk: string; reasons: { code: string; detail: string }[] };
+		assert.equal(details.risk, "unassessable");
+		assert.equal(details.reasons[0].code, NATIVE_REVIEW_ERROR_CODE.EMPTY_OUTPUT);
+		assert.doesNotMatch(JSON.stringify(result), /hidden|private_project| project|file\.ts|\/private\//);
+		assert.match(details.reasons[0].detail, /untracked scope declaration required; use --untracked-scope=exclude or select/);
+		assert.ok(details.reasons[0].detail.length < 4300);
+	});
+}
+
+for (const selection of [
+	{ untrackedScope: "exclude", expectedUntrackedInventory: "inventory-v1" },
+	{ untrackedScope: "select", expectedUntrackedInventory: "inventory-v1", intendedUntracked: ["new/file.ts", "notes.md"] },
+] as const) {
+	test(`native and facade assess forward explicit ${selection.untrackedScope} without choosing scope`, async () => {
+		const queue = queuedAdapter([{ stdout: JSON.stringify(validEnvelope()) }, { stdout: JSON.stringify(validEnvelope()) }]);
+		const client = nativeClient(queue.adapter);
+		await client.assess({ cwd: process.cwd(), ...selection });
+		const tool = reviewControllerTool({ assess: client.assess.bind(client) });
+		const result = await tool.execute("selected", { operation: "assess", input: JSON.stringify({ ...selection, baseRef: "origin/main", committedOnly: true }) }, undefined, undefined, ctx);
+		assert.equal((result.details as { risk: string }).risk, "medium");
+		const flags = [`--untracked-scope=${selection.untrackedScope}`, "--expected-untracked-inventory=inventory-v1", ...(selection.untrackedScope === "select" ? selection.intendedUntracked.map((path) => `--intended-untracked=${path}`) : [])];
+		assert.deepEqual(queue.calls[0].arguments, ["review", "assess", "--cwd", process.cwd(), ...flags, "--json"]);
+		assert.deepEqual(queue.calls[1].arguments, ["review", "assess", "--cwd", process.cwd(), "--base-ref", "origin/main", "--committed-only", ...flags, "--json"]);
+	});
+}
+
+test("native and facade assess reject invalid declarations before launching", async () => {
+	const invalid = [
+		{ untrackedScope: "exclude" },
+		{ expectedUntrackedInventory: "inventory" },
+		{ intendedUntracked: ["file.ts"] },
+		{ untrackedScope: "all", expectedUntrackedInventory: "inventory" },
+		{ untrackedScope: "exclude", expectedUntrackedInventory: "inventory", intendedUntracked: ["file.ts"] },
+		{ untrackedScope: "select", expectedUntrackedInventory: "inventory" },
+		{ untrackedScope: "select", expectedUntrackedInventory: "inventory", intendedUntracked: [] },
+		...[null, 42, "", " inventory", "inventory\n", "inv\u0000entory"].map((expectedUntrackedInventory) => ({ untrackedScope: "exclude", expectedUntrackedInventory })),
+		...["/absolute", "C:\\absolute", "dir\\file", ".", "..", "../file", "dir/../file", "dir/./file", "dir//file", "dir/", " file", "file\n"].map((path) => ({ untrackedScope: "select", expectedUntrackedInventory: "inventory", intendedUntracked: [path] })),
+		{ untrackedScope: "select", expectedUntrackedInventory: "inventory", intendedUntracked: ["file", "file"] },
+		{ untrackedScope: "select", expectedUntrackedInventory: "inventory", intendedUntracked: "file" },
+	];
+	for (const selection of invalid) {
+		const queue = queuedAdapter([]);
+		const client = nativeClient(queue.adapter);
+		await assert.rejects(() => client.assess({ cwd: process.cwd(), ...selection } as NativeReviewAssessRequest), TypeError);
+		const tool = reviewControllerTool({ assess: client.assess.bind(client) });
+		await assert.rejects(() => tool.execute("invalid", { operation: "assess", input: JSON.stringify(selection) }, undefined, undefined, ctx));
+		assert.equal(queue.calls.length, 0);
+	}
+});
+
+test("facade assess leaves absent declarations to native and preserves stale-inventory refusal", async () => {
+	for (const selection of [{}, { untrackedScope: "exclude", expectedUntrackedInventory: "stale-inventory" }]) {
+		const queue = queuedAdapter([{ stdout: "", stderr: "untracked inventory changed; inspect and declare the current inventory", exitCode: 1 }]);
+		const client = nativeClient(queue.adapter);
+		const tool = reviewControllerTool({ assess: client.assess.bind(client) });
+		const result = await tool.execute("stale", { operation: "assess", input: JSON.stringify(selection) }, undefined, undefined, ctx);
+		const details = result.details as { risk: string; reasons: { detail: string }[] };
+		assert.equal(details.risk, "unassessable");
+		assert.match(details.reasons[0].detail, /inventory changed/);
+		if (!("untrackedScope" in selection)) assert.deepEqual(queue.calls[0].arguments, ["review", "assess", "--cwd", process.cwd(), "--json"]);
+	}
+});
+
 test("native assess: decodes a well-formed envelope and sends the exact plain-versioned argv", async () => {
 	const queue = queuedAdapter([{ stdout: JSON.stringify({ schema: REVIEW_ASSESSMENT_SCHEMA, risk: "medium", reasons: [], changed_paths: 1, changed_lines: 2, candidate: { kind: "current-changes" } }) }]);
 	const result = await nativeClient(queue.adapter).assess!({ cwd: process.cwd() });

package/tests/shell-bar.test.ts

@@ -9,6 +9,7 @@ import {
 	renderGauge,
 	renderShellBar,
 	renderShellHeaderBar,
+	renderShellHeaderRule,
 	renderShellSidebarBar,
 	shellEnabled,
 	type ShellBarModel,
@@ -427,3 +428,10 @@ test("renderShellHeaderBar's usage span always points at the usage text, not ctx
 		assert.equal(usageSpan.end, visibleWidth(text), "the usage segment always ends at the right edge");
 	}
 });
+
+test("renderShellHeaderRule paints one full-width line in the editor frame color", () => {
+	assert.equal(renderShellHeaderRule(taggedTheme, 4), "<border>────</border>", "the rule uses the editor frame's border role");
+	assert.equal(renderShellHeaderRule(plainTheme, 12), "─".repeat(12), "the rule spans the full width");
+	assert.equal(renderShellHeaderRule(plainTheme, 0), "");
+	assert.equal(renderShellHeaderRule(plainTheme, -3), "", "negative widths clamp to an empty rule");
+});

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

@@ -23,7 +23,7 @@ function rail(f: ReturnType<typeof fixture>): ScrollView {
 	assert.equal(node.type, "hstack");
 	return node.entries[1].component;
 }
-type HstackNode = { type: string; gap: number; align: string; entries: { component: unknown; basis: number; grow: number; shrink: number; minSize: number }[] };
+type HstackNode = { type: string; gap: number; align: string; entries: { component: unknown; basis: number | string; grow: number; shrink: number; minSize: number }[] };
 // Finds the [left, scroll] hstack regardless of whether it is returned
 // directly (no active header) or nested one level under the header vstack.
 function hstackOf(f: ReturnType<typeof fixture>): HstackNode {
@@ -130,7 +130,7 @@ test("wheel scrolls the rail and is consumed at both boundaries and blank space"
 	f.host.terminal.columns = 160;
 	const restored = rail(f);
 	assert.deepEqual(f.bottom.render(80), []);
-	const layout = f.root[NODE]() as unknown as { gap: number; entries: { basis: number; grow: number; shrink: number; minSize: number }[] };
+	const layout = f.root[NODE]() as unknown as { gap: number; entries: { basis: number | string; grow: number; shrink: number; minSize: number }[] };
 	assert.equal(layout.gap, 3);
 	assert.deepEqual(layout.entries.map(({ basis, grow, shrink, minSize }) => ({ basis, grow, shrink, minSize })), [
 		{ basis: 0, grow: 1, shrink: 1, minSize: 1 },
@@ -188,11 +188,13 @@ test("rail dispatches a clipped, scroll-translated left click to only the matchi
 	const hit = scroll.handleMouse(mouse("click", "left", headerY));
 	assert.equal(hit?.handled, true);
 	assert.equal(clicks, 1);
-	assert.deepEqual(received.at(-1) && { x: received.at(-1)!.x, y: received.at(-1)!.y, width: received.at(-1)!.width, height: received.at(-1)!.height }, { x: 1, y: 0, width: 47, height: 2 });
+		// With a transient scrollbar the rail no longer reserves a column, so
+	// clipped parts are one column wider than in the always-on geometry.
+	assert.deepEqual(received.at(-1) && { x: received.at(-1)!.x, y: received.at(-1)!.y, width: received.at(-1)!.width, height: received.at(-1)!.height }, { x: 1, y: 0, width: 48, height: 2 });
 
 	const gapY = headerY - 1;
 	assert.equal(scroll.handleMouse(mouse("click", "left", gapY)), undefined, "section gaps do not hit a neighbor");
-	assert.equal(scroll.handleMouse({ ...mouse("click", "left", headerY), x: 48 }), undefined, "padding outside the clipped part is inert");
+	assert.equal(scroll.handleMouse({ ...mouse("click", "left", headerY), x: 49 }), undefined, "padding outside the clipped part is inert");
 	invalidateSidebar(f.tui);
 	assert.equal(scroll.handleMouse(mouse("click", "left", headerY)), undefined, "stale geometry is inert");
 	f.host.terminal.columns = 139;
@@ -586,8 +588,10 @@ test("an active header wraps the hstack in a vstack and removes the banner from
 	assert.equal(node.type, "vstack");
 	assert.equal(node.gap, 0);
 	assert.equal(node.align, "stretch");
+	// basis "auto": pi-tui measures the header leaf from its rendered lines
+	// (one line: the status bar; with the rule row: two) instead of hard-pinning the row.
 	assert.deepEqual(node.entries.map(({ basis, grow, shrink, minSize }) => ({ basis, grow, shrink, minSize })), [
-		{ basis: 1, grow: 0, shrink: 0, minSize: 1 },
+		{ basis: "auto", grow: 0, shrink: 0, minSize: 1 },
 		{ basis: 0, grow: 1, shrink: 1, minSize: 1 },
 	]);
 	const header = node.entries[0].component as { render(width: number): string[] };
@@ -608,6 +612,31 @@ test("an active header wraps the hstack in a vstack and removes the banner from
 	assert.notEqual(rail[1]?.trim(), "", "the first card starts on the second row");
 });
 
+test("the header leaf carries the rule row: a two-line header renders both lines at full width", (t) => {
+	const f = fixture();
+	sidebarHeader(f.tui, {
+		render: (width: number) => [`HEADER ${width}`, `RULE ${width}`],
+		invalidate() {},
+	});
+	t.after(installSidebar(f.tui, theme));
+
+	const node = f.root[NODE]() as unknown as { type: string; entries: { component: Component }[] };
+	assert.equal(node.type, "vstack", "a two-line header still wraps the hstack in a vstack");
+	const header = node.entries[0]!.component as { render(width: number): string[] };
+	assert.deepEqual(header.render(0), ["HEADER 138", "RULE 138"], "both the status line and the rule row reach the layout, rendered at the terminal width minus the rail's right inset");
+});
+
+test("below the sidebar breakpoint a rule-like header paints no rule row", (t) => {
+	const f = fixture("fullscreen", 139);
+	sidebarHeader(f.tui, { render: (width: number) => [`HEADER ${width}`, `RULE ${width}`], invalidate() {} });
+	t.after(installSidebar(f.tui, theme));
+
+	// Below SIDEBAR_BREAKPOINT prepare() declines, so the replacement hands
+	// back the native root's own layout node: neither the header wrapper nor
+	// a rule row ever paints.
+	assert.deepEqual(f.root[NODE](), f.original(), "below the breakpoint the rule is removed with the whole sidebar");
+});
+
 test("without a registered header the rail keeps the banner and the plain hstack", (t) => {
 	const f = fixture();
 	t.after(installSidebar(f.tui, theme));
@@ -707,3 +736,29 @@ test("the header component's handleMouse is a harmless no-op when no header part
 	// backward-compatible fallback), so there is no header leaf to click at all.
 	assert.equal(node.type, "hstack");
 });
+
+test("rail scrollbar is transient: hidden by default, visible only while scrolling overflow", (t) => {
+	const f = fixture();
+	t.mock.timers.enable({ apis: ["setTimeout"] });
+	t.after(installSidebar(f.tui, theme));
+	const scroll = rail(f);
+	// Regression guard: the rail scroll view used to hardcode scrollbar
+	// "always", re-slicing its column on every render pass even when idle.
+	assert.equal(scroll.scrollbar, "auto");
+	sidebarPart(f.tui, "todo", { render: () => Array.from({ length: 60 }, (_, i) => `todo row ${i}`), invalidate() {} });
+	renderLayoutFrame(f.root, 140, 20, () => {});
+	assert.equal(scroll.isScrollbarVisible, false, "no scroll yet: hidden even with overflow");
+	scroll.scrollBy(1);
+	assert.equal(scroll.isScrollbarVisible, true, "rail scroll reveals the transient scrollbar");
+	t.mock.timers.tick(1000);
+	assert.equal(scroll.isScrollbarVisible, false, "hidden again after the transient window");
+});
+
+test("rail scrollbar stays hidden when the rail does not overflow", (t) => {
+	const f = fixture();
+	t.after(installSidebar(f.tui, theme));
+	const scroll = rail(f);
+	renderLayoutFrame(f.root, 140, 20, () => {});
+	scroll.scrollBy(1);
+	assert.equal(scroll.isScrollbarVisible, false);
+});

package/tests/shell-usage.test.ts

@@ -7,15 +7,20 @@ import {
 	parseAnthropicHeaders,
 	parseCodexHeaders,
 	parseNanQuota,
+	parseProviderUsage,
 	parseUsageHeaders,
 	parseCodexUsage,
+	parseUsageSource,
 	providerNote,
 	renderUsageBar,
 	renderUsagePanel,
 	SUPPORTED_USAGE_PROVIDERS,
+	UsageSourceRegistry,
+	USAGE_SOURCE_SCHEMA,
 	UsageStore,
 	windowLabel,
 	type ProviderUsage,
+	type UsageSource,
 	type UsageWindow,
 } from "../lib/shell-usage.ts";
 
@@ -243,6 +248,130 @@ test("nan is a supported usage provider with its own pending note", () => {
 	assert.deepEqual(renderUsagePanel([], plainTheme, 100, NOW, { provider: "nan" }), ["✿ nan · no usage yet · r to fetch"]);
 });
 
+// A generic hook: any extension can register a usage source for its own
+// provider at runtime, without gentle-shell knowing anything about it.
+
+test("parseUsageSource validates the registration payload and ignores anything malformed", () => {
+	const fetchFn = async () => undefined;
+	const valid = parseUsageSource({ schema: USAGE_SOURCE_SCHEMA, provider: "acme-cloud", fetch: fetchFn });
+	assert.equal(valid?.schema, USAGE_SOURCE_SCHEMA);
+	assert.equal(valid?.provider, "acme-cloud");
+	assert.equal(valid?.fetch, fetchFn);
+	assert.equal(valid?.pendingNote, undefined);
+
+	const withNote = parseUsageSource({ schema: USAGE_SOURCE_SCHEMA, provider: "acme-cloud", pendingNote: "warming up", fetch: fetchFn });
+	assert.equal(withNote?.pendingNote, "warming up");
+
+	assert.equal(parseUsageSource({ schema: "gentle-pi.usage-source/v0", provider: "acme-cloud", fetch: fetchFn }), undefined, "wrong schema");
+	assert.equal(parseUsageSource({ schema: USAGE_SOURCE_SCHEMA, provider: "", fetch: fetchFn }), undefined, "empty provider");
+	assert.equal(parseUsageSource({ schema: USAGE_SOURCE_SCHEMA, provider: "acme cloud", fetch: fetchFn }), undefined, "unsafe provider id");
+	assert.equal(parseUsageSource({ schema: USAGE_SOURCE_SCHEMA, provider: "acme-cloud", fetch: "nope" }), undefined, "fetch not a function");
+	assert.equal(parseUsageSource({ schema: USAGE_SOURCE_SCHEMA, provider: "acme-cloud", pendingNote: 7, fetch: fetchFn }), undefined, "pendingNote must be a string when present");
+	assert.equal(parseUsageSource(null), undefined);
+	assert.equal(parseUsageSource(undefined), undefined);
+	assert.equal(parseUsageSource("acme-cloud"), undefined);
+	assert.equal(parseUsageSource({}), undefined);
+});
+
+test("UsageSourceRegistry replaces a provider's source on re-registration", () => {
+	const registry = new UsageSourceRegistry();
+	assert.equal(registry.has("acme-cloud"), false);
+	assert.equal(registry.get("acme-cloud"), undefined);
+	assert.equal(registry.note("acme-cloud"), undefined);
+
+	const first: UsageSource = { schema: USAGE_SOURCE_SCHEMA, provider: "acme-cloud", fetch: async () => undefined };
+	registry.register(first);
+	assert.equal(registry.has("acme-cloud"), true);
+	assert.equal(registry.get("acme-cloud"), first);
+	assert.equal(registry.note("acme-cloud"), "no usage yet · r to fetch", "default note when the source sets none");
+
+	const second: UsageSource = { schema: USAGE_SOURCE_SCHEMA, provider: "acme-cloud", pendingNote: "still warming up", fetch: async () => undefined };
+	registry.register(second);
+	assert.equal(registry.get("acme-cloud"), second, "re-registration replaces, never accumulates");
+	assert.equal(registry.note("acme-cloud"), "still warming up");
+});
+
+test("a registered provider is supported without touching the built-in note map", () => {
+	const registry = new UsageSourceRegistry();
+	assert.equal(providerNote("acme-cloud"), "no subscription usage for this provider");
+	assert.equal(providerNote("acme-cloud", registry), "no subscription usage for this provider", "an empty registry changes nothing");
+	registry.register({ schema: USAGE_SOURCE_SCHEMA, provider: "acme-cloud", fetch: async () => undefined });
+	assert.equal(providerNote("acme-cloud", registry), "no usage yet · r to fetch");
+	assert.equal(providerNote("nan", registry), "no usage yet · r to fetch", "the static built-ins are unaffected");
+	assert.deepEqual(renderUsagePanel([], plainTheme, 100, NOW, { provider: "acme-cloud" }, registry), ["✿ acme-cloud · no usage yet · r to fetch"]);
+});
+
+// A registered source's resolved value crosses the same trust boundary a
+// parsed HTTP payload does. parseProviderUsage validates it exactly like
+// one, and the object gentle-shell records is always freshly built, never
+// the caller's own reference.
+
+const VALID_SOURCE_USAGE = {
+	provider: "acme-cloud",
+	plan: "Acme · 42 credits",
+	fetchedAt: 100,
+	limits: [
+		{
+			name: "acme-cloud",
+			limitReached: false,
+			windows: [
+				{ label: "week", usedPercent: 40, windowSeconds: 604_800, resetAt: null },
+				{ label: "day", usedPercent: 12, windowSeconds: 86_400, resetAt: 200, used: 5, budget: 40 },
+			],
+		},
+	],
+};
+
+test("parseProviderUsage accepts a matching shape and copies it defensively", () => {
+	const source = structuredClone(VALID_SOURCE_USAGE);
+	const parsed = parseProviderUsage(source, "acme-cloud");
+	assert.deepEqual(parsed, source);
+	assert.notEqual(parsed, source, "the recorded object must never be the caller's own reference");
+	assert.notEqual(parsed?.limits, source.limits);
+	assert.notEqual(parsed?.limits[0], source.limits[0]);
+	assert.notEqual(parsed?.limits[0].windows, source.limits[0].windows);
+	assert.notEqual(parsed?.limits[0].windows[0], source.limits[0].windows[0]);
+
+	// Mutating the caller's own object after the fact must never reach the copy.
+	source.limits[0].windows[0].usedPercent = 999;
+	assert.equal(parsed?.limits[0].windows[0].usedPercent, 40);
+});
+
+test("parseProviderUsage rejects a resolution for a different provider", () => {
+	assert.equal(parseProviderUsage(structuredClone(VALID_SOURCE_USAGE), "other-provider"), undefined);
+});
+
+test("parseProviderUsage rejects a missing or malformed limits array", () => {
+	assert.equal(parseProviderUsage({ provider: "acme-cloud", plan: undefined, fetchedAt: 0 }, "acme-cloud"), undefined, "limits missing entirely");
+	assert.equal(parseProviderUsage({ provider: "acme-cloud", plan: undefined, fetchedAt: 0, limits: "nope" }, "acme-cloud"), undefined, "limits not an array");
+	assert.equal(
+		parseProviderUsage({ provider: "acme-cloud", plan: undefined, fetchedAt: 0, limits: [{ name: "x", limitReached: "nope", windows: [] }] }, "acme-cloud"),
+		undefined,
+		"limitReached must be a boolean",
+	);
+});
+
+test("parseProviderUsage rejects a non-numeric usedPercent inside a window", () => {
+	const usage = structuredClone(VALID_SOURCE_USAGE);
+	(usage.limits[0].windows[0] as unknown as { usedPercent: unknown }).usedPercent = "40";
+	assert.equal(parseProviderUsage(usage, "acme-cloud"), undefined);
+});
+
+test("parseProviderUsage rejects a limit whose windows is not an array", () => {
+	const usage = structuredClone(VALID_SOURCE_USAGE);
+	(usage.limits[0] as unknown as { windows: unknown }).windows = "nope";
+	assert.equal(parseProviderUsage(usage, "acme-cloud"), undefined);
+});
+
+test("parseProviderUsage rejects malformed inputs outright", () => {
+	assert.equal(parseProviderUsage(undefined, "acme-cloud"), undefined);
+	assert.equal(parseProviderUsage(null, "acme-cloud"), undefined);
+	assert.equal(parseProviderUsage("acme-cloud", "acme-cloud"), undefined);
+	assert.equal(parseProviderUsage({ provider: "acme-cloud", plan: 7, fetchedAt: 0, limits: [] }, "acme-cloud"), undefined, "plan must be a string when present");
+	assert.equal(parseProviderUsage({ provider: "acme-cloud", plan: undefined, fetchedAt: Number.POSITIVE_INFINITY, limits: [] }, "acme-cloud"), undefined, "fetchedAt must be finite");
+	assert.deepEqual(parseProviderUsage({ provider: "acme-cloud", plan: undefined, fetchedAt: 0, limits: [] }, "acme-cloud"), { provider: "acme-cloud", plan: undefined, fetchedAt: 0, limits: [] });
+});
+
 test("renderUsagePanel lists each NaN model allowance with its reset on the same row", () => {
 	const usage = parseNanQuota(NAN_QUOTA, NOW);
 	const lines = renderUsagePanel([usage], plainTheme, 80, NOW, { provider: "nan" });

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

@@ -25,7 +25,7 @@ const PREFIXED_NAMES: Record<string, string> = {
 	"work-unit-commits": "gentle-ai-work-unit-commits",
 };
 
-const UNPREFIXED_DIRS = ["gentle-ai", "release"];
+const UNPREFIXED_DIRS = ["gentle-ai"];
 
 for (const [dir, expectedName] of Object.entries(PREFIXED_NAMES)) {
 	test(`skills/${dir}/SKILL.md frontmatter name is prefixed`, () => {