pi-pier 0.1.5 → 0.2.1

package/src/stale-core.ts

@@ -1,48 +1,50 @@
 /**
- * todo 陈旧度纯核心（反冻结：会话 01a03253 实证）。
+ * Pure core for todo staleness (anti-freeze behavior, evidenced by session 01a03253).
  *
- * 实证：全完成列表（3✓）冻结 16h / 37 轮，模型持续做新工作但 todo_write 零调用；
- * 读钩每轮复读死列表反而背书"无事可跟踪"，标题满权重渲染死计数。
- * 本模块把"列表是否还反映现实"收敛为纯函数，三层消费：
- *  - stale（A）：open==0 且 ≥ STALE_TURNS 轮未写 → 读钩注入改 stale 警告（限频 + 封顶）；
- *  - archived（B）：open==0 且墙钟 ≥ STALE_CLOCK_MS 未写 → 按不存在处理
- *    （注入/投影不再复读明细；条目保留，/todos 可查；会话 JSONL 权威不动）；
- *  - 标题（D）：archived 时窗格/侧栏渲染 `✓N done <age>`，不再冒充当前状态。
+ * Evidence: a fully completed list (3✓) froze for 16h / 37 turns while the model continued new work but made no
+ * todo_write calls; rereading the dead list every read hook falsely endorsed "nothing to track," and the title
+ * rendered dead counts at full weight. This module reduces whether a list still reflects reality to pure functions
+ * consumed in three places:
+ *  - stale (A): open==0 with ≥ STALE_TURNS turns since the last write → the read hook injects a rate-limited,
+ *    capped stale warning;
+ *  - archived (B): open==0 with wall-clock age ≥ STALE_CLOCK_MS since the last write → treat it as absent
+ *    (injection/projection no longer rereads details; entries remain queryable through /todos; session JSONL stays authoritative);
+ *  - title (D): when archived, pane/sidebar renders `✓N done <age>` instead of impersonating current state.
  *
- * 有 open 项（pending/in_progress/blocked）的列表永不判 stale——未完成工作
- * 仍由 agent_settled 提醒兜底；lastWriteAt 未知（旧会话无时间戳）→ 时钟维度
- * 保守不判 archived，turns 维度不受影响。
+ * A list with open items (pending/in_progress/blocked) is never stale: agent_settled continues to cover unfinished
+ * work. When lastWriteAt is unknown (old sessions lack timestamps), conservatively do not archive on the clock axis;
+ * the turns axis remains unaffected.
  */
 import { countTodos, type TodoItem } from './vocab.ts';
 
-/** A：turns 维度过期阈值（用户轮次，自上次 todo 写入起算）。 */
+/** A: turn-based expiry threshold (user turns counted from the last todo write). */
 export const STALE_TURNS = 6;
 
-/** B：墙钟维度归档阈值（全完成列表最后一次写入距今）。 */
+/** B: wall-clock archive threshold (age of the last write for a completed list). */
 export const STALE_CLOCK_MS = 60 * 60 * 1000;
 
-/** A：每次停滞期最多注入的 stale 警告数（防空转噪音；archived 后转归档通知节奏）。 */
+/** A: maximum stale warnings injected during one stalled period (prevent spin noise; archived changes to archive-notice cadence). */
 export const STALE_NOTICE_MAX = 3;
 
 export type StalenessKind = 'fresh' | 'stale' | 'archived';
 
 export interface Staleness {
   kind: StalenessKind;
-  /** open = pending + in_progress + blocked（abandoned 不算未完成）。 */
+  /** open = pending + in_progress + blocked (abandoned does not count as unfinished). */
   open: number;
-  /** now - lastWriteAt；lastWriteAt 未知 → null。 */
+  /** now - lastWriteAt; unknown lastWriteAt → null. */
   ageMs: number | null;
 }
 
