@yaag/runtime 0.1.0

package/src/tool-probe.ts

@@ -0,0 +1,141 @@
+import { fileURLToPath } from "node:url";
+
+import type { Frame } from "./transport.ts";
+
+/** The private status key used only by yaag's internal pi tool probe extension. */
+export const TOOL_PROBE_STATUS_KEY = "yaag.tool-probe.v1";
+/** Filesystem sibling path of the probe extension; decodes percent-escapes (e.g. spaces). */
+export function toolProbeExtensionPath(moduleUrl: string): string {
+  return fileURLToPath(new URL("./tool-probe-extension.ts", moduleUrl));
+}
+
+/** Loadable source path for the private extension that reports pi's active tools. */
+export const TOOL_PROBE_EXTENSION_PATH = toolProbeExtensionPath(import.meta.url);
+
+const TOOL_PROBE_TIMEOUT_MS = 30_000;
+
+/** Startup collector for the private extension's effective-tool report. */
+export interface ToolProbe {
+  /** True when the frame belongs to the probe and must not cross the transport seam. */
+  accept(frame: Frame): boolean;
+  /** Resolves with active tool names or rejects on malformed output or timeout. */
+  wait(): Promise<readonly string[]>;
+  /** Rejects startup when the spawned pi process ends before reporting. */
+  fail(error: Error): void;
+}
+
+/**
+ * Returns promised tools that survive pi's final denylist composition.
+ *
+ * Null means no tool allowlist promised anything and therefore needs no probe.
+ */
+export function requestedToolNames(
+  tools: readonly string[] | undefined,
+  disallowedTools: readonly string[] | undefined = undefined,
+): readonly string[] | null {
+  if (tools === undefined || tools.length === 0) return null;
+  const denied = new Set(disallowedTools);
+  const names: string[] = [];
+  const seen = new Set<string>();
+  for (const tool of tools) {
+    if (denied.has(tool) || seen.has(tool)) continue;
+    seen.add(tool);
+    names.push(tool);
+  }
+  return names;
+}
+
+/** Creates a startup collector only when a non-empty allowlist promised tool selection. */
+export function createToolProbe(
+  tools: readonly string[] | undefined,
+  _disallowedTools: readonly string[] | undefined = undefined,
+  timeoutMs = TOOL_PROBE_TIMEOUT_MS,
+): ToolProbe | null {
+  if (tools === undefined || tools.length === 0) return null;
+  let resolveResult: (names: readonly string[]) => void = () => {};
+  let rejectResult: (error: Error) => void = () => {};
+  let settled = false;
+  const result = new Promise<readonly string[]>((resolve, reject) => {
+    resolveResult = resolve;
+    rejectResult = reject;
+  });
+  // Startup can fail its get_state round trip before it reaches wait().
+  void result.catch(() => {});
+  const settle = (names: readonly string[]): void => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(timer);
+    resolveResult(names);
+  };
+  const fail = (error: Error): void => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(timer);
+    rejectResult(error);
+  };
+  const timer = setTimeout(() => {
+    fail(new Error("tool verification extension did not report active tools during startup"));
+  }, timeoutMs);
+  return {
+    accept(frame: Frame): boolean {
+      if (!isToolProbeFrame(frame)) return false;
+      try {
+        settle(parseToolProbeFrame(frame));
+      } catch (error) {
+        fail(error instanceof Error ? error : new Error("malformed tool probe report"));
+      }
+      return true;
+    },
+    wait(): Promise<readonly string[]> {
+      return result;
+    },
+    fail,
+  };
+}
+
+/** True exactly for a status frame emitted by the private probe extension. */
+export function isToolProbeFrame(frame: Frame): boolean {
+  return (
+    frame.type === "extension_ui_request" &&
+    frame.method === "setStatus" &&
+    frame.statusKey === TOOL_PROBE_STATUS_KEY
+  );
+}
+
+/** Parses the private status payload, rejecting every malformed boundary. */
+export function parseToolProbeFrame(frame: Frame): readonly string[] {
+  if (!isToolProbeFrame(frame) || typeof frame.statusText !== "string") {
+    throw new Error("malformed tool probe report");
+  }
+  let payload: unknown;
+  try {
+    payload = JSON.parse(frame.statusText);
+  } catch {
+    throw new Error("malformed tool probe report");
+  }
+  if (!Array.isArray(payload) || payload.some((name) => typeof name !== "string" || name === "")) {
+    throw new Error("malformed tool probe report");
+  }
+  const names: string[] = [];
+  const seen = new Set<string>();
+  for (const name of payload) {
+    if (typeof name !== "string" || seen.has(name)) continue;
+    seen.add(name);
+    names.push(name);
+  }
+  return names;
+}
+
+/** Throws a diagnostic naming every missing requested tool. */
+export function verifyEffectiveTools(
+  promised: readonly string[],
+  effective: readonly string[],
+): void {
+  const active = new Set(effective);
+  const missing = promised.filter((name) => !active.has(name));
+  if (missing.length === 0) return;
+  const listed = missing.map((name) => JSON.stringify(name)).join(", ");
+  throw new Error(
+    `agent is missing requested tool(s): ${listed}; declare the extension(s) providing these tools via spawn.extensions`,
+  );
+}

