@oh-my-pi/pi-coding-agent 15.2.1 → 15.2.3

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 ## [Unreleased]
 
+## [15.2.3] - 2026-05-22
+### Breaking Changes
+
+- Changed PR and task-isolation worktree directory layout to hash-based `~/.omp/wt/<identifier>-<path-hash>` style paths, replacing the previous nested encoded-repo layout
+
+### Added
+
+- Added `omp worktree` command (alias `wt`) to list and manage agent-managed worktrees under `~/.omp/wt`
+- Added `omp worktree clear` to remove orphaned worktree directories, with `--all` to include live PR-checkouts, `--dry-run` for preview, and `--json` reporting
+- Added machine-readable JSON output to `omp worktree list` for scripted inspection
+- Added `display.shimmer` appearance setting with `classic`, `kitt` (Knight Rider K.I.T.T. scanner), and `disabled` modes
+
+### Changed
+
+- Changed the welcome intro animation to a 3-second eased gradient sweep with a diagonal shine highlight across the logo
+- Changed background job completion follow-ups to batch multiple finished jobs into a single `async-result` message, showing each completed job and its result in one place
+- Changed MCP notification follow-ups to combine multiple resource updates into a single consolidated message and suppress duplicate server/uri entries
+- Updated PR checkout to reuse `hashPath`-based worktree roots when creating and scanning worktrees for cleanup
+- Updated `worktree` cleanup logic to gracefully prune parent git metadata after removing worktree directories
+- Reworked working-message shimmer animation for 60fps rendering: ANSI sequences are coalesced per same-tier run instead of emitted per code point, palettes compile once and cache per active theme, and the band position is now fractional so motion is smooth at any frame rate
+- Switched MCP health-check and "Connecting to…" spinners from hard-coded ASCII (`|/-\`) to `theme.spinnerFrames` so they pick up the active symbol preset (braille on unicode/nerd, ASCII when explicitly themed)
+
+### Fixed
+
+- Fixed PR checkout failures when the default worktree path was already registered or occupied by stale leftovers by automatically selecting suffixed alternatives (`-2`, `-3`, etc.)
+- Fixed Memory tab in the settings UI not revealing or hiding the Hindsight-only rows (`Hindsight API URL`, `Hindsight Bank ID`, `Hindsight Scoping`, etc.) when `Memory Backend` was switched via the inline submenu. The selector now rebuilds its item list after every change so condition-gated rows appear/disappear immediately instead of requiring a tab switch
+
+## [15.2.2] - 2026-05-22
+
+### Fixed
+
+- Fixed `RULES.md` not being injected. The documented sticky-rules file at `~/.omp/agent/RULES.md` and `<repo>/.omp/RULES.md` was never read by any discovery provider; only `.omp/rules/*.md` was scanned. The native provider now loads both as always-apply rules so they re-attach every turn as documented ([#1266](https://github.com/can1357/oh-my-pi/issues/1266)).
+
 ## [15.2.1] - 2026-05-21
 
 ### Fixed
@@ -8505,4 +8538,4 @@ Initial public release.
 - Git branch display in footer
 - Message queueing during streaming responses
 - OAuth integration for Gmail and Google Calendar access
-- HTML export with syntax highlighting and collapsible sections
+- HTML export with syntax highlighting and collapsible sections

package/dist/types/cli/worktree-cli.d.ts

@@ -0,0 +1,26 @@
+type WorktreeKind = "pr-checkout" | "task-isolation" | "empty" | "stray";
+export interface WorktreeEntry {
+    /** Absolute path to the worktree dir (or stray container) under `~/.omp/wt/`. */
+    path: string;
+    /** Classification of what we found on disk. */
+    kind: WorktreeKind;
+    /** Parent repo root, when this is a registered git worktree. */
+    parentRepo?: string;
+    /** Branch name extracted from the parent's tracking file, when available. */
+    branch?: string;
+    /** When set, the entry is unhealthy and `omp worktree clear` will remove it. */
+    orphanReason?: string;
+}
+export interface ListWorktreesOptions {
+    json: boolean;
+}
+export interface ClearWorktreesOptions {
+    /** Remove every entry, including live PR-checkout worktrees. */
+    all: boolean;
+    /** Print what would be removed without touching the filesystem. */
+    dryRun: boolean;
+    json: boolean;
+}
+export declare function listWorktrees(options: ListWorktreesOptions): Promise<void>;
+export declare function clearWorktrees(options: ClearWorktreesOptions): Promise<void>;
+export {};

