@yaag/runtime 0.10.0 → 0.11.0

package/src/cassette/resume-transport.ts

@@ -4,6 +4,9 @@ import type {
   AskCompletion,
   AskMarker,
   AskPlayback,
+  CompactionMarker,
+  CompactionPlayback,
+  CompactionResult,
   Frame,
   OpenOptions,
   RecordedSpawnSelection,
@@ -64,6 +67,7 @@ class ResumeTransport implements AgentTransport {
   readonly #frames = new FrameQueue();
   readonly #buffered: Frame[] = [];
   #askCursor = 0;
+  #compactionCursor = 0;
   #mode: "replay" | "activating" | "live" = "replay";
   #live: AgentTransport | null = null;
   #activation: Promise<void> | null = null;
@@ -112,6 +116,27 @@ class ResumeTransport implements AgentTransport {
     if (this.#mode === "live") this.#live?.finishAsk(completion);
   }
 
+  /**
+   * A compaction the Cassette does not hold activates live, exactly as a
+   * diverged Ask does: the recorded prefix cannot answer it (ADR-0043).
+   */
+  beginCompaction(marker: CompactionMarker): CompactionPlayback | undefined {
+    if (this.#mode === "live") return this.#live?.beginCompaction(marker);
+    if (this.#mode === "activating") return undefined;
+    const mismatch = replayMismatch.compaction(this.#agent, this.#compactionCursor, marker);
+    if (!mismatch) {
+      this.#compactionCursor += 1;
+      return this.#replay.beginCompaction(marker);
+    }
+    this.#mode = "activating";
+    this.#activation = this.#activate(null);
+    return undefined;
+  }
+
+  finishCompaction(result: CompactionResult | undefined): void {
+    if (this.#mode === "live") this.#live?.finishCompaction(result);
+  }
+
   recordedExtractionPolicy(index: number): string | undefined {
     return this.#mode === "replay" ? this.#agent.asks[index]?.extractionPolicy : undefined;
   }
@@ -121,7 +146,7 @@ class ResumeTransport implements AgentTransport {
     return this.#closed;
   }
 
-  async #activate(marker: AskMarker): Promise<void> {
+  async #activate(marker: AskMarker | null): Promise<void> {
     // End the old source before attaching the new one, but keep the outward
     // queue open so Connection remains attached across the handoff.
     this.#replay.finish();
@@ -131,7 +156,7 @@ class ResumeTransport implements AgentTransport {
     try {
       const live = await this.#liveFactory.open(this.#continuation);
       this.#live = live;
-      live.beginAsk(marker);
+      if (marker !== null) live.beginAsk(marker);
       for (const frame of this.#buffered.splice(0)) live.send(frame);
       this.#mode = "live";
       void this.#forward(live.frames());

package/src/errors.ts

@@ -44,6 +44,10 @@ export type YaagErrorCode =
   | "ASK_TIMEOUT" // timeoutMs elapsed
   | "ASK_LIMIT" // soft Ask budget exceeded after grace
   | "ASK_STALLED" // no frame arrived within the silence budget; escalated, then kill
+  | "COMPACT_DURING_ASK" // compact() was called while an Ask was in flight
+  | "COMPACT_FAILED" // pi refused or could not summarize the context
+  | "FORK_DURING_ASK" // fork() was called while the source Ask was in flight
+  | "FORK_REFUSED" // the fork source died mid-Ask, or holds no session file
   | "ASK_INVALID_OUTPUT" // settled text could not be extracted or satisfy outputSchema
   | "ARGS_INVALID" // arguments failed schema validation before the Run started
   | "CONFIG_INVALID" // a config layer is missing, unparsable, or violates the schema

package/src/events.ts

@@ -22,7 +22,7 @@ export type RunOutcome = "completed" | "failed" | "stopped" | "paused" | "interr
 
 /**
  * How an Agent came to be. An absent value on an event means "spawn"; "fork"
- * arrives with the forking spec.
+ * marks an Agent created from a copy of another Agent's session (ADR-0044).
  */
 export type SpawnOrigin = "spawn" | "fork";
 
@@ -169,6 +169,31 @@ export type LifecycleEventBody =
       /** Cumulative assistant-completion cost observed so far. */
       readonly cost: number;
     }
+  | {
+      /**
+       * One compaction of an Agent's context (ADR-0043).
+       *
+       * It carries the summary call's own spend, so a Run Summary does not
+       * silently lose it. `agent_exit` stays authoritative for the Agent's
+       * total: pi's `get_session_stats` already includes compaction spend.
+       * The custom instructions never ride the wire (ticket 09); only the
+       * `custom` flag says that the program supplied some.
+       */
+      readonly type: "agent_compaction";
+      readonly agent: string;
+      /** Monotonic per Agent, from 0. */
+      readonly index: number;
+      /** Context tokens before the summary replaced the transcript; null when unknown. */
+      readonly tokensBefore: number | null;
+      /** Estimated context tokens after the summary; null when unknown. */
+      readonly tokensAfter: number | null;
+      /** The summary call's own token breakdown; null when unknown. */
+      readonly tokens: TokenBreakdown | null;
+      /** The summary call's own cost; null when unknown. */
+      readonly cost: number | null;
+      /** The program supplied custom compaction instructions. */
+      readonly custom: boolean;
+    }
   | {
       readonly type: "agent_exit";
       readonly agent: string;

package/src/index.ts

@@ -5,6 +5,7 @@ export type {
   CassetteAgent,
   CassetteArtifact,
   CassetteAsk,
+  CassetteCompaction,
   CassetteGit,
   CassetteRun,
   CassetteSink,
@@ -79,6 +80,7 @@ export type {
   AgentInfo,
   AgentState,
   AskingAgentInfo,
+  CompactionInfo,
   EndedRunSummary,
   ExitedAgentInfo,
   IdleAgentInfo,
@@ -96,6 +98,9 @@ export type {
   AskMarker,
   AskMarkerContext,
   AskPlayback,
+  CompactionMarker,
+  CompactionPlayback,
+  CompactionResult,
   DiscoveredSkill,
   Frame,
   ReapPath,
@@ -110,6 +115,7 @@ export type {
 export { readSystemPromptSidecar, reap, worktreeTransport } from "./transport/index.ts";
 export type {
   AskOptions,
+  ForkOptions,
   Handle,
   ResolvedSpawnOptions,
   SpawnOptions,

package/src/summary/index.ts

@@ -16,6 +16,7 @@ export type {
   AgentInfo,
   AgentState,
   AskingAgentInfo,
+  CompactionInfo,
   ExitedAgentInfo,
   IdleAgentInfo,
   ModelFallbackInfo,

package/src/summary/summary-agent.ts

@@ -7,6 +7,15 @@ export type { AgentActivity, SpawnOrigin } from "../events.ts";
 export type { ModelFallbackInfo } from "./summary-fallbacks.ts";
 export type { NodeInfo } from "./summary-nodes.ts";
 
+/** What one compaction of an Agent's context reported (ADR-0043). */
+export interface CompactionInfo {
+  readonly tokensBefore: number | null;
+  readonly tokensAfter: number | null;
+  /** The summary call's own cost, already included in `agent_exit` accounting. */
+  readonly cost: number | null;
+  readonly at: number | null;
+}
+
 /** The observer-facing lifecycle state of an Agent. */
 export type AgentState = "idle" | "asking" | "exited";
 
@@ -34,6 +43,10 @@ interface AgentInfoBase {
   /** Timestamp ordering only cumulative live accounting, never lifecycle state. */
   readonly usageUpdatedAt: number | null;
   readonly askStartedAt: number | null;
+  /** Compactions of this Agent's context so far (ADR-0043). */
+  readonly compactions: number;
+  /** What the newest compaction reported, or null when the Agent compacted none. */
+  readonly lastCompaction: CompactionInfo | null;
   /** This Agent's bounded Nested Node table, in first-seen order (spec §3). */
   readonly nodes: readonly NodeInfo[];
   /** Exited Nested Nodes dropped to keep the table bounded. */
@@ -103,6 +116,8 @@ export function placeholderAgent(): IdleAgentInfo {
     sessionFile: null,
     parent: null,
     origin: "spawn",
+    compactions: 0,
+    lastCompaction: null,
     state: "idle",
     askIndex: null,
     promptGist: null,
@@ -264,6 +279,29 @@ export function setUsage(
   return { ...agent, tokens: observation.tokens, cost: observation.cost, usageUpdatedAt: at };
 }
 
+/**
+ * Counts one compaction and keeps what it reported.
+ *
+ * It folds no cost: the summary call's spend reaches the Summary through
+ * `agent_usage`, and `agent_exit` stays authoritative (ADR-0043). A terminal
+ * Agent still counts a late compaction, because the count is a fact about the
+ * conversation rather than a lifecycle state.
+ */
+export function compactAgent(
+  current: AgentRecord | undefined,
+  observation: CompactionInfo,
+  at: number | null,
+): AgentRecord {
+  const agent = current ?? placeholderAgent();
+  const stale =
+    at !== null && agent.lastCompaction?.at !== null && at < (agent.lastCompaction?.at ?? at);
+  return {
+    ...agent,
+    compactions: agent.compactions + 1,
+    lastCompaction: stale ? agent.lastCompaction : { ...observation, at },
+  };
+}
+
 /**
  * Folds authoritative shutdown accounting into the terminal Agent state.
  *

package/src/summary/summary.ts

@@ -3,6 +3,7 @@ import type { TokenBreakdown } from "../transport/index.ts";
 import type { AgentInfo } from "./summary-agent.ts";
 import {
   type AgentRecord,
+  compactAgent,
   endAsk,
   exitAgent,
   placeholderAgent,
@@ -22,6 +23,7 @@ export type {
   AgentInfo,
   AgentState,
   AskingAgentInfo,
+  CompactionInfo,
   ExitedAgentInfo,
   IdleAgentInfo,
   ModelFallbackInfo,
@@ -51,6 +53,8 @@ interface RunSummaryBase {
   readonly worstFrameGapMs: number;
   /** Run-wide Model Resolution fallbacks, pruned per-Agent entries included. */
   readonly modelFallbacks: number;
+  /** Compactions across every Agent of this Run (ADR-0043). */
+  readonly compactions: number;
 }
 
 /** A Run that has not settled; it has neither outcome nor compatibility result. */
@@ -109,6 +113,7 @@ export function initialSummary(): RunningRunSummary {
     durationMs: 0,
     worstFrameGapMs: 0,
     modelFallbacks: 0,
+    compactions: 0,
     ok: null,
   };
 }
@@ -160,6 +165,21 @@ export function applyEvent(
         event.agent,
         applyAgentModel(summary.agents[event.agent] ?? placeholderAgent(), event),
       );
+    case "agent_compaction":
+      return withAgent(
+        { ...summary, compactions: summary.compactions + 1 },
+        event.agent,
+        compactAgent(
+          summary.agents[event.agent],
+          {
+            tokensBefore: event.tokensBefore,
+            tokensAfter: event.tokensAfter,
+            cost: event.cost,
+            at,
+          },
+          at,
+        ),
+      );
     case "agent_usage":
       return withAgent(summary, event.agent, setUsage(summary.agents[event.agent], event, at));
     case "ask_end":

package/src/transport/fake-transport.ts

@@ -6,7 +6,13 @@ import {
 import type { AvailableModel } from "../model/index.ts";
 import { FrameQueue } from "./frame-queue.ts";
 import { parseFrame } from "./jsonl.ts";
-import type { AgentStats, AgentTransport, AskMarker, Frame } from "./transport.ts";
+import type {
+  AgentStats,
+  AgentTransport,
+  AskMarker,
+  CompactionMarker,
+  Frame,
+} from "./transport.ts";
 
 /**
  * Scripted frame playback for one prompt sent through a FakeTransport.
@@ -50,6 +56,10 @@ export interface FakeTransportOptions extends FakePromptScript {
   readonly steerError?: string;
   /** Makes an abort RPC response fail without embedding a limit decision in playback. */
   readonly abortError?: string;
+  /** Payload of a `compact` command response; omission answers a bare success. */
+  readonly compaction?: Record<string, unknown>;
+  /** Makes a `compact` command response fail, as pi does when it cannot summarize. */
+  readonly compactError?: string;
   /** Makes the private report_result schema command fail. */
   readonly schemaCommandError?: string;
   /** The snapshot answered to `get_available_models`; defaults to this fake's own model. */
@@ -87,6 +97,7 @@ export class FakeTransport implements AgentTransport {
   /** Everything the runtime wrote, in order. */
   readonly sent: Frame[] = [];
   readonly asks: AskMarker[] = [];
+  readonly compactions: CompactionMarker[] = [];
   readonly #queue = new FrameQueue();
   readonly #options: FakeTransportOptions;
   #closed = false;
@@ -113,6 +124,7 @@ export class FakeTransport implements AgentTransport {
     if (frame.type === "abort") void this.#answerAbort(frame);
     if (frame.type === "get_last_assistant_text") this.#answerLastText(frame);
     if (frame.type === "get_state") this.#answerState(frame);
+    if (frame.type === "compact") this.#answerCompact(frame);
     if (frame.type === "get_available_models") this.#answerAvailableModels(frame);
     if (frame.type === "set_model") this.#answerSetModel(frame);
     if (frame.type === "set_thinking_level")
@@ -133,6 +145,15 @@ export class FakeTransport implements AgentTransport {
     // This live test transport does not persist Ask outcomes.
   }
 
+  beginCompaction(marker: CompactionMarker): undefined {
+    this.compactions.push(marker);
+    return undefined;
+  }
+
+  finishCompaction(): void {
+    // This live test transport does not persist compaction outcomes.
+  }
+
   /** True once the runtime shut this Agent down. */
   get closed(): boolean {
     return this.#closed;
@@ -295,6 +316,19 @@ export class FakeTransport implements AgentTransport {
     });
   }
 
+  #answerCompact(frame: Frame): void {
+    const error = this.#options.compactError;
+    this.#queue.push({
+      type: "response",
+      command: "compact",
+      id: frame.id,
+      success: error === undefined,
+      ...(error === undefined
+        ? { data: this.#options.compaction ?? { summary: "summary" } }
+        : { error }),
+    });
+  }
+
   #answerState(frame: Frame): void {
     if (this.#options.stateSilent === true) return;
     this.#queue.push({

package/src/transport/index.ts

@@ -17,7 +17,12 @@ export { FrameGapTracker } from "./frame-gap.ts";
 export { FrameQueue } from "./frame-queue.ts";
 export { decodeFrames } from "./jsonl.ts";
 export { liveTransport } from "./live-transport.ts";
-export { type AgentProgress, piCommand, readAgentProgress } from "./pi-state.ts";
+export {
+  type AgentProgress,
+  piCommand,
+  readAgentProgress,
+  readCompaction,
+} from "./pi-state.ts";
 export { type ReapPath, type ReapTarget, reap } from "./reap.ts";
 export { type DiscoveredSkill, liveSkillProbe, type SkillProbeFactory } from "./skill-probe.ts";
 export { skillRestrictionTransport } from "./skill-restriction-transport.ts";
@@ -34,6 +39,9 @@ export type {
   AskMarker,
   AskMarkerContext,
   AskPlayback,
+  CompactionMarker,
+  CompactionPlayback,
+  CompactionResult,
   Frame,
   OpenOptions,
   TokenBreakdown,

package/src/transport/live-transport.ts

@@ -140,6 +140,15 @@ class LiveTransport implements AgentTransport {
     // Live transport has no Cassette outcome to complete.
   }
 
+  beginCompaction(): undefined {
+    // Nothing to do live; a recording implementation groups frames by this.
+    return undefined;
+  }
+
+  finishCompaction(): void {
+    // Live transport has no Cassette compaction to complete.
+  }
+
   close(): Promise<AgentStats> {
     this.#closing ??= this.#shutdown();
     return this.#closing;

package/src/transport/pi-state.ts

@@ -1,6 +1,12 @@
 import { REPORT_RESULT_EXTENSION_PATH, REPORT_RESULT_TOOL_NAME } from "../ask-contract/index.ts";
 import { SYSTEM_PROMPT_RECORDER_EXTENSION_PATH } from "./system-prompt-recorder.ts";
-import type { AgentStats, Frame, OpenOptions, TokenBreakdown } from "./transport.ts";
+import type {
+  AgentStats,
+  CompactionResult,
+  Frame,
+  OpenOptions,
+  TokenBreakdown,
+} from "./transport.ts";
 
 /** What the Agent reported about its own work, read from a `get_state` probe. */
 export interface AgentProgress {
@@ -23,7 +29,10 @@ export function piCommand(options: OpenOptions, toolProbeExtensionPath?: string)
   }
   appendCapabilities(cmd, options, toolProbeExtensionPath);
   if (options.sessionDir) cmd.push("--session-dir", options.sessionDir);
+  // `--session` and `--fork` are mutually exclusive in pi, and a resume is the
+  // stronger claim: it names the very session this Agent must continue.
   if (options.sessionFile) cmd.push("--session", options.sessionFile);
+  else if (options.forkSession) cmd.push("--fork", options.forkSession);
   // No --approve: Agents inherit the user's saved project-trust decision (ADR-0009).
   return cmd;
 }
@@ -154,6 +163,47 @@ export function readStats(response: Frame): AgentStats {
   return { tokens: readBreakdown("tokens" in data ? data.tokens : null), cost };
 }
 
+/**
+ * What a `compact` response reports (ADR-0043).
+ *
+ * A missing field becomes null rather than 0, so "unknown" and "free" stay
+ * distinguishable: a custom compaction handler may answer without usage.
+ */
+export function readCompaction(response: Frame): CompactionResult {
+  const data: unknown = response.data;
+  if (typeof data !== "object" || data === null) {
+    return { tokensBefore: null, tokensAfter: null, tokens: null, cost: null };
+  }
+  const record: Record<string, unknown> = { ...data };
+  const usage: unknown = record.usage;
+  const usageRecord: Record<string, unknown> =
+    typeof usage === "object" && usage !== null ? { ...usage } : {};
+  const cost: unknown = usageRecord.cost;
+  return {
+    tokensBefore: typeof record.tokensBefore === "number" ? record.tokensBefore : null,
+    tokensAfter:
+      typeof record.estimatedTokensAfter === "number" ? record.estimatedTokensAfter : null,
+    tokens: readCompactionTokens(usageRecord),
+    cost:
+      typeof cost === "object" &&
+      cost !== null &&
+      typeof (cost as { total?: unknown }).total === "number"
+        ? (cost as { total: number }).total
+        : null,
+  };
+}
+
+/** The summary call's own token breakdown, or null when pi reported none. */
+function readCompactionTokens(usage: Record<string, unknown>): TokenBreakdown | null {
+  return readBreakdown({
+    input: usage.input,
+    output: usage.output,
+    cacheRead: usage.cacheRead,
+    cacheWrite: usage.cacheWrite,
+    total: usage.totalTokens,
+  });
+}
+
 function readBreakdown(tokens: unknown): TokenBreakdown | null {
   if (typeof tokens !== "object" || tokens === null) return null;
   const record: Record<string, unknown> = { ...tokens };

package/src/transport/transport.ts

@@ -31,6 +31,23 @@ export interface AgentStats {
   readonly cost: number | null;
 }
 
+/**
+ * What one compaction of an Agent's context reported (ADR-0043).
+ *
+ * Every field is null when pi reported nothing for it: a custom compaction
+ * handler may answer without usage, and "unknown" must stay distinct from 0.
+ */
+export interface CompactionResult {
+  /** Context tokens before the summary replaced the transcript. */
+  readonly tokensBefore: number | null;
+  /** Estimated context tokens after the summary replaced the transcript. */
+  readonly tokensAfter: number | null;
+  /** Token breakdown of the summary call itself. */
+  readonly tokens: TokenBreakdown | null;
+  /** Cost of the summary call itself. */
+  readonly cost: number | null;
+}
+
 /** Recorded inputs used to explain an Ask-hash mismatch without changing identity. */
 export interface AskMarkerContext {
   readonly prompt: string;
@@ -93,6 +110,27 @@ export interface AskCompletion {
   readonly recovered?: true;
 }
 
+/**
+ * Opaque marker naming one compaction of an Agent's context.
+ *
+ * A compaction sits between two Asks, so it cannot ride the Agent-level frame
+ * streams: a Cassette replay switches those cursors to an Ask and never
+ * switches back. The marker gives the exchange its own recorded streams.
+ */
+export interface CompactionMarker {
+  /** Monotonic per Agent, from 0. */
+  readonly index: number;
+  /** sha256 of the settled-Ask count and the custom instructions, when given. */
+  readonly hash: string;
+  /** Settled Asks of this Agent at the compaction point. */
+  readonly afterAsks: number;
+}
+
+/** Presence identifies Cassette playback of one compaction. */
+export interface CompactionPlayback {
+  readonly result: CompactionResult;
+}
+
 /** Presence identifies Cassette playback, including recorded successful Asks. */
 export interface AskPlayback {
   /** Limit outcome recorded for this Ask, if it rejected with ASK_LIMIT. */
@@ -143,6 +181,15 @@ export interface AgentTransport {
   /** Reports surfaced live outcomes; replay ignores completion. */
   finishAsk(completion: AskCompletion): void;
 
+  /**
+   * Begins one compaction. Live transports return undefined; replay transports
+   * return the recorded result.
+   */
+  beginCompaction(marker: CompactionMarker): CompactionPlayback | undefined;
+
+  /** Ends the compaction exchange, so later frames belong to the Agent again. */
+  finishCompaction(result: CompactionResult | undefined): void;
+
   /**
    * The extraction policy recorded for the Ask at `index`, when a Cassette
    * backs it. An Ask recorded under an older policy keeps that policy, so its
@@ -200,6 +247,22 @@ export interface OpenOptions {
   readonly sessionDir?: string;
   /** Resumes an existing pi session, translated to `--session <path>`. */
   readonly sessionFile?: string;
+  /** How the Agent came to be; absent means an ordinary spawn. Spawn identity. */
+  readonly origin?: "fork";
+  /** Name of the Agent this one was forked from. Spawn identity; never argv. */
+  readonly forkOf?: string;
+  /** Settled Asks of the fork source at the fork point. Spawn identity. */
+  readonly forkAsks?: number;
+  /**
+   * The fork source's session file, translated to `pi --fork <path>`.
+   * Never spawn identity: the path is machine-specific.
+   */
+  readonly forkSession?: string;
+  /**
+   * The fork source's worktree, so the fork branches from it instead of from a
+   * clean base tree. Never spawn identity.
+   */
+  readonly worktreeFrom?: WorktreeResolution;
 }
 
 /** Nondeterministic worktree identity resolved below the transport seam. */

package/src/transport/worktree-transport.ts

@@ -28,9 +28,17 @@ export function worktreeTransport(inner: TransportFactory): TransportFactory {
       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 from = options.worktreeFrom;
+      const root = await repositoryRoot(from?.cwd ?? options.cwd, options.name);
+      // A fork branches from what its source already committed, so the source's
+      // dirty files stay behind and no clean check applies (ADR-0044).
+      if (from === undefined) await requireClean(root, options.name);
+      const resolution = await addWorktree({
+        root,
+        name: options.name,
+        namingRoot: await namingRoot(root),
+        startPoint: from?.branch ?? "HEAD",
+      });
       const { worktree: _worktree, ...innerOptions } = options;
       let reported = false;
       const transport = await inner.open(
@@ -69,18 +77,43 @@ async function requireClean(cwd: string, name: string): Promise<void> {
   }
 }
 
-async function addWorktree(options: { readonly root: string; readonly name: string }): Promise<{
+/**
+ * The repository the worktree directory is named after.
+ *
+ * For a worktree it is the main repository, not the worktree itself, so a fork
+ * of a Worktree Agent does not nest `repo-worktrees/a1-worktrees/a2`.
+ */
+async function namingRoot(root: string): Promise<string> {
+  const result = await git(root, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
+  const common = result.stdout.trim();
+  if (result.code !== 0 || common === "" || !common.endsWith("/.git")) return root;
+  return common.slice(0, -"/.git".length);
+}
+
+async function addWorktree(options: {
+  readonly root: string;
+  readonly name: string;
+  readonly namingRoot: string;
+  readonly startPoint: string;
+}): Promise<{
   readonly cwd: string;
   readonly branch: string;
 }> {
-  const parent = join(dirname(options.root), `${basename(options.root)}-worktrees`);
+  const parent = join(dirname(options.namingRoot), `${basename(options.namingRoot)}-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"]);
+    const result = await git(options.root, [
+      "worktree",
+      "add",
+      "-b",
+      branch,
+      cwd,
+      options.startPoint,
+    ]);
     if (result.code === 0) return { cwd, branch };
     if (isCollision(result)) continue;
     throw new Error(`git worktree add failed: ${result.stderr.trim() || result.stdout.trim()}`);