gentle-pi 2.4.0 → 2.6.0

package/lib/sdd-research-capabilities.ts

@@ -0,0 +1,228 @@
+import { isAbsolute, resolve, dirname, basename } from "node:path";
+import { realpathSync, lstatSync, openSync, readSync, fstatSync, closeSync } from "node:fs";
+import { createHash } from "node:crypto";
+import type { AgentDefinition } from "./agents-config.ts";
+
+// Exact registered Pi names, not provider display namespaces. MCP's generic
+// `mcp` and dynamic `mcp__context7` gateways are deliberately NOT grants: an
+// active gateway does not prove which remote methods it can safely expose.
+export const RESEARCH_TOOLS = ["fetch_content", "web_search", "source_check", "get_search_content"] as const;
+export const RESEARCH_CHILD_TOOLS_ENV = "GENTLE_PI_RESEARCH_TOOLS";
+export const RESEARCH_SELECTION_ENV = "GENTLE_PI_RESEARCH_SELECTION";
+export interface ResearchGrant {
+	tools: string[];
+	extensions: Record<string, string>;
+}
+export type ResearchSelection = Partial<Record<keyof ResearchCapabilities, ResearchGrant>>;
+type Inventory = {
+	getActiveTools?: () => string[];
+	getAllTools?: () => Array<{ name: string; sourceInfo?: { source?: string; path?: string } }>;
+};
+type Capability = { status: "available" | "blocked"; tools: string[]; reason: string };
+export type ResearchCapabilities = Record<"documentation" | "open-web", Capability>;
+
+export function resolveResearchCapabilities(pi: Inventory, restriction?: readonly string[]): ResearchCapabilities {
+	let names: string[] = [];
+	try {
+		const active = new Set(pi.getActiveTools?.() ?? []);
+		names = (pi.getAllTools?.() ?? [])
+			.filter(tool => active.has(tool.name) && tool.sourceInfo?.source !== "sdk" &&
+				(restriction === undefined || restriction.includes(tool.name)))
+			.map(tool => tool.name);
+	} catch { /* Inventory failure is not a grant. */ }
+	const tools = RESEARCH_TOOLS.filter(name => names.includes(name));
+	const capability = (required: string[], guidance: string): Capability => {
+		const missing = required.filter(name => !tools.includes(name as typeof RESEARCH_TOOLS[number]));
+		return {
+			status: missing.length === 0 ? "available" : "blocked",
+			tools: required.filter(name => tools.includes(name as typeof RESEARCH_TOOLS[number])),
+			reason: `${missing.length === 0 ? "" : `Missing active, approved, child-reachable tools: ${missing.join(", ")}. `}${guidance}`,
+		};
+	};
+	return {
+		documentation: capability(["fetch_content"], "Fetch official documentation URLs; validate publisher and version before citing."),
+		"open-web": capability(["web_search", "source_check", "fetch_content", "get_search_content"], "All four tools are required. Search, check sources and retrieve original content; inventory and search snippets alone are not evidence."),
+	};
+}
+
+export function renderResearchCapabilities(capabilities: ResearchCapabilities): string {
+	return [
+		"## SDD Research Capabilities",
+		"Package-approved mapping intersected with active runtime tools and explicit agent restrictions:",
+		...Object.entries(capabilities).map(([kind, value]) => `- ${kind}: ${value.status}; tools=${JSON.stringify(value.tools)}. ${value.reason}`),
+		"Availability is not evidence or proposal admission. Run selected supported classes, record tool calls, source URLs, retrieval time, publisher/version, excerpts and claim-to-source IDs. Child-local inventory must confirm availability before evidence collection.",
+		"Missing required tools block only the affected class. Any selected unavailable or partial class keeps proposal_ready=false. Preserve explicit source restrictions; never recommend skipping selected research because of a blanket denial.",
+		"Generic MCP and dynamic namespace gateways are not approved evidence routes. Never infer remote method access from gateway names, tool descriptions, bash, persistence tools, or remembered facts.",
+	].join("\n");
+}
+
+export function researchAgent(agent: AgentDefinition, pi: Inventory, selection?: unknown) {
+	const capabilities = resolveResearchCapabilities(pi, agent.tools);
+	const extensionPaths = new Set<string>();
+	const requested = selection && typeof selection === "object" && !Array.isArray(selection)
+		? selection as Record<string, unknown> : {};
+	let registered: ReturnType<NonNullable<Inventory["getAllTools"]>> = [];
+	try { registered = pi.getAllTools?.() ?? []; } catch { /* No provenance, no route. */ }
+	for (const [kind, capability] of Object.entries(capabilities)) {
+		const value = requested[kind];
+		const grant = value && typeof value === "object" ? value as Partial<ResearchGrant> : {};
+		const required = kind === "documentation" ? ["fetch_content"] : ["web_search", "source_check", "fetch_content", "get_search_content"];
+		const exact = Object.keys(requested).every(key => Object.hasOwn(capabilities, key)) &&
+			Array.isArray(grant.tools) && grant.tools.length === required.length &&
+			required.every(name => grant.tools!.includes(name)) &&
+			grant.extensions && Object.keys(grant.extensions).length === required.length;
+		const paths = required.map(name => registered.find(tool => tool.name === name)?.sourceInfo?.path);
+		capability.tools = exact ? required.filter((name, i) => capability.tools.includes(name) &&
+			typeof paths[i] === "string" && isAbsolute(paths[i]!) && paths[i] === grant.extensions![name]) : [];
+		if (capability.tools.length !== required.length) {
+			capability.status = "blocked";
+			capability.reason = `Selected exact grants and matching active extension provenance required. ${capability.reason}`;
+		} else {
+			for (const path of paths) extensionPaths.add(path!);
+		}
+	}
+	const available = new Set(Object.values(capabilities).filter(value => value.status === "available").flatMap(value => value.tools));
+	const local = new Set(["read", "grep", "find", "edit", "write", "mem_search", "mem_get_observation", "mem_save"]);
+	const tools = agent.tools.filter(name => local.has(name) || available.has(name));
+	return { agent: { ...agent, tools, instructions: `${agent.instructions}\n\n${renderResearchCapabilities(capabilities)}` }, capabilities, extensionPaths: [...extensionPaths] };
+}
+
+export const RESEARCH_ARTIFACT_ENV = "GENTLE_PI_RESEARCH_ARTIFACT";
+const ARTIFACT_STORES = ["openspec", "engram", "both", "none"] as const;
+interface EngramLocator {
+	id: number;
+	project: string;
+	topic_key: string;
+	revision_count: number;
+}
+export interface ResearchWriteIdentity {
+	revision: number;
+	digest: string;
+}
+interface ResearchLocator extends ResearchWriteIdentity {
+	artifact: string;
+	path?: string;
+	engram?: EngramLocator;
+}
+export interface ResearchArtifactIntent {
+	store: typeof ARTIFACT_STORES[number];
+	worktree: string;
+	changeName: string;
+	retainedIntent: string;
+	locators: ResearchLocator[];
+}
+const record = (value: unknown): Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+const positive = (value: unknown) => Number.isSafeInteger(value) && Number(value) > 0;
+// Missing leaves are allowed for diagnostic persistence; existing symlinks are not.
+export function canonicalArtifactPath(path: string): string {
+	try { lstatSync(path); }
+	catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT" || dirname(path) === path) throw error;
+		return resolve(canonicalArtifactPath(dirname(path)), basename(path));
+	}
+	return realpathSync(path);
+}
+export function parseResearchArtifactIntent(value: unknown, cwd: string, previous?: ResearchArtifactIntent): ResearchArtifactIntent {
+	const input = record(value);
+	if (!ARTIFACT_STORES.includes(input.store as ResearchArtifactIntent["store"])
+		|| input.worktree !== realpathSync(cwd) || input.worktree !== cwd) throw new Error("Research artifact worktree/store scope mismatch.");
+	if (typeof input.changeName !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(input.changeName)
+		|| typeof input.retainedIntent !== "string" || !input.retainedIntent.trim() || !Array.isArray(input.locators)) throw new Error("Missing bounded research scope/retained intent.");
+	const scope = structuredClone(input) as unknown as ResearchArtifactIntent;
+	const local = scope.store === "openspec" || scope.store === "both";
+	const memory = scope.store === "engram" || scope.store === "both";
+	if (scope.locators.length > 3 || (scope.store === "none" ? scope.locators.length !== 0 : scope.locators.length === 0)) throw new Error("Invalid research locator scope.");
+	const names = new Set<string>();
+	for (const locator of scope.locators) {
+		const item = record(locator), engram = record(item.engram);
+		if (!["research", "preproposal", "explore"].includes(String(item.artifact))
+			|| names.has(String(item.artifact))
+			|| !positive(item.revision) || typeof item.digest !== "string" || !/^[a-f0-9]{64}$/.test(item.digest)) throw new Error("Invalid research identity scope.");
+		names.add(locator.artifact);
+		const path = resolve(cwd, "openspec/changes", scope.changeName, `${locator.artifact}.md`);
+		if (local ? item.path !== path || canonicalArtifactPath(path) !== path : item.path !== undefined) throw new Error("OpenSpec locator outside exact scope.");
+		if (memory ? !positive(engram.id) || !positive(engram.revision_count) || typeof engram.project !== "string" || !engram.project.trim() || engram.topic_key !== `sdd/${scope.changeName}/${locator.artifact}` : item.engram !== undefined) throw new Error("Engram locator outside exact scope.");
+	}
+	if (previous) {
+		if (scope.store !== previous.store || scope.worktree !== previous.worktree
+			|| scope.changeName !== previous.changeName || scope.retainedIntent !== previous.retainedIntent || scope.locators.length !== previous.locators.length) throw new Error("Research continuation cannot replace retained scope.");
+		for (const next of scope.locators) {
+			const old = previous.locators.find(item => item.artifact === next.artifact);
+			if (!old || old.path !== next.path || old.engram?.id !== next.engram?.id
+				|| old.engram?.project !== next.engram?.project || old.engram?.topic_key !== next.engram?.topic_key) throw new Error("Research continuation cannot broaden scope.");
+			if (next.revision < old.revision || (next.engram?.revision_count ?? 0) < (old.engram?.revision_count ?? 0)
+				|| next.revision === old.revision && next.digest !== old.digest) throw new Error("Research continuation has stale/divergent scope.");
+		}
+	}
+	return scope;
+}
+
+// Negative intersection only: callers must still enforce host permissions/inventory.
+export function researchArtifactCall(scope: ResearchArtifactIntent, cwd: string, tool: string, input: Record<string, unknown>): number {
+	if (realpathSync(cwd) !== scope.worktree) throw new Error("Research artifact worktree changed.");
+	const index = scope.locators.findIndex(locator => {
+		if (locator.artifact === "explore" && ["write", "edit", "mem_save"].includes(tool)) return false;
+		if (["read", "write", "edit", "grep"].includes(tool)) {
+			if (!locator.path || typeof input.path !== "string") return false;
+			const path = resolve(cwd, input.path);
+			return path === locator.path && canonicalArtifactPath(path) === path;
+		}
+		if (!locator.engram) return false;
+		if (tool === "mem_get_observation") return input.id === locator.engram.id && Object.keys(input).every(key => key === "id");
+		if (tool === "mem_search") return input.project === locator.engram.project && input.query === locator.engram.topic_key && input.all_projects !== true;
+		if (tool === "mem_save") return input.project === locator.engram.project && input.topic_key === locator.engram.topic_key;
+		return false;
+	});
+	if (index < 0) throw new Error("Tool arguments outside retained research artifact scope.");
+	return index;
+}
+
+// Consume actual child tool results, never transported success assertions.
+export function researchArtifactReadback(locator: ResearchLocator, tool: string, returned: unknown, afterWrite = false): boolean {
+	let bytes: unknown = returned;
+	if (tool === "mem_get_observation") {
+		const value = record(returned), expected = locator.engram;
+		if (!expected || value.id !== expected.id || value.project !== expected.project || value.topic_key !== expected.topic_key
+			|| (afterWrite ? !positive(value.revision_count) || Number(value.revision_count) <= expected.revision_count : value.revision_count !== expected.revision_count)) return false;
+		bytes = value.content;
+	} else if (tool !== "read") return false;
+	if (typeof bytes !== "string" || createHash("sha256").update(bytes).digest("hex") !== locator.digest) return false;
+	try { return record(JSON.parse(bytes)).revision === locator.revision; } catch { return false; }
+}
+
+export const RESEARCH_PERSISTENCE_ENTRY = "gentle-sdd-research-persistence";
+export function parseResearchPersistence(value: unknown, scope: ResearchArtifactIntent, cwd: string) {
+	const saved = record(value), previous = parseResearchArtifactIntent(saved.scope, cwd);
+	parseResearchArtifactIntent(scope, cwd, previous);
+	if (saved.version !== 1 || !saved.accepted || typeof saved.accepted !== "object" || Array.isArray(saved.accepted) || !saved.writes || typeof saved.writes !== "object" || Array.isArray(saved.writes)) throw new Error("Invalid research persistence snapshot");
+	const accepted = record(saved.accepted) as Record<string, ResearchLocator>, writes = record(saved.writes) as Record<string, ResearchWriteIdentity>;
+	const tools = scope.store === "both" ? ["read", "mem_get_observation"] : [scope.store === "openspec" ? "read" : "mem_get_observation"];
+	for (const key of new Set([...Object.keys(accepted), ...Object.keys(writes)])) {
+		const [index, tool] = key.split(":"), old = previous.locators[Number(index)];
+		if (!/^[0-2]:(read|mem_get_observation)$/.test(key) || !old || !tools.includes(tool)) throw new Error("Research persistence key outside scope");
+		if (Object.hasOwn(accepted, key)) parseResearchArtifactIntent({ ...previous, locators: [accepted[key]] }, cwd, { ...previous, locators: [old] });
+		const desired = writes[key];
+		if (Object.hasOwn(writes, key) && (!desired || !positive(desired.revision) || desired.revision <= (accepted[key] ?? old).revision || typeof desired.digest !== "string" || !/^[a-f0-9]{64}$/.test(desired.digest))) throw new Error("Invalid durable desired identity");
+	}
+	for (const [index, locator] of scope.locators.entries()) {
+		const identities = [previous.locators[index], ...tools.map(tool => ({ ...(accepted[`${index}:${tool}`] ?? previous.locators[index]), ...writes[`${index}:${tool}`] }))];
+		const advanced = identities.slice(1).filter(item => item.revision > previous.locators[index].revision);
+		if (scope.store === "both" && advanced.length === 2 && (advanced[0].revision !== advanced[1].revision || advanced[0].digest !== advanced[1].digest)) throw new Error("Divergent durable hybrid desired identity");
+		if (!identities.some(item => item.revision === locator.revision && item.digest === locator.digest && item.engram?.revision_count === locator.engram?.revision_count)) throw new Error("Transported research identity differs from retained operation");
+	}
+	return structuredClone({ accepted, writes });
+}
+
+// Pi may defer custom entries in an in-memory/unflushed session. Verify the
+// actual bounded tail, not appendEntry's void return or an in-memory receipt.
+export function assertResearchCheckpoint(file: string, expected: unknown): void {
+	const fd = openSync(file, "r");
+	try {
+		const size = fstatSync(fd).size, length = Math.min(size, 65_536), tail = Buffer.alloc(length);
+		if (readSync(fd, tail, 0, length, size - length) !== length) throw new Error("Incomplete research checkpoint read");
+		const text = tail.toString("utf8");
+		if (!text.endsWith("\n")) throw new Error("Research checkpoint append incomplete");
+		const last = JSON.parse(text.trimEnd().split("\n").at(-1)!);
+		if (last.type !== "custom" || last.customType !== RESEARCH_PERSISTENCE_ENTRY || JSON.stringify(last.data) !== JSON.stringify(expected)) throw new Error("Research checkpoint not durably retained");
+	} finally { closeSync(fd); }
+}