package/dist/types/commands/worktree.d.ts

@@ -0,0 +1,34 @@
+/**
+ * List and clean up agent-managed git worktrees under `~/.omp/wt`.
+ */
+import { Command } from "@oh-my-pi/pi-utils/cli";
+export default class Worktree extends Command {
+    static description: string;
+    static aliases: string[];
+    static args: {
+        action: import("@oh-my-pi/pi-utils/cli").ArgDescriptor & {
+            description: string;
+            required: false;
+            options: string[];
+            default: string;
+        };
+    };
+    static flags: {
+        all: import("@oh-my-pi/pi-utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+            default: boolean;
+        };
+        "dry-run": import("@oh-my-pi/pi-utils/cli").FlagDescriptor<"boolean"> & {
+            char: string;
+            description: string;
+            default: boolean;
+        };
+        json: import("@oh-my-pi/pi-utils/cli").FlagDescriptor<"boolean"> & {
+            char: string;
+            description: string;
+            default: boolean;
+        };
+    };
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/types/config/settings-schema.d.ts

@@ -648,6 +648,29 @@ export declare const SETTINGS_SCHEMA: {
         readonly type: "number";
         readonly default: 3;
     };
+    readonly "display.shimmer": {
+        readonly type: "enum";
+        readonly values: readonly ["classic", "kitt", "disabled"];
+        readonly default: "classic";
+        readonly ui: {
+            readonly tab: "appearance";
+            readonly label: "Shimmer";
+            readonly description: "Animation style for working/loading messages";
+            readonly options: readonly [{
+                readonly value: "classic";
+                readonly label: "Classic";
+                readonly description: "Soft cosine wave sweeping across the text";
+            }, {
+                readonly value: "kitt";
+                readonly label: "KITT Scanner";
+                readonly description: "Knight Rider 1982 red light bouncing left-right";
+            }, {
+                readonly value: "disabled";
+                readonly label: "Disabled";
+                readonly description: "No animation; static muted text";
+            }];
+        };
+    };
     readonly "display.showTokenUsage": {
         readonly type: "boolean";
         readonly default: false;

package/dist/types/modes/theme/shimmer.d.ts

@@ -1,12 +1,12 @@
 import type { Theme, ThemeColor } from "./theme";
-type ShimmerTheme = Pick<Theme, "bold" | "fg">;
+type ShimmerTheme = Pick<Theme, "bold" | "fg" | "getFgAnsi">;
 /** Three-tier color stack a shimmer character cycles through as the band sweeps. */
 export interface ShimmerPalette {
-    /** Color for chars outside / at the edge of the band (intensity < 0.2). */
+    /** Color for chars outside / at the edge of the band (intensity < ~0.22). */
     low: ThemeColor;
-    /** Color for chars approaching the crest (0.2 <= intensity < 0.6). */
+    /** Color for chars approaching the crest (~0.22 ≤ intensity < ~0.65). */
     mid: ThemeColor;
-    /** Color at the band's crest (intensity >= 0.6). */
+    /** Color at the band's crest (intensity ≥ ~0.65). */
     high: ThemeColor;
     /** Whether to bold the crest tier. Default `false`. */
     bold?: boolean;
@@ -18,9 +18,17 @@ export interface ShimmerSegment {
 }
 export declare const DEFAULT_SHIMMER_PALETTE: ShimmerPalette;
 /**
- * Apply a shimmer sweep across one or more segments, treating them as a single
- * continuous string for band positioning. Each segment can supply its own
- * palette so the gradient stays in lockstep while the colors differ.
+ * Apply a shimmer sweep across one or more segments, treating them as a
+ * single continuous string for band positioning. Each segment can supply
+ * its own palette so the gradient stays in lockstep while the colors
+ * differ.
+ *
+ * Performance shape (per call, dominant cost):
+ *   - One `Date.now()` read.
+ *   - One `compile()` lookup per segment (Symbol-keyed cache slot, hot path
+ *     skipped after first frame).
+ *   - One ANSI open/close pair per **run of same-tier chars**, not per char.
+ *   - No per-char allocations beyond the run buffer.
  */
 export declare function shimmerSegments(segments: readonly ShimmerSegment[], theme: ShimmerTheme): string;
 export declare function shimmerText(text: string, theme: ShimmerTheme, palette?: ShimmerPalette): string;

package/dist/types/session/agent-session.d.ts

@@ -45,6 +45,7 @@ import type { ClientBridge } from "./client-bridge";
 import { type CustomMessage } from "./messages";
 import type { BranchSummaryEntry, NewSessionOptions, SessionContext, SessionManager } from "./session-manager";
 import { ToolChoiceQueue } from "./tool-choice-queue";
+import { YieldQueue } from "./yield-queue";
 /** Session-specific events that extend the core AgentEvent */
 export type AgentSessionEvent = AgentEvent | {
     type: "auto_compaction_start";
@@ -264,6 +265,7 @@ export declare class AgentSession {
     readonly agent: Agent;
     readonly sessionManager: SessionManager;
     readonly settings: Settings;
+    readonly yieldQueue: YieldQueue;
     readonly configWarnings: string[];
     readonly rawSseDebugBuffer: RawSseDebugBuffer;
     constructor(config: AgentSessionConfig);

package/dist/types/session/yield-queue.d.ts

@@ -0,0 +1,24 @@
+import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
+export interface YieldDispatcher<P> {
+    /** Drop entries already delivered through another path. Called per-entry at flush time. */
+    isStale?(entry: P): boolean;
+    /** Produce one batched AgentMessage from non-stale entries. Return null to skip. */
+    build(survivors: P[]): AgentMessage | null;
+}
+export interface YieldQueueOptions {
+    isStreaming: () => boolean;
+    injectStreaming(msg: AgentMessage): void;
+    injectIdle(messages: AgentMessage[]): Promise<void>;
+    scheduleIdleFlush(run: () => Promise<void>): void;
+}
+type YieldFlushMode = "streaming" | "idle";
+export declare class YieldQueue {
+    #private;
+    constructor(options: YieldQueueOptions);
+    register<P>(kind: string, dispatcher: YieldDispatcher<P>): () => void;
+    enqueue<P>(kind: string, entry: P): void;
+    has(kind?: string): boolean;
+    flush(mode: YieldFlushMode): Promise<void>;
+    clear(): void;
+}
+export {};

package/dist/types/slash-commands/helpers/format.d.ts

@@ -1,7 +1,7 @@
 import { type Theme } from "../../modes/theme/theme";
 /** Format a millisecond duration as a coarse-grained human label. */
 export declare function formatDuration(ms: number): string;
-type ProgressBarTheme = Pick<Theme, "bold" | "fg">;
+type ProgressBarTheme = Pick<Theme, "bold" | "fg" | "getFgAnsi">;
 /**
  * Render an ASCII progress bar with a trailing percent label.
  * `fraction` is clamped to `[0, 1]`. `undefined` renders a dotted placeholder.

package/dist/types/task/worktree.d.ts

@@ -19,7 +19,6 @@ export interface WorktreeBaseline {
         baseline: RepoBaseline;
     }>;
 }
-export declare function getEncodedProjectName(cwd: string): string;
 export declare function getRepoRoot(cwd: string): Promise<string>;
 export declare function getGitNoIndexNullPath(): string;
 export declare function captureBaseline(repoRoot: string): Promise<WorktreeBaseline>;

package/dist/types/tools/browser/launch.d.ts

@@ -48,6 +48,8 @@ export interface UserAgentSession {
     override: UserAgentOverride;
     browserSession: CDPSession | null;
 }
+/** Builds the browser-page stealth bootstrap source for regression tests. */
+export declare function buildStealthInjectionScriptForTest(scripts?: readonly string[]): string;
 /** Apply stealth patches + UA override to a headless page. Idempotent within a tab. */
 export declare function applyStealthPatches(browser: Browser, page: Page, state: {
     browserSession: CDPSession | null;

package/dist/types/utils/git.d.ts

@@ -263,6 +263,7 @@ export declare const worktree: {
         signal?: AbortSignal;
     }): Promise<boolean>;
     list(cwd: string, signal?: AbortSignal): Promise<GitWorktreeEntry[]>;
+    prune(cwd: string, signal?: AbortSignal): Promise<void>;
 };
 export declare const patch: {
     /** Apply a patch file. */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "15.2.1",
+	"version": "15.2.3",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -47,12 +47,12 @@
 		"@agentclientprotocol/sdk": "0.21.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@oh-my-pi/omp-stats": "15.2.1",
-		"@oh-my-pi/pi-agent-core": "15.2.1",
-		"@oh-my-pi/pi-ai": "15.2.1",
-		"@oh-my-pi/pi-natives": "15.2.1",
-		"@oh-my-pi/pi-tui": "15.2.1",
-		"@oh-my-pi/pi-utils": "15.2.1",
+		"@oh-my-pi/omp-stats": "15.2.3",
+		"@oh-my-pi/pi-agent-core": "15.2.3",
+		"@oh-my-pi/pi-ai": "15.2.3",
+		"@oh-my-pi/pi-natives": "15.2.3",
+		"@oh-my-pi/pi-tui": "15.2.3",
+		"@oh-my-pi/pi-utils": "15.2.3",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/src/autoresearch/storage.ts

@@ -2,10 +2,22 @@ import { Database, type SQLQueryBindings } from "bun:sqlite";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { getAutoresearchDbPath, getAutoresearchProjectDir, logger } from "@oh-my-pi/pi-utils";
-import { getEncodedProjectName } from "../task/worktree";
 import * as git from "../utils/git";
 import type { ASIData, ExperimentStatus, MetricDirection, NumericMetricMap } from "./types";
 
+/**
+ * Encode an absolute project path into a single filesystem-safe segment.
+ *
+ * Used to key per-project autoresearch state under `~/.omp/autoresearch/`.
+ * The `--…--` wrapper is historical — existing on-disk state depends on it,
+ * so changing the format here would orphan every prior autoresearch DB.
+ * Not collision-free for pathological inputs (`/a/b` vs `/a-b`) but matches
+ * the rest of the codebase and stays human-readable for `ls`.
+ */
+function encodeProjectKey(repoRoot: string): string {
+	return `--${repoRoot.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`;
+}
+
 export interface SessionRow {
 	id: number;
 	name: string;
@@ -561,7 +573,7 @@ export async function openAutoresearchStorageIfExists(cwd: string): Promise<Auto
 async function resolveAutoresearchPaths(cwd: string): Promise<{ dbPath: string; projectDir: string }> {
 	const override = process.env.OMP_AUTORESEARCH_DB_DIR;
 	const repoRoot = (await git.repo.root(cwd)) ?? cwd;
-	const encoded = getEncodedProjectName(repoRoot);
+	const encoded = encodeProjectKey(repoRoot);
 	if (override) {
 		return {
 			dbPath: path.join(override, `${encoded}.db`),

package/src/cli/worktree-cli.ts

@@ -0,0 +1,291 @@
+/**
+ * CLI handler for `omp worktree` — list and clean up agent-managed worktrees.
+ *
+ * Layout under `~/.omp/wt/`:
+ *
+ *   - **PR-checkout worktrees** (`tools/gh.ts`): a regular git worktree dir
+ *     containing a `.git` *file* that points back at
+ *     `<parent-repo>/.git/worktrees/<name>/`.
+ *   - **Task-isolation dirs** (`task/worktree.ts`): a wrapper dir with a
+ *     `merged` subdir mounted/cloned by `natives.isoStart`. These are ephemeral
+ *     — `ensureIsolation` always `rm -rf`s the base before re-creating it, so
+ *     any leftover on disk is a leak from a crashed run.
+ *
+ * Legacy entries from before the encoding change keep working because git still
+ * tracks them by branch name. This command exists to GC them on demand.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { getWorktreesDir, isEnoent } from "@oh-my-pi/pi-utils";
+import chalk from "chalk";
+import * as git from "../utils/git";
+
+type WorktreeKind = "pr-checkout" | "task-isolation" | "empty" | "stray";
+
+export interface WorktreeEntry {
+	/** Absolute path to the worktree dir (or stray container) under `~/.omp/wt/`. */
+	path: string;
+	/** Classification of what we found on disk. */
+	kind: WorktreeKind;
+	/** Parent repo root, when this is a registered git worktree. */
+	parentRepo?: string;
+	/** Branch name extracted from the parent's tracking file, when available. */
+	branch?: string;
+	/** When set, the entry is unhealthy and `omp worktree clear` will remove it. */
+	orphanReason?: string;
+}
+
+export interface ListWorktreesOptions {
+	json: boolean;
+}
+
+export interface ClearWorktreesOptions {
+	/** Remove every entry, including live PR-checkout worktrees. */
+	all: boolean;
+	/** Print what would be removed without touching the filesystem. */
+	dryRun: boolean;
+	json: boolean;
+}
+
+export async function listWorktrees(options: ListWorktreesOptions): Promise<void> {
+	const entries = await scanWorktrees();
+	if (options.json) {
+		console.log(JSON.stringify(entries, null, 2));
+		return;
+	}
+	if (entries.length === 0) {
+		console.log(chalk.dim(`No agent-managed worktrees found under ${getWorktreesDir()}.`));
+		return;
+	}
+	let live = 0;
+	let orphaned = 0;
+	for (const entry of entries) {
+		const tag = entry.orphanReason ? chalk.yellow("orphaned") : chalk.green("live    ");
+		const detail = formatEntryDetail(entry);
+		console.log(`${tag}  ${entry.path}`);
+		if (detail) console.log(`          ${chalk.dim(detail)}`);
+		if (entry.orphanReason) orphaned += 1;
+		else live += 1;
+	}
+	console.log(chalk.dim(`\n${live} live · ${orphaned} orphaned · ${entries.length} total`));
+}
+
+export async function clearWorktrees(options: ClearWorktreesOptions): Promise<void> {
+	const entries = await scanWorktrees();
+	const targets = options.all ? entries : entries.filter(entry => entry.orphanReason !== undefined);
+
+	if (targets.length === 0) {
+		if (options.json) {
+			console.log(JSON.stringify({ removed: 0, kept: entries.length }));
+		} else {
+			console.log(chalk.dim(options.all ? "No worktrees to remove." : "No orphaned worktrees to remove."));
+		}
+		return;
+	}
+
+	if (options.dryRun) {
+		if (options.json) {
+			console.log(JSON.stringify({ wouldRemove: targets.map(t => t.path) }, null, 2));
+		} else {
+			for (const target of targets) {
+				console.log(`${chalk.yellow("would remove")}  ${target.path}`);
+			}
+			console.log(chalk.dim(`\n${targets.length} dir${targets.length === 1 ? "" : "s"} would be removed.`));
+		}
+		return;
+	}
+
+	const results: { path: string; ok: boolean; error?: string }[] = [];
+	const parentsToPrune = new Set<string>();
+	for (const target of targets) {
+		try {
+			if (target.kind === "pr-checkout" && target.parentRepo && !target.orphanReason) {
+				// Live worktree: ask git to remove it cleanly. If git refuses (locked,
+				// dirty, etc.), fall back to fs.rm and rely on `worktree prune` to
+				// clean the bookkeeping on the parent side.
+				const removed = await git.worktree.tryRemove(target.parentRepo, target.path, { force: true });
+				if (!removed) {
+					await fs.rm(target.path, { recursive: true, force: true });
+					parentsToPrune.add(target.parentRepo);
+				}
+			} else {
+				await fs.rm(target.path, { recursive: true, force: true });
+				if (target.parentRepo) parentsToPrune.add(target.parentRepo);
+			}
+			results.push({ path: target.path, ok: true });
+		} catch (err) {
+			results.push({ path: target.path, ok: false, error: err instanceof Error ? err.message : String(err) });
+		}
+	}
+
+	// Best-effort: drop stale entries from each affected parent's `.git/worktrees/`.
+	for (const parent of parentsToPrune) {
+		try {
+			await git.worktree.prune(parent);
+		} catch {
+			/* parent repo may already be gone or pruned — ignore */
+		}
+	}
+
+	const succeeded = results.filter(r => r.ok).length;
+	const failed = results.length - succeeded;
+
+	if (options.json) {
+		console.log(JSON.stringify({ removed: succeeded, failed, results }, null, 2));
+		if (failed > 0) process.exitCode = 1;
+		return;
+	}
+
+	for (const result of results) {
+		if (result.ok) {
+			console.log(`${chalk.green("removed")}  ${result.path}`);
+		} else {
+			console.log(`${chalk.red("failed ")}  ${result.path}`);
+			if (result.error) console.log(`          ${chalk.dim(result.error)}`);
+		}
+	}
+	console.log(chalk.dim(`\n${succeeded} removed${failed > 0 ? ` · ${chalk.red(`${failed} failed`)}` : ""}`));
+	if (failed > 0) process.exitCode = 1;
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Scanner
+// ───────────────────────────────────────────────────────────────────────────
+
+async function scanWorktrees(): Promise<WorktreeEntry[]> {
+	const root = getWorktreesDir();
+	let topLevel: string[];
+	try {
+		topLevel = await fs.readdir(root);
+	} catch (err) {
+		if (isEnoent(err)) return [];
+		throw err;
+	}
+
+	const entries: WorktreeEntry[] = [];
+	for (const name of topLevel) {
+		const dir = path.join(root, name);
+		const stat = await fs.stat(dir).catch(() => null);
+		if (!stat?.isDirectory()) continue;
+
+		const direct = await classifyDir(dir);
+		if (direct) {
+			entries.push(direct);
+			continue;
+		}
+
+		// Legacy nesting: ~/.omp/wt/<encoded-project>/<branch-or-id>
+		let children: string[];
+		try {
+			children = await fs.readdir(dir);
+		} catch {
+			continue;
+		}
+		let nested = 0;
+		for (const child of children) {
+			const childDir = path.join(dir, child);
+			const childStat = await fs.stat(childDir).catch(() => null);
+			if (!childStat?.isDirectory()) continue;
+			const childClassified = await classifyDir(childDir);
+			if (childClassified) {
+				entries.push(childClassified);
+				nested += 1;
+			}
+		}
+		if (nested === 0) {
+			entries.push({
+				path: dir,
+				kind: children.length === 0 ? "empty" : "stray",
+				orphanReason: children.length === 0 ? "empty directory" : "no recognizable worktree contents",
+			});
+		}
+	}
+	return entries;
+}
+
+async function classifyDir(dir: string): Promise<WorktreeEntry | null> {
+	const gitEntry = path.join(dir, ".git");
+	const gitStat = await fs.stat(gitEntry).catch(() => null);
+	if (gitStat?.isFile()) {
+		return classifyPrCheckout(dir, gitEntry);
+	}
+	const mergedStat = await fs.stat(path.join(dir, "merged")).catch(() => null);
+	if (mergedStat?.isDirectory()) {
+		return {
+			path: dir,
+			kind: "task-isolation",
+			orphanReason: "task-isolation leftover (no live task owns it)",
+		};
+	}
+	return null;
+}
+
+async function classifyPrCheckout(dir: string, gitEntry: string): Promise<WorktreeEntry> {
+	let contents: string;
+	try {
+		contents = await fs.readFile(gitEntry, "utf8");
+	} catch (err) {
+		return {
+			path: dir,
+			kind: "pr-checkout",
+			orphanReason: `cannot read .git file: ${err instanceof Error ? err.message : String(err)}`,
+		};
+	}
+	const match = /^gitdir:\s*(.+?)\s*$/m.exec(contents);
+	const parentGitDir = match?.[1];
+	if (!parentGitDir) {
+		return { path: dir, kind: "pr-checkout", orphanReason: "malformed .git file (no gitdir line)" };
+	}
+	// parentGitDir is `<parent-repo>/.git/worktrees/<name>`; back out the repo root.
+	const parentRepo = path.dirname(path.dirname(path.dirname(parentGitDir)));
+	const branch = await readWorktreeBranch(path.join(parentGitDir, "HEAD"));
+
+	const parentDirStat = await fs.stat(parentGitDir).catch(() => null);
+	if (!parentDirStat?.isDirectory()) {
+		return {
+			path: dir,
+			kind: "pr-checkout",
+			parentRepo,
+			branch,
+			orphanReason: "parent repo no longer tracks this worktree",
+		};
+	}
+	const parentRepoStat = await fs.stat(parentRepo).catch(() => null);
+	if (!parentRepoStat?.isDirectory()) {
+		return {
+			path: dir,
+			kind: "pr-checkout",
+			parentRepo,
+			branch,
+			orphanReason: "parent repo missing",
+		};
+	}
+	return { path: dir, kind: "pr-checkout", parentRepo, branch };
+}
+
+async function readWorktreeBranch(headFile: string): Promise<string | undefined> {
+	try {
+		const head = (await fs.readFile(headFile, "utf8")).trim();
+		const refMatch = /^ref:\s*refs\/heads\/(.+)$/.exec(head);
+		return refMatch?.[1];
+	} catch {
+		return undefined;
+	}
+}
+
+function formatEntryDetail(entry: WorktreeEntry): string {
+	const parts: string[] = [];
+	if (entry.kind === "pr-checkout") {
+		const repo = entry.parentRepo ? path.basename(entry.parentRepo) : "unknown repo";
+		const branch = entry.branch ?? "unknown branch";
+		parts.push(`${repo} · ${branch}`);
+	} else if (entry.kind === "task-isolation") {
+		parts.push("task-isolation sandbox");
+	} else if (entry.kind === "empty") {
+		parts.push("legacy project shell");
+	} else {
+		parts.push("unrecognized contents");
+	}
+	if (entry.orphanReason) parts.push(entry.orphanReason);
+	return parts.join(" — ");
+}

package/src/cli.ts

@@ -46,6 +46,7 @@ const commands: CommandEntry[] = [
 	{ name: "ssh", load: () => import("./commands/ssh").then(m => m.default) },
 	{ name: "stats", load: () => import("./commands/stats").then(m => m.default) },
 	{ name: "update", load: () => import("./commands/update").then(m => m.default) },
+	{ name: "worktree", load: () => import("./commands/worktree").then(m => m.default), aliases: ["wt"] },
 	{ name: "search", load: () => import("./commands/web-search").then(m => m.default), aliases: ["q"] },
 ];