@ordewell/core 0.9.1 → 0.10.0

package/dist/{Task-1Q19y7sZ.d.mts → Task-CxwnCJLi.d.mts}

@@ -1,3 +1,15 @@
+interface TaskDiffRead {
+    repo?: string;
+    path?: string;
+}
+type TaskDiffResult = {
+    available: true;
+    text: string;
+} | {
+    available: false;
+    reason: string;
+};
+
 /**
  * Why isolated execution is unavailable for a workspace. The orchestrator needs
  * the reason, not just a boolean: `dirty` is offered a stash or an explicit
@@ -45,6 +57,10 @@ type IsolationOutcome = 'merged' | 'conflict' | 'failed';
 type IsolationTaskStatus = 'active' | 'kept' | 'conflict' | 'repairing' | 'failed' | 'merged';
 /** One repo's share of a task: its worktree inside the task workspace. */
 interface IsolationTaskRepo {
+    /** Integration tip when this task started; absent in older saved runs. */
+    baseRef?: string;
+    /** Task branch tip before integration removes it; excludes concurrent landings. */
+    taskTip?: string;
     /** Absolute path of this repo's worktree: the task workspace joined with the repo's path. */
     worktree: string;
     /**
@@ -79,6 +95,8 @@ interface IsolationTaskRecord {
     status: IsolationTaskStatus;
     /** Keyed by repo path. */
     repos: Record<string, IsolationTaskRepo>;
+    /** Unrecovered branches from a conflict fallback, so a later continue cannot forget them. */
+    continuationWork?: PreservedWork[];
     /** The repo whose merge stopped the task from landing, while `status` is `conflict` or `failed`. */
     conflictRepo?: string;
     /**
@@ -226,6 +244,12 @@ interface IsolationHandoff {
     repos: IsolationHandoffRepo[];
     /** Tasks that landed on the integration branches, in plan order. */
     landed: IsolationLandedTask[];
+    /**
+     * The run's end is an Act supervisor's to handle first (ADR-0029), so a
+     * surface shows the handoff without popping it up. Sent again without this
+     * once the supervisor's turn on it ends with the run still unmerged.
+     */
+    deferredTo?: 'supervisor';
 }
 /** A plan's isolation as a surface shows it: a mark for each task the run touched, and its handoff. */
 interface IsolationView {
@@ -288,6 +312,11 @@ type RepairEvidence = {
     repo: string;
     files?: string[];
 };
+interface SetupFailure {
+    /** Relative to the task workspace; `.` for a lone repository. */
+    repo: string;
+    detail: string;
+}
 interface PreparedTask {
     cwd: string;
     branch: string;
@@ -297,8 +326,11 @@ interface PreparedTask {
      * stay in the task, so the user is told.
      */
     copied: string[];
+    /** Repos whose setup command failed, so they got the default links instead; absent when none did. */
+    setupFailed?: SetupFailure[];
     /** What the attempt this one replaces left unlanded, kept on a branch before its worktree went; absent when nothing was. */
     preserved?: PreservedWork[];
+    continuation?: 'restored' | 'fallback';
 }
 /** A task as a removal names it. */
 type IsolationTaskRef = Pick<IsolationTaskRecord, 'taskId' | 'order' | 'title'>;
@@ -368,11 +400,11 @@ interface IWorktreeIsolation {
     /**
      * Create the task workspace — one worktree per isolated repo from its
      * integration tip, the shared paths linked in — and return the cwd to spawn
-     * the Runner into. A second `prepare` for the same task is a retry: the old
-     * attempt is discarded and the workspace recreated from the tips, so the
-     * task sees everything its predecessors have integrated.
+     * the Runner into. Fresh attempts start clean from the tips. A continuation
+     * restores the previous attempt's preserved work on top of them, falling
+     * back to the tips in every repo when any restoration conflicts (ADR-0018).
      */
-    prepare(task: Task, run: IsolationRun): Promise<PreparedTask>;
+    prepare(task: Task, run: IsolationRun, intent?: 'fresh' | 'continuation'): Promise<PreparedTask>;
     /**
      * Hand a conflicted task's kept workspace to a conflict repair (ADR-0015)
      * as it is — nothing is re-cut — and return the same cwd. Records each
@@ -433,6 +465,7 @@ interface IWorktreeIsolation {
     pruneOrphans(run: IsolationRun): Promise<IsolationPruneResult>;
     /** Unified diff of each repo's integration branch against its base ref. */
     reviewDiff(run: IsolationRun): Promise<string>;
+    taskDiff?(run: IsolationRun, taskId: string, options: TaskDiffRead): Promise<TaskDiffResult>;
     /**
      * Mark the landed tasks whose work the checked-out HEAD now contains in
      * every repo they changed (`git merge-base --is-ancestor`), and return their
@@ -495,6 +528,8 @@ interface UsageRecord {
     /** The provider or runner id that reported the call — `openai`, `claude-code`, … */
     source: string;
     model?: string;
+    /** A session breakdown can name a model without identifying the current context. */
+    aggregate?: true;
     inputTokens?: number;
     outputTokens?: number;
     /** The share of `inputTokens` served from the provider's prompt cache. */
@@ -547,6 +582,9 @@ declare function addUsage(totals: UsageTotals, record: UsageRecord): UsageTotals
 interface PlannerUsage {
     totals: UsageTotals;
     bySubagent?: Record<string, UsageTotals>;
+    byModel?: ModelUsage[];
+    source?: string;
+    model?: string;
     lastPromptTokens?: number;
     contextWindow?: number;
 }
@@ -555,6 +593,8 @@ declare function addPlannerUsage(usage: PlannerUsage, record: UsageRecord): Plan
 declare function isMeasured(totals: UsageTotals): boolean;
 /** What the token line shows of a ledger — live from its broadcast, or reloaded from the saved one. */
 interface UsageLine {
+    byModel?: ModelUsage[];
+    model?: string;
     totals: UsageTotals;
     bySubagent?: Record<string, UsageTotals>;
     contextFill?: {
@@ -574,6 +614,81 @@ declare function plannerContextFill(usage: PlannerUsage): {
     usedTokens: number;
     windowTokens: number;
 } | undefined;
+interface ModelUsage {
+    source: string;
+    model?: string;
+    totals: UsageTotals;
+}
+declare function addModelUsage(models: readonly ModelUsage[], record: UsageRecord): ModelUsage[];
+interface AttemptUsage extends PlannerUsage {
+    attempt: number;
+    runner: string;
+    startedAt: string;
+    endedAt?: string;
+    wallTimeMs: number;
+}
+declare function startAttemptUsage(attempt: number, runner: string, startedAt: string): AttemptUsage;
+declare function addAttemptUsage(usage: AttemptUsage, record: UsageRecord, now: string): AttemptUsage;
+declare function endAttemptUsage(usage: AttemptUsage, now: string): AttemptUsage;
+interface PlanUsage {
+    totals: UsageTotals;
+    byModel: ModelUsage[];
+    wallTimeMs: number;
+    attempts: number;
+}
+declare function addUsageTotals(totals: UsageTotals, addition: UsageTotals): UsageTotals;
+interface UsageTask {
+    attemptUsage?: readonly AttemptUsage[];
+    subtasks?: readonly UsageTask[];
+}
+declare function planUsage(tasks: readonly UsageTask[]): PlanUsage;
+
+/**
+ * How far a plan's supervisor may act in its wake-up turns (ADR-0029): a plan
+ * setting, saved on the run as it starts. Off: it never wakes. Watch: it
+ * wakes, reads and suggests. Act: Watch, and acting within its loop guards
+ * without asking.
+ */
+type SupervisorLevel = 'off' | 'watch' | 'act';
+declare function isSupervisorLevel(value: unknown): value is SupervisorLevel;
+/**
+ * Who asked the command seam for an action (ADR-0029): the user, a planner
+ * turn the user started, or the supervisor at its level.
+ */
+type ExecutionActor = {
+    kind: 'user';
+} | {
+    kind: 'planner-turn';
+} | {
+    kind: 'supervisor';
+    level: SupervisorLevel;
+}
+/** The user's standing instruction to start each plan the planner submits (ADR-0030). */
+ | {
+    kind: 'autorun';
+};
+type ExecutionCommandName = 'run_plan' | 'run_task' | 'stop_task' | 'stop_run' | 'retry_task' | 'message_task' | 'answer_approval' | 'merge_all' | 'skip_task';
+/**
+ * One call at the command seam as the timeline keeps it: what was asked, by
+ * whom, about which task, and how it ended — done, refused by the seam, or
+ * declined by the user it asked.
+ */
+interface ExecutionRecord {
+    command: ExecutionCommandName;
+    actor: ExecutionActor['kind'];
+    /** Present when the supervisor asked. */
+    level?: SupervisorLevel;
+    /** `ref` is how the plan numbers it: "#4", or "#4.1" for a subtask. */
+    task?: {
+        id: string;
+        ref: string;
+        title: string;
+    };
+    outcome: 'done' | 'refused' | 'declined';
+    /** The refusal, the message sent, or the note a denial carried. */
+    detail?: string;
+    at: string;
+}
 
 declare const BUILTIN_SKILL_NAMES: readonly ["grilling", "to-spec", "improve-codebase-architecture", "tdd"];
 interface SkillMetadata {
@@ -665,6 +780,109 @@ declare class SkillsService {
  */
 declare function createSkillsService(workspaceRoot?: string, workspaceRepos?: readonly string[]): SkillsService;
 
+/**
+ * The loop guards of an Act supervisor (ADR-0029): pure checks that stop it
+ * spinning. Each answers with the trip — the note the model is refused with,
+ * and the message the user is told — or null to let the action through. The
+ * session keeps what they remember of the run and calls them where the action
+ * executes: the command seam for retries, the edit path for edits, the
+ * supervisor for its wake-ups.
+ */
+/** Retries an Act supervisor may make of one task in a run when the plan sets none. */
+declare const DEFAULT_SUPERVISOR_RETRY_LIMIT = 2;
+/** A guard that tripped. */
+interface GuardTrip {
+    /** The guard and what it caught, so the user is told of one trip once however often the model repeats the call. */
+    key: string;
+    /** The note the model is refused with: the guard, and what would be accepted. */
+    refusal: string;
+    /** What the user is told, as the supervisor's message. */
+    escalation: string;
+}
+/** A task as the command seam located it: the task, and how the plan numbers it. */
+interface GuardTarget {
+    task: Readonly<Task>;
+    ref: string;
+}
+/** What an attempt was told and who ran it: a retry after a failure has to change one of them. */
+interface AttemptShape {
+    prompt: string;
+    skills: readonly string[];
+    runner: string;
+    model: string | null;
+    effort: string | null;
+}
+/**
+ * What the loop guards remember as plain data, saved on the plan so a daemon
+ * restart does not hand an Act supervisor a fresh retry budget or forget the
+ * tasks it removed (ADR-0029). Maps become records and the reported-trip set an
+ * array, so it round-trips through JSON.
+ */
+interface SupervisionMemorySnapshot {
+    /** Retries of one task this run, by task id. */
+    retries: Record<string, number>;
+    /** Skips of a task the supervisor had retried, by task id: each counts against the retry limit. Absent on saves before skip. */
+    skips?: Record<string, number>;
+    /** What each failed task's attempt ran with, by task id. */
+    failedWith: Record<string, AttemptShape>;
+    /** The supervisor's own edits this run. */
+    edits: EditMemory;
+    /** The keys of the guard trips the user was already told of. */
+    told: string[];
+}
+/** What the supervisor's own edits did this run: the tasks it removed, and each field it changed. */
+interface EditMemory {
+    removed: readonly {
+        title: string;
+        prompt: string;
+    }[];
+    changed: readonly {
+        taskId: string;
+        field: string;
+        from: string;
+    }[];
+}
+
+/**
+ * When the supervisor wakes during a run, and what it is told (#27). Only an
+ * attention event wakes it; passes ride along as context. It keeps no clock:
+ * the host stamps each event and polls on its own tick.
+ */
+type RunEventKind = 'task_passed' | 'task_failed' | 'waiting_input' | 'waiting_approval' | 'task_idle' | 'landing_conflict' | 'usage_limit' | 'auto_merge_stopped' | 'run_finished';
+type RunEvent = {
+    kind: RunEventKind;
+    taskId?: string;
+    /** Epoch ms, on the same clock the host passes to `poll`. */
+    at: number;
+    detail?: string;
+    /** `usage_limit` only: the runner whose limit paused the task. */
+    runner?: string;
+    /** `usage_limit` only: when its tasks resume on their own (ISO time); null when they wait for a manual retry. */
+    resumeAt?: string | null;
+    /** `usage_limit` in a batch: every task the runner's limit paused in it, in arrival order. */
+    taskIds?: string[];
+};
+/** What the policy holds before its next wake-up, for the plan (ADR-0029). */
+interface WakePolicySnapshot {
+    /** Attention events inside the debounce window, in arrival order. */
+    attention: RunEvent[];
+    /** The passes since the previous wake-up. */
+    sinceLast: RunEvent[];
+}
+
+/**
+ * What the supervisor gathered but has not delivered, saved on the plan so a
+ * daemon restart still delivers a batch that was inside its debounce window
+ * (ADR-0029). Undelivered batches already wait as `pendingTurns`; this is only
+ * the state the policy and the wake-up rate keep before a batch exists.
+ */
+interface SupervisorSnapshot {
+    /** The events inside the debounce window and the passes since the last wake-up. */
+    policy: WakePolicySnapshot;
+    /** When each wake-up since the last pass was delivered, for the wake-up rate guard. */
+    wakeUps: number[];
+}
+
 interface UserStep {
     order: number;
     instruction: string;
@@ -687,19 +905,27 @@ interface Verdict {
 }
 interface TaskOutputSummary {
     reviewReason: string;
+    /** The `task_complete` summary, the task's report; absent when the attempt ended without one, and from sessions saved before it was kept. */
+    report?: string;
+    /** Empty when there is a report: the turn's final text is the report itself. */
     logTail: string;
     capturedAt: string;
 }
 type TaskType = 'ai' | 'user';
-type TaskStatus = 'pending' | 'approved' | 'in_progress' | 'completed' | 'failed' | 'blocked' | 'awaiting_user';
+/**
+ * `skipped` is terminal and verdict-less: the task will not be waited for, and
+ * nothing it did lands. Its dependents go ahead without it.
+ */
+type TaskStatus = 'pending' | 'approved' | 'in_progress' | 'completed' | 'failed' | 'blocked' | 'awaiting_user' | 'skipped';
 type TaskMode = string;
 /**
  * Why an `awaiting_user` task waits (ADR-0018, W1): a structured turn that
  * ended without a `task_complete` call, a checkpoint question, work that did not
- * land, or an ops task that changed tracked files (ADR-0020). Saved, so no
- * surface has to guess it from whether an attempt is live.
+ * land, an ops task that changed tracked files (ADR-0020), or its runner's
+ * usage limit. Saved, so no surface has to guess it from whether an attempt
+ * is live.
  */
-type AwaitingReason = 'input' | 'checkpoint' | 'conflict' | 'files-changed';
+type AwaitingReason = 'input' | 'checkpoint' | 'conflict' | 'files-changed' | 'usage-limit';
 declare function isAwaitingReason(value: unknown): value is AwaitingReason;
 interface TaskModelAssignment {
     modelId: string;
@@ -714,14 +940,6 @@ interface TaskModelAssignment {
     availableVariants?: string[];
 }
 type RunnerId = string;
-/**
- * Bring loaded tasks to the structured-only shape, in place. A task saved
- * while the terminal transport existed may say it ran there, and why; neither
- * means anything now, and such a task left no session to continue. Its
- * completion marker id went with the text markers: completion is reported
- * only through `task_complete`.
- */
-declare function migrateLoadedTasks(tasks: readonly Task[]): void;
 /**
  * A task skill as one attempt received it: read from the task's own worktree
  * (or global) at spawn, kept so the user can see what the runner was told
@@ -750,15 +968,23 @@ interface Task {
     outputSummary?: TaskOutputSummary;
     assignedModel?: TaskModelAssignment;
     assignedRunner: RunnerId;
-    thinkingEffort?: string;
     taskMode?: TaskMode;
     autonomy?: 'AFK' | 'HITL';
     sliceType?: 'HITL' | 'AFK';
     userStoriesCovered?: string[];
     /** The runner's saved session for a later continue; cleared when a fresh attempt starts. */
     runnerSessionId?: string;
-    /** Set only while `status` is `awaiting_user`, and not always then — a usage-limit pause has none. */
+    /** Set only while `status` is `awaiting_user`, and not always then — a pause saved by an older build has none. */
     awaitingReason?: AwaitingReason;
+    /**
+     * When a task paused on its runner's usage limit is resumed on its own (ISO
+     * time): the reset the runner announced, plus a short margin. Absent when no
+     * reset time could be read or the user cancelled the resume — the task then
+     * waits for a manual retry. Set only with `awaitingReason` `usage-limit`.
+     */
+    resumeAt?: string;
+    /** Why the task was skipped, as whoever skipped it put it; set only while `status` is `skipped`, and not always then. */
+    skipReason?: string;
     /**
      * An ops task (ADR-0020): it changes no repository files, runs at the
      * workspace root rather than in a worktree, and waits for the change tasks
@@ -780,13 +1006,15 @@ interface Task {
     skills?: string[];
     /** The skills the latest attempt was given, as read when it spawned. */
     attemptSkills?: TaskSkillSnapshot[];
+    /**
+     * Who put the task in the plan, when it was not the user's own planning:
+     * `supervisor` for a task an Act supervisor added during a run, which
+     * counts as approved to run (ADR-0029). Set by the session, never by an op.
+     */
+    addedBy?: 'supervisor';
+    attemptUsage?: AttemptUsage[];
 }
-interface DiscoveredMode {
-    id: string;
-    label: string;
-    description: string;
-}
-type ResearchToolType = 'read_file' | 'read_files' | 'glob' | 'grep' | 'find_symbol' | 'list_dir' | 'bash' | 'fetch' | 'web_search' | 'spawn_research_agent'
+type ResearchToolType = 'read_file' | 'read_files' | 'glob' | 'grep' | 'find_symbol' | 'list_dir' | 'bash' | 'fetch' | 'web_search' | 'spawn_research_agent' | 'task_query' | 'task_output' | 'task_diff'
 /**
  * A tool belonging to a harness planner's own toolbox (ADR-0009) that has no
  * Ordewell equivalent — Edit, WebFetch, TodoWrite, whatever a coding agent
@@ -870,19 +1098,6 @@ interface ResearchProgress {
     digest?: string;
     usage?: UsageTotals;
 }
-interface ThinkingBlock {
-    id: string;
-    text: string;
-}
-interface StreamThinkingEvent {
-    type: 'thinking';
-    block: ThinkingBlock;
-}
-interface StreamStepEvent {
-    type: 'step';
-    step: ResearchStep;
-}
-type StreamEvent = StreamThinkingEvent | StreamStepEvent;
 interface DiscoveredModel {
     modelId: string;
     modelLabel: string;
@@ -933,12 +1148,21 @@ interface ConversationMessage {
      * user-triggered compaction left in place of the earlier messages — always
      * the transcript's first entry. 'skill_load' is a skill loaded into the
      * conversation, its snapshot in `skill`; one the user invoked follows the
-     * message that named it. Absent for ordinary chat turns, so sessions saved
-     * before markers existed degrade gracefully.
+     * message that named it. 'execution' is a call at the command seam
+     * (ADR-0029), its record in `execution`. 'wake_up' is the digest a wake-up
+     * gave the supervisor (role 'user': the model was told it), and
+     * 'supervisor' what the supervisor said in a wake-up turn (ADR-0029).
+     * Absent for ordinary chat turns, so sessions saved before markers existed
+     * degrade gracefully.
      */
-    kind?: 'plan_generated' | 'system' | 'compaction' | 'skill_load';
+    kind?: 'plan_generated' | 'system' | 'compaction' | 'skill_load' | 'execution' | 'wake_up' | 'supervisor';
+    actor?: 'Ordewell setting';
     /** Present exactly when `kind` is 'skill_load'. */
     skill?: SkillLoad;
+    /** Present exactly when `kind` is 'execution'. */
+    execution?: ExecutionRecord;
+    /** A user's message that was force sent, stopping the turn before it (ADR-0023). */
+    forced?: true;
 }
 /**
  * A skill's SKILL.md as it was when loaded into a planner conversation. A
@@ -964,24 +1188,65 @@ interface SkillLoad {
 }
 /** A skill load as a surface announces it — the body stays with the transcript. */
 type SkillLoadNotice = Omit<SkillLoad, 'content'>;
-/** A message the user sent, as opposed to a skill load their message caused. */
-declare function isUserMessage(entry: ConversationMessage): boolean;
+/** A message the user sent, as opposed to a skill load their message caused or a wake-up digest. */
+declare function isUserMessage(entry: Pick<ConversationMessage, 'role' | 'kind'>): boolean;
+/** A follow-up an older build queued behind a run's batch boundary; read only to carry it over as a {@link PendingPlanTurn}. */
 interface QueuedMessage {
     id: string;
     text: string;
     timestamp: string;
-    /** What its `/name` tokens loaded when it was sent: the drain composes them with the text, as a live send does. */
     skills?: SkillLoad[];
 }
-interface PlanModificationWarnings {
-    deletedCompleted: string[];
-    changedCompleted: string[];
-    deletedInProgress: string[];
-    modifiedInProgress: string[];
-    brokenDependencies: string[];
+/** Who a planner turn answers (ADR-0029): the user's message, or a wake-up batch the supervisor is given. */
+type PlanTurnSource = 'user' | 'supervisor';
+/**
+ * A planner turn's input not yet answered by a turn that ended. It leaves the
+ * plan with the change its turn made, in the same save, so a reload replays
+ * exactly the inputs no turn answered — once. A supervisor's input is a
+ * wake-up batch not yet delivered (ADR-0029): it stays until a turn lands
+ * with it, whatever turns fail meanwhile.
+ */
+interface PendingPlanTurn {
+    id: string;
+    source: PlanTurnSource;
+    /** The user's message, or a wake-up batch's digest. */
+    text: string;
+    timestamp: string;
+    /** What its `/name` tokens loaded when it was sent, so a replay sends the same skills. */
+    skills?: SkillLoad[];
+    /** Force sent: it waits ahead of every input not forced, and its turn is its own (ADR-0023, F2). */
+    forced?: true;
+}
+/**
+ * The run's own copy of the user's run settings (ADR-0030): taken when the
+ * user starts it, changed at once by a change made in this session, and
+ * lowered by a tripped guard or a failed supervisor.
+ */
+interface RunSettings {
+    mergeAtGatesAutomatically: boolean;
+    /** Absent on a run started before supervisor levels existed: Off. */
+    supervisorLevel?: SupervisorLevel;
+    /** Absent on a run started before ADR-0030: the user's setting. */
+    supervisorRetryLimit?: number;
+    /** Absent on a run started before ADR-0030: the user's setting. */
+    wakeUpReadBudget?: number;
+    /** Why the supervisor stopped for the rest of this run, which carries on as Off; absent while it watches. */
+    unsupervised?: string;
+}
+/**
+ * What supervision remembers across a daemon restart (ADR-0029): the loop
+ * guards' memory and the wake-up state not yet delivered with a turn.
+ */
+interface SupervisionSnapshot {
+    /** Retries, failed-attempt shapes, the supervisor's edits and what the user was told. */
+    guards?: SupervisionMemorySnapshot;
+    /** The events inside their debounce window and the wake-up rate's timestamps. */
+    wake?: SupervisorSnapshot;
 }
-declare function emptyWarnings(): PlanModificationWarnings;
 interface LegacyPlanState {
+    runSettings?: RunSettings;
+    /** What supervision remembers across a daemon restart (ADR-0029); absent on plans saved before it existed. */
+    supervision?: SupervisionSnapshot;
     tasks: Task[];
     generatedAt: string;
     status: PlanStatus;
@@ -992,7 +1257,9 @@ interface LegacyPlanState {
     conversationHistory?: ConversationMessage[];
     /** Full markdown PRD once written by the planner (PRD mode), also saved to .scratch/<slug>/PRD.md. */
     prdMarkdown?: string;
-    /** Follow-ups queued while tasks execute — applied as plan modifications between batches. */
+    /** Planner turn inputs no turn has answered yet (ADR-0029); a reload replays them. */
+    pendingTurns?: PendingPlanTurn[];
+    /** Written by builds that queued mid-run edits; a load moves it into {@link pendingTurns}. */
     queuedMessages?: QueuedMessage[];
     /**
      * The plan's isolation run (ADR-0013), written from the orchestrator at
@@ -1003,6 +1270,13 @@ interface LegacyPlanState {
     isolation?: PlanIsolation;
     /** Kept so a reopened session shows the same token line (#49). */
     plannerUsage?: PlannerUsage;
+    /**
+     * The tasks the user approved to run: every task when they executed the
+     * plan, and each one they started or retried themselves since. A command
+     * from anyone else starts only these (ADR-0029); a task the planner added
+     * after the approval waits for the user's.
+     */
+    approvedTasks?: string[];
 }
 interface Message {
     id: string;
@@ -1032,91 +1306,36 @@ type PlanState = {
     status: PlanStatus;
 };
 declare function migratePlanState(raw: unknown): PlanState;
-declare function migrateLegacyPlan(legacy: LegacyPlanState): PlanState;
 
 declare function createTask(overrides?: Partial<Task>): Task;
-declare function isSkillName(name: string): boolean;
-/**
- * The `skills` field as a task stores it, however it arrived: the planner's
- * JSON is untyped. Names are trimmed, lower-cased and deduplicated, and one
- * no skill could have is dropped; none at all is stored absent, so a plan
- * without skills reads exactly as it did before them.
- */
-declare function skillNames(value: unknown): string[] | undefined;
-/**
- * The skills of a task a merge or a split makes from others: what the edit
- * chose when it named any, none when it chose an explicit `[]`, else what the
- * tasks it came from had — a malformed value is not a request to drop them.
- */
-declare function inheritedSkills(chosen: unknown, inherited: readonly string[] | undefined): string[] | undefined;
-/**
- * The `ops` flag as a task stores it (ADR-0020), however it arrived. Only a
- * literal `true` on an AI task marks an ops task: the planner's JSON is
- * untyped, and a quoted "true" read as ops would move a task out of its
- * worktree. Anything else is a change task, stored absent so saved plans need
- * no migration. Whether the task may be ops at all — a subtask may not — is
- * for whoever knows where it sits: parsing drops the flag, an edit refuses it.
- */
-declare function opsFlag(value: unknown, type?: Task['type']): true | undefined;
-/**
- * The flag of a task a merge or a split makes from others: what the edit
- * chose, else ops only when every task it came from was. A merge that takes
- * in a change edits files, so it is a change; a split part runs where its
- * task did.
- */
-declare function inheritedOps(from: readonly Pick<Task, 'ops'>[], chosen?: boolean): boolean;
 /** The runner set a plan has until one is chosen: the one runner every host ships. */
 declare const DEFAULT_RUNNERS: readonly RunnerId[];
 declare function createEmptyPlan(): LegacyPlanState;
 declare function flattenTasks(tasks: readonly Task[]): Task[];
-/** A flattened task with the parent it hangs under, null for a top-level task. */
-interface TaskWithParent {
-    task: Task;
-    parent: Task | null;
-}
-declare function flattenTasksWithParents(tasks: readonly Task[]): TaskWithParent[];
-declare function migrateTask(task: Record<string, unknown>): Task;
-declare function addTaskToPlan(tasks: readonly Task[], partial: Partial<Task>): Task[];
-declare function removeTaskFromPlan(tasks: readonly Task[], taskId: string): Task[];
-declare function updateTaskInPlan(tasks: readonly Task[], taskId: string, changes: Partial<Task>): Task[];
-declare function renumberTasks(tasks: readonly Task[]): Task[];
 /**
- * Lay a planner-written task list over the plan it rewrites without letting it
- * change execution state. A planner restates tasks; it never witnessed one run,
- * so the status it writes is not evidence. A settled task is kept exactly as
- * it stands wherever the rewrite names it, and put back beside its old
- * neighbour where the rewrite leaves it out. Every other task keeps the status
- * it had; a task the rewrite adds starts pending.
+ * A phase-tagged plan rejoined into its tree. The execution log is flat — a
+ * finished subtask is logged on its own as well as inside its parent — and in
+ * the order tasks finished, so read as a list it puts subtasks at the top level
+ * under orders that clash with real top-level tasks. A task's own entry is the
+ * latest word on it: its parent's copy was taken when the parent last changed.
  */
-declare function keepExecutionState(current: readonly Task[], rewrite: Task[]): Task[];
-/** What only execution reads; {@link keepExecutionState} puts it back on whatever a planner returns. */
-declare const EXECUTION_ONLY: readonly ["attemptSkills", "runnerSessionId", "awaitingReason", "forcedPastGate", "outputSummary"];
-type PlannerTaskView = Omit<Task, typeof EXECUTION_ONLY[number] | 'subtasks'> & {
-    subtasks: PlannerTaskView[];
-};
+declare function rejoinPlanTree<T extends {
+    id: string;
+    order: number;
+    subtasks?: T[];
+}>(pending: readonly T[], log: readonly T[]): T[];
 /**
- * A task as a planner prompt carries it. An attempt's skill snapshots are
- * whole SKILL.md bodies and an output summary holds a log tail: sent on every
- * planner call, they cost tokens and invite the planner to edit state it does
- * not own.
+ * A flattened task with the parent it hangs under, null for a top-level task,
+ * and the path label and reference (`#2.1.3`) `TaskRefs` renders for it.
  */
-declare function plannerTaskView(task: Task): PlannerTaskView;
-declare function validateModifiedPlan(original: Task[], modified: Task[]): PlanModificationWarnings;
-interface ActiveTaskSession {
-    id: string;
-    taskId: string;
-}
-interface ValidationResult {
-    valid: boolean;
-    errors: string[];
-}
-interface ValidationContext {
-    executionLog: TaskSnapshot[];
-    oldPending: Task[];
-    newPending: Task[];
-    activeSessions: Map<string, ActiveTaskSession>;
+interface TaskWithParent {
+    task: Task;
+    parent: Task | null;
+    label: string;
+    ref: string;
 }
-type ValidationCheck = (ctx: ValidationContext) => ValidationResult;
-declare function warningsText(w: PlanModificationWarnings): string | null;
+declare function flattenTasksWithParents(tasks: readonly Task[]): TaskWithParent[];
+/** A task paused on its runner's usage limit, whether it resumes on its own or waits for the user (#84). */
+declare function pausedOnLimit(task: Readonly<Task>): boolean;
 
-export { type SkillLoad as $, type ActiveTaskSession as A, BUILTIN_SKILL_NAMES as B, type ConversationMessage as C, DEFAULT_RUNNERS as D, type PlanStatus as E, type PlannerTaskView as F, type PlannerUsage as G, type PreparedTask as H, type IWorktreeIsolation as I, type PreservedWork as J, type RepairEvidence as K, type LegacyPlanState as L, type Message as M, type RepoGroupLayout as N, type ResearchLogEntry as O, type PlanIsolation as P, type QueuedMessage as Q, type RefusedRemoval as R, type ResearchProgress as S, type ResearchStep as T, type ResearchStepOutcome as U, type ResearchToolType as V, type RunnerId as W, type ShadowedSkill as X, type SkillAppliesTo as Y, type SkillCatalog as Z, type SkillInfo as _, type AwaitingReason as a, warningsText as a$, type SkillLoadNotice as a0, type SkillMetadata as a1, type SkillSource as a2, SkillsService as a3, type StreamEvent as a4, type StreamStepEvent as a5, type StreamThinkingEvent as a6, type SubagentLogEntry as a7, type SubagentOutcome as a8, type Task as a9, createEmptyPlan as aA, createSkillsService as aB, createTask as aC, emptyWarnings as aD, flattenTasks as aE, flattenTasksWithParents as aF, inheritedOps as aG, inheritedSkills as aH, isAwaitingReason as aI, isMeasured as aJ, isSkillName as aK, isUserMessage as aL, keepExecutionState as aM, migrateLegacyPlan as aN, migrateLoadedTasks as aO, migratePlanState as aP, migrateTask as aQ, opsFlag as aR, partedPromptUsage as aS, plannerContextFill as aT, plannerTaskView as aU, removeTaskFromPlan as aV, renumberTasks as aW, skillNames as aX, updateTaskInPlan as aY, usageLine as aZ, validateModifiedPlan as a_, type TaskIsolation as aa, type TaskIsolationState as ab, type TaskMode as ac, type TaskModelAssignment as ad, type TaskOutputSummary as ae, type TaskSkillNotice as af, type TaskSkillSnapshot as ag, type TaskSnapshot as ah, type TaskStatus as ai, type TaskType as aj, type TaskWithParent as ak, type ThinkingBlock as al, type TreeSnapshot as am, type UsageLine as an, type UsageRecord as ao, type UsageTotals as ap, type UserPromptEntry as aq, type UserStep as ar, type ValidationCheck as as, type ValidationContext as at, type ValidationResult as au, type Verdict as av, type VerificationCheck as aw, addPlannerUsage as ax, addTaskToPlan as ay, addUsage as az, type DiscoveredMode as b, type DiscoveredModel as c, type IntegrationDisposal as d, type InvalidSkill as e, type IsolationAvailability as f, type IsolationHandoff as g, type IsolationHandoffRepo as h, type IsolationInactiveReason as i, type IsolationLandedTask as j, type IsolationLanding as k, type IsolationMergeBlock as l, type IsolationMergeBlockReason as m, type IsolationMergeResult as n, type IsolationOutcome as o, type IsolationPruneResult as p, type IsolationRemoval as q, type IsolationRepo as r, type IsolationRun as s, type IsolationTaskRecord as t, type IsolationTaskRef as u, type IsolationTaskRepo as v, type IsolationTaskStatus as w, type IsolationView as x, type PlanModificationWarnings as y, type PlanState as z };
+export { type RunnerId as $, type AttemptUsage as A, BUILTIN_SKILL_NAMES as B, type ConversationMessage as C, DEFAULT_RUNNERS as D, type ExecutionActor as E, type IsolationView as F, type GuardTarget as G, type PlanIsolation as H, type IWorktreeIsolation as I, type PlanState as J, type PlanStatus as K, type LegacyPlanState as L, type ModelUsage as M, type PlanUsage as N, type PlannerUsage as O, type PendingPlanTurn as P, type PreparedTask as Q, type PreservedWork as R, type RefusedRemoval as S, type RepairEvidence as T, type RepoGroupLayout as U, type ResearchLogEntry as V, type ResearchProgress as W, type ResearchStep as X, type ResearchStepOutcome as Y, type ResearchToolType as Z, type RunSettings as _, type AwaitingReason as a, type SetupFailure as a0, type ShadowedSkill as a1, type SkillAppliesTo as a2, type SkillCatalog as a3, type SkillInfo as a4, type SkillLoad as a5, type SkillLoadNotice as a6, type SkillMetadata as a7, type SkillSource as a8, SkillsService as a9, endAttemptUsage as aA, flattenTasks as aB, flattenTasksWithParents as aC, isAwaitingReason as aD, isMeasured as aE, isSupervisorLevel as aF, isUserMessage as aG, migratePlanState as aH, partedPromptUsage as aI, pausedOnLimit as aJ, planUsage as aK, plannerContextFill as aL, rejoinPlanTree as aM, startAttemptUsage as aN, usageLine as aO, type SubagentOutcome as aa, type SupervisorLevel as ab, type Task as ac, type TaskDiffRead as ad, type TaskDiffResult as ae, type TaskIsolation as af, type TaskIsolationState as ag, type TaskModelAssignment as ah, type TaskSkillNotice as ai, type TaskSkillSnapshot as aj, type TaskSnapshot as ak, type TaskStatus as al, type TreeSnapshot as am, type UsageLine as an, type UsageRecord as ao, type UsageTotals as ap, type Verdict as aq, type VerificationCheck as ar, addAttemptUsage as as, addModelUsage as at, addPlannerUsage as au, addUsage as av, addUsageTotals as aw, createEmptyPlan as ax, createSkillsService as ay, createTask as az, DEFAULT_SUPERVISOR_RETRY_LIMIT as b, type DiscoveredModel as c, type ExecutionCommandName as d, type ExecutionRecord as e, type GuardTrip as f, type IntegrationDisposal as g, type InvalidSkill as h, type IsolationAvailability as i, type IsolationHandoff as j, type IsolationHandoffRepo as k, type IsolationInactiveReason as l, type IsolationLandedTask as m, type IsolationLanding as n, type IsolationMergeBlock as o, type IsolationMergeBlockReason as p, type IsolationMergeResult as q, type IsolationOutcome as r, type IsolationPruneResult as s, type IsolationRemoval as t, type IsolationRepo as u, type IsolationRun as v, type IsolationTaskRecord as w, type IsolationTaskRef as x, type IsolationTaskRepo as y, type IsolationTaskStatus as z };