package/src/transport.ts

@@ -0,0 +1,178 @@
+import type { CanonicalJsonObject } from "./ask-contract-identity.ts";
+import type { AskLimitOutcome, AskStalledOutcome } from "./errors.ts";
+import type { AskOptions, SpawnOptions, ThinkingLevel } from "./types.ts";
+
+/**
+ * The one seam of the runtime (ticket 04). An AgentTransport represents a whole
+ * Agent and exchanges raw JSONL frames; it is the only place a process is known.
+ *
+ * Ask resolution and Lifecycle Events sit ABOVE this interface, so a replay
+ * implementation added later (ADR-0013) exercises the frame interpretation
+ * rather than bypassing it.
+ */
+
+/** One JSONL frame in either direction. Unknown `type`s must survive (ticket 01). */
+export type Frame = { readonly type: string; readonly [k: string]: unknown };
+
+/** pi's full token usage for one Agent, as reported by `get_session_stats`. */
+export interface TokenBreakdown {
+  readonly input: number;
+  readonly output: number;
+  readonly cacheRead: number;
+  readonly cacheWrite: number;
+  readonly total: number;
+}
+
+/** Cost and usage read at Agent shutdown (ADR-0012). */
+export interface AgentStats {
+  /** Null when unavailable — e.g. killed before the first Ask completed. */
+  readonly tokens: TokenBreakdown | null;
+  readonly cost: number | null;
+}
+
+/** Recorded inputs used to explain an Ask-hash mismatch without changing identity. */
+export interface AskMarkerContext {
+  readonly prompt: string;
+  readonly spawn: Pick<
+    SpawnOptions,
+    | "cwd"
+    | "model"
+    | "systemPrompt"
+    | "thinking"
+    | "appendSystemPrompt"
+    | "tools"
+    | "disallowedTools"
+    | "skills"
+    | "disallowedSkills"
+    | "worktree"
+  >;
+  readonly ask: Pick<
+    AskOptions,
+    "maxTurns" | "maxToolCalls" | "maxDurationMs" | "idleMs" | "wrapUpPrompt"
+  > & {
+    readonly outputSchema?: CanonicalJsonObject;
+    readonly maxSteers?: number;
+    readonly extractionPolicy?: string;
+  };
+}
+
+/** Opaque marker naming the Ask that subsequent frames belong to. */
+export interface AskMarker {
+  /** Monotonic per Agent, from 0. */
+  readonly index: number;
+  /** sha256 of prompt, spawn options, soft Ask behavior, and an optional output contract. */
+  readonly hash: string;
+  /** Canonical structured-output contract, present only for schema-bearing Asks. */
+  readonly outputSchema?: CanonicalJsonObject;
+  /** Explicit structured-output correction bound; omission remains distinct from a default. */
+  readonly maxSteers?: number;
+  /** Structured-output extraction behavior identifier. */
+  readonly extractionPolicy?: string;
+  /** Definition identity for Cassette diagnostics; never participates in the hash. */
+  readonly definitionName?: string;
+  /** Hash inputs retained only for definition-spawned Ask divergence diagnostics. */
+  readonly context?: AskMarkerContext;
+}
+
+/** Compact Cassette result for a surfaced structured-output exhaustion. */
+export interface AskInvalidOutputPlayback {
+  readonly kind: "invalid_output";
+  readonly steeringEfforts: number;
+}
+
+/** Presence identifies Cassette playback, including recorded successful Asks. */
+export interface AskPlayback {
+  /** Limit outcome recorded for this Ask, if it rejected with ASK_LIMIT. */
+  readonly limit?: AskLimitOutcome;
+  /** Stalled outcome recorded for this Ask, if it rejected with ASK_STALLED. */
+  readonly stalled?: AskStalledOutcome;
+  /** Invalid structured-output result recorded for this Ask, if it surfaced. */
+  readonly outcome?: AskInvalidOutputPlayback;
+  /** Whether recorded correction history has an abort settlement after final text. */
+  readonly awaitsAbortSettlement?: true;
+}
+
+/** One Agent, as the layer above sees it. */
+export interface AgentTransport {
+  /** Resolved model id from the startup `get_state` round-trip (ticket 03). */
+  readonly model: string;
+
+  /** Write one frame. Safe immediately after open: pi buffers stdin (ticket 01). */
+  send(frame: Frame): void;
+
+  /** Every frame from the Agent, in arrival order. Ends when the Agent is gone. */
+  frames(): AsyncIterable<Frame>;
+
+  /**
+   * Begins one Ask. Live transports return undefined; replay transports return
+   * playback metadata even when the recorded Ask succeeded.
+   */
+  beginAsk(marker: AskMarker): AskPlayback | undefined;
+
+  /** Reports surfaced live outcomes; replay ignores completion. */
+  finishAsk(
+    outcome?: AskLimitOutcome,
+    stalled?: AskStalledOutcome,
+    invalidOutput?: AskInvalidOutputPlayback,
+  ): void;
+
+  /**
+   * Shut the Agent down and report its cost. Idempotent.
+   * Owns the whole reap contract, so nothing above this interface knows what a
+   * signal is (ticket 02).
+   */
+  close(): Promise<AgentStats>;
+}
+
+/** Everything needed to open one Agent. */
+export interface OpenOptions {
+  /** Base cwd when requesting a worktree; resolved cwd after the wrapper opens it. */
+  readonly cwd: string;
+  readonly name: string;
+  /** Deterministic request for an isolated worktree; stripped before inner open. */
+  readonly worktree?: true;
+  readonly model?: string;
+  readonly systemPrompt?: string;
+  /** Process-start discovery policy; true restores pi's normal discovery, omission or false is hermetic. */
+  readonly inherit?: boolean;
+  /** Deterministic process-start thinking level; omission preserves pi's default. */
+  readonly thinking?: ThinkingLevel;
+  /** Deterministic process-start text appended to pi's system prompt. */
+  readonly appendSystemPrompt?: string;
+  /** Tool allowlist; an empty list disables all tools. */
+  readonly tools?: readonly string[];
+  /** Tool denylist, applied by pi after the allowlist. */
+  readonly disallowedTools?: readonly string[];
+  /** Skill allowlist by discovered name; identity only, never emitted as argv paths. */
+  readonly skills?: readonly string[];
+  /** Skill denylist by discovered name; identity only, never emitted as argv paths. */
+  readonly disallowedSkills?: readonly string[];
+  /** Resolved SKILL.md paths, injected only by the live restriction wrapper. */
+  readonly resolvedSkillPaths?: readonly string[];
+  /** Absolute launch-ready extension paths resolved above the seam, emitted as repeated `-e` flags. */
+  readonly resolvedExtensionPaths?: readonly string[];
+  /** Session storage directory. Used by the e2e suite to stay out of ~/.pi (ticket 06). */
+  readonly sessionDir?: string;
+  /** Resumes an existing pi session, translated to `--session <path>`. */
+  readonly sessionFile?: string;
+}
+
+/** Nondeterministic worktree identity resolved below the transport seam. */
+export interface WorktreeResolution {
+  readonly cwd: string;
+  readonly branch: string;
+}
+
+/** Startup facts a factory may report without widening AgentTransport. */
+export interface TransportStartup {
+  readonly sessionFile?: string;
+  readonly worktree?: WorktreeResolution;
+}
+
+/** Receives startup facts after a successful factory open. */
+export type TransportStartupObserver = (startup: TransportStartup) => void;
+
+/** How the layer above obtains transports. Swapped wholesale for replay. */
+export interface TransportFactory {
+  open(options: OpenOptions, observeStartup?: TransportStartupObserver): Promise<AgentTransport>;
+}