-/** open 计数：stale/archived 只对 open==0 的全完成（或全放弃）列表生效。 */
+/** Count open items: stale/archived apply only to fully completed (or fully abandoned) lists with open==0. */
 export function openTodos(items: readonly TodoItem[]): number {
   const c = countTodos(items as TodoItem[]);
   return c.pending + c.inProgress + c.blocked;
 }
 
 /**
- * 陈旧度判定（双条件：turns 维度 → stale；墙钟维度 → archived，时钟优先）。
- * 空列表 → fresh（空守卫另有归属）；lastWriteAt null → 永不 stale（保守）。
+ * Determine staleness (two conditions: turns → stale; wall clock → archived, with the clock taking precedence).
+ * Empty list → fresh (a separate guard owns empty-list handling); null lastWriteAt → never stale (conservative).
  */
 export function evaluateStaleness(opts: {
   items: readonly TodoItem[];
@@ -59,7 +61,7 @@ export function evaluateStaleness(opts: {
   return st;
 }
 
-/** 标题/镜像路径专用（无 turn 信息）：仅墙钟维度的 archived 判定。 */
+/** For title/mirror paths without turn information: only evaluate wall-clock archive status. */
 export function isArchived(
   items: readonly TodoItem[],
   lastWriteAt: number | null,
@@ -68,7 +70,7 @@ export function isArchived(
   return evaluateStaleness({ items, lastWriteAt, turnsSinceWrite: null, now }).kind === 'archived';
 }
 
-/** 年龄显示：<60m → `Nm`；<48h → `Nh`（floor）；否则 `Nd`。 */
+/** Age display: <60m → `Nm`; <48h → `Nh` (floor); otherwise `Nd`. */
 export function formatAge(ms: number): string {
   if (ms < 60 * 60_000) return `${Math.max(1, Math.floor(ms / 60_000))}m`;
   if (ms < 48 * 3_600_000) return `${Math.floor(ms / 3_600_000)}h`;

package/src/storage-layout.ts

@@ -0,0 +1,80 @@
+/**
+ * Storage path layout (history, session dirs, role dirs).
+ *
+ * Why: sessionDirName / historyFilePath / userRolesDir were duplicated across
+ * history-store, session-tail, and role-loader. One module owns the encoding
+ * so path conventions cannot drift.
+ *
+ * Writes use a collision-resistant encoding (`a/b` ≠ `a-b`). Reads prefer the
+ * new name, then the legacy flattened name, so existing history/session dirs
+ * stay reachable. If only the legacy dir exists, writes keep appending there
+ * instead of splitting the ledger.
+ */
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * Legacy flattening (`--F--herdr-pi--`).
+ * Why kept: `a/b` and `a-b` collide, but on-disk dirs already use this form.
+ */
+export function sessionDirNameLegacy(cwd: string): string {
+  const flat = cwd.replace(/[\\/]/g, '-').replace(/:/g, '-');
+  return `--${flat}--`;
+}
+
+/**
+ * Collision-resistant session directory name.
+ * `%` is escaped first so `/` `\` `:` round-trip: `a/b` → `--a%2Fb--`, `a-b` → `--a-b--`.
+ */
+export function sessionDirName(cwd: string): string {
+  const encoded = cwd
+    .replace(/%/g, '%25')
+    .replace(/\\/g, '%5C')
+    .replace(/\//g, '%2F')
+    .replace(/:/g, '%3A');
+  return `--${encoded}--`;
+}
+
+/** New encoding first, then legacy when they differ. */
+export function sessionDirCandidates(cwd: string): readonly string[] {
+  const next = sessionDirName(cwd);
+  const prev = sessionDirNameLegacy(cwd);
+  return next === prev ? [next] : [next, prev];
+}
+
+/**
+ * Directory to read/write under `parent`.
+ * Existing legacy dirs win over a missing new dir so history is not split.
+ */
+export function preferredSessionDir(parent: string, cwd: string): string {
+  const names = sessionDirCandidates(cwd);
+  for (const name of names) {
+    const dir = join(parent, name);
+    if (existsSync(dir)) return dir;
+  }
+  return join(parent, names[0]);
+}
+
+export function historyFilePath(agentRoot: string, cwd: string): string {
+  return join(agentRoot, 'herdr-pi', 'history', sessionDirName(cwd), 'history.jsonl');
+}
+
+export function historyFilePathLegacy(agentRoot: string, cwd: string): string {
+  return join(agentRoot, 'herdr-pi', 'history', sessionDirNameLegacy(cwd), 'history.jsonl');
+}
+
+/** Dual-read history path: existing ledger (legacy or new) else canonical new file. */
+export function preferredHistoryFile(agentRoot: string, cwd: string): string {
+  return join(preferredSessionDir(join(agentRoot, 'herdr-pi', 'history'), cwd), 'history.jsonl');
+}
+
+/** User-global roles directory (`~/.pi/agent/herdr-pi/roles/`). */
+export function userRolesDir(): string {
+  return join(homedir(), '.pi', 'agent', 'herdr-pi', 'roles');
+}
+
+/** Workspace-level roles directory (`<base>/.pi-herdr/roles/`). */
+export function workspaceRolesDir(baseDir: string): string {
+  return join(baseDir, '.pi-herdr', 'roles');
+}

package/src/subagent-core.ts

@@ -1,15 +1,4 @@
-/**
- * subagent 纯逻辑：子 pane 命令构造、并发信号量、注册表、进度回调。
- * 无副作用、无 pi/herdr API 依赖 → 可单测。
- *
- * v1.1（DESIGN.md §12，方案 C）：子 pane 统一为交互式 pi TUI。
- *  - 启动：常驻 shell 里 `node cli.js -e <本扩展>`（Windows 经 powershell 包裹、
- *    POSIX 直启；无 prompt 参数，prompt 经扩展管道注入），herdr 自动检测 +
- *    本扩展上报状态；
- *  - 并发上限 4（D10）：信号量压制并行 spawn；
- *  - 结果通道 = 子会话 JSONL（session-tail.ts），不再解析 pane 文本；
- *  - 软锁：仅在 herdr agent_status ∈ {idle} 时注入（index.ts 的状态门）。
- */
+/** Why: Preserve the established compatibility and safety behavior (D10). */
 import { normalizeEntryKind } from './history-store.ts';
 
 export interface SubagentSpec {
@@ -17,21 +6,17 @@ export interface SubagentSpec {
   prompt: string;
 }
 
-/** PowerShell 单引号转义（''）。 */
+/** Why: Preserve the established compatibility and safety behavior. */
 export function psQuote(s: string): string {
   return `'${String(s).replace(/'/g, "''")}'`;
 }
 
-/** POSIX sh 单引号转义（'\''）。 */
+/** Why: Preserve the established compatibility and safety behavior. */
 export function shQuote(s: string): string {
   return `'${String(s).replace(/'/g, `'\\''`)}'`;
 }
 
-/**
- * 子代理启动命令行（注入子 pane 的 shell，经 pane.send_text + CR 提交）。
- * 片段 = 裸 argv 词（如 ['pi', '--session', '<file>']）；win32 输出 PowerShell
- * 调用语法（`&` 引导 + `''` 转义），其余输出 POSIX sh 语法（单引号 + `'\''` 转义）。
- */
+/** Why: Preserve the established compatibility and safety behavior. */
 export function buildLaunchLine(parts: readonly string[], platform: NodeJS.Platform = process.platform): string {
   const quoted = platform === 'win32'
     ? parts.map((s) => psQuote(s))
@@ -39,7 +24,7 @@ export function buildLaunchLine(parts: readonly string[], platform: NodeJS.Platf
   return (platform === 'win32' ? '& ' : '') + quoted.join(' ');
 }
 
-/** 计数信号量：并发上限内的 acquire 立即执行，超出排队（FIFO）。 */
+/** Why: Preserve the established compatibility and safety behavior. */
 export class Semaphore {
   private active = 0;
   private queue: Array<() => void> = [];
@@ -76,11 +61,11 @@ export class Semaphore {
 
 export interface SubagentOutcome {
   kind: 'completed' | 'timeout' | 'no-output' | 'blocked' | 'spawn-failed';
-  /** 最终文本（completed 时为子代理最终回答；timeout/blocked 时为部分输出）。 */
+  /** Why: Preserve the established compatibility and safety behavior. */
   text: string;
 }
 
-/** 把提取结果规范为工具返回文本。 */
+/** Why: Preserve the established compatibility and safety behavior. */
 export function formatSubagentResult(outcome: SubagentOutcome, description: string): string {
   switch (outcome.kind) {
     case 'completed': {
@@ -98,25 +83,25 @@ export function formatSubagentResult(outcome: SubagentOutcome, description: stri
   }
 }
 
-/* ── 探活 + 存活通知（A2/B1 统一出口；纯逻辑，IO 在 adapter） ────── */
+/** Why: Preserve the established compatibility and safety behavior (A2, B1). */
 
-/** 探活快照：pane 实时状态 + 会话活动时间（毫秒 epoch；null = 未知）。 */
+/** Why: Preserve the established compatibility and safety behavior. */
 export interface AliveProbe {
   paneExists: boolean;
   agentStatus: string | null;
-  /** 会话文件 mtime（最新候选）；无文件/不可读 = null。 */
+  /** Why: Preserve the established compatibility and safety behavior. */
   lastActivityMs: number | null;
 }
 
-/** 探活判活：pane 在 +（working/blocked 或近期有会话活动）→ 视为还在干活。 */
+/** Why: Preserve the established compatibility and safety behavior. */
 export function isAlive(probe: AliveProbe, nowMs: number, staleAfterMs = 120_000): boolean {
   if (!probe.paneExists) return false;
   if (probe.agentStatus === 'working' || probe.agentStatus === 'blocked') return true;
-  // idle/unknown：会话 2 分钟内有活动仍算活（写作间隙/刚结算未采集）
+  // Why: Preserve the established compatibility and safety behavior.
   return probe.lastActivityMs != null && nowMs - probe.lastActivityMs < staleAfterMs;
 }
 
-/** 人话相对时间（"12s ago" / "3m ago"）。 */
+/** Why: Preserve the established compatibility and safety behavior. */
 export function agoText(ms: number, nowMs: number): string {
   const s = Math.max(0, Math.round((nowMs - ms) / 1000));
   if (s < 60) return `${s}s ago`;
@@ -124,11 +109,7 @@ export function agoText(ms: number, nowMs: number): string {
   return `${Math.floor(s / 3600)}h ago`;
 }
 
-/**
- * 存活通知（A2 转后台返回值 与 B1 tool_result 改写 的统一构造出口）：
- * 两场景同一话术——"它在干活 / 别重做 / 转后台了 / 结算会通知 / list_agents 可查"。
- * scenario: 'moved-to-bg'（耐心阈值转后台）| 'error-alive'（工具报错但探活判活，兜底改写）。
- */
+/** Why: Preserve the established compatibility and safety behavior (A2, B1). */
 export function buildAliveNotice(
   opts: { paneId: string; description: string; scenario: 'moved-to-bg' | 'error-alive'; probe: AliveProbe },
   nowMs: number,
@@ -151,11 +132,7 @@ export function buildAliveNotice(
   ].join(' ');
 }
 
-/**
- * 人类闸门通知（E1/E2 统一出口）：subagent blocked（ask_user_question 等人类）时
- * 给 master 的话术——不揽活、引导用户去 pane、授权例外经 send_message 转达。
- * question 来自 herdr tokens['pi-ask']（子扩展 reportAskFlag 上报）。
- */
+/** Why: Preserve the established compatibility and safety behavior (E1, E2). */
 export function buildBlockedGateNotice(opts: { paneId: string; description: string; question: string | null }): string {
   const { paneId, description, question } = opts;
   const q = question ? ` (question: "${question}")` : '';
@@ -168,34 +145,42 @@ export function buildBlockedGateNotice(opts: { paneId: string; description: stri
   ].join(' ');
 }
 
-/* ── 子代理注册表（custom 条目持久化） ────────────────────────────── */
+/** Why: Preserve the established compatibility and safety behavior. */
 
 export const SUBS_CUSTOM_TYPE = 'pi-herdr.subs';
 
 export interface SubEntry {
   taskId: string;
-  /** 'task' 或 role 名；旧 short/resident 读盘归一为 task，不参与 GC。 */
+  /** Why: Preserve the established compatibility and safety behavior. */
   kind: string;
   paneId: string;
   tabId: string;
-  /** v1.3：任务 tab 名（D25/D26；tab.rename 后可能漂移，仅为显示/复活参考）。 */
+  /** Why: Preserve the established compatibility and safety behavior (D25, D26). */
   tabName: string;
   cwd: string;
   description: string;
   background: boolean;
   status: 'running' | 'settled' | 'consumed' | 'closed';
-  /** 消费时间（GC 宽限期判据）。 */
+  /** Why: Preserve the established compatibility and safety behavior. */
   consumedAt?: number | null;
   sessionFile: string | null;
   launchCommand: string[];
   createdAt: number;
   revivedFrom?: string | null;
-  /** D94：用户是否接管控制（暂停 master 管理）。 */
+  /** Why: Preserve the established compatibility and safety behavior (D94). */
   userTakeover?: boolean;
-  /** D94：接管检测时间（ms）；settled 后进入观察期开始计时。 */
+  /** Why: Preserve the established compatibility and safety behavior (D94). */
   observationStartedAt?: number | null;
-  /** D94：上次 agent 状态（用于检测 idle→working 的用户介入）。 */
+  /** Why: Preserve the established compatibility and safety behavior (D94). */
   lastAgentStatus?: string | null;
+  /** Why: Preserve the established compatibility and safety behavior (D98). */
+  isolate?: {
+    worktreePath: string;
+    branch: string;
+    baseSha: string;
+    releasedAt: number | null;
+    retainNotified: boolean;
+  };
 }
 
 export interface SubsRegistry {
@@ -207,11 +192,7 @@ export function makeRegistry(subs: SubEntry[] = []): SubsRegistry {
   return { version: 2, subs };
 }
 
-/**
- * 从会话分支条目折叠注册表（last-wins，与 todo 折叠同构）。
- * custom 条目形状（session-format 实测）：{type:'custom', customType, data}。
- * 兼容 v1 条目（缺字段按默认补齐：taskId=paneId、kind=task、tabId=''、launchCommand=[]）。
- */
+/** Why: Preserve the established compatibility and safety behavior. */
 export function foldSubsRegistry(entries: readonly BranchEntryLike2[]): SubsRegistry {
   let found = makeRegistry();
   for (const entry of entries) {
@@ -240,6 +221,17 @@ export function foldSubsRegistry(entries: readonly BranchEntryLike2[]): SubsRegi
         userTakeover: s.userTakeover === true ? true : undefined,
         observationStartedAt: typeof s.observationStartedAt === 'number' ? s.observationStartedAt : null,
         lastAgentStatus: typeof s.lastAgentStatus === 'string' ? s.lastAgentStatus : null,
+        isolate: s.isolate && typeof s.isolate === 'object'
+          && typeof s.isolate.worktreePath === 'string' && typeof s.isolate.branch === 'string'
+          && typeof s.isolate.baseSha === 'string'
+          ? {
+            worktreePath: s.isolate.worktreePath,
+            branch: s.isolate.branch,
+            baseSha: s.isolate.baseSha,
+            releasedAt: typeof s.isolate.releasedAt === 'number' ? s.isolate.releasedAt : null,
+            retainNotified: s.isolate.retainNotified === true,
+          }
+          : undefined,
       }));
     found = { version: 2, subs };
   }
@@ -252,36 +244,30 @@ export interface BranchEntryLike2 {
   data?: unknown;
 }
 
-/* ── 工具进度回调 ─────────────────────────────────────────────────── */
+/** Why: Preserve the established compatibility and safety behavior. */
 
 export interface ProgressUpdate {
   content: Array<{ type: 'text'; text: string }>;
   details: Record<string, never>;
 }
 
-/**
- * 构造 onUpdate 的合法负载。
- *
- * ⚠️ pi 0.84.2 实测：AgentToolUpdateCallback 期待 AgentToolResult（{content, details}），
- * 传字符串会让交互式 TUI 在 getTextOutput 处崩溃（undefined.filter）并整个退出 pi。
- * 所有进度回调必须经本助手构造。
- */
+/** Why: Preserve the established compatibility and safety behavior. */
 export function makeProgressUpdate(msg: string): ProgressUpdate {
   return { content: [{ type: 'text', text: msg }], details: {} };
 }
 
-/* ── v1.3 任务 tab 放置（D25/D26 纯逻辑，可单测） ─────────────────── */
+/** Why: Preserve the established compatibility and safety behavior (D25, D26). */
 
 export const TAB_NAME_MAX = 20;
 
-/** tab 名规范化：折叠空白、截断 ≤20 字符；空 → 'task'。 */
+/** Why: Preserve the established compatibility and safety behavior. */
 export function tabNameForTask(description: string): string {
   const cleaned = String(description ?? '').replace(/\s+/g, ' ').trim();
   const truncated = cleaned.slice(0, TAB_NAME_MAX).trim();
   return truncated || 'task';
 }
 
-/** 缺省放置撞名加序号后缀（-2、-3…），并保持总长 ≤20（D26：缺省永远开新 tab）。 */
+/** Why: Preserve the established compatibility and safety behavior (D26). */
 export function nextTaskTabName(base: string, existingNames: ReadonlySet<string>): string {
   let name = base;
   let n = 2;
@@ -294,16 +280,16 @@ export function nextTaskTabName(base: string, existingNames: ReadonlySet<string>
 }
 
 export interface TabPlacementPlan {
-  /** append = 追加进既有 tab（锚 pane split）；new = 新命名 tab。 */
+  /** Why: Preserve the established compatibility and safety behavior. */
   mode: 'append' | 'new';
   tabName: string;
-  /** append 时的既有 tabId（须调用方再校验存活）；new 时为 null。 */
+  /** Why: Preserve the established compatibility and safety behavior. */
   tabId: string | null;
 }
 
-/* ── D86：worktree 分组键（纯逻辑） ─────────────────────────────── */
+/** Why: Preserve the established compatibility and safety behavior (D86). */
 
-/** 路径包含判定（大小写不敏感 + 斜杠统一；cwd === wt 或 cwd 在 wt 之下）。D86 信任旗标也用它。 */
+/** Why: Preserve the established compatibility and safety behavior (D86). */
 export function isPathUnder(cwd: string, wt: string): boolean {
   const n = (p: string) => p.replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
   const a = n(cwd);
@@ -312,17 +298,13 @@ export function isPathUnder(cwd: string, wt: string): boolean {
 }
 
 export interface WorktreeZone {
-  /** main = 主检出（split 进 main tab）；worktree = 命名 worktree tab；非 git/无关目录也兜底 main。 */
+  /** Why: Preserve the established compatibility and safety behavior. */
   zone: 'main' | 'worktree';
-  /** zone=worktree 时的 tab 名（目录名原样，撞名后缀由 nextTaskTabName 处理）。 */
+  /** Why: Preserve the established compatibility and safety behavior. */
   tabName: string | null;
 }
 
-/**
- * D86 分类器：cwd 落在哪个 worktree 分组。
- * `worktrees` = git porcelain 顺序（主检出在前，仅用于列表本身；归属判定按包含）；
- * 非 git / 不属任何 worktree → main（「无新 worktree → 同 tab」的兜底）。
- */
+/** Why: Preserve the established compatibility and safety behavior (D86). */
 export function classifyWorktreeZone(opts: {
   cwd: string;
   masterCwd: string;
@@ -330,27 +312,21 @@ export function classifyWorktreeZone(opts: {
 }): WorktreeZone {
   for (const wt of opts.worktrees) {
     if (!isPathUnder(opts.cwd, wt)) continue;
-    if (isPathUnder(opts.masterCwd, wt)) return { zone: 'main', tabName: null }; // 主检出 → main tab
+    if (isPathUnder(opts.masterCwd, wt)) return { zone: 'main', tabName: null }; // Why: Preserve the established compatibility and safety behavior.
     const base = wt.replace(/\\/g, '/').split('/').filter(Boolean).pop() ?? 'worktree';
     return { zone: 'worktree', tabName: base };
   }
   return { zone: 'main', tabName: null };
 }
 
-/**
- * 放置决策（D26 显式层 + D86 缺省层）：
- *  - 显式 `tab` 参数：规范名 → 已知 tab 同名则 append（用其 tabId），否则 new；
- *  - 缺省（D86）：`zone` 给出分组——main → append 进 mainTabId；worktree →
- *    join-or-create 该目录名 tab（已知同名 append，否则 new）。
- * `knownTabs` = 调用时刻的存活 tab（label, id）。
- */
+/** Why: Preserve the established compatibility and safety behavior (D26, D86). */
 export function planTabPlacement(opts: {
   desiredTab?: string | null;
   description: string;
   knownTabs: ReadonlyArray<{ tabName: string; tabId: string }>;
-  /** D86 缺省分组（classifyWorktreeZone 输出；不传 = 旧 description 派生路径，兼容用）。 */
+  /** Why: Preserve the established compatibility and safety behavior (D86). */
   zone?: WorktreeZone;
-  /** D86 main 分组的目标 tab（master 所在 tab）。 */
+  /** Why: Preserve the established compatibility and safety behavior (D86). */
   mainTabId?: string | null;
 }): TabPlacementPlan {
   const known = new Map<string, string>();
@@ -362,39 +338,33 @@ export function planTabPlacement(opts: {
   }
   const zone = opts.zone;
   if (zone?.zone === 'main' && opts.mainTabId) {
-    // D86 R1：主检出 → split 进 main tab（锚 pane 由调用方选）
+    // Why: Preserve the established compatibility and safety behavior (D86, R1).
     return { mode: 'append', tabName: 'main', tabId: opts.mainTabId };
   }
   if (zone?.zone === 'worktree' && zone.tabName) {
-    // D86 R1：worktree → join-or-create 目录名 tab（原样 label，大小写不敏感撞名 join）
+    // Why: Preserve the established compatibility and safety behavior (D86, R1).
     const base = zone.tabName;
     const existing = [...known.keys()].find((k) => k.toLowerCase() === base.toLowerCase());
     if (existing) return { mode: 'append', tabName: existing, tabId: known.get(existing)! };
     const tabName = nextTaskTabName(base, new Set(known.keys()));
     return { mode: 'new', tabName, tabId: null };
   }
-  // 兜底（无 zone 信息）：由 description 派生名 + 撞名加序号后缀 → 永远 new。
+  // Why: Preserve the established compatibility and safety behavior.
   const base = tabNameForTask(opts.description);
   const tabName = nextTaskTabName(base, new Set(known.keys()));
   return { mode: 'new', tabName, tabId: null };
 }
 
-/* ── D97：worker 启动参数（纯逻辑，可单测） ───────────────────────── */
+/** Why: Preserve the established compatibility and safety behavior (D97). */
 
-/** launchLine 的运行时三要素（master 侧探测：node 解释器 / pi cli / 本扩展入口）。 */
+/** Why: Preserve the established compatibility and safety behavior. */
 export interface LaunchRuntime {
   nodePath: string;
   cliPath: string;
   extPath: string;
 }
 
-/**
- * worker 启动裸 argv。`--tui-mode fullscreen`（D97 静帧前提）：
- * alt-screen 行级差分——窄条静帧不变 → PTY 零输出，流式 thinking 不再整屏
- * dump 闪烁；regular 主屏改动在视口上方即全量重倒（pi tui-main-screen
- * firstChanged < viewportTop 路径），overlay 盖不住。
- * `PI_HERDR_TUI=regular` 回退旧行为（逃生口）。
- */
+/** Why: Preserve the established compatibility and safety behavior (D97). */
 export function buildLaunchParts(
   runtime: LaunchRuntime,
   opts: { resumeFile?: string | null; roleModel?: string | null; approve?: boolean } = {},
@@ -408,3 +378,90 @@ export function buildLaunchParts(
   if (opts.resumeFile) parts.push('--session', opts.resumeFile);
   return parts;
 }
+
+/** Why: Preserve the established compatibility and safety behavior (D98). */
+
+/** Why: Preserve the established compatibility and safety behavior. */
+export interface IsolatePlan {
+  branch: string;
+  slug: string;
+  worktreeDirName: string;
+}
+
+/** Why: Preserve the established compatibility and safety behavior. */
+export const ISOLATE_SLUG_MAX = 40;
+
+/** Why: Preserve the established compatibility and safety behavior (D98). */
+export function planIsolateWorktree(opts: {
+  description: string;
+  taskHex: string;
+  existingPierBranches: ReadonlySet<string>;
+}): IsolatePlan {
+  const folded = String(opts.description ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, ISOLATE_SLUG_MAX)
+    .replace(/-+$/g, '');
+  const slug = folded || `task-${opts.taskHex}`;
+  let name = slug;
+  let n = 2;
+  while (opts.existingPierBranches.has(name)) {
+    name = `${slug}-${n}`;
+    n++;
+  }
+  return { branch: `pier/${name}`, slug: name, worktreeDirName: `pier-${name}` };
+}
+
+/** Why: Preserve the established compatibility and safety behavior (D98). */
+export function buildIsolatePreamble(opts: { worktreePath: string; branch: string; baseShort: string }): string {
+  return [
+    `You are working in an isolated git worktree: ${opts.worktreePath} (branch ${opts.branch}, base ${opts.baseShort}).`,
+    'Every file you create or edit must stay inside this worktree.',
+    'Commit your work to your branch as you go (git add -A && git commit). NEVER push to any remote.',
+    'Do not touch the main checkout or other worktrees; if you find issues outside your task, report them in your final message instead of fixing them.',
+    'Before finishing: commit everything, then end with a short summary of what changed and why.',
+  ].join('\n');
+}
+
+/** Why: Preserve the established compatibility and safety behavior (D98). */
+export function formatWorktreeStat(opts: {
+  branch: string | null;
+  commits: number | null;
+  statLine: string | null;
+  dirtyCount: number | null;
+}): string | null {
+  if (opts.dirtyCount == null) return null;
+  if (opts.branch != null) {
+    if (opts.commits == null || !opts.statLine) return null;
+    const dirty = opts.dirtyCount > 0
+      ? `${opts.dirtyCount} file(s) (worker should have committed)`
+      : `${opts.dirtyCount} file(s)`;
+    return `Worktree ${opts.branch}: ${opts.commits} commit(s) since base; ${opts.statLine}; uncommitted: ${dirty}`;
+  }
+  if (!opts.statLine) return null;
+  return `git: ${opts.statLine}; uncommitted: ${opts.dirtyCount} file(s)`;
+}
+
+/** Why: Preserve the established compatibility and safety behavior (D98). */
+export type ReleaseDecision = { action: 'release' } | { action: 'retain'; reason: 'unmerged' | 'dirty' | 'unknown' };
+
+export function evaluateRelease(opts: { merged: boolean | null; dirtyCount: number | null }): ReleaseDecision {
+  if (opts.merged === null || opts.dirtyCount === null) return { action: 'retain', reason: 'unknown' };
+  if (!opts.merged) return { action: 'retain', reason: 'unmerged' };
+  if (opts.dirtyCount > 0) return { action: 'retain', reason: 'dirty' };
+  return { action: 'release' };
+}
+
+/** Why: Preserve the established compatibility and safety behavior (D98). */
+export function parseWorktreePorcelain(out: string): Map<string, string> {
+  const byBranch = new Map<string, string>();
+  let curPath: string | null = null;
+  for (const line of out.replace(/\r/g, '').split('\n')) {
+    const m = /^worktree (.+)$/.exec(line.trim());
+    if (m) { curPath = m[1]!; continue; }
+    const b = /^branch (.+)$/.exec(line.trim());
+    if (b && curPath) byBranch.set(b[1]!.replace(/^refs\/heads\//, ''), curPath);
+  }
+  return byBranch;
+}