piher 0.0.0-stage → 0.2.0

package/src/swallow.ts

@@ -0,0 +1,59 @@
+/**
+ * `swallow(tag, err)` keeps catch-site cleanup behaviour, but records the event in a bounded ring
+ * buffer, so `/piher-config` can show the recent ones and a bug report can quote them. Stays
+ * silent: cleanup paths must never add noise to the transcript.
+ */
+
+export interface SwallowedError {
+  /** Stable site label, e.g. 'role.persist-switch'. */
+  readonly tag: string;
+  readonly message: string;
+  /** Epoch ms. */
+  readonly at: number;
+}
+
+export const SWALLOW_BUFFER_MAX = 50;
+
+const buffer: SwallowedError[] = [];
+
+function describe(err: unknown): string {
+  if (err instanceof Error) {
+    const code = (err as { code?: unknown }).code;
+    return code !== undefined ? `${err.name}: ${err.message} (code ${String(code)})` : `${err.name}: ${err.message}`;
+  }
+  if (typeof err === 'string') return err;
+  try {
+    return JSON.stringify(err);
+  } catch {
+    return String(err);
+  }
+}
+
+/**
+ * Record a caught error that is being intentionally ignored; call sites keep their cleanup and stay
+ * `} catch (err) { swallow('tag', err); }`.
+ */
+export function swallow(tag: string, err: unknown): void {
+  const entry: SwallowedError = { tag, message: describe(err), at: Date.now() };
+  buffer.push(entry);
+  if (buffer.length > SWALLOW_BUFFER_MAX) buffer.splice(0, buffer.length - SWALLOW_BUFFER_MAX);
+}
+
+/** Recent swallowed errors, oldest first (diagnostics only; never persisted). */
+export function swallowedErrors(): readonly SwallowedError[] {
+  return [...buffer];
+}
+
+export function resetSwallowedErrors(): void {
+  buffer.length = 0;
+}
+
+/** Render for `/piher-config`; the section is never ambiguous even with no entries. */
+export function formatSwallowedErrors(entries: readonly SwallowedError[] = swallowedErrors()): string {
+  if (entries.length === 0) return 'swallowed errors: none this session';
+  const lines = entries.slice(-10).map((e) => {
+    const hhmmss = new Date(e.at).toISOString().slice(11, 19);
+    return `${hhmmss} ${e.tag}: ${e.message}`;
+  });
+  return [`swallowed errors: ${entries.length} this session (last 10)`, ...lines].join('\n');
+}

package/src/task-row.ts