package/src/types.ts

@@ -0,0 +1,130 @@
+import type { Static, TSchema } from "typebox";
+
+/** pi's supported thinking levels. */
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+
+/** Options for spawning one Agent (ADR-0001, ADR-0009, ADR-0026). */
+export interface SpawnOptions {
+  /** Working directory. Defaults to the Orchestrator's cwd. */
+  readonly cwd?: string;
+  /** Model pattern, e.g. "anthropic/claude-haiku-4". Unset inherits the user's default. */
+  readonly model?: string;
+  /** Replaces the default system prompt (`pi --system-prompt`). */
+  readonly systemPrompt?: string;
+  /** Sets pi's thinking level; omission preserves pi's default. */
+  readonly thinking?: ThinkingLevel;
+  /** Appends text to pi's system prompt (`pi --append-system-prompt`). */
+  readonly appendSystemPrompt?: string;
+  /**
+   * Restores pi discovery. Omission or false selects ADR-0026's hermetic baseline.
+   */
+  readonly inherit?: boolean;
+  /**
+   * Explicit pi extensions layer over either ADR-0026 baseline. Relative entries
+   * resolve from the Orchestration Program file; each becomes `pi -e <path>`.
+   */
+  readonly extensions?: readonly string[];
+  /**
+   * Tool allowlist layered over the ADR-0026 baseline; omission is tool-free when hermetic.
+   * `disallowedTools` applies last. A non-empty surviving allowlist is verified after startup;
+   * a missing promised name rejects spawn.
+   */
+  readonly tools?: readonly string[];
+  /**
+   * Tool denylist applied last under ADR-0026; `['yaag_run']` prevents nested yaag Runs.
+   * Denying an absent tool is inert and is not presence-validated.
+   */
+  readonly disallowedTools?: readonly string[];
+  /**
+   * Skill-name allowlist, not filesystem paths, layered over the ADR-0026 baseline.
+   * Omission is skill-free when hermetic; `disallowedSkills` applies last. Unknown requested
+   * names reject spawn.
+   */
+  readonly skills?: readonly string[];
+  /** Skill-name denylist discovered from pi and applied last (ADR-0026). */
+  readonly disallowedSkills?: readonly string[];
+  /** Log and event label. Defaults to a1, a2, …; duplicate names are suffixed. */
+  readonly name?: string;
+  /** Request a fresh Git worktree. The requested cwd remains the base until spawn resolves. */
+  readonly worktree?: boolean;
+}
+
+/** Topology-only fields that may change when spawning an Agent Definition. */
+export interface SpawnOverrides {
+  /** Log and event label. Defaults to the definition's name; duplicates are suffixed. */
+  readonly name?: string;
+  /** Working directory. Defaults to the Orchestrator's cwd. */
+  readonly cwd?: string;
+  /** Request a fresh Git worktree. */
+  readonly worktree?: boolean;
+}
+
+/**
+ * Options for one Ask (ADR-0003).
+ *
+ * Soft limits trip at their configured count: turns are `turn_start` frames and
+ * tool calls are `tool_execution_start` frames between `agent_start` and
+ * `agent_settled`; duration is wall time from prompt send. A trip steers the
+ * Agent, permits one further turn (or a fixed duration grace), then aborts and
+ * rejects with `ASK_LIMIT` if it has not settled. This leaves the Handle alive.
+ * `timeoutMs` is independent: it kills the Agent and rejects with `ASK_TIMEOUT`.
+ */
+export interface AskOptions {
+  /** Reject and kill the Agent if it has not settled in time. Unset = no bound. */
+  readonly timeoutMs?: number;
+  /** Soft budget of `turn_start` frames between `agent_start` and `agent_settled`. */
+  readonly maxTurns?: number;
+  /** Soft budget of `tool_execution_start` frames between `agent_start` and `agent_settled`. */
+  readonly maxToolCalls?: number;
+  /** Soft wall-clock budget in milliseconds, measured from prompt send. */
+  readonly maxDurationMs?: number;
+  /**
+   * Maximum silence in milliseconds: rejects with `ASK_STALLED` when no frame
+   * arrives for this span. Complementary to `maxDurationMs` (silence vs.
+   * trickle) and separate from `timeoutMs`, which always kills. Unset disables
+   * idle detection (ADR-0020).
+   */
+  readonly idleMs?: number;
+  /** Per-Ask replacement for the runtime's wrap-up steering message. */
+  readonly wrapUpPrompt?: string;
+}
+
+/** Ask options that require a schema and preserve its inferred successful result. */
+export interface StructuredAskOptions<Schema extends TSchema> extends AskOptions {
+  /** TypeBox schema that changes successful Ask resolution from text to a parsed value. */
+  readonly outputSchema: Schema;
+  /** Maximum corrective steering efforts for this Ask; defaults to 3 when omitted. */
+  readonly maxSteers?: number;
+}
+
+/**
+ * A handle to one long-lived Agent.
+ * ADR-0003: `ask()` is the only conversational verb; everything else is data.
+ */
+export interface Handle {
+  /** Stable identity, used in every Lifecycle Event and log line. */
+  readonly name: string;
+  /** Resolved absolute working directory; a worktree's actual cwd after spawn resolves. */
+  readonly cwd: string;
+  /** Fresh branch for a worktree Agent; undefined for ordinary Agents. */
+  readonly branch: string | undefined;
+  /** Model id as reported by the Agent's own `get_state` — not the requested pattern. */
+  readonly model: string;
+
+  /**
+   * Sends a prompt and resolves after the Agent's turn settles.
+   *
+   * Schema-free calls resolve with the exact final assistant text. Calls with
+   * `outputSchema` resolve with the extracted, TypeBox-validated value. Rejects
+   * with a YaagError for a failed or empty turn, timeout, `ASK_LIMIT`, or dead
+   * Agent; invalid structured output rejects recoverably with
+   * `ASK_INVALID_OUTPUT` after at most `maxSteers` (default 3) in-Ask
+   * correction efforts and an abort settlement. These recoverable outcomes
+   * leave the Handle reusable. A concurrent call rejects with `AGENT_BUSY`.
+   */
+  ask<Schema extends TSchema>(
+    prompt: string,
+    options: StructuredAskOptions<Schema>,
+  ): Promise<Static<Schema>>;
+  ask(prompt: string, options?: AskOptions): Promise<string>;
+}