package/lib/sdd-status.ts

@@ -1,5 +1,6 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, join, relative, resolve } from "node:path";
+import type { NativeSddStatusV2 } from "./native-review-cli.ts";
 import {
 	detectActiveDomainCollisions,
 	detectLegacyFlatSpec,
@@ -14,6 +15,12 @@ export type ArtifactState = "missing" | "done" | "partial";
 export type DependencyState = "blocked" | "ready" | "all_done" | "not_applicable";
 export type ApplyState = "blocked" | "ready" | "all_done" | "not_applicable";
 export type SddPhase = "apply" | "verify" | "sync" | "archive";
+export type SddNextRecommended =
+	| `sdd-${"propose" | "spec" | "design" | "tasks" | SddPhase}`
+	| "fix-task-ownership-marker"
+	| "archived"
+	| "resolve-via-engram"
+	| "blocked";
 
 export interface SddArtifactPaths {
 	proposal: string[];
@@ -107,7 +114,7 @@ export interface SddStatus {
 	 * When set, `nextRecommended` is "archived" and no further phase is recommended.
 	 */
 	archived?: { path: string };
-	nextRecommended: string;
+	nextRecommended: SddNextRecommended;
 	instructions?: SddPhaseInstructions;
 	blockedReasons: string[];
 	/**
@@ -258,6 +265,15 @@ function reportIsClearlyPassing(path: string | undefined): boolean {
 	return hasPassSignal && !hasBlocker;
 }
 
+// Planning routes repair the first incomplete prerequisite; diagnostics remain separate.
+function planningRecommendation(artifacts: SddStatus["artifacts"], taskTotal: number): SddNextRecommended {
+	if (artifacts.proposal !== "done") return "sdd-propose";
+	if (artifacts.specs !== "done") return "sdd-spec";
+	if (artifacts.design !== "done") return "sdd-design";
+	if (artifacts.tasks !== "done" || taskTotal === 0) return "sdd-tasks";
+	return "blocked";
+}
+
 function emptyStatus(cwd: string, changeName: string | null, blockedReasons: string[], artifactStore: SddArtifactStore = "openspec", isNonAuthoritative = false): SddStatus {
 	const root = resolve(cwd);
 	const changesDir = join(root, "openspec", "changes");
@@ -299,7 +315,7 @@ function emptyStatus(cwd: string, changeName: string | null, blockedReasons: str
 			sameDomainActiveChanges: [],
 		},
 		collisions: [],
-		nextRecommended: blockedReasons[0] ?? "Start an SDD change.",
+		nextRecommended: "blocked",
 		blockedReasons,
 		isNonAuthoritative,
 	};
@@ -594,7 +610,7 @@ export function resolveSddStatus(options: ResolveSddStatusOptions): SddStatus {
 		archive: coreArtifactsReady && verifyClean && syncClean && taskProgress.remaining === 0 && !taskArtifactBlocked ? "ready" : "blocked",
 	};
 	const archiveReady = dependencies.archive === "ready";
-	const nextRecommended = taskArtifactBlocked
+	const nextRecommended: SddNextRecommended = taskArtifactBlocked
 		? "fix-task-ownership-marker"
 		: dependencies.apply === "ready"
 			? "sdd-apply"
@@ -604,7 +620,7 @@ export function resolveSddStatus(options: ResolveSddStatusOptions): SddStatus {
 					? "sdd-sync"
 					: archiveReady
 						? "sdd-archive"
-						: blockedReasons[0] ?? "Resolve blockers.";
+						: planningRecommendation(artifacts, taskProgress.total);
 
 	const status: SddStatus = {
 		schemaName: "gentle-pi.sdd-status",
@@ -645,9 +661,15 @@ export function isNonAuthoritativeStatus(status: SddStatus): boolean {
 	return status.isNonAuthoritative;
 }
 
-export function renderNativeSddPhasePrompt(status: SddStatus, phase?: SddPhase): string {
-	const selectedInstructions = phase ? status.instructions?.[phase] : undefined;
-	const isNonAuthoritative = isNonAuthoritativeStatus(status);
+export function renderNativeSddPhasePrompt(status: SddStatus | NativeSddStatusV2, phase?: SddPhase | "remediate"): string {
+	const native = status.schemaName === "gentle-ai.sdd-status";
+	let selectedInstructions: readonly string[] | undefined;
+	if (phase) {
+		selectedInstructions = native
+			? phase === "sync" ? undefined : status.phaseInstructions?.[phase]
+			: phase === "remediate" ? undefined : status.instructions?.[phase];
+	}
+	const isNonAuthoritative = !native && isNonAuthoritativeStatus(status);
 	const authorityLine = isNonAuthoritative
 		? `This status is non-authoritative (artifact store: ${status.artifactStore}). The orchestrator must resolve readiness from Engram instead.`
 		: "The parent/orchestrator resolved this status deterministically. Treat it as authoritative over prompt inference.";

package/lib/session-worktree-registry.ts

@@ -0,0 +1,118 @@
+import { execFileSync } from "node:child_process";
+import { realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+
+export const SESSION_WORKTREE_ENTRY = "gentle-pi.session-worktree/v1";
+export const SESSION_WORKTREE_CHANGED = "gentle-pi:session-worktree-changed";
+export interface WorktreeIdentity { root: string; commonDir: string }
+export type WorktreeResolver = (path: string, cwd: string) => WorktreeIdentity | undefined;
+interface SessionReader {
+	getSessionId(): string;
+	getEntries(): readonly { type: string; customType?: string; data?: unknown }[];
+}
+interface RegistryHost {
+	appendEntry(type: string, data: unknown): void;
+	events: { emit(name: string, data: unknown): void };
+}
+interface Registration { sessionId: string; root: string; evidence: string }
+
+// Pass this as a complete child environment, not an overlay on inherited env.
+export function worktreeGitEnvironment(env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+	return Object.fromEntries(Object.entries(env).filter(([key]) => !key.toUpperCase().startsWith("GIT_")));
+}
+
+// Match Pi's ordinary path spelling; Git, not the argument, establishes identity.
+export function resolveSessionWorktreeWithGit(path: string, cwd: string, run: typeof execFileSync = execFileSync): WorktreeIdentity | undefined {
+	try {
+		let spelling = path.replace(/^@/, "").replace(/[\u00a0\u2000-\u200a\u202f\u205f\u3000]/g, " ");
+		if (spelling === "~" || spelling.startsWith("~/")) spelling = homedir() + spelling.slice(1);
+		const canonical = realpathSync(resolve(cwd, spelling));
+		const directory = statSync(canonical).isDirectory() ? canonical : dirname(canonical);
+		// Ambient Git routing must not redirect a path into another repository.
+		const env = worktreeGitEnvironment();
+		const git = (arg: string) => String(run("git", ["--no-optional-locks", "-C", directory, "rev-parse", "--path-format=absolute", arg], { encoding: "utf8", timeout: 5000, stdio: ["ignore", "pipe", "pipe"], shell: false, windowsHide: true, env })).replace(/\r?\n$/, "");
+		return { root: realpathSync(git("--show-toplevel")), commonDir: realpathSync(git("--git-common-dir")) };
+	} catch {
+		return undefined;
+	}
+}
+
+export const resolveSessionWorktree: WorktreeResolver = resolveSessionWorktreeWithGit;
+
+export function toolWorktreePath(name: string, input: Record<string, unknown>): string | undefined {
+	if (!["read", "write", "edit", "grep", "find", "ls"].includes(name)) return undefined;
+	if (typeof input.path === "string") return input.path;
+	return input.path === undefined && ["grep", "find", "ls"].includes(name) ? "." : undefined;
+}
+
+// No global store: both extensions append through their bound Pi API. Reading
+// all entries also catches a launch that happened while the shell was absent.
+export class SessionWorktreeRegistry {
+	readonly sessionId: string;
+	private readonly host: RegistryHost;
+	private readonly session: SessionReader;
+	private readonly cwd: string;
+	private readonly resolver: WorktreeResolver;
+	private readonly identity: WorktreeIdentity | undefined;
+	private readonly recorded = new Set<string>();
+	private active = true;
+
+	constructor(host: RegistryHost, session: SessionReader, cwd: string, resolver: WorktreeResolver = resolveSessionWorktree) {
+		this.host = host;
+		this.session = session;
+		this.cwd = cwd;
+		this.resolver = resolver;
+		this.sessionId = session.getSessionId();
+		this.identity = resolver(cwd, cwd);
+	}
+
+	start(): void {
+		if (this.identity) this.register(this.identity.root, "session:cwd");
+	}
+
+	close(): void { this.active = false; }
+
+	private isCurrent(): boolean {
+		try { return this.active && this.sessionId.length > 0 && this.session.getSessionId() === this.sessionId; }
+		catch { return false; }
+	}
+
+	validate(path: string): string {
+		if (!this.isCurrent()) throw new Error("Cannot register a worktree for an inactive session.");
+		const target = this.resolver(path, this.cwd);
+		if (!target || !this.identity || target.commonDir !== this.identity.commonDir) throw new Error("Select an existing worktree in the same Git clone as this session.");
+		return target.root;
+	}
+
+	private restore(): void {
+		for (const entry of this.session.getEntries()) {
+			if (entry.type !== "custom" || entry.customType !== SESSION_WORKTREE_ENTRY || !entry.data || typeof entry.data !== "object") continue;
+			const data = entry.data as Partial<Registration>;
+			if (data.sessionId === this.sessionId && typeof data.root === "string" && typeof data.evidence === "string") this.recorded.add(data.root);
+		}
+	}
+
+	register(path: string, evidence: string): string {
+		const root = this.validate(path);
+		this.restore();
+		if (this.recorded.has(root)) return root;
+		// appendEntry is synchronous, so concurrent tool completions dedupe before
+		// yielding. Mark locally only after a successful durable append.
+		this.host.appendEntry(SESSION_WORKTREE_ENTRY, { sessionId: this.sessionId, root, evidence } satisfies Registration);
+		this.recorded.add(root);
+		this.host.events.emit(SESSION_WORKTREE_CHANGED, { sessionId: this.sessionId });
+		return root;
+	}
+
+	roots(): string[] {
+		if (!this.isCurrent()) return [];
+		this.restore();
+		const roots = new Set<string>();
+		for (const recorded of this.recorded) {
+			try { roots.add(this.validate(recorded)); }
+			catch { /* Missing/prunable roots remain durable but cannot be scanned. */ }
+		}
+		return [...roots];
+	}
+}

