pi-subagents-lite 1.0.2 → 1.2.0

package/src/ui/agent-widget.ts

@@ -4,20 +4,23 @@
 
 import { truncateToWidth } from "@earendil-works/pi-tui";
 import type { AgentManager } from "../agent-manager.js";
-import { getConfig } from "../agent-types.js";
-import type { AgentRecord, SubagentType } from "../types.js";
+import type { AgentRecord, Theme } from "../types.js";
 import {
-  formatTokens,
+  formatCost,
   getLifetimeTotal,
   getSessionContextPercent,
   type LifetimeUsage,
   type SessionLike,
 } from "../usage.js";
+import { formatMs, buildStatsParts, getDisplayName } from "../format.js";
+
+// Re-export Theme so existing consumers (model-selector, result-viewer) don't break
+export type { Theme } from "../types.js";
 
 // ---- Constants ----
 
 /** Maximum number of rendered lines before overflow collapse kicks in. */
-const MAX_WIDGET_LINES = 12;
+const DEFAULT_MAX_WIDGET_LINES = 12;
 
 /** Braille spinner frames for animated running indicator. */
 const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
@@ -58,11 +61,6 @@ const TOOL_DISPLAY: Record<string, string> = {
 
 // ---- Types ----
 
-export type Theme = {
-  fg(color: string, text: string): string;
-  bold(text: string): string;
-  italic?: (text: string) => string;
-};
 
 export type UICtx = {
   setStatus(key: string, text: string | undefined): void;
@@ -99,95 +97,10 @@ export interface AgentActivity {
   lifetimeUsage: LifetimeUsage;
 }
 
+// ---- Re-exports from format.ts (backward compatibility) ----
+export { formatMs, buildStatsParts, getDisplayName } from "../format.js";
 
-
-// ---- Formatting helpers ----
-
-/**
- * Token count with optional context-fill % and compaction-count annotations.
- * Thresholds for percent: <70% dim, 70–85% warning, ≥85% error.
- * Compaction count rendered as `↻ N` in dim.
- *
- *   "12.3k"                     — no annotations
- *   "12.3k(45%)"                — percent only
- *   "12.3k(↻ 2)"                 — compactions only (e.g. right after compact)
- *   "12.3k(45%·↻ 2)"             — both
- */
-function formatSessionTokens(
-  tokens: number,
-  percent: number | null,
-  theme: Theme,
-  compactions = 0,
-): string {
-  const tokenStr = formatTokens(tokens);
-  const annot: string[] = [];
-  if (percent !== null) {
-    const color = percent >= 85 ? "error" : percent >= 70 ? "warning" : "dim";
-    annot.push(theme.fg(color, `${Math.round(percent)}%`));
-  }
-  if (compactions > 0) {
-    annot.push(theme.fg("dim", `↻ ${compactions}`));
-  }
-  if (annot.length === 0) return tokenStr;
-  // Include closing paren in the last annotation's color span to prevent
-  // ANSI reset from leaving `)` in default color when wrapped in outer dim.
-  const lastIdx = annot.length - 1;
-  annot[lastIdx] += ")";
-  return `${tokenStr}(${annot.join("·")}`;
-}
-
-/** Format turn count with optional max limit: "5≤30⟳" or "5⟳". */
-function formatTurns(turnCount: number, maxTurns?: number | null): string {
-  return maxTurns != null ? `${turnCount}≤${maxTurns}⟳ ` : `${turnCount}⟳ `;
-}
-
-/** Format milliseconds as a compact human-readable duration: "1h 1m 1s", "5m 37s", "10s", "<1s". */
-export function formatMs(ms: number): string {
-  if (!Number.isFinite(ms) || ms < 1000) return "<1s";
-
-  const totalSeconds = Math.floor(ms / 1000);
-  const hours = Math.floor(totalSeconds / 3600);
-  const minutes = Math.floor((totalSeconds % 3600) / 60);
-  const seconds = totalSeconds % 60;
-
-  const parts: string[] = [];
-  if (hours > 0) parts.push(`${hours}h`);
-  if (minutes > 0) parts.push(`${minutes}m`);
-  if (seconds > 0 || parts.length === 0) parts.push(`${seconds}s`);
-
-  return parts.join(" ");
-}
-
-/**
- * Build common stats parts: toolUses · turns · tokens with context %.
- * Shared by AgentWidget and index.ts for consistent stats display.
- */
-export function buildStatsParts(
-  args: {
-    toolUses: number;
-    turnCount?: number;
-    maxTurns?: number;
-    tokens: number;
-    contextPercent: number | null;
-    compactions: number;
-  },
-  theme: Theme,
-): string[] {
-  const parts: string[] = [];
-  if (args.toolUses > 0) parts.push(`${args.toolUses}🛠 `);
-  if (args.turnCount != null) parts.push(formatTurns(args.turnCount, args.maxTurns));
-  if (args.tokens > 0) {
-    parts.push(formatSessionTokens(
-      args.tokens, args.contextPercent, theme, args.compactions,
-    ));
-  }
-  return parts;
-}
-
-/** Get display name for any agent type (built-in or custom). */
-export function getDisplayName(type: SubagentType): string {
-  return getConfig(type).displayName;
-}
+// ---- Widget-internal helpers ----
 
 /**
  * Wrap a stats line in dim ANSI codes, re-applying dim after any inner
@@ -245,6 +158,8 @@ export class AgentWidget {
   /** Finished agents: agent ID → turns since finished. */
   private finishedTurnAge = new Map<string, number>();
 
+  /** Whether to show cost in stats and status bar. */
+  private showCost = false;
 
   /** Whether the widget callback is currently registered with the TUI. */
   private widgetRegistered = false;
@@ -252,12 +167,67 @@ export class AgentWidget {
   private tui: TUI | undefined;
   /** Last status bar text, used to avoid redundant setStatus calls. */
   private lastStatusText: string | undefined;
+  /** Pending tool expansion state from onTerminalInput (push-based, no polling). */
+  private pendingToolsExpanded: boolean | undefined;
+
+  /** Whether to use compact mode (1-line per agent). */
+  private compactMode = false;
+
+  /** Whether "force compact" mode is ON — overrides ctrl+o shortcut. */
+  private forceCompact = false;
+
+  /** Whether ctrl+o shortcut is enabled (syncs compact with toolsExpanded). */
+  private widgetShortcut = false;
+
+  /** Maximum lines for full mode. */
+  private maxLines = DEFAULT_MAX_WIDGET_LINES;
+
+  /** Maximum lines for compact mode. */
+  private maxLinesCompact = Math.floor(DEFAULT_MAX_WIDGET_LINES / 2);
 
   constructor(
     private manager: AgentManager,
     private agentActivity: Map<string, AgentActivity>,
   ) {}
 
+  /** Set whether to show cost in stats and status bar. */
+  setShowCost(enabled: boolean) {
+    this.showCost = enabled;
+  }
+
+  /** Set compact mode (internal, for sync from ctrl+o). */
+  setCompactMode(enabled: boolean) {
+    if (this.compactMode === enabled) return;
+    this.compactMode = enabled;
+    this.update();
+  }
+
+  /** Set force compact mode — overrides ctrl+o shortcut. */
+  setForceCompact(enabled: boolean) {
+    this.forceCompact = enabled;
+  }
+
+  /** Set whether ctrl+o shortcut is enabled. */
+  setWidgetShortcut(enabled: boolean) {
+    this.widgetShortcut = enabled;
+  }
+
+  /** Notify widget that tool expansion state changed (push-based, no polling). */
+  notifyToolsExpansionChanged(expanded: boolean) {
+    this.pendingToolsExpanded = expanded;
+    this.update();
+  }
+
+  /** Set max lines for full mode. */
+  setMaxLines(lines: number) {
+    this.maxLines = lines;
+  }
+
+  /** Set max lines for compact mode. */
+  setMaxLinesCompact(lines: number) {
+    this.maxLinesCompact = lines;
+  }
+
   /** Set the UI context (grabbed from first tool execution). */
   setUICtx(ctx: UICtx) {
     if (ctx !== this.uiCtx) {
@@ -297,9 +267,9 @@ export class AgentWidget {
     const queued: AgentRecord[] = [];
     const finished: AgentRecord[] = [];
     for (const a of allAgents) {
-      if (a.status === "running") running.push(a);
-      else if (a.status === "queued") queued.push(a);
-      else if (a.completedAt && this.shouldShowFinished(a.id, a.status)) finished.push(a);
+      if (a.lifecycle.status === "running") running.push(a);
+      else if (a.lifecycle.status === "queued") queued.push(a);
+      else if (a.lifecycle.completedAt && this.shouldShowFinished(a.id, a.lifecycle.status)) finished.push(a);
     }
     return { running, queued, finished };
   }
@@ -342,47 +312,44 @@ export class AgentWidget {
   }
 
   /** Render a finished agent line. */
-  private renderFinishedLine(a: {
-    id: string; type: SubagentType; status: string; description: string;
-    toolUses: number; startedAt: number; completedAt?: number; error?: string;
-    compactionCount: number; lifetimeUsage: LifetimeUsage;
-    turnCount?: number; maxTurns?: number; session?: SessionLike;
-    outputFile?: string;
-  }, theme: Theme): string {
-    const name = getDisplayName(a.type);
-    const duration = formatMs((a.completedAt ?? Date.now()) - a.startedAt);
-    const { icon, statusText } = this.finishedIconAndStatus(a.status, a.error, theme);
+  private renderFinishedLine(a: AgentRecord, theme: Theme): string {
+    const name = getDisplayName(a.display.type);
+    const duration = formatMs((a.lifecycle.completedAt ?? Date.now()) - a.lifecycle.startedAt);
+    const { icon, statusText } = this.finishedIconAndStatus(a.lifecycle.status, a.error, theme);
 
     const activity = this.agentActivity.get(a.id);
+    const usage = activity?.lifetimeUsage ?? a.stats.lifetimeUsage;
     const statsParts = buildStatsParts({
-      toolUses: a.toolUses,
-      turnCount: activity?.turnCount ?? a.turnCount,
-      maxTurns: activity?.maxTurns ?? a.maxTurns,
-      tokens: getLifetimeTotal(activity?.lifetimeUsage ?? a.lifetimeUsage),
-      contextPercent: getSessionContextPercent(activity?.session ?? a.session),
-      compactions: a.compactionCount,
+      toolUses: a.stats.toolUses,
+      turnCount: activity?.turnCount ?? a.stats.turnCount,
+      maxTurns: activity?.maxTurns ?? a.stats.maxTurns,
+      tokens: getLifetimeTotal(usage),
+      contextPercent: activity?.session ? getSessionContextPercent(activity.session) : a.stats.contextPercent ?? null,
+      compactions: a.stats.compactionCount,
+      cost: this.showCost ? usage.cost : undefined,
     }, theme);
     statsParts.push(duration);
 
     const statsLine = statsParts.join("·");
-    return `${icon} ${theme.fg("dim", name)}  ${theme.fg("dim", a.description)}  ${wrapInDim(theme, statsLine)}${statusText}`;
+    return `${icon} ${theme.fg("dim", name)}  ${theme.fg("dim", a.display.description)}  ${wrapInDim(theme, statsLine)}${statusText}`;
   }
 
-  /** Build the stats line (toolUses · turns · tokens · elapsed) for a running agent. */
+  /** Build the stats line (toolUses · turns · tokens · cost · elapsed) for a running agent. */
   private buildStatsLine(
-    agent: { toolUses: number; compactionCount: number; startedAt: number },
+    agent: AgentRecord,
     activity: AgentActivity | undefined,
     theme: Theme,
   ): string {
     const parts = buildStatsParts({
-      toolUses: activity?.toolUses ?? agent.toolUses,
+      toolUses: activity?.toolUses ?? agent.stats.toolUses,
       turnCount: activity?.turnCount,
       maxTurns: activity?.maxTurns,
       tokens: getLifetimeTotal(activity?.lifetimeUsage),
       contextPercent: getSessionContextPercent(activity?.session),
-      compactions: agent.compactionCount,
+      compactions: agent.stats.compactionCount,
+      cost: this.showCost ? activity?.lifetimeUsage?.cost : undefined,
     }, theme);
-    parts.push(formatMs(Date.now() - agent.startedAt));
+    parts.push(formatMs(Date.now() - agent.lifecycle.startedAt));
     return parts.join("·");
   }
 
@@ -395,11 +362,18 @@ export class AgentWidget {
     const truncate = (line: string) => truncateToWidth(line, w);
     const blocks: RenderBlock[] = [];
     for (const a of finished) {
+      const continuations: string[] = [];
+      if (!this.isCompact()) {
+        if (a.display.outputFile || a.display.worktreeLabel) {
+          const parts: string[] = [];
+          if (a.display.worktreeLabel) parts.push(`@${a.display.worktreeLabel}`);
+          if (a.display.outputFile) parts.push(`tail -f ${a.display.outputFile}`);
+          continuations.push(truncate(theme.fg("dim", `${VLINE}    ${parts.join("  ")}`)));
+        }
+      }
       blocks.push({
         header: truncate(`${theme.fg("dim", BRANCH)} ${this.renderFinishedLine(a, theme)}`),
-        continuations: a.outputFile
-          ? [truncate(theme.fg("dim", `${VLINE}    tail -f ${a.outputFile}`))]
-          : [],
+        continuations,
       });
     }
     return blocks;
@@ -415,21 +389,35 @@ export class AgentWidget {
     const truncate = (line: string) => truncateToWidth(line, w);
     const blocks: RenderBlock[] = [];
     for (const a of running) {
-      const name = getDisplayName(a.type);
+      const name = getDisplayName(a.display.type);
       const bg = this.agentActivity.get(a.id);
       const statsLine = this.buildStatsLine(a, bg, theme);
       const activity = bg ? describeActivity(bg.activeTools, bg.responseText) : THINKING_TEXT;
 
-      const headerLine = `${BRANCH} ${theme.fg("accent", frame)} ${theme.bold(name)}  ${a.description}  ${statsLine}`;
-      blocks.push({
-        header: truncate(headerLine),
-        continuations: [
-          ...(a.outputFile
-            ? [truncate(`${VLINE}  ` + theme.fg("dim", `${VLINE} tail -f ${a.outputFile}`))]
-            : []),
-          truncate(`${VLINE}  ` + theme.fg("dim", `└ ${activity}`)),
-        ],
-      });
+      if (this.isCompact()) {
+        // Compact: single line with activity inline, truncated description
+        const desc = a.display.description.length > 30 ? a.display.description.slice(0, 27) + "..." : a.display.description;
+        const headerLine = `${BRANCH} ${theme.fg("accent", frame)} ${theme.bold(name)}  ${desc}  ${statsLine}  ${theme.fg("dim", activity)}`;
+        blocks.push({
+          header: truncate(headerLine),
+          continuations: [],
+        });
+      } else {
+        // Full: header + continuation lines
+        const headerLine = `${BRANCH} ${theme.fg("accent", frame)} ${theme.bold(name)}  ${a.display.description}  ${statsLine}`;
+        const continuations: string[] = [];
+        if (a.display.outputFile || a.display.worktreeLabel) {
+          const parts: string[] = [];
+          if (a.display.worktreeLabel) parts.push(`@${a.display.worktreeLabel}`);
+          if (a.display.outputFile) parts.push(`tail -f ${a.display.outputFile}`);
+          continuations.push(truncate(`${VLINE}  ` + theme.fg("dim", `${VLINE} ${parts.join("  ")}`)));
+        }
+        continuations.push(truncate(`${VLINE}  ` + theme.fg("dim", `└ ${activity}`)));
+        blocks.push({
+          header: truncate(headerLine),
+          continuations,
+        });
+      }
     }
     return blocks;
   }
@@ -455,6 +443,11 @@ export class AgentWidget {
    * connectors in a single pass. Last visible block gets CORNER + spaces, all others
    * keep BRANCH + VLINE.
    */
+  /** Whether the widget should render in compact mode. */
+  private isCompact(): boolean {
+    return this.forceCompact || (this.widgetShortcut && this.compactMode);
+  }
+
   private renderWidget(tui: TUI, theme: Theme): string[] {
     const { running, queued, finished } = this.categorizeAgents();
 
@@ -485,7 +478,8 @@ export class AgentWidget {
 
     // ---- Overflow logic (works with blocks, not lines) ----
 
-    const maxBody = MAX_WIDGET_LINES - 1; // heading takes 1 line
+    const maxBodyLines = this.isCompact() ? this.maxLinesCompact : this.maxLines;
+    const maxBody = maxBodyLines - 1; // heading takes 1 line
     const totalBody = blocks.reduce((sum, b) => sum + 1 + b.continuations.length, 0);
 
     const heading = `${theme.fg(headingColor, headingIcon)} ${theme.fg(headingColor, "Agents")}`;
@@ -601,21 +595,40 @@ export class AgentWidget {
   }
 
   /** Update the status bar text, only if it changed. */
-  private updateStatusBar(runningCount: number, queuedCount: number) {
-    const statusParts: string[] = [];
-    if (runningCount > 0) statusParts.push(`${runningCount} running`);
-    if (queuedCount > 0) statusParts.push(`${queuedCount} queued`);
+  private updateStatusBar(runningCount: number, queuedCount: number, running: AgentRecord[]) {
     const total = runningCount + queuedCount;
-    const newStatusText = `${statusParts.join(", ")} agent${total === 1 ? "" : "s"}`;
-    if (newStatusText !== this.lastStatusText) {
-      this.uiCtx?.setStatus(STATUS_KEY, newStatusText);
-      this.lastStatusText = newStatusText;
+    let statusText = total > 0 ? `${total} agent${total === 1 ? "" : "s"}` : `agents`;
+    if (this.showCost) {
+      const sessionCost = this.manager.getTotalAgentCost();
+      // Also include in-flight running agents (not yet completed, so not in accumulator)
+      const runningCost = running.reduce((sum, a) => sum + a.stats.lifetimeUsage.cost, 0);
+      const totalCost = sessionCost + runningCost;
+      if (totalCost > 0) statusText += `: ${formatCost(totalCost)}`;
+    }
+    if (statusText !== this.lastStatusText) {
+      this.uiCtx?.setStatus(STATUS_KEY, statusText);
+      this.lastStatusText = statusText;
     }
   }
 
   /** Force an immediate widget update. */
   update() {
+    if (!this.manager) {
+      // Widget lost its manager reference (e.g., after session shutdown)
+      clearInterval(this.widgetInterval);
+      this.widgetInterval = undefined;
+      return;
+    }
     if (!this.uiCtx) return;
+
+    // Sync compact mode with tool expansion state (ctrl+o)
+    // Tools expanded → widget full, tools collapsed → widget compact
+    // Note: sync is triggered by onTerminalInput detecting ctrl+o, not polling
+    if (this.widgetShortcut && !this.forceCompact && this.pendingToolsExpanded !== undefined) {
+      this.compactMode = !this.pendingToolsExpanded;
+      this.pendingToolsExpanded = undefined;
+    }
+
     const { running, queued, finished } = this.categorizeAgents();
 
     const hasActive = running.length > 0 || queued.length > 0;
@@ -628,7 +641,7 @@ export class AgentWidget {
     }
 
     // Status bar — only call setStatus when the text actually changes
-    this.updateStatusBar(running.length, queued.length);
+    this.updateStatusBar(running.length, queued.length, running);
 
     this.widgetFrame++;
 

package/src/usage.ts

@@ -36,6 +36,11 @@ export function formatTokens(count: number): string {
   return `${count}`;
 }
 
+/** Format cost as a dollar amount: "$0.00", "$0.01", "$1.23". */
+export function formatCost(cost: number): string {
+  return `$${cost.toFixed(2)}`;
+}
+
 /**
  * Context-window utilization (0–100), or null when unavailable
  * (no model contextWindow, or post-compaction before the next response).

package/src/worktree-validator.ts

@@ -0,0 +1,199 @@
+/**
+ * worktree-validator.ts — Validate, resolve, and label a worktree path.
+ *
+ * Pure async functions that validate a `worktree_path` value against the parent's
+ * git repository. Depends on `pi.exec` for git commands.
+ *
+ * Validation strategy: compare `git-common-dir` of the parent and target paths.
+ * If they share the same common dir, the target is a worktree of the parent's repo.
+ */
+
+import * as path from "node:path";
+import { existsSync, statSync, realpathSync } from "node:fs";
+
+/** Timeout for git commands (ms). */
+const GIT_EXEC_TIMEOUT_MS = 5000;
+
+/** Specific error messages returned to the LLM for self-correction. */
+export const WORKTREE_VALIDATION_ERRORS = {
+  PATH_DOES_NOT_EXIST: "worktree_path does not exist: the specified path was not found on disk",
+  NOT_A_DIRECTORY: "worktree_path is not a directory: the specified path exists but is not a directory",
+  PARENT_NOT_IN_GIT_REPO: "worktree_path validation failed: the parent session is not inside a git repository",
+  NOT_IN_GIT_REPO: "worktree_path is not inside a git repository",
+  DIFFERENT_REPO: "worktree_path is not a worktree of the parent's repository",
+  GIT_NOT_FOUND: "worktree_path validation failed: git executable not found on this host",
+  GIT_TIMEOUT: "worktree_path validation failed: git command timed out",
+} as const;
+
+/** Successful validation result. */
+export interface WorktreeValidationSuccess {
+  ok: true;
+  /** Resolved absolute path (symlinks followed, relative resolved). Undefined when path is empty/omitted. */
+  resolvedPath?: string;
+  /** Worktree root directory. */
+  worktreeRoot?: string;
+  /** Short display label for the widget. */
+  label?: string;
+}
+
+/** Failed validation result. */
+export interface WorktreeValidationFailure {
+  ok: false;
+  /** Human-readable error describing the specific failure reason. */
+  error: string;
+}
+
+export type WorktreeValidationResult = WorktreeValidationSuccess | WorktreeValidationFailure;
+
+/**
+ * Minimal interface for the pi exec function — only what the validator needs.
+ */
+interface PiExec {
+  exec(cmd: string, args: string[], opts?: { cwd?: string; timeout?: number }): Promise<{ code: number; stdout: string; stderr: string }>;
+}
+
+/**
+ * Run `git rev-parse --git-common-dir` and return the trimmed result.
+ * Returns a failure result if the command fails or git is unavailable.
+ */
+async function getGitCommonDir(
+  pi: PiExec,
+  cwd: string,
+  notInRepoError: string,
+): Promise<{ ok: true; commonDir: string } | { ok: false; error: string }> {
+  try {
+    const result = await pi.exec("git", ["rev-parse", "--git-common-dir"], { cwd, timeout: GIT_EXEC_TIMEOUT_MS });
+    if (result.code !== 0) return { ok: false, error: notInRepoError };
+    const commonDir = result.stdout.trim();
+    if (!commonDir) return { ok: false, error: notInRepoError };
+    return { ok: true, commonDir };
+  } catch (err: unknown) {
+    const msg = String(err instanceof Error ? err.message : err);
+    if (msg.includes("ENOENT") || msg.includes("not found")) {
+      return { ok: false, error: WORKTREE_VALIDATION_ERRORS.GIT_NOT_FOUND };
+    }
+    return { ok: false, error: WORKTREE_VALIDATION_ERRORS.GIT_TIMEOUT };
+  }
+}
+
+/**
+ * Validate a worktree path against the parent's git repository.
+ *
+ * Resolution order:
+ * 1. Empty/whitespace → treated as omitted (return ok with no path)
+ * 2. Resolve relative against parent cwd
+ * 3. Resolve symlinks (realpath)
+ * 4. Check exists + is directory
+ * 5. Get and compare git-common-dir for parent and target
+ * 6. Get worktree root via --show-toplevel
+ * 7. Normalize and compute display label
+ *
+ * @param pi - Minimal exec interface (pi.exec)
+ * @param worktreePath - The raw worktree_path value from the LLM
+ * @param parentCwd - The parent session's working directory
+ * @returns Validation result with resolved path + label, or error
+ */
+export async function validateWorktreePath(
+  pi: PiExec,
+  worktreePath: string,
+  parentCwd: string,
+): Promise<WorktreeValidationResult> {
+  // Step 1: Empty / whitespace → treat as omitted
+  if (!worktreePath || worktreePath.trim() === "") {
+    return { ok: true };
+  }
+
+  // Step 2: Resolve relative paths against parent cwd
+  const resolved = path.isAbsolute(worktreePath)
+    ? worktreePath
+    : path.resolve(parentCwd, worktreePath);
+
+  // Step 3: Check existence
+  if (!existsSync(resolved)) {
+    return { ok: false, error: WORKTREE_VALIDATION_ERRORS.PATH_DOES_NOT_EXIST };
+  }
+
+  // Step 4: Check is directory (resolve symlinks first via stat)
+  let realPath: string;
+  try {
+    const stat = statSync(resolved);
+    if (!stat.isDirectory()) {
+      return { ok: false, error: WORKTREE_VALIDATION_ERRORS.NOT_A_DIRECTORY };
+    }
+    // Resolve symlinks — use realpathSync to get the canonical path
+    realPath = realpathSync(resolved);
+  } catch {
+    // stat failed — likely a broken symlink or permission issue
+    return { ok: false, error: WORKTREE_VALIDATION_ERRORS.PATH_DOES_NOT_EXIST };
+  }
+
+  // Step 5: Get and compare git-common-dir for parent and target
+  const parentResult = await getGitCommonDir(pi, parentCwd, WORKTREE_VALIDATION_ERRORS.PARENT_NOT_IN_GIT_REPO);
+  if (!parentResult.ok) return parentResult;
+
+  const targetResult = await getGitCommonDir(pi, realPath, WORKTREE_VALIDATION_ERRORS.NOT_IN_GIT_REPO);
+  if (!targetResult.ok) return targetResult;
+
+  // Compare common dirs — must share the same repo
+  const parentCommonAbs = path.isAbsolute(parentResult.commonDir)
+    ? parentResult.commonDir
+    : path.resolve(parentCwd, parentResult.commonDir);
+  const targetCommonAbs = path.isAbsolute(targetResult.commonDir)
+    ? targetResult.commonDir
+    : path.resolve(realPath, targetResult.commonDir);
+
+  if (parentCommonAbs !== targetCommonAbs) {
+    return { ok: false, error: WORKTREE_VALIDATION_ERRORS.DIFFERENT_REPO };
+  }
+
+  // Step 6: Get the worktree root via git rev-parse --show-toplevel
+  let worktreeRoot: string;
+  try {
+    const result = await pi.exec("git", ["rev-parse", "--show-toplevel"], { cwd: realPath, timeout: GIT_EXEC_TIMEOUT_MS });
+    if (result.code !== 0) {
+      worktreeRoot = realPath;
+    } else {
+      const raw = result.stdout.trim();
+      worktreeRoot = raw ? (path.isAbsolute(raw) ? raw : path.resolve(realPath, raw)) : realPath;
+    }
+  } catch {
+    worktreeRoot = realPath;
+  }
+
+  // Step 7: Normalize and compute display label
+  const normalizedRealPath = realPath.replace(/\\/g, "/");
+  const normalizedRoot = worktreeRoot.replace(/\\/g, "/");
+  const label = computeLabel(normalizedRealPath, normalizedRoot);
+
+  return {
+    ok: true,
+    resolvedPath: normalizedRealPath,
+    worktreeRoot: normalizedRoot,
+    label,
+  };
+}
+
+/**
+ * Compute a short display label for the worktree path.
+ *
+ * Rules:
+ * - Root of worktree → basename (e.g., "/wt/feature" → "feature")
+ * - Subdirectory → basename/relative (e.g., "/wt/feature/packages/web" → "feature/packages/web")
+ * - Always forward slashes regardless of host OS
+ */
+export function computeLabel(resolvedPath: string, worktreeRoot: string): string {
+  // Normalize both paths to forward slashes for cross-platform comparison
+  const normalizedResolved = resolvedPath.replace(/\\/g, "/");
+  const normalizedRoot = worktreeRoot.replace(/\\/g, "/");
+
+  const rootBasename = normalizedRoot.split("/").filter(Boolean).pop() ?? "";
+
+  if (normalizedResolved === normalizedRoot) {
+    return rootBasename;
+  }
+
+  // Compute relative path using posix separator
+  const relative = path.posix.relative(normalizedRoot, normalizedResolved);
+
+  return `${rootBasename}/${relative}`;
+}