package/src/validation-errors.ts

@@ -0,0 +1,70 @@
+import type { TLocalizedValidationError } from "typebox/error";
+
+/** Formats TypeBox errors with stable JSON-path prefixes for public diagnostics. */
+export function formatValidationErrors(
+  value: unknown,
+  errors: Iterable<TLocalizedValidationError>,
+): readonly string[] {
+  return Array.from(errors).flatMap((error) => formatError(value, error));
+}
+
+function formatError(value: unknown, error: TLocalizedValidationError): readonly string[] {
+  if (error.keyword === "required") {
+    return error.params.requiredProperties.map(
+      (property) => `${toJsonPath(value, error.instancePath, property)}: ${error.message}`,
+    );
+  }
+  return [`${toJsonPath(value, error.instancePath)}: ${error.message}`];
+}
+
+function toJsonPath(value: unknown, instancePath: string, property?: string): string {
+  const segments = reconstructSegments(value, instancePath);
+  if (property !== undefined) segments.push(property);
+  return segments.reduce((path, segment) => `${path}${formatSegment(segment)}`, "$");
+}
+
+function reconstructSegments(value: unknown, instancePath: string): string[] {
+  if (instancePath === "") return [];
+  const segments: string[] = [];
+  let current = value;
+  let remaining: string | null = instancePath.slice(1);
+
+  while (remaining !== null) {
+    if (Array.isArray(current)) {
+      const [component, suffix] = splitComponent(remaining);
+      if (!isArrayIndex(component)) break;
+      segments.push(component);
+      current = current[Number(component)];
+      remaining = suffix;
+      continue;
+    }
+
+    const key = findRawPropertyKey(current, remaining);
+    if (key === undefined) break;
+    segments.push(key);
+    current = Object.getOwnPropertyDescriptor(current, key)?.value;
+    remaining = remaining === key ? null : remaining.slice(key.length + 1);
+  }
+
+  return remaining === null ? segments : [...segments, ...remaining.split("/")];
+}
+
+function findRawPropertyKey(value: unknown, remaining: string): string | undefined {
+  if (typeof value !== "object" || value === null) return undefined;
+  return Object.getOwnPropertyNames(value)
+    .filter((key) => remaining === key || remaining.startsWith(`${key}/`))
+    .sort((left, right) => right.length - left.length)[0];
+}
+
+function splitComponent(path: string): readonly [string, string | null] {
+  const separator = path.indexOf("/");
+  return separator === -1 ? [path, null] : [path.slice(0, separator), path.slice(separator + 1)];
+}
+
+function isArrayIndex(value: string): boolean {
+  return /^(0|[1-9]\d*)$/.test(value);
+}
+
+function formatSegment(segment: string): string {
+  return /^[A-Za-z_$][\w$]*$/.test(segment) ? `.${segment}` : `[${JSON.stringify(segment)}]`;
+}