package/lib/shell-bar.ts

@@ -0,0 +1,184 @@
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { GAUGE_CELLS, gaugeTone, paintGauge, renderGauge, type GaugeTone } from "./shell-gauge.ts";
+import { renderUsageBar, type ProviderUsage } from "./shell-usage.ts";
+import { sanitizeTerminalText } from "./terminal-theme.ts";
+import { CARD_TONE, cardInnerWidth, renderCard } from "./shell-card.ts";
+
+export { gaugeTone, renderGauge, type GaugeTone };
+
+// Gentle Shell status bar: one line of segments that replaces pi's built-in
+// three-line footer. Everything here is pure so the bar can be rendered and
+// verified without a live TUI.
+
+export interface ShellBarModel {
+	cwd: string;
+	branch: string | null;
+	dirty: number | undefined;
+	sessionName: string | undefined;
+	modelId: string;
+	effort: string | undefined;
+	contextPercent: number | null;
+	contextWindow: number;
+	costTotal: number;
+	subscription: boolean;
+	usage: ProviderUsage | undefined;
+	statuses: string[];
+}
+
+export interface ShellBarTheme {
+	fg(color: string, text: string): string;
+	bold(text: string): string;
+}
+
+// Theme roles the bar paints with. Keys are pi theme colors; the Gentle themes
+// map them to the rose palette (accent = rose, syntaxFunction = powder blue).
+const ROLE = {
+	BRAND: "accent",
+	SEPARATOR: "dim",
+	PATH: "muted",
+	BRANCH: "text",
+	DIRTY: "warning",
+	MODEL: "text",
+	EFFORT: "syntaxFunction",
+	LABEL: "muted",
+	VALUE: "text",
+	STATUS: "muted",
+	SESSION: "dim",
+} as const;
+
+export const SHELL_BAR_BRAND = "✿ gentle-pi";
+export const SHELL_BAR_SEPARATOR = "⟡";
+export const SHELL_BAR_GAUGE_CELLS = GAUGE_CELLS;
+const RIGHT_PADDING = 2;
+const COMPACT_BRANCH_WIDTH = 15;
+
+export function shellEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+	if (env.GENTLE_PI_AGENTS_CHILD === "1") return false;
+	const value = env.GENTLE_PI_SHELL?.trim().toLowerCase();
+	return !(value === "0" || value === "false" || value === "off");
+}
+
+export function formatTokens(count: number): string {
+	if (count < 1000) return count.toString();
+	if (count < 10_000) return `${(count / 1000).toFixed(1)}k`;
+	if (count < 1_000_000) return `${Math.round(count / 1000)}k`;
+	if (count < 10_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
+	return `${Math.round(count / 1_000_000)}M`;
+}
+
+export function formatCost(total: number, subscription: boolean): string {
+	const amount = total >= 1 ? total.toFixed(2) : total.toFixed(3);
+	return subscription ? `$${amount} sub` : `$${amount}`;
+}
+
+// Extensions may paint their status themselves (pi-mcp-adapter does); the bar
+// owns the palette, so their escapes go and the text takes the status role.
+function sanitizeStatus(text: string): string {
+	return sanitizeTerminalText(text.replace(/[\r\n\t]/g, " ")).replace(/ +/g, " ").trim();
+}
+
+function buildSegments(model: ShellBarModel, theme: ShellBarTheme): string[] {
+	const dirty = model.dirty ? ` ${theme.fg(ROLE.DIRTY, `±${model.dirty}`)}` : "";
+	const location = model.branch
+		? `${theme.fg(ROLE.PATH, model.cwd)} ${theme.fg(ROLE.BRANCH, model.branch)}${dirty}`
+		: theme.fg(ROLE.PATH, model.cwd) + dirty;
+	const modelSegment = model.effort
+		? `${theme.fg(ROLE.MODEL, model.modelId)} ${theme.fg(ROLE.LABEL, "·")} ${theme.fg(ROLE.EFFORT, model.effort)}`
+		: theme.fg(ROLE.MODEL, model.modelId);
+	const percentText = model.contextPercent === null ? "?%" : `${Math.round(model.contextPercent)}%`;
+	const context = `${theme.fg(ROLE.LABEL, "ctx")} ${paintGauge(model.contextPercent, theme)} ${theme.fg(ROLE.VALUE, percentText)}`;
+	const cost = theme.fg(ROLE.VALUE, formatCost(model.costTotal, model.subscription));
+	const usage = model.usage ? renderUsageBar(model.usage, theme) : undefined;
+	const statuses = model.statuses.map((status) => theme.fg(ROLE.STATUS, sanitizeStatus(status)));
+	return [theme.fg(ROLE.BRAND, SHELL_BAR_BRAND), location, modelSegment, context, cost, ...(usage ? [usage] : []), ...statuses];
+}
+
+// When the line overflows, the location gives way first: the path shrinks to
+// its last segment and a long branch is clipped, so the trailing statuses
+// (MCP servers, extension notices) survive on ordinary terminal widths.
+function compactModel(model: ShellBarModel): ShellBarModel {
+	const cwd = model.cwd.split("/").filter((part) => part.length > 0).pop() ?? model.cwd;
+	const branch = model.branch && visibleWidth(model.branch) > COMPACT_BRANCH_WIDTH ? clipText(model.branch, COMPACT_BRANCH_WIDTH) : model.branch;
+	return { ...model, cwd, branch };
+}
+
+// Plain clip: pi's truncateToWidth wraps the result in resets, which would end
+// up inside a painted segment.
+function clipText(text: string, max: number): string {
+	let clipped = "";
+	for (const char of text) {
+		if (visibleWidth(clipped + char) > max - 1) break;
+		clipped += char;
+	}
+	return `${clipped}…`;
+}
+
+function joinSegments(segments: string[], theme: ShellBarTheme): string {
+	return segments.join(` ${theme.fg(ROLE.SEPARATOR, SHELL_BAR_SEPARATOR)} `);
+}
+
+// Sidebar groups use structured fields, never positional compact-bar segments
+// or inferred meanings from opaque extension status strings.
+export function renderShellSidebarBar(model: ShellBarModel, theme: ShellBarTheme, width: number): string[] {
+	const value = (text: string) => theme.fg(ROLE.VALUE, theme.bold(text));
+	const label = (text: string) => theme.fg(ROLE.LABEL, text);
+	const dirty = model.dirty ? theme.fg(ROLE.DIRTY, `±${model.dirty}`) : "";
+	const branch = model.branch ? `${label("Branch")} ${value(model.branch)}` : "";
+	const percent = model.contextPercent === null ? "?%" : `${Math.round(model.contextPercent)}%`;
+	const capacity = label(`${formatTokens(model.contextWindow)} tokens`);
+	const usage = model.usage ? renderUsageBar(model.usage, theme) : undefined;
+	const groups: Array<{ title: string; lines: string[] }> = [
+		{
+			title: "Project",
+			lines: [
+				value(model.cwd),
+				...((branch || dirty) ? [[branch, dirty].filter(Boolean).join(" ")] : []),
+				...(model.sessionName ? [`${label("Session")} ${value(model.sessionName)}`] : []),
+			],
+		},
+		{
+			title: "Model",
+			lines: [value(model.modelId), ...(model.effort ? [`${label("Effort")} ${theme.fg(ROLE.EFFORT, model.effort)}`] : [])],
+		},
+		{
+			title: "Context",
+			lines: [`${paintGauge(model.contextPercent, theme)} ${value(percent)}  ${capacity}`],
+		},
+		{
+			title: "Usage",
+			lines: [`${label("Cost")} ${value(formatCost(model.costTotal, model.subscription))}`, ...(usage ? [usage] : [])],
+		},
+		...(model.statuses.length ? [{ title: "Integrations", lines: model.statuses.map((status) => theme.fg(ROLE.STATUS, sanitizeStatus(status))) }] : []),
+	];
+	// Pre-wrap values before indenting so Unicode/ANSI continuation lines keep
+	// the same inset without consuming the card's right border.
+	const innerWidth = cardInnerWidth(width);
+	const inset = Math.min(1, innerWidth - 1);
+	const body = groups.flatMap((group, index) => [
+		...(index ? [""] : []),
+		label(group.title),
+		...group.lines.flatMap((line) => wrapTextWithAnsi(line, innerWidth - inset).map((part) => " ".repeat(inset) + part)),
+	]);
+	return renderCard({ title: "Status", body, tone: CARD_TONE.INFO }, theme, width, { expanded: true });
+}
+
+export function renderShellBar(model: ShellBarModel, theme: ShellBarTheme, width: number): string[] {
+	let segments = buildSegments(model, theme);
+	const right = model.sessionName ? theme.fg(ROLE.SESSION, model.sessionName) : undefined;
+
+	let left = joinSegments(segments, theme);
+	if (right && visibleWidth(left) + RIGHT_PADDING + visibleWidth(right) <= width) {
+		const padding = " ".repeat(width - visibleWidth(left) - visibleWidth(right));
+		return [left + padding + right];
+	}
+
+	if (visibleWidth(left) > width) {
+		segments = buildSegments(compactModel(model), theme);
+		left = joinSegments(segments, theme);
+	}
+	while (segments.length > 1 && visibleWidth(left) > width) {
+		segments.pop();
+		left = joinSegments(segments, theme);
+	}
+	return [truncateToWidth(left, width, "…")];
+}