@@ -0,0 +1,257 @@
+/**
+ * Task rows: the one row type behind delegation state (spec S1-S12, `docs/spec/domain.md`).
+ *
+ * A task is one delegation unit — a spawned subagent, never a tool call (S1). Every later
+ * action sends, closes, retries or resumes the same task; only the generation (pane, tab,
+ * transcript) is replaced on revive (S3). The durable facts are exactly the row below (S10);
+ * liveness is an observation from core and lives in memory only (S11).
+ */
+import { foldWorktree, type WorktreeRecord } from './worktree.ts';
+import type { Lifecycle } from './role-manifest.ts';
+
+/** One observation of a task's liveness, read from core when a surface needs it (S11). It feeds
+ *  only the state text a surface prints; an action never reads it to decide (S26). A stale
+ *  observation can mislabel a row — never revive, close or steer the wrong one. */
+export interface TaskObservation {
+  paneExists: boolean;
+  agentStatus: string | null;
+  lastActivityMs: number | null;
+  at: number;
+}
+
+/** The state text `list` and the widget print (contracts): the three predicates plus what core
+ *  last said. Without an observation the durable facts alone decide: a delivered report reads
+ *  `idle`, anything else `running` — the zero-observation base a fresh spawn shares. */
+export type TaskStateText = 'running' | 'idle' | 'no report' | 'no pane';
+
+export function describeTaskState(
+  row: Pick<TaskRow, 'gen'>,
+  obs?: Pick<TaskObservation, 'paneExists' | 'agentStatus'> | null,
+): TaskStateText {
+  if (obs) {
+    if (!obs.paneExists) return 'no pane';
+    if (obs.agentStatus === 'working' || obs.agentStatus === 'blocked') return 'running';
+  }
+  return row.gen.consumedAt !== null ? 'idle' : obs ? 'no report' : 'running';
+}
+
+/** One generation: the pane, tab and transcript a revive replaces wholesale (S3). Earlier
+ *  generations leave no durable trace. */
+export interface TaskGeneration {
+  paneId: string;
+  slug: string;
+  tabId: string;
+  tabName: string;
+  /** The worker's transcript: resume needs it to exist. */
+  sessionFile: string | null;
+  launchCommand: string[];
+  startedAt: number;
+  /** The report reached the master (S10). */
+  consumedAt: number | null;
+  reportDelivered: { fingerprint: string; at: number } | null;
+}
+
+export interface TaskRow {
+  /** Minted at spawn; the task's identity across revives (S1). */
+  taskId: string;
+  description: string;
+  /** Role profile the worker was launched with. */
+  kind: string;
+  lifecycle: 'one-shot' | 'persistent';
+  cwd: string;
+  /** The checkout the spawn created, if any. */
+  worktree?: WorktreeRecord;
+  createdAt: number;
+  /** The master's final word (S9). */
+  closedAt: number | null;
+  gen: TaskGeneration;
+}
+
+/** What id resolution answers: a resident memory row or a transient record copy, flagged when
+ *  the row belongs to another session (S17). Transient rows resolve for action, never adopted. */
+export type ResolvedTaskEntry = { entry: TaskEntry; foreign: boolean } | { error: string };
+
+/** A task resident in memory: the durable row plus transient control state. The transient
+ *  fields are stripped at the document seam (`toTaskRow`) and never reach disk. Liveness is
+ *  not among them: it is observed from core per surface, never stored (S11, S12). */
+export interface TaskEntry extends TaskRow {
+  /** Settle window start (poller state): settlement waits until the transcript settles. */
+  settleWindowStartedAt?: number | null;
+  /** The closing text already announced for this pane (fingerprint + time). Two pollers can
+   *  settle the same transcript — a recovery re-arm and a live request carry different ids —
+   *  and the claim is per request, so this is what stops the master from reading one
+   *  settlement twice. */
+  noticeAnnounced?: { fingerprint: string; at: number } | null;
+}
+
+/** The durable row alone: what a record file holds. */
+export function toTaskRow(entry: TaskEntry): TaskRow {
+  const { settleWindowStartedAt: _w, noticeAnnounced: _n, ...row } = entry;
+  void _w;
+  void _n;
+  const fingerprint = row.gen.reportDelivered ? { ...row.gen.reportDelivered } : null;
+  const delivered = fingerprint ? { reportDelivered: fingerprint } : {};
+  return {
+    ...row,
+    gen: { ...row.gen, ...delivered },
+    ...(row.worktree ? { worktree: { ...row.worktree } } : {}),
+  };
+}
+
+/* ── predicates (S12) ─────────────────────────────────────────── */
+
+export function isClosed(row: Pick<TaskRow, 'closedAt'>): boolean {
+  return row.closedAt !== null;
+}
+
+export function isSpent(row: Pick<TaskRow, 'lifecycle' | 'gen'>): boolean {
+  return row.lifecycle === 'one-shot' && row.gen.consumedAt !== null;
+}
+
+export function isActionable(row: Pick<TaskRow, 'closedAt' | 'lifecycle' | 'gen'>): boolean {
+  return !isClosed(row) && !isSpent(row);
+}
+
+/* ── tolerant parsing ─────────────────────────────────────────── */
+
+/** Legacy short/resident/missing kinds normalize to task; role names pass through. */
+export function normalizeEntryKind(kind: string | null | undefined): string {
+  if (!kind || kind === 'short' || kind === 'resident') return 'task';
+  return kind;
+}
+
+/** Only a .jsonl path is accepted, so an invalid report cannot overwrite a valid one. */
+export function applyReportedSessionFile(
+  current: string | null,
+  reported: string | null | undefined,
+): string | null {
+  if (typeof reported === 'string' && /\.jsonl$/i.test(reported)) return reported;
+  return current;
+}
+
+function asString(value: unknown, fallback = ''): string {
+  return typeof value === 'string' ? value : fallback;
+}
+
+function asTime(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+/** One row out of an unknown document. Unknown fields are kept off; a row without a taskId
+ *  is not a row. Never throws. */
+export function parseTaskRow(value: unknown): TaskRow | null {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return null;
+  const rec = value as Record<string, unknown>;
+  if (typeof rec.taskId !== 'string' || rec.taskId.trim() === '') return null;
+  const gen = (rec.gen !== null && typeof rec.gen === 'object' && !Array.isArray(rec.gen)
+    ? rec.gen as Record<string, unknown>
+    : {});
+  const delivered = gen.reportDelivered !== null && typeof gen.reportDelivered === 'object'
+    && !Array.isArray(gen.reportDelivered)
+    && typeof (gen.reportDelivered as Record<string, unknown>).fingerprint === 'string'
+    && typeof (gen.reportDelivered as Record<string, unknown>).at === 'number'
+    ? {
+      fingerprint: (gen.reportDelivered as Record<string, unknown>).fingerprint as string,
+      at: (gen.reportDelivered as Record<string, unknown>).at as number,
+    }
+    : null;
+  const worktree = foldWorktree(rec.worktree);
+  const lifecycle: Lifecycle = rec.lifecycle === 'one-shot' ? 'one-shot' : 'persistent';
+  return {
+    taskId: rec.taskId,
+    description: asString(rec.description),
+    kind: normalizeEntryKind(typeof rec.kind === 'string' ? rec.kind : undefined),
+    lifecycle,
+    cwd: asString(rec.cwd),
+    ...(worktree ? { worktree } : {}),
+    createdAt: asTime(rec.createdAt) ?? 0,
+    closedAt: asTime(rec.closedAt),
+    gen: {
+      paneId: asString(gen.paneId),
+      slug: asString(gen.slug),
+      tabId: asString(gen.tabId),
+      tabName: asString(gen.tabName),
+      sessionFile: typeof gen.sessionFile === 'string' ? gen.sessionFile : null,
+      launchCommand: Array.isArray(gen.launchCommand)
+        ? gen.launchCommand.filter((part): part is string => typeof part === 'string')
+        : [],
+      startedAt: asTime(gen.startedAt) ?? 0,
+      consumedAt: asTime(gen.consumedAt),
+      reportDelivered: delivered,
+    },
+  };
+}
+
+export interface TaskDocument {
+  rows: TaskRow[];
+  taskIds: string[];
+}
+
+/**
+ * The `{version:1, rows:[TaskRow]}` envelope both documents share, read tolerantly: a
+ * missing, torn or foreign document parses to empty lists and never raises (S6). The record
+ * file holds its row under `rows`, the session view its ids under `taskIds`.
+ */
+export function parseTaskDocument(value: unknown): TaskDocument {
+  const empty: TaskDocument = { rows: [], taskIds: [] };
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return empty;
+  const rec = value as Record<string, unknown>;
+  if (rec.version !== 1) return empty;
+  const rows = Array.isArray(rec.rows)
+    ? rec.rows.map(parseTaskRow).filter((row): row is TaskRow => row !== null)
+    : [];
+  const isId = (id: unknown): id is string => typeof id === 'string' && id.trim() !== '';
+  const taskIds = Array.isArray(rec.taskIds) ? [...new Set(rec.taskIds.filter(isId))] : [];
+  return { rows, taskIds };
+}
+
+/* ── task slugs ───────────────────────────────────────────────── */
+
+/** Slug cap: short enough for tool args and list rows, long enough to stay distinctive. */
+const SLUG_MAX = 24;
+
+/** Kebab-case a task description; non-ASCII (CJK descriptions) sanitizes to '' — the allocator
+ * then falls back to a taskId-derived ascii slug, because tool args must stay typeable. */
+export function slugifyTask(description: string): string {
+  return description
+    .toLowerCase()
+    .replace(/[''']/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, SLUG_MAX)
+    .replace(/-+$/g, '');
+}
+
+/** Allocate a unique slug among live rows: base, then base-2, base-3, …; a description that
+ * sanitizes to nothing (CJK, emoji-only) falls back to `task-<taskId prefix>`. */
+export function allocateTaskSlug(
+  description: string,
+  taskId: string,
+  taken: ReadonlySet<string>,
+): string {
+  const base = slugifyTask(description) || `task-${taskId.slice(0, 6)}`;
+  if (!taken.has(base)) return base;
+  for (let n = 2; ; n++) {
+    const next = `${base}-${n}`;
+    if (!taken.has(next)) return next;
+  }
+}
+
+/** Stable display/argument form for a task row: `slug@paneId` when a slug exists. */
+export function taskRef(task: { paneId: string; slug?: string }): string {
+  return task.slug ? `${task.slug}@${task.paneId}` : task.paneId;
+}
+
+/* ── memory index ─────────────────────────────────────────────── */
+
+/** Resolve a pane id to its task's entry through the pane→task index. A task outlives its
+ *  pane; the pane id is part of the generation, so lookups by pane go through the task. */
+export function taskForPane(
+  tasks: ReadonlyMap<string, TaskEntry>,
+  panes: ReadonlyMap<string, string>,
+  paneId: string,
+): TaskEntry | undefined {
+  const taskId = panes.get(paneId);
+  if (!taskId) return undefined;
+  return tasks.get(taskId);
+}

package/src/task-store.ts

@@ -0,0 +1,173 @@
+/**
+ * The task document store: one atomic writer and reader for both durable documents (S5, S6).
+ *
+ * - task record `<repo>/.piher/tasks/<taskId>.json` — `{version:1, rows:[TaskRow]}`, one row;
+ * - session view `<sessionDir>/piher/<sessionId>/tasks.json` — `{version:1, taskIds:[...]}`.
+ *
+ * Every write is a temporary file + rename, so a crash mid-write leaves the previous document
+ * intact (S6). A missing, torn or foreign document reads as "no record" and never raises (S6).
+ * Nothing durable is pruned by age or by count (S8).
+ */
+import {
+  copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import { sessionStatePath } from './session-state.ts';
+import { mainWorktreeRoot } from './storage-layout.ts';
+import { parseTaskDocument, toTaskRow, type TaskEntry, type TaskRow } from './task-row.ts';
+import { swallow } from './swallow.ts';
+
+export const TASKS_DIR_NAME = 'tasks';
+export const TASK_VIEW_NAME = 'tasks.json';
+
+/**
+ * The task directory of the repository containing `cwd`: one directory per repository inside
+ * the main checkout, so every worktree of a repository shares it. Outside a git repository
+ * there is no directory and no fallback. `.piher/tasks/` must be git-ignored (never the
+ * parent `.piher/`, whose `roles/` are meant to be committed).
+ */
+export function repoTasksDir(cwd: string): string | null {
+  const root = mainWorktreeRoot(cwd);
+  return root === null ? null : join(root, '.piher', TASKS_DIR_NAME);
+}
+
+export function taskRecordPath(dir: string, taskId: string): string {
+  return join(dir, `${taskId}.json`);
+}
+
+/** Replace the document atomically (tmp + rename): a crash mid-write must not leave half of one. */
+function writeDocument(file: string, doc: unknown): boolean {
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+    const tmp = `${file}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(doc)}\n`);
+    renameSync(tmp, file);
+    return true;
+  } catch (err) {
+    console.error(`[piher] task document write failed: ${file}: ${(err as Error).message}`);
+    return false;
+  }
+}
+
+/** One log line per checkout with no repository, so a long session outside git stays readable. */
+const noRepoLogged = new Set<string>();
+
+function logNoRepo(cwd: string): void {
+  // A checkout the spawn itself removed is not a misconfiguration: the rows it wrote while it
+  // existed are its history, and a line about a path that no longer exists only reads as an error.
+  if (!existsSync(cwd)) return;
+  if (noRepoLogged.has(cwd)) return;
+  noRepoLogged.add(cwd);
+  console.error(
+    `[piher] no delegation ledger: ${cwd} is not inside a git repository, ` +
+      'so delegation history is not recorded and resume needs one',
+  );
+}
+
+/**
+ * Write one task record: the task, its current generation and its decision. Best-effort —
+ * bookkeeping must never break delegation. Only the durable row is written; the transient
+ * memory state stays out of the document (S11, S12).
+ */
+export function writeTaskRecord(cwd: string, entry: TaskEntry): boolean {
+  const dir = repoTasksDir(cwd);
+  if (dir === null) {
+    logNoRepo(cwd);
+    return false;
+  }
+  const row: TaskRow = toTaskRow(entry);
+  return writeDocument(taskRecordPath(dir, row.taskId), { version: 1, rows: [row] });
+}
+
+/**
+ * Delete one task record (S8: besides `close`, deleting its record file is the only way a task
+ * leaves use). What never started leaves nothing behind; anything else goes through `close`.
+ */
+export function deleteTaskRecord(cwd: string, taskId: string): void {
+  const dir = repoTasksDir(cwd);
+  if (dir === null || taskId.trim() === '') return;
+  try {
+    rmSync(taskRecordPath(dir, taskId), { force: true });
+  } catch (err) {
+    swallow('task-store.delete-record', err);
+  }
+}
+
+/** Read one task record by id. A missing, torn or foreign document is "no record", never raised. */
+export function readTaskRecord(cwd: string, taskId: string): TaskRow | null {
+  const dir = repoTasksDir(cwd);
+  if (dir === null || taskId.trim() === '') return null;
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(taskRecordPath(dir, taskId), 'utf8'));
+    const row = parseTaskDocument(parsed).rows[0] ?? null;
+    // The file name is the address: a row for another task inside is a foreign document.
+    if (!row || row.taskId !== taskId) return null;
+    return row;
+  } catch (err) {
+    swallow('task-store.read-record', err);
+    return null;
+  }
+}
+
+/** Every readable record of the repository containing `cwd`: the candidate set `resume`
+ *  resolves against. Unreadable files are skipped, not fatal. */
+export function listTaskRecords(cwd: string): TaskRow[] {
+  const dir = repoTasksDir(cwd);
+  if (dir === null) return [];
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch (err) {
+    swallow('task-store.list-records', err);
+    return [];
+  }
+  const rows: TaskRow[] = [];
+  for (const name of names) {
+    if (!name.endsWith('.json')) continue;
+    const row = readTaskRecord(cwd, name.slice(0, -'.json'.length));
+    if (row) rows.push(row);
+  }
+  return rows;
+}
+
+/**
+ * The session's view: the ordered task ids it delegated. Null when the session has nowhere to
+ * sit (no transcript path — the view then stays in memory only, S25) or when the document is
+ * missing, torn or foreign.
+ */
+export function readTaskView(sessionFile: string | null | undefined): string[] | null {
+  const file = sessionStatePath(sessionFile ?? null, TASK_VIEW_NAME);
+  if (!file) return null;
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(file, 'utf8'));
+    return parseTaskDocument(parsed).taskIds;
+  } catch (err) {
+    swallow('task-store.read-view', err);
+    return null;
+  }
+}
+
+/** Replace the session view. A session with no transcript path keeps it in memory only (S25). */
+export function writeTaskView(
+  sessionFile: string | null | undefined,
+  taskIds: readonly string[],
+): boolean {
+  const file = sessionStatePath(sessionFile ?? null, TASK_VIEW_NAME);
+  if (!file) return false;
+  return writeDocument(file, { version: 1, taskIds: [...taskIds] });
+}
+
+/** A fork gets the view it branched from: the parent's document is copied once, before the
+ *  restore reads it. Records are shared, not copied: the fork continues the same tasks. */
+export function seedTaskView(to: string | null, from: string | null): boolean {
+  if (!to || !from || to === from) return false;
+  try {
+    if (existsSync(to) || !existsSync(from)) return false;
+    mkdirSync(dirname(to), { recursive: true });
+    copyFileSync(from, to);
+    return true;
+  } catch (err) {
+    swallow('task-store.seed-view', err);
+    return false;
+  }
+}

package/src/tool-error.ts

@@ -0,0 +1,19 @@
+/**
+ * pi only marks a tool result as failed when `execute()` throws; returning a value never sets the
+ * error flag (pi docs/extensions.md, "Signaling errors"). Every hard failure goes through
+ * `toolError()`, while deliberate non-failures (empty result set, "no match within Xms", a pane that
+ * has not produced output yet) stay normal results.
+ *
+ * The leading "Error: " text is stripped: the provider's tool-result error channel and pi's red
+ * rendering already mark it, and keeping it would double the prefix once pi formats a thrown error.
+ */
+export class ToolError extends Error {
+  constructor(message: string) {
+    super(String(message).replace(/^Error:\s*/, ''));
+    this.name = 'ToolError';
+  }
+}
+
+export function toolError(message: string): never {
+  throw new ToolError(message);
+}

package/src/tool-gate.ts

@@ -0,0 +1,99 @@
+/**
+ * Worker execution enforcement (C7, D76/D77/D82) — pure. RuntimeRoleManifest is THE runtime manifest
+ * shape; the file format lives in role-manifest.ts and the composed/persisted shapes derive from it
+ * (manifest-compose.ts, role-state.ts).
+ */
+import type { PermissionAction, UnknownToolStance } from './role-manifest.ts';
+
+export interface RuntimeRoleManifest {
+  role: string;
+  version?: string;
+  tools: string[];
+  permissions: Record<string, PermissionAction>;
+  /** Stance for tools outside `tools`; 'allow' keeps user-installed extensions visible (D82). */
+  unknownTools?: UnknownToolStance;
+  /** P0 per-role guidelines (RFC §4.6): injected as a `piher-role` prompt section each turn. */
+  guidelines?: string[];
+  /** Prose injected after the guidelines, in the same `piher-role` section. */
+  instructions?: string;
+}
+
+/** Parse the env-carried manifest; malformed input is null (fail-open: no gate) rather than a crash. */
+export function parseRuntimeManifest(envValue: string | undefined): RuntimeRoleManifest | null {
+  if (!envValue) return null;
+  try {
+    const m = JSON.parse(envValue) as RuntimeRoleManifest;
+    if (!m || typeof m.role !== 'string' || !Array.isArray(m.tools)) return null;
+    if (m.unknownTools !== undefined && m.unknownTools !== 'allow' && m.unknownTools !== 'deny') {
+      m.unknownTools = 'deny';
+    }
+    if (m.guidelines !== undefined) {
+      m.guidelines = Array.isArray(m.guidelines)
+        ? m.guidelines.filter((g) => typeof g === 'string' && g.trim() !== '')
+        : undefined;
+    }
+    if (m.instructions !== undefined && (typeof m.instructions !== 'string' || m.instructions.trim() === '')) {
+      m.instructions = undefined;
+    }
+    return m;
+  } catch {
+    return null;
+  }
+}
+
+export type ToolGatePlan =
+  | { kind: 'open' }
+  | { kind: 'allow' }
+  | { kind: 'deny'; reason: string };
+
+export function planToolGate(toolName: string, manifest: RuntimeRoleManifest | null): ToolGatePlan {
+  if (!manifest) return { kind: 'open' };
+  const ruleKey = manifest.permissions[toolName] !== undefined ? toolName : '*';
+  const perm = manifest.permissions[ruleKey] ?? 'allow';
+  const known = manifest.tools.includes(toolName);
+  const stance = manifest.unknownTools ?? 'deny';
+  if (perm === 'deny' || (!known && stance === 'deny')) {
+    return {
+      kind: 'deny',
+      reason:
+        `role "${manifest.role}" does not permit tool "${toolName}" ` +
+        `(manifest tools: ${manifest.tools.join(', ')}). ` +
+        `If the task needs it, ask the master to delegate differently or adjust the role profile.`,
+    };
+  }
+  return { kind: 'allow' };
+}
+
+/**
+ * 'allow' keeps every tool but the explicit deny rules (D82 user-installed-extension axis); 'deny'
+ * intersects with the manifest. Shared by planActiveTools (visibility) and role-state's switch
+ * planning (all-tools universe).
+ */
+export function filterToolsByStance(
+  manifestTools: readonly string[],
+  universe: readonly string[],
+  opts?: { unknownTools?: UnknownToolStance; permissions?: Record<string, PermissionAction> },
+): string[] {
+  if ((opts?.unknownTools ?? 'deny') === 'allow') {
+    const denied = new Set(
+      Object.entries(opts?.permissions ?? {})
+        .filter(([, action]) => action === 'deny')
+        .map(([name]) => name),
+    );
+    return universe.filter((name) => !denied.has(name));
+  }
+  const wanted = new Set(manifestTools);
+  return universe.filter((name) => wanted.has(name));
+}
+
+/** Null means "keep the current active set": an empty result must never clear every tool (D77). */
+export function planActiveTools(
+  manifestTools: readonly string[],
+  currentActive: readonly string[],
+  opts?: { unknownTools?: UnknownToolStance; permissions?: Record<string, PermissionAction> },
+): { next: string[]; changed: boolean } | null {
+  if (manifestTools.length === 0 || currentActive.length === 0) return null;
+  const next = filterToolsByStance(manifestTools, currentActive, opts);
+  if (next.length === 0) return null;
+  return { next, changed: next.length !== currentActive.length };
+}

package/src/tree-view.ts

@@ -0,0 +1,58 @@
+/**
+ * The resident widget: one line per running subagent. Pure builders only.
+ */
+
+/** One running worker row as the widget consumes it. */
+export interface WorkerWidgetRow {
+  paneId: string;
+  slug?: string;
+  /** Role name the worker was launched with; `task` when it was spawned without one. */
+  role?: string;
+  /** Observed state text. The widget is handed workers still awaiting a report only. */
+  state?: string;
+  /** Spawn time, for the elapsed field on a widget row. */
+  startedAt?: number;
+  /** Pane label for `list` and the settle notice. A widget row never shows it. */
+  description?: string;
+}
+
+/** `<60s → Ns`; `<60m → Nm`; `<48h → Nh` (floor); otherwise `Nd`. */
+function formatAge(ms: number): string {
+  const seconds = Math.max(0, Math.floor(ms / 1_000));
+  if (seconds < 60) return `${seconds}s`;
+  if (seconds < 3_600) return `${Math.floor(seconds / 60)}m`;
+  if (seconds < 172_800) return `${Math.floor(seconds / 3_600)}h`;
+  return `${Math.floor(seconds / 86_400)}d`;
+}
+
+/**
+ * One widget row: `↳ <slug> (<paneId>) · <role> · <state> · <elapsed>`. The pane id rides beside the
+ * name because it is the address the app and `send`/`output` take; a row without a slug is the pane
+ * id alone, since `↳ p9 (p9)` would spend the width on a duplicate. A label or a description is still
+ * not a field — those would cost the line the fold budget pays for.
+ */
+export function workerLine(row: WorkerWidgetRow, now = Date.now()): string {
+  const elapsed = row.startedAt != null ? formatAge(Math.max(now - row.startedAt, 0)) : undefined;
+  const handle = row.slug ? `${row.slug} (${row.paneId})` : row.paneId;
+  const fields = [handle, row.role, row.state, elapsed]
+    .filter((field): field is string => typeof field === 'string' && field.length > 0);
+  return `↳ ${fields.join(' · ')}`;
+}
+
+/**
+ * The whole widget budget, fold tail included: pi wraps a string-array widget in
+ * `content.slice(0, 10)` and appends its own `... (widget truncated)` line when given more, so a
+ * tenth row plus a tail would cost the tail — the one line that says where the rest went.
+ */
+export const WIDGET_MAX_LINES = 10;
+
+/** One widget line per running worker; overflow folds into a tail that still fits the budget. */
+export function widgetLines(workers: readonly WorkerWidgetRow[], now = Date.now()): string[] {
+  if (workers.length === 0) return [];
+  const rows = workers.map((worker) => workerLine(worker, now));
+  // Reserve the tail line before slicing, so the rendered widget never exceeds the budget.
+  const overflow = rows.length > WIDGET_MAX_LINES;
+  const shown = rows.slice(0, overflow ? WIDGET_MAX_LINES - 1 : WIDGET_MAX_LINES);
+  const hidden = rows.length - shown.length;
+  return [...shown, ...(hidden > 0 ? [`…+${hidden} more subagents · subagent list`] : [])];
+}