@ordewell/core 0.12.0 → 0.12.1

package/dist/{Task-BTEH-ztX.d.mts → Task-CxGgN6I0.d.mts}

@@ -5,7 +5,7 @@ declare const SEVERITY_LABEL: Record<FindingSeverity, string>;
 declare function severityLabel(severity: FindingSeverity): string;
 /** The worst severity among `findings`, or null for none: what a compact row says at a glance. */
 declare function worstSeverity(findings: readonly Pick<HandoffFinding, 'severity'>[]): FindingSeverity | null;
-/** The plan a pinned reference is under while every plan is the root's (ADR-0057 R1). */
+/** The root's plan: the node a pinned reference is under until a plan below names its own (ADR-0057 R1). */
 declare const ROOT_NODE = "root";
 /**
  * A typed reference a reader can check rather than trust. A `task` names the
@@ -26,16 +26,23 @@ type HandoffEvidence = {
     sha: string;
     repo?: string;
     resolved?: boolean;
-} | {
+} | TaskEvidence | {
+    kind: 'url';
+    url: string;
+};
+/**
+ * `label` is how the task's own plan names it, kept once a reference has
+ * crossed a level: a reader in another plan has no plan to name it from, and a
+ * task id can repeat between plans, so no plan names one that has it.
+ */
+interface TaskEvidence {
     kind: 'task';
     node?: string;
     task: string;
     attempt?: number;
     finding?: string;
-} | {
-    kind: 'url';
-    url: string;
-};
+    label?: string;
+}
 /**
  * What a saved patch does not carry as the task's worktree held it
  * (ADR-0050): `excluded`, a symbolic link or a submodule, never carried;
@@ -92,6 +99,41 @@ interface HandoffCommit {
     subject: string;
     body?: string;
 }
+/** A finding as it crossed a level (ADR-0057 R2): its author's words, by the reference that names it. A subplanner's own has none. */
+interface ReportItem {
+    ref?: TaskEvidence;
+    finding: HandoffFinding;
+}
+/**
+ * What a delegated task's report carries past any task's (ADR-0057 R2). All of
+ * it comes from Ordewell, the findings by reference, so what a subplanner left
+ * out shows and it cannot have reworded what it passes on. It is read once, as
+ * the report is taken, so the renderer stays a pure function of the digest:
+ * references are pinned, so the words cannot have moved.
+ */
+interface SubtreeReport {
+    /** The child plan's node: what a read of this report's subtree starts from. */
+    node: string;
+    counts: {
+        done: number;
+        failed: number;
+        blocked: number;
+        skipped: number;
+        commits: number;
+        tokens: number;
+    };
+    /** Every finding below, by severity, read from the latest attempt of each task. */
+    findings: Record<FindingSeverity, number>;
+    /** What the parent must decide. */
+    open: ReportItem[];
+    /** What the subplanner passed up. */
+    promoted: ReportItem[];
+    /** What its branch changed outside its declared scope, first paths and how many (ADR-0056 M7). */
+    outsideScope?: {
+        paths: string[];
+        count: number;
+    };
+}
 /** What the plan keeps on a task: enough for a surface or a dependent's prompt without reading a log. */
 interface HandoffDigest {
     commit?: HandoffCommit;
@@ -102,6 +144,10 @@ interface HandoffDigest {
     artifacts?: HandoffArtifact[];
     /** The attempt it is from, which a reference to it is pinned to (ADR-0057 R1); absent on a plan saved before it was kept. */
     attempt?: number;
+    /** A delegated task's: what Ordewell derived of its subtree. */
+    subtree?: SubtreeReport;
+    /** A delegated task's words with no {@link subtree} to say whose they are: a repair's, or a report that never opened a child. */
+    held?: true;
 }
 /** The whole handoff, as the attempt's log keeps it. */
 interface StoredHandoff extends HandoffDigest {
@@ -116,6 +162,7 @@ interface Handoff {
     findings?: Omit<HandoffFinding, 'id'>[];
     artifacts?: HandoffArtifact[];
     report?: string;
+    subtree?: SubtreeReport;
 }
 /** The most a report keeps: whole findings fit, and a runaway one does not bloat the files that hold it. */
 declare const REPORT_MAX_CHARS = 20000;
@@ -128,6 +175,7 @@ declare const HANDOFF_LIMITS: {
     readonly commitSubject: 100;
     readonly commitBody: 500;
     readonly findings: 50;
+    readonly promoted: 8;
     readonly title: 200;
     readonly detail: 2000;
     readonly reference: 2000;
@@ -159,6 +207,13 @@ interface WrittenTaskRef {
     attempt?: number;
     finding?: string;
 }
+/** The plan a written reference names below this one, `3/2:#4@2/F3`, and the rest as a plan reads it (ADR-0057 R1). */
+declare function parsePlanPath(written: string): {
+    path: string;
+    rest: string;
+} | undefined;
+/** A node's path as a reader writes it: `root/3/2` is `3/2`. */
+declare function nodeText(node: string): string;
 /**
  * The parts of a written reference, its task as written. What this cuts off
  * is no part of `TaskRefs`' grammar, which stays as it was; a caller tries the
@@ -182,7 +237,7 @@ declare function resolveWrittenRef(plan: readonly Task[], written: string): (Omi
  * reference naming no attempt takes the newest one cited. `asked` is an attempt
  * given apart from the text. Undefined when nothing it may read cites one.
  */
-declare function removedAttempt(plan: readonly Task[], readerId: string, logs: HandoffLogs, written: string, asked?: number): {
+declare function removedAttempt(plan: readonly Task[], readable: ReadonlySet<string>, logs: HandoffLogs, written: string, asked?: number): {
     taskId: string;
     attempt: number;
     finding?: string;
@@ -240,6 +295,12 @@ declare function savedPatchView(handoff: HandoffDigest | undefined): PatchView |
 declare function findingLines(f: HandoffFinding, taskName?: HandoffTaskName): string[];
 /** A handoff's artifacts as one line, or none when it lists none. */
 declare function artifactLines(handoff: HandoffDigest, taskName?: HandoffTaskName): string[];
+/** A delegated task's words as its parent's update holds them, every line indented, so none can pass for a line of Ordewell's (ADR-0057 R3). */
+declare function heldWords(text: string): string[];
+/** The same handoff, marked as a delegated task's where no report already says so: a mark that travels with it to whatever renders it. */
+declare function heldHandoff<H extends HandoffDigest>(task: {
+    type?: string;
+}, handoff: H): H;
 /** A handoff's opening as text: its commit, subject then body, then the summary. */
 declare function openingLines(handoff: HandoffDigest): string[];
 /**
@@ -302,7 +363,26 @@ interface HandoffPins {
     logs?: HandoffLogs;
     /** The attempt making the call: what a task naming itself is pinned to. */
     attempt?: number;
+    /** The plan these references are pinned under. Absent, the root's. */
+    node?: string;
+    /** What the producer may cite in `plan`, for one the plan's graph cannot give it: a subplanner, the plan below its own delegated task, is in none of its tasks' graphs. */
+    readable?: ReadonlySet<string>;
+    /** The plan at a path below this one that the producer may read; undefined for one it may not, or that is not there. */
+    below?: (path: string) => BelowPlan | undefined;
+    /** The handoff goes up a level, so what it cites keeps the name its plan gives it. */
+    crossing?: true;
 }
+/** A plan of the subtree, as a reference reads it. */
+interface BelowPlan {
+    node: string;
+    tasks: readonly Task[];
+    logs: HandoffLogs;
+}
+/**
+ * One written reference pinned, in the producer's plan or a plan below it:
+ * the text is tried whole first, since a title may read like a path.
+ */
+declare function pinReference(plan: readonly Task[], producerId: string, pins: HandoffPins, ref: TaskEvidence, field: string, findings: number, refuse: (why: string) => void): TaskEvidence | undefined;
 /**
  * Check the references a handoff makes, at the call (ADR-0047): a `task`
  * must be one the producer may read and a finding of it one that exists, and
@@ -319,6 +399,8 @@ interface HandoffPins {
 declare function checkHandoff<H extends Handoff>(handoff: H, producerId: string, plan: readonly Task[], pins?: HandoffPins): HandoffCheck<H>;
 
 interface TaskDiffRead {
+    /** Only the changed paths, joined by NUL: what a verdict reads (ADR-0055 D6). */
+    names?: boolean;
     repo?: string;
     path?: string;
 }
@@ -472,6 +554,8 @@ interface IsolationTaskRecord {
     status: IsolationTaskStatus;
     /** Keyed by repo path. */
     repos: Record<string, IsolationTaskRepo>;
+    /** The child session whose code root this worktree is (ADR-0055 D11): what stops a prune taking it from under that child (D17). */
+    childSession?: string;
     /** 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`. */
@@ -572,7 +656,13 @@ interface IsolationRepo {
  */
 interface IsolationRun {
     id: string;
+    /** The code root: what git reads for the run's repos, branch and base (ADR-0055 D11). */
     workspaceRoot: string;
+    /**
+     * A child run's state root, the root Session's workspace: where its worktrees
+     * and Ordewell's own files go. Absent on a flat run, whose workspace is both.
+     */
+    stateRoot?: string;
     repos: IsolationRepo[];
     /**
      * Workspace paths outside every isolated repo, linked live into each task
@@ -962,6 +1052,8 @@ interface IWorktreeIsolation {
      * each, and the config enabled; otherwise the reason it is not.
      */
     isActive(workspaceRoot: string): Promise<IsolationAvailability>;
+    /** What the git on this machine holds back, as the line the user is told; null when it does everything, or there is no git to speak of. */
+    gitShortfall(): Promise<string | null>;
     /**
      * Put the tracked changes of every dirty repo of the group on its git stash,
      * the user's way out of a `dirty` refusal. Untracked files stay: they never
@@ -971,9 +1063,11 @@ interface IWorktreeIsolation {
     /**
      * Mint a run: resolve each repo's base ref to a commit now, and share the
      * repos that cannot be isolated. Only meaningful after `isActive` said yes;
-     * throws when no repo of the group can be isolated after all.
+     * throws when no repo of the group can be isolated after all. `stateRoot`
+     * makes it a child's run (ADR-0055 D11), and it throws for a `workspaceRoot`
+     * that is not a task's workspace under that root (D12).
      */
-    startRun(workspaceRoot: string): Promise<IsolationRun>;
+    startRun(workspaceRoot: string, stateRoot?: string): Promise<IsolationRun>;
     /**
      * Create the task workspace — one worktree per isolated repo from its
      * integration tip, the shared paths linked in — and return the cwd to spawn
@@ -1002,6 +1096,13 @@ interface IWorktreeIsolation {
      * else: a task that fails stays `repairing` until released.
      */
     verifyRepair(task: Task, run: IsolationRun): Promise<RepairEvidence>;
+    /**
+     * The paths a repair brings onto the integration tip, by their place in the
+     * workspace: `repairBase` to the branch where the landing changed a repo, and
+     * the task's tip to it where it did not, since a repair can still edit that
+     * repo. Read after {@link verifyRepair} commits, before `integrate` moves the tip.
+     */
+    repairPaths?(task: Task, run: IsolationRun): Promise<string[]>;
     /**
      * Land the task atomically across the repos it changed: commit each
      * worktree, then `git merge --no-ff` the task branch into each changed
@@ -1071,6 +1172,14 @@ interface IWorktreeIsolation {
     /** 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>;
+    /**
+     * The blob `file` holds on `branch`, relative to `root`, the workspace
+     * (ADR-0057 R9): null where it holds none, undefined where nothing can be read.
+     * Refs are shared across worktrees, so a child reads an ancestor's branch too.
+     * A branch gone with its merged run reads as what `root` has checked out, which
+     * is where it merged.
+     */
+    blobOn?(root: string, branch: string, file: string): Promise<string | null | undefined>;
     /**
      * Read each landed task's mark again from git: on where the user's branch
      * contains its work in every repo it changed (`git merge-base --is-ancestor`),
@@ -1119,6 +1228,7 @@ interface IWorktreeIsolation {
      * Never a branch of `run` itself, one a worktree has checked out, or any
      * branch of a run that still has a worktree — that run may be live in
      * another plan. Tries every repo, then throws naming those where git failed.
+     * A child's run sweeps nothing (ADR-0055 D11).
      */
     sweep(run: IsolationRun): Promise<void>;
 }
@@ -1220,6 +1330,12 @@ declare function partedPromptUsage(parts: {
     cacheRead?: number;
     cacheWrite?: number;
 }): Pick<UsageRecord, 'inputTokens' | 'cachedInputTokens'>;
+/**
+ * What a budget counts (ADR-0056 M5), of a record or of totals alike: the same
+ * tokens a total holds, input and output. `cachedInputTokens` is a share of the
+ * input, so cache reads count, once.
+ */
+declare function spentTokens({ inputTokens, outputTokens }: Pick<UsageTotals, 'inputTokens' | 'outputTokens'>): number;
 declare function addUsage(totals: UsageTotals, record: UsageRecord): UsageTotals;
 /**
  * What the planner has consumed over a session (#49). `totals` includes every
@@ -1332,6 +1448,7 @@ interface PlanUsage {
 }
 declare function addUsageTotals(totals: UsageTotals, addition: UsageTotals): UsageTotals;
 interface UsageTask {
+    type?: string;
     attemptUsage?: readonly AttemptUsage[];
     subtasks?: readonly UsageTask[];
 }
@@ -1347,7 +1464,7 @@ interface TaskUsageSummary {
     attempts: number;
     contextFill?: ContextFill;
 }
-declare function taskUsageSummary(task: Pick<UsageTask, 'attemptUsage'>): TaskUsageSummary;
+declare function taskUsageSummary(task: Pick<UsageTask, 'attemptUsage' | 'type'>): TaskUsageSummary;
 /** `950`, `1.5k`, `61k`, `261k`, `1.2M`. */
 declare function formatTokenCount(n: number): string;
 /** Two decimals from 1 up and up to four below it: a call can cost a fraction of a cent, a session several dollars. */
@@ -1565,6 +1682,349 @@ declare class SkillsService {
  */
 declare function createSkillsService(workspaceRoot?: string, workspaceRepos?: readonly string[]): SkillsService;
 
+/** A script task's time limit when it sets none. */
+declare const DEFAULT_SCRIPT_TIMEOUT_MS: number;
+/** What a script task runs, its time limit filled in. */
+type ScriptBody = 
+/** Argument vectors run in order with no shell, stopping at the first that fails. */
+{
+    commands: string[][];
+    timeoutMs: number;
+}
+/** One script, run by the research shell's interpreter. */
+ | {
+    script: string;
+    timeoutMs: number;
+};
+type BodyFields = Pick<Task, 'type' | 'commands' | 'script' | 'timeoutMs'>;
+/** The body a script task runs; null for any other task, or one whose body the plan's rules refuse. */
+declare function scriptBodyOf(task: BodyFields): ScriptBody | null;
+/**
+ * An argument vector as a reader would type it in a shell: a word is quoted
+ * only where it needs to be, and one holding a character a reader cannot see
+ * is written with escapes (`$'…'`), so a command is always one line and reads
+ * as what runs. For reading only; nothing runs it.
+ */
+declare function commandLine(argv: readonly string[]): string;
+/**
+ * A script task's body as the approval card shows it (ADR-0035), so the
+ * consent is to what will run: each command on a line of its own, or the
+ * script as written, then the time limit. A character a reader cannot see in
+ * a script, but for its line breaks and tabs, is shown as its code.
+ */
+declare function scriptBodyText(body: ScriptBody): string;
+/**
+ * A script task as a row shows it: the body {@link scriptBodyText} gives the
+ * approval card, so what the user read when consenting is what the plan lists.
+ * A task whose body the plan's rules refuse says so rather than showing nothing.
+ */
+declare function scriptTaskText(task: BodyFields): string;
+/** A time limit in the largest units it is a whole number of: "10 minutes", "90 seconds". */
+declare function timeLimitText(ms: number): string;
+
+/**
+ * The planner's standing approvals (ADR-0026): what runs without asking
+ * anyone, under every approval mode.
+ *
+ * One entry is one of:
+ *
+ *   - a **command rule**, `gh issue list` or `gcloud * * list`: the binary,
+ *     then words matched against the command's leading arguments, the ones
+ *     before its first flag. A command whose leading words match the rule's
+ *     runs, whatever arguments follow — but the rule must spell out at least
+ *     the words the command's approval scope holds (ADR-0008, T1), so
+ *     `az group` never covers `az group delete`, and a one-word read takes a
+ *     `*` for its argument (`kubectl get *`). `*` stands for one word, and
+ *     inside a word for any run of characters (`describe-*`). An entry equal
+ *     to a scope also matches that scope, as pre-approved scopes always did.
+ *   - an **MCP tool rule**, `mcp:find-*`: a glob over the tool's own name,
+ *     without the server, case-insensitive.
+ *   - a **scope pattern**, anything starting with `/`, `~`, `http://`,
+ *     `https://`, `web_search:`, `mcp__`, `mcp-server:` or a drive letter: matched against an approval's
+ *     scope as ADR-0008 always matched pre-approved entries, `*` matching any
+ *     run of characters.
+ *
+ * A leading `!` excludes instead, and an exclusion wins over every rule. A
+ * command exclusion's words are looked for anywhere among the arguments, in
+ * order, flags included and case ignored, so `!kubectl *secret*` and
+ * `!* --endpoint*` hold wherever the word appears; a lone short flag (`-s`)
+ * also holds inside a bundle (`-As`, `-shost`). `*` as its binary covers
+ * every command.
+ */
+/** The words a command rule is matched against: a lexed segment's binary and arguments. */
+interface CommandWords {
+    binary: string;
+    args: readonly string[];
+    /** How many leading arguments the command's approval scope holds; a rule must cover at least that many. */
+    scopeWords?: number;
+}
+interface RuleWord {
+    matches: (word: string) => boolean;
+    wildcard: boolean;
+}
+interface CommandRule {
+    text: string;
+    binary: string;
+    words: RuleWord[];
+}
+interface PlannerAllowlist {
+    commands: CommandRule[];
+    commandExclusions: CommandRule[];
+    tools: RegExp[];
+    toolExclusions: RegExp[];
+    scopes: RegExp[];
+    scopeExclusions: RegExp[];
+}
+declare function parseAllowlist(entries: readonly string[]): PlannerAllowlist;
+/** The rule that lets this command run unasked, or undefined when none does or an exclusion holds. */
+declare function commandAllowedBy(list: PlannerAllowlist, command: CommandWords): string | undefined;
+/** Whether an MCP tool, by its own name without the server, runs unasked. */
+declare function toolAllowed(list: PlannerAllowlist, tool: string): boolean;
+/** Whether an approval scope — a directory, an origin, a tool's full name — is pre-approved. */
+declare function scopeAllowed(list: PlannerAllowlist, scope: string): boolean;
+/**
+ * Read-only command families that are safe to run unasked: they read, never
+ * write a file or change a resource, and need no argument that runs code.
+ * Absent on purpose: commands that run the repository's own code (test
+ * runners, builds, package scripts, a package manager the repository pins or
+ * extends — on an untrusted repository someone else wrote that code), commands
+ * a repository's own config can point at another endpoint with the user's
+ * credentials (`.npmrc`, `.sentryclirc`, a Terraform or Pulumi backend), and
+ * commands whose usual output is a secret.
+ */
+declare const DEFAULT_PLANNER_ALLOWLIST: readonly string[];
+
+/** A delegated task's budget: tokens, and optionally wall-clock time (ADR-0056 M5). */
+interface DelegatedBudget {
+    tokens: number;
+    wallClockMs?: number;
+}
+/** Where a child plan's tasks stand now: the counts a delegated task's row shows while its child runs (ADR-0055 D20). */
+interface ChildTaskCounts {
+    completed: number;
+    running: number;
+    /** Waiting on a person, a checkpoint among them. */
+    waiting: number;
+    pending: number;
+    failed: number;
+    skipped: number;
+}
+/**
+ * What a delegated task's row says beyond any task's (ADR-0055 D16, D20): all of
+ * it derived where it is read, from the child's plan, the tree's ledger and the
+ * Stop, never kept. Every part is absent when there is nothing to say.
+ */
+interface DelegatedRow {
+    /** The child's tasks by where they stand; absent with no child session open. */
+    tasks?: ChildTaskCounts;
+    /** The task's token budget, and what the tree has not yet spent of it, across every child it has had (ADR-0056 M10). */
+    tokens?: {
+        budget: number;
+        left: number;
+    };
+    /** A Stop is still winding the subtree down, though the task already reads as not started (D16). */
+    stopping?: true;
+}
+/** What a task declares it works on (ADR-0057 R6). Advisory: nothing gates on it. */
+interface TaskScope {
+    paths?: string[];
+    provides?: string[];
+    consumes?: string[];
+}
+/** Something a check is made of. A `command` is the check itself at any length, where prose says little until it has some. */
+interface CheckWord {
+    text: string;
+    command: boolean;
+}
+
+/**
+ * The effect allowlist (ADR-0035): the user's standing approval for named
+ * effects, beside the planner allowlist, which names reads. It pre-approves a
+ * script task whose `commands` are all covered; it never covers a `script`
+ * body, whose shell text no rule can be matched against.
+ *
+ * A rule is matched against the whole command, every word in order and flags
+ * included, because an effect's flags change what it does: `git push origin
+ * feature/*` covers `git push origin feature/login`, never the same push with
+ * `--force`. `*` stands for one word, or inside a word for any run of
+ * characters, as in the planner allowlist, except that it never stands for
+ * what changes the effect: a flag (`--force`, and `/force` on Windows), a
+ * refspec's force or delete (`+main`, `:main`), or a `:` outside a URL
+ * (`feature/x:main`, which pushes to `main`). The rule writes any of those
+ * itself. A rule spells out its operation before any `*`, so
+ * `az webapp config * set` is no rule at all.
+ *
+ * Exclusions are the planner allowlist's `!` entries, with any `!` entry
+ * written here; an exclusion wins. A command exclusion is matched as the
+ * planner allowlist matches it; a path or URL exclusion holds for an argument
+ * that names an absolute path or URL it covers, whole or after a `=`, `@`,
+ * `:` or `,` or a short flag (`--url=…`, `-d @…`). A relative path is not
+ * resolved, since the body does not say where it runs. A program named by its
+ * path is a file the repository ships (ADR-0026), so it is never covered.
+ * There are no built-in rules: a default would pre-approve an effect the user
+ * never chose.
+ */
+interface EffectRule {
+    text: string;
+    binary: string;
+    words: RuleWord[];
+}
+interface EffectRules {
+    rules: EffectRule[];
+    exclusions: PlannerAllowlist;
+    platform: NodeJS.Platform;
+    /** The entries that are no rule, each with the warning that says why it is ignored. */
+    ignored: {
+        rule: string;
+        warning: string;
+    }[];
+}
+/**
+ * `entries` are the effect allowlist's; `plannerEntries` the planner allowlist
+ * in force, whose `!` entries hold here too; `platform` the one the commands
+ * run on, which decides how a flag is spelled and how a path resolves.
+ */
+declare function parseEffectAllowlist(entries: readonly string[], plannerEntries?: readonly string[], platform?: NodeJS.Platform): EffectRules;
+/**
+ * The rules, by name, that cover every command of a `commands` body, or null
+ * when one command is not covered, an exclusion holds for one, or the body is
+ * a `script`.
+ */
+declare function effectRuleFor(list: EffectRules, body: ScriptBody): string | null;
+
+/**
+ * The mandate (ADR-0056): what a node may do without a person, and within what
+ * limits. The root's is derived on each read from today's settings and never
+ * saved; a child's is one pure function of its parent's and its request, which
+ * can only narrow what the parent may hand on. Authority only: capability stays
+ * at the boundary a session runs in, and a prompt enforces nothing.
+ */
+declare const GRANTS: readonly ["observe", "steer", "control", "replan", "approve", "delegate", "effect", "research", "merge"];
+/** Each is a set of things a node may do unasked (M2). */
+type Grant = (typeof GRANTS)[number];
+/** What a mandate could not finish without: a child holds these unasked, and `narrow` refuses one that would lack any (M2). */
+declare const FLOOR_GRANTS: readonly Grant[];
+/** The shape of a tree, by ADR-0055 D19: refused past the hard cap, never dropped. */
+declare const SHAPE_LIMITS: {
+    readonly depth: {
+        readonly default: 2;
+        readonly hard: 4;
+    };
+    readonly delegatedTasks: {
+        readonly default: 8;
+        readonly hard: 30;
+    };
+    readonly tasksPerPlan: {
+        readonly default: 30;
+        readonly hard: 100;
+    };
+};
+interface MandateLimits {
+    /** The node's token budget; the root's is the tree's, from the delegation setting (M3, M5). */
+    tokens: number;
+    /** Null: no limit, which only the root has. */
+    wallClockMs: number | null;
+    /** How many levels may still open below this node. */
+    depth: number;
+    delegatedTasks: number;
+    tasksPerPlan: number;
+    runners: readonly RunnerId[];
+    /** The models a runner is held to; a runner not named may use any it offers, as the user's allowlist reads. */
+    models: Readonly<Record<RunnerId, readonly string[]>>;
+}
+interface MandateExclusions {
+    protectedPaths: readonly string[];
+}
+interface Mandate {
+    /** What this node may do. */
+    grants: ReadonlySet<Grant>;
+    /** What it may hand a child. */
+    grantable: ReadonlySet<Grant>;
+    /** Read in place of the global level. */
+    autonomy: 'full' | 'guarded';
+    limits: MandateLimits;
+    /** These only accumulate. */
+    exclusions: MandateExclusions;
+    /** One per level, each with its own `!` rules: a command must match at every level (M4). */
+    effectRules: readonly EffectRules[];
+    /** The level of `effectRules` this node's own request added: all of it a node keeps, the levels above being read as they stand (M1). */
+    ownEffectRules: readonly EffectRules[];
+}
+/** What the root's mandate is read from, each where it lives today (M1). */
+interface RootSettings {
+    /** The run's own copy: where a guard or a failure lowers it, and the user's change lands. */
+    level: SupervisorLevel;
+    autorun: boolean;
+    autonomous: boolean;
+    /** The tree's budget; 0 is delegation off (ADR-0055 D21). */
+    delegationTokens: number;
+    /** The effect allowlist, absent where nothing was read. */
+    effects?: EffectRules;
+    runners: readonly RunnerId[];
+    models: Readonly<Record<RunnerId, readonly string[]>>;
+}
+/** What a delegated task asks of the mandate it is given. `grants` names what it asks for past the floor; absent asks for nothing. */
+interface MandateRequest {
+    /** The level of the node narrowing, the root being 0: the one a refusal names. */
+    level: number;
+    grants?: readonly Grant[];
+    autonomy?: Mandate['autonomy'];
+    /** A delegated task must carry one (M5). */
+    tokens?: number;
+    wallClockMs?: number;
+    depth?: number;
+    delegatedTasks?: number;
+    tasksPerPlan?: number;
+    runners?: readonly RunnerId[];
+    models?: Readonly<Record<RunnerId, readonly string[]>>;
+    protectedPaths?: readonly string[];
+    effectRules?: EffectRules;
+}
+interface MandateRefusal {
+    level: number;
+    field: string;
+    asked: string;
+    there: string;
+}
+type Narrowed = {
+    ok: true;
+    mandate: Mandate;
+} | {
+    ok: false;
+    refusal: MandateRefusal;
+};
+declare function mandateRefusalText({ level, field, asked, there }: MandateRefusal): string;
+/**
+ * The root's mandate, as it stands now (M1): built afresh on each read, so an
+ * Act that a guard lowered reads Watch at the next check, and nothing saved
+ * could disagree with the settings.
+ */
+declare function rootMandate(settings: RootSettings): Mandate;
+/**
+ * What holds at a node now (M1): its saved mandate within every ancestor's
+ * `grantable` as it stands, under every ancestor's effect rules as they stand,
+ * so a change at the root reaches the subtree at the next check. This reading
+ * intersects and refuses nothing: the floor binds {@link narrow}, which writes
+ * a new child, not this.
+ */
+declare function heldMandate(saved: Mandate, ancestors: readonly Mandate[]): Mandate;
+/**
+ * A child's mandate (M4), or the refusal that names the level that refused,
+ * the field, what was asked and what is there. Pure, and written to be proved:
+ * no result is wider than its parent. `parent.limits.tokens` and `wallClockMs`
+ * are what the parent has left, which is the caller's to read.
+ */
+declare function narrow(parent: Mandate, request: MandateRequest): Narrowed;
+/** What a node reads of its own authority, at each check (M1). */
+interface NodeAuthority {
+    /** How far below the root, which is 0 and where a person remains. */
+    readonly depth: number;
+    /** The mandate that holds now. `level` is what the root's is read at; a child's does not depend on it. */
+    mandate(level: SupervisorLevel): Mandate;
+}
+/** The root: its settings read as each check asks, the level included, which each caller names. */
+declare function rootAuthority(settings: () => Omit<RootSettings, 'level'>): NodeAuthority;
+
 /** How many times a loop's check runs when the loop sets no `maxRounds`. */
 declare const DEFAULT_LOOP_ROUNDS = 3;
 /** The most rounds a loop may set: past it, the fix is not converging, and a person should look. */
@@ -1698,7 +2158,7 @@ interface EditMemory {
  * It wakes the planner whatever the supervisor's level, since the planner
  * asked for it.
  */
-type RunEventKind = 'task_passed' | 'task_failed' | 'waiting_input' | 'waiting_approval' | 'task_idle' | 'landing_conflict' | 'usage_limit' | 'auto_merge_stopped' | 'run_finished' | 'task_report';
+type RunEventKind = 'task_passed' | 'task_failed' | 'waiting_input' | 'waiting_approval' | 'approval_denied' | 'task_idle' | 'landing_conflict' | 'usage_limit' | 'auto_merge_stopped' | 'start_refused' | 'run_finished' | 'task_report';
 type RunEvent = {
     kind: RunEventKind;
     taskId?: string;
@@ -1755,7 +2215,7 @@ interface UserStep {
  * `script_exit` is a script task's exit status, its one evidence (ADR-0035).
  */
 interface VerificationCheck {
-    name: 'exit_code' | 'completion_marker' | 'task_complete' | 'manual' | 'script_exit';
+    name: 'exit_code' | 'completion_marker' | 'task_complete' | 'manual' | 'script_exit' | 'protected_paths';
     passed: boolean;
     /** A check that did not apply. Skipped checks don't affect the verdict. */
     skipped: boolean;
@@ -1786,8 +2246,11 @@ interface TaskOutputSummary {
     logTail: string;
     capturedAt: string;
 }
-/** `script` is an ops task whose body Ordewell runs with no model (ADR-0035). */
-type TaskType = 'ai' | 'user' | 'script';
+/**
+ * `script` is an ops task whose body Ordewell runs with no model (ADR-0035);
+ * `delegated` holds a goal, and its attempt is a child plan (ADR-0055).
+ */
+type TaskType = 'ai' | 'user' | 'script' | 'delegated';
 /**
  * `skipped` is terminal and verdict-less: the task will not be waited for, and
  * nothing it did lands. Its dependents go ahead without it once the work it
@@ -1804,7 +2267,7 @@ type TaskMode = string;
  * usage limit. Saved, so no surface has to guess it from whether an attempt
  * is live.
  */
-type AwaitingReason = 'input' | 'checkpoint' | 'conflict' | 'files-changed' | 'usage-limit';
+type AwaitingReason = 'input' | 'checkpoint' | 'question-lost' | 'conflict' | 'files-changed' | 'usage-limit';
 declare function isAwaitingReason(value: unknown): value is AwaitingReason;
 interface TaskModelAssignment {
     modelId: string;
@@ -1869,6 +2332,12 @@ interface Task {
     runnerSessionOwner?: RunnerId;
     /** Set only while `status` is `awaiting_user`, and not always then — a pause saved by an older build has none. */
     awaitingReason?: AwaitingReason;
+    /**
+     * The question a delegated task's subplanner is parked on (ADR-0056 M8). The
+     * live one is held in memory by what answers it, so this copy is only what a
+     * restart can still say was lost (ADR-0055 D17). Goes with the wait.
+     */
+    parkedQuestion?: string;
     /**
      * How many waits have ended since its latest attempt started, or since the
      * task was written if none has: an attempt can wait many times, and this
@@ -1945,6 +2414,22 @@ interface Task {
     script?: string;
     /** A script task's time limit; absent means ten minutes (`DEFAULT_SCRIPT_TIMEOUT_MS`). */
     timeoutMs?: number;
+    /** What a delegated task's child plan must achieve, in place of a prompt (ADR-0055 D1). */
+    goal?: string;
+    /** A delegated task's budget (ADR-0056 M5). */
+    budget?: DelegatedBudget;
+    /** What a delegated task asks for past the floor; absent asks for nothing (ADR-0056 M2). */
+    grants?: Grant[];
+    /** The paths a delegated task's child may not change, what its check runs among them (ADR-0055 D7). */
+    protectedPaths?: string[];
+    /** What a delegated task declares it works on (ADR-0057 R6). */
+    scope?: TaskScope;
+    /**
+     * On a delegated task, it answers a question and lands nothing (ADR-0055 D1).
+     * On a script task, it runs sealed in a throwaway worktree, past no gate (D8).
+     * A read-only AI task says so by its mode (ADR-0031) and stores none.
+     */
+    readOnly?: boolean;
     /** Set on a loop's check (ADR-0045): the tasks that fix what it finds, and how many times it may run. */
     loop?: TaskLoop;
     /**
@@ -2270,6 +2755,8 @@ interface PendingPlanTurn {
      * the run. While the user has stopped all of them it opens no turn (ADR-0029).
      */
     tasks?: string[];
+    /** It goes with the next turn and opens none (ADR-0057 R6). */
+    rides?: true;
 }
 /**
  * The run's own copy of the user's run settings (ADR-0030): taken when the
@@ -2467,4 +2954,4 @@ type ApprovalRecord = Pick<LegacyPlanState, 'approved' | 'approvedTasks'>;
  */
 declare function waitsForApproval(task: Pick<Task, 'id' | 'type' | 'status'>, record: ApprovalRecord): boolean;
 
-export { type IsolationRevertTask as $, type ApprovalRecord as A, BUILTIN_SKILL_NAMES as B, type ContextCheckpoint as C, DEFAULT_LOOP_ROUNDS as D, type ExecutionActor as E, type FindingSeverity as F, type GuardTarget as G, HANDOFF_LIMITS as H, type IIsolationPreview as I, type IntegrationDisposal as J, type InvalidSkill as K, type IsolationAvailability as L, type IsolationHandoff as M, type IsolationHandoffRepo as N, type IsolationInactiveReason as O, type IsolationLandedTask as P, type IsolationLanding as Q, type IsolationMergeBlock as R, type IsolationMergeBlockReason as S, type IsolationMergeResult as T, type IsolationOutcome as U, type IsolationPreview as V, type IsolationPruneResult as W, type IsolationRemoval as X, type IsolationRepo as Y, type IsolationRepoRevert as Z, type IsolationRevertResult as _, type AttemptUsage as a, type SubagentOutcome as a$, type IsolationRun as a0, type IsolationTaskRecord as a1, type IsolationTaskRef as a2, type IsolationTaskRepo as a3, type IsolationTaskStatus as a4, type IsolationView as a5, type LandedTask as a6, type LandedWork as a7, type LegacyPlanState as a8, type LoopSubject as a9, type RepoHead as aA, type ReportedWindow as aB, type ResearchLogEntry as aC, type ResearchProgress as aD, type ResearchStep as aE, type ResearchStepOutcome as aF, type ResearchToolType as aG, type RevertCommand as aH, type RevertWatch as aI, type RunSettings as aJ, type RunnerId as aK, type RunnerSessionCost as aL, SEVERITY_LABEL as aM, type ScriptConsent as aN, type ScriptResult as aO, type SessionBilling as aP, type SetupFailure as aQ, type ShadowedSkill as aR, type SkillAppliesTo as aS, type SkillCatalog as aT, type SkillInfo as aU, type SkillLoad as aV, type SkillLoadNotice as aW, type SkillMetadata as aX, type SkillSource as aY, SkillsService as aZ, type StoredHandoff as a_, MAX_LOOP_ROUNDS as aa, type ModelUsage as ab, type PatchFlag as ac, type PatchView as ad, type PendingPlanTurn as ae, type PlanIsolation as af, type PlanState as ag, type PlanStatus as ah, type PlanUsage as ai, type PlannerCompaction as aj, type PlannerCompactionOutcome as ak, type PlannerContextPause as al, type PlannerResendState as am, type PlannerUsage as an, type PrepareIntent as ao, type PreparedTask as ap, type PreservedWork as aq, type PreviewRepo as ar, type PreviousWork as as, REPORT_MAX_CHARS as at, ROOT_NODE as au, type RefusedRemoval as av, type RepairEvidence as aw, type RepairWait as ax, type ReplyRun as ay, type RepoGroupLayout as az, type AwaitingReason as b, openingLines as b$, type SupervisorLevel as b0, type Task as b1, type TaskDiffRead as b2, type TaskDiffResult as b3, type TaskIsolation as b4, type TaskIsolationState as b5, type TaskLoop as b6, type TaskModelAssignment as b7, type TaskReportTo as b8, type TaskSkillNotice as b9, costText as bA, countedSessionCost as bB, createEmptyPlan as bC, createSkillsService as bD, createTask as bE, endAttemptUsage as bF, findingLines as bG, findingRefText as bH, flattenTasks as bI, flattenTasksWithParents as bJ, formatCost as bK, formatTokenCount as bL, handoffDigest as bM, handoffLines as bN, handoffPreviewLines as bO, handoffReferenceText as bP, handoffWakeLines as bQ, inLoop as bR, isAwaitingReason as bS, isMeasured as bT, isSupervisorLevel as bU, isUserMessage as bV, loopRemovalRefusal as bW, loopRoundOf as bX, migratePlanState as bY, modelCostTitle as bZ, namedHandoff as b_, type TaskSkillSnapshot as ba, type TaskSnapshot as bb, type TaskStatus as bc, type TaskType as bd, type TaskUsageSummary as be, type TreeSnapshot as bf, type UsageLine as bg, type UsageRecord as bh, type UsageTotals as bi, type Verdict as bj, type VerificationCheck as bk, type WrittenTaskRef as bl, actorAuthority as bm, addAttemptUsage as bn, addModelUsage as bo, addPlannerUsage as bp, addUsage as bq, addUsageTotals as br, artifactLines as bs, betweenRounds as bt, boundedHandoffLines as bu, byteSize as bv, checkHandoff as bw, checkOf as bx, contextMeterText as by, contextMeterTitle as bz, type ContextFill as c, outOfRounds as c0, parseFindingRef as c1, partedPromptUsage as c2, patchChangesText as c3, patchFlagText as c4, patchLines as c5, patchLinesText as c6, patchText as c7, patchView as c8, pausedOnLimit as c9, planUsage as ca, plannerContextFill as cb, readableTaskIds as cc, rejoinPlanTree as cd, removedAttempt as ce, resolveWrittenRef as cf, resumedSessionWindow as cg, savedPatchOf as ch, savedPatchView as ci, savedPatchViews as cj, severityLabel as ck, startAttemptUsage as cl, storedHandoff as cm, subagentCostTitle as cn, taskUsageSummary as co, tasksTotalText as cp, usageLine as cq, usageText as cr, waitsForApproval as cs, withPatch as ct, wordsFrom as cu, worstSeverity as cv, type ConversationMessage as d, type CostProvenance as e, DEFAULT_RUNNERS as f, DEFAULT_SUPERVISOR_RETRY_LIMIT as g, DIGEST_FINDINGS as h, type DiscoveredModel as i, type ExecutionCommandName as j, type ExecutionRecord as k, type GuardTrip as l, HANDOFF_PUSH_CHARS as m, type Handoff as n, type HandoffArtifact as o, type HandoffCheck as p, type HandoffCommit as q, type HandoffDigest as r, type HandoffEvidence as s, type HandoffFinding as t, type HandoffLogs as u, type HandoffPatch as v, type HandoffPins as w, type HandoffPreviewOptions as x, type HandoffTaskName as y, type IWorktreeIsolation as z };
+export { type IsolationLanding as $, type ApprovalRecord as A, BUILTIN_SKILL_NAMES as B, type CheckWord as C, DEFAULT_LOOP_ROUNDS as D, type EffectRules as E, FLOOR_GRANTS as F, GRANTS as G, HANDOFF_LIMITS as H, type HandoffCheck as I, type HandoffCommit as J, type HandoffDigest as K, type HandoffEvidence as L, type HandoffFinding as M, type HandoffLogs as N, type HandoffPatch as O, type HandoffPins as P, type HandoffPreviewOptions as Q, type HandoffTaskName as R, type IIsolationPreview as S, type IWorktreeIsolation as T, type IntegrationDisposal as U, type InvalidSkill as V, type IsolationAvailability as W, type IsolationHandoff as X, type IsolationHandoffRepo as Y, type IsolationInactiveReason as Z, type IsolationLandedTask as _, type AttemptUsage as a, type RevertCommand as a$, type IsolationMergeBlock as a0, type IsolationMergeBlockReason as a1, type IsolationMergeResult as a2, type IsolationOutcome as a3, type IsolationPreview as a4, type IsolationPruneResult as a5, type IsolationRemoval as a6, type IsolationRepo as a7, type IsolationRepoRevert as a8, type IsolationRevertResult as a9, type PlanUsage as aA, type PlannerAllowlist as aB, type PlannerCompaction as aC, type PlannerCompactionOutcome as aD, type PlannerContextPause as aE, type PlannerResendState as aF, type PlannerUsage as aG, type PrepareIntent as aH, type PreparedTask as aI, type PreservedWork as aJ, type PreviewRepo as aK, type PreviousWork as aL, REPORT_MAX_CHARS as aM, ROOT_NODE as aN, type RefusedRemoval as aO, type RepairEvidence as aP, type RepairWait as aQ, type ReplyRun as aR, type RepoGroupLayout as aS, type RepoHead as aT, type ReportItem as aU, type ReportedWindow as aV, type ResearchLogEntry as aW, type ResearchProgress as aX, type ResearchStep as aY, type ResearchStepOutcome as aZ, type ResearchToolType as a_, type IsolationRevertTask as aa, type IsolationRun as ab, type IsolationTaskRecord as ac, type IsolationTaskRef as ad, type IsolationTaskRepo as ae, type IsolationTaskStatus as af, type IsolationView as ag, type LandedTask as ah, type LandedWork as ai, type LegacyPlanState as aj, type LoopSubject as ak, MAX_LOOP_ROUNDS as al, type Mandate as am, type MandateExclusions as an, type MandateLimits as ao, type MandateRefusal as ap, type MandateRequest as aq, type ModelUsage as ar, type Narrowed as as, type NodeAuthority as at, type PatchFlag as au, type PatchView as av, type PendingPlanTurn as aw, type PlanIsolation as ax, type PlanState as ay, type PlanStatus as az, type AwaitingReason as b, costText as b$, type RevertWatch as b0, type RootSettings as b1, type RunSettings as b2, type RunnerId as b3, type RunnerSessionCost as b4, SEVERITY_LABEL as b5, SHAPE_LIMITS as b6, type ScriptBody as b7, type ScriptConsent as b8, type ScriptResult as b9, type TaskSnapshot as bA, type TaskStatus as bB, type TaskType as bC, type TaskUsageSummary as bD, type TreeSnapshot as bE, type UsageLine as bF, type UsageRecord as bG, type UsageTotals as bH, type Verdict as bI, type VerificationCheck as bJ, type WrittenTaskRef as bK, actorAuthority as bL, addAttemptUsage as bM, addModelUsage as bN, addPlannerUsage as bO, addUsage as bP, addUsageTotals as bQ, artifactLines as bR, betweenRounds as bS, boundedHandoffLines as bT, byteSize as bU, checkHandoff as bV, checkOf as bW, commandAllowedBy as bX, commandLine as bY, contextMeterText as bZ, contextMeterTitle as b_, type SessionBilling as ba, type SetupFailure as bb, type ShadowedSkill as bc, type SkillAppliesTo as bd, type SkillCatalog as be, type SkillInfo as bf, type SkillLoad as bg, type SkillLoadNotice as bh, type SkillMetadata as bi, type SkillSource as bj, SkillsService as bk, type StoredHandoff as bl, type SubagentOutcome as bm, type SubtreeReport as bn, type SupervisorLevel as bo, type Task as bp, type TaskDiffRead as bq, type TaskDiffResult as br, type TaskEvidence as bs, type TaskIsolation as bt, type TaskIsolationState as bu, type TaskLoop as bv, type TaskModelAssignment as bw, type TaskReportTo as bx, type TaskSkillNotice as by, type TaskSkillSnapshot as bz, type BelowPlan as c, scriptTaskText as c$, countedSessionCost as c0, createEmptyPlan as c1, createSkillsService as c2, createTask as c3, effectRuleFor as c4, endAttemptUsage as c5, findingLines as c6, findingRefText as c7, flattenTasks as c8, flattenTasksWithParents as c9, parseEffectAllowlist as cA, parseFindingRef as cB, parsePlanPath as cC, partedPromptUsage as cD, patchChangesText as cE, patchFlagText as cF, patchLines as cG, patchLinesText as cH, patchText as cI, patchView as cJ, pausedOnLimit as cK, pinReference as cL, planUsage as cM, plannerContextFill as cN, readableTaskIds as cO, rejoinPlanTree as cP, removedAttempt as cQ, resolveWrittenRef as cR, resumedSessionWindow as cS, rootAuthority as cT, rootMandate as cU, savedPatchOf as cV, savedPatchView as cW, savedPatchViews as cX, scopeAllowed as cY, scriptBodyOf as cZ, scriptBodyText as c_, formatCost as ca, formatTokenCount as cb, handoffDigest as cc, handoffLines as cd, handoffPreviewLines as ce, handoffReferenceText as cf, handoffWakeLines as cg, heldHandoff as ch, heldMandate as ci, heldWords as cj, inLoop as ck, isAwaitingReason as cl, isMeasured as cm, isSupervisorLevel as cn, isUserMessage as co, loopRemovalRefusal as cp, loopRoundOf as cq, mandateRefusalText as cr, migratePlanState as cs, modelCostTitle as ct, namedHandoff as cu, narrow as cv, nodeText as cw, openingLines as cx, outOfRounds as cy, parseAllowlist as cz, type ChildTaskCounts as d, severityLabel as d0, spentTokens as d1, startAttemptUsage as d2, storedHandoff as d3, subagentCostTitle as d4, taskUsageSummary as d5, tasksTotalText as d6, timeLimitText as d7, toolAllowed as d8, usageLine as d9, usageText as da, waitsForApproval as db, withPatch as dc, wordsFrom as dd, worstSeverity as de, type CommandWords as e, type ContextCheckpoint as f, type ContextFill as g, type ConversationMessage as h, type CostProvenance as i, DEFAULT_PLANNER_ALLOWLIST as j, DEFAULT_RUNNERS as k, DEFAULT_SCRIPT_TIMEOUT_MS as l, DEFAULT_SUPERVISOR_RETRY_LIMIT as m, DIGEST_FINDINGS as n, type DelegatedRow as o, type DiscoveredModel as p, type ExecutionActor as q, type ExecutionCommandName as r, type ExecutionRecord as s, type FindingSeverity as t, type Grant as u, type GuardTarget as v, type GuardTrip as w, HANDOFF_PUSH_CHARS as x, type Handoff as y, type HandoffArtifact as z };