package/src/wire-constants.ts

@@ -0,0 +1,24 @@
+/**
+ * Cap on `ask_start.promptGist` characters (ticket 09). Shared so producers
+ * and observers agree on how much prompt ever rides the wire — the full
+ * prompt never does; `promptChars` carries its true length.
+ */
+export const PROMPT_GIST_MAX_CHARS = 160;
+
+/** Cap on the one-line argument gist carried by `ask_activity` tool observations. */
+export const TOOL_ARGS_GIST_MAX_CHARS = 120;
+
+/** Delay before a live Ask's pending assistant output tail is emitted. */
+export const ASK_OUTPUT_FLUSH_INTERVAL_MS = 250;
+
+/** Maximum UTF-8 payload bytes in one coalesced live Ask output batch. */
+export const ASK_OUTPUT_MAX_BYTES = 2 * 1024;
+
+/** Cap on the one-line `activityGist` carried by a `node_update` event. */
+export const NODE_GIST_MAX_CHARS = 120;
+
+/** Maximum Nested Nodes the Summary keeps per Agent; past it, exited nodes prune oldest-first. */
+export const AGENT_NODE_TABLE_MAX = 64;
+
+/** Prefix marking that the oldest pending Ask output was dropped to fit the wire cap. */
+export const ASK_OUTPUT_TRUNCATION_MARKER = "[…output truncated…]";

package/src/worktree-transport.ts

@@ -0,0 +1,125 @@
+import { lstat, mkdir } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { YaagError } from "./errors.ts";
+import type {
+  AgentTransport,
+  OpenOptions,
+  TransportFactory,
+  TransportStartupObserver,
+} from "./transport.ts";
+
+interface GitResult {
+  readonly code: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+/**
+ * Creates an isolated Git worktree before opening flagged Agents.
+ *
+ * Refuses non-repositories and dirty base trees with `WORKTREE_REFUSED`, before
+ * opening `inner`. Created worktrees and branches are deliberately never
+ * removed: yaag does not own the user's work after creation (ADR-0007).
+ */
+export function worktreeTransport(inner: TransportFactory): TransportFactory {
+  return {
+    async open(
+      options: OpenOptions,
+      observeStartup?: TransportStartupObserver,
+    ): Promise<AgentTransport> {
+      if (options.worktree !== true) return inner.open(options, observeStartup);
+      const root = await repositoryRoot(options.cwd, options.name);
+      await requireClean(root, options.name);
+      const resolution = await addWorktree({ root, name: options.name });
+      const { worktree: _worktree, ...innerOptions } = options;
+      let reported = false;
+      const transport = await inner.open(
+        {
+          ...innerOptions,
+          cwd: resolution.cwd,
+        },
+        (startup) => {
+          reported = true;
+          observeStartup?.({ ...startup, worktree: resolution });
+        },
+      );
+      if (!reported) observeStartup?.({ worktree: resolution });
+      return transport;
+    },
+  };
+}
+
+async function repositoryRoot(cwd: string, name: string): Promise<string> {
+  const result = await git(cwd, ["rev-parse", "--show-toplevel"]);
+  const root = result.stdout.trim();
+  if (result.code !== 0 || root === "" || root.includes("\n")) {
+    throw new YaagError("WORKTREE_REFUSED", `agent "${name}": cwd is not a Git repository`, name);
+  }
+  return root;
+}
+
+async function requireClean(cwd: string, name: string): Promise<void> {
+  const result = await git(cwd, ["status", "--porcelain"]);
+  if (result.code !== 0 || result.stdout.trim() !== "") {
+    throw new YaagError(
+      "WORKTREE_REFUSED",
+      `agent "${name}": base repository is dirty, commit or stash changes before spawning a worktree`,
+      name,
+    );
+  }
+}
+
+async function addWorktree(options: { readonly root: string; readonly name: string }): Promise<{
+  readonly cwd: string;
+  readonly branch: string;
+}> {
+  const parent = join(dirname(options.root), `${basename(options.root)}-worktrees`);
+  await mkdir(parent, { recursive: true });
+  for (let suffix = 1; ; suffix += 1) {
+    const leaf = suffix === 1 ? options.name : `${options.name}-${suffix}`;
+    const branch = `yaag/${leaf}`;
+    const cwd = join(parent, leaf);
+    if (await candidateTaken(options.root, branch, cwd)) continue;
+    const result = await git(options.root, ["worktree", "add", "-b", branch, cwd, "HEAD"]);
+    if (result.code === 0) return { cwd, branch };
+    if (isCollision(result)) continue;
+    throw new Error(`git worktree add failed: ${result.stderr.trim() || result.stdout.trim()}`);
+  }
+}
+
+async function candidateTaken(root: string, branch: string, cwd: string): Promise<boolean> {
+  const [branchResult, occupiedPath] = await Promise.all([
+    git(root, ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`]),
+    pathExists(cwd),
+  ]);
+  return branchResult.code === 0 || occupiedPath;
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await lstat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isCollision(result: GitResult): boolean {
+  return /already exists|already registered|already checked out|cannot lock ref .*reference already exists/i.test(
+    `${result.stdout}\n${result.stderr}`,
+  );
+}
+
+async function git(cwd: string, args: readonly string[]): Promise<GitResult> {
+  try {
+    const process = Bun.spawn({ cmd: ["git", "-C", cwd, ...args], stdout: "pipe", stderr: "pipe" });
+    const [code, stdout, stderr] = await Promise.all([
+      process.exited,
+      new Response(process.stdout).text(),
+      new Response(process.stderr).text(),
+    ]);
+    return { code, stdout, stderr };
+  } catch (error) {
+    return { code: -1, stdout: "", stderr: String(error) };
+  }
+}