@ordewell/core 0.10.12 → 0.11.1

package/dist/{IFileSystem-1PqRCjhu.d.mts → IRunner-B5l9PCTv.d.ts}

@@ -1,7 +1,47 @@
 import { ChildProcess } from 'child_process';
-import { a7 as RunnerId, az as UsageRecord, ak as SubagentOutcome, a8 as RunnerSessionCost, f as DiscoveredModel, at as TaskSkillSnapshot } from './Task-CfBM0wkV.mjs';
+import { aS as Task, az as RunnerId, b6 as UsageRecord, aQ as SubagentOutcome, aA as RunnerSessionCost, i as DiscoveredModel, a$ as TaskSkillSnapshot, p as HandoffCheck } from './Task-BL4Idm9r.js';
 import { z } from 'zod/v4';
 
+/** 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.
@@ -118,6 +158,23 @@ interface ResearchShell {
      */
     utilsDir: string | null;
 }
+/**
+ * How one command starts: the research shell itself, or the sandbox launcher
+ * around it (ADR-0011 B6). Either way the command string is appended after
+ * `args`, and `file: null` means `shell: true`.
+ */
+interface ShellLaunch {
+    file: string | null;
+    args: readonly string[];
+    /** Undefined inherits the host's environment. */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * A sealed run's wall-time limit (ADR-0036 S1): the adapter kills the
+     * launch with SIGKILL once it has run this long, in place of its own
+     * timeout, and stops waiting for output a moment after it exits.
+     */
+    wallTimeMs?: number;
+}
 interface ResearchShellDeps {
     platform?: NodeJS.Platform;
     exists?: (candidate: string) => boolean;
@@ -401,6 +458,12 @@ interface ApprovalRequest {
     scopes?: string[];
     /** One-line context for the prompt. */
     detail?: string;
+    /**
+     * For a `task_start` of a script task: what it runs, verbatim, one command
+     * to a line, and its time limit (ADR-0035). Shown in full, since the
+     * consent is to it, not to a description.
+     */
+    body?: string;
     /** The task whose runner asked; absent for the planner's own requests. */
     taskId?: string;
     /** "Allow for this task" can be offered: the runner proposed its own session-scoped grant. */
@@ -472,6 +535,8 @@ interface CatalogModel {
         completion: string;
     };
     contextLength: number;
+    /** The longest reply the catalog says the model is served with, when it says. */
+    maxOutputTokens?: number;
 }
 declare class ModelCatalog {
     static fetchModels(apiKey: string, baseUrl?: string, fetchImpl?: typeof fetch): Promise<CatalogModel[]>;
@@ -512,6 +577,8 @@ interface OrchestratorOption {
     pricing?: string;
     /** The model's context window when the catalog reports one (#49). */
     contextWindow?: number;
+    /** The longest reply the catalog says the model is served with, when it says. */
+    maxOutputTokens?: number;
 }
 
 interface FetchAllProviderModelsOptions {
@@ -641,8 +708,16 @@ interface IConfig {
     approvalPreApproved: string[];
     /** Whether the built-in allowlist of read-only command families and MCP tools applies. */
     approvalDefaults: boolean;
+    /** The user's effect allowlist rules (ADR-0035, `effectAllowlist.ts`), read on every request. It has no defaults. */
+    effectAllowlist: string[];
     /** How many fetches and searches one planner turn may make (ADR-0027). User-only, like the approval settings. */
     webReadBudget: number;
+    /**
+     * Let a harness planner use its own shell beside `run_command` (ADR-0036
+     * N1), where the installed version passed the live checks (N2, N4). Off by
+     * default, and never a workspace's to choose.
+     */
+    plannerNativeShell: boolean;
     /** Get the base URL for an OpenAI-compatible provider. */
     getProviderBaseUrl(provider: AiProvider): string;
     /** Get the API key for a provider. */
@@ -655,23 +730,205 @@ interface IConfig {
 }
 declare function enabledRunners(cfg: IConfig): RunnerId[];
 
+interface ToolOutcome {
+    success: boolean;
+    output: string;
+    truncated: boolean;
+    /**
+     * The child was killed at its time limit, so what it had not finished did
+     * not happen (ADR-0036 S1). The adapters set it, and a sealed run's result
+     * names the limit it ran out of rather than blaming the command.
+     */
+    timedOut?: boolean;
+}
+interface ReadFileOpts {
+    maxBytes?: number;
+    offset?: number;
+    limit?: number;
+}
 /**
- * The tools of the Ordewell MCP server, per token role (ADR-0022), and the
- * handler interfaces the session side implements to answer them.
- *
- * Every handler method is optional so each tool can be wired on its own; one
- * left unset answers its call with a "not available" error rather than
- * disappearing from `tools/list`, so the list a runner sees never depends on
- * how far the wiring has got.
+ * `content` returns matching lines, `files` only the paths that matched, and
+ * `count` a per-file tally. Cheap models otherwise grep and then read whole
+ * files to answer "which files touch this", burning rounds against the budget.
+ */
+type GrepOutputMode = 'content' | 'files' | 'count';
+interface GrepOptions {
+    /** File glob filter, e.g. `*.ts`. */
+    include?: string;
+    /** Search root. Relative to the workspace unless approved as external. */
+    path?: string;
+    outputMode?: GrepOutputMode;
+    /** Lines of context around each match (`content` mode only). */
+    contextBefore?: number;
+    contextAfter?: number;
+    /** Treat the pattern as a literal string rather than a regex. */
+    literal?: boolean;
+    caseInsensitive?: boolean;
+    /** Global cap on returned rows. Defaults to {@link GREP_DEFAULT_HEAD_LIMIT}. */
+    headLimit?: number;
+}
+interface GlobOptions {
+    /** Search root. Relative to the workspace unless approved as external. */
+    path?: string;
+    headLimit?: number;
+}
+interface FindSymbolOptions {
+    /** Language id or file extension, e.g. `typescript` or `.go`. Narrows the keyword set. */
+    language?: string;
+    /** Search root. Relative to the workspace unless approved as external. */
+    path?: string;
+}
+/** Global row cap for grep. A per-file cap is not a budget — see PoolFileSystem. */
+declare const GREP_DEFAULT_HEAD_LIMIT = 100;
+/**
+ * Directories that are never interesting to a planner and would otherwise eat
+ * the result budget. Applied by every search entry point, not just `glob` —
+ * `dist/` and `.ordewell/` are frequently not gitignored.
  */
+declare const SEARCH_EXCLUSIONS: string[];
+interface BashOptions {
+    /**
+     * Run the command sealed (ADR-0036 S2): no network, no home directory,
+     * nothing written reaching the workspace, and nobody asked. Refused where
+     * the host has no sandbox to seal it in.
+     */
+    sealed?: boolean;
+}
+/** Where a read-only task's commands run (ADR-0046). */
+interface TaskShellSite {
+    /** Where its commands start, and what their paths are confined to: the task's worktree, or the workspace root when the run does not isolate. */
+    cwd: string;
+    /** The task's own worktree, the one directory but scratch a sealed run may write; absent without one. */
+    writable?: string;
+    /**
+     * The git worktree roots inside `writable` whose `.git` a sealed run must
+     * not rewrite into a repository of its own (ADR-0046): one per repo in a
+     * group. Left out, the single `writable` worktree's `.git` is protected.
+     */
+    worktrees?: readonly string[];
+}
+/**
+ * Sealed runs of Ordewell's own scripts in a read-only task's shell, while
+ * the shell is held for them (ADR-0050). They are judged by no command rule,
+ * since the task did not write them, but run under the task's sealed profile
+ * and are checked after as each of its sealed runs is: Ordewell runs no git
+ * in a worktree a sealed run wrote anywhere but inside the seal (ADR-0046).
+ */
+interface OwnSealedRuns {
+    /** The repository roots the task's sealed runs may write: one per repo, none without a worktree. */
+    readonly worktrees: readonly string[];
+    /** Whether a sealed run has started in the shell: until one has, its worktree holds only what Ordewell checked out. */
+    readonly touched: boolean;
+    /** The attempt's scratch directory, which a sealed run has as `$TMPDIR` and `$HOME`. */
+    readonly scratch: string;
+    /** `script` run sealed from `cwd`, one of {@link worktrees}; refused once the shell is stopped, or where no sandbox can seal. */
+    run(script: string, cwd: string): Promise<ToolOutcome>;
+}
+/**
+ * A read-only task's `run_command` (ADR-0046): the planner's command rules at
+ * the task's working directory, with nobody to ask. One per attempt, with a
+ * scratch directory of its own; once one of its commands has run sealed,
+ * every later one does.
+ */
+interface TaskShell {
+    run(command: string, signal?: AbortSignal): Promise<ToolOutcome>;
+    /**
+     * Hold the shell for Ordewell's own `work` (ADR-0050): no command of the
+     * task runs until it settles, so nothing changes the worktree between the
+     * sealed runs it makes. `signal` stops those runs.
+     */
+    hold?<T>(work: (runs: OwnSealedRuns) => Promise<T>, signal?: AbortSignal): Promise<T>;
+    /** The attempt ended: its scratch directory goes. */
+    end(): void;
+}
+interface IFileSystem {
+    readFile(path: string, opts?: ReadFileOpts): Promise<ToolOutcome>;
+    readFiles(paths: string[]): Promise<ToolOutcome>;
+    glob(pattern: string, opts?: GlobOptions): Promise<ToolOutcome>;
+    grep(pattern: string, opts?: GrepOptions): Promise<ToolOutcome>;
+    listDir(path: string, depth?: number): Promise<ToolOutcome>;
+    /**
+     * `signal` stops the planning turn this command belongs to: adapters kill
+     * the spawned child rather than let it run out its own timeout. The other
+     * tools here are short enough that the loop's between-call abort check is
+     * indistinguishable from cancelling them mid-flight; a `bash` call is not.
+     */
+    bash(command: string, signal?: AbortSignal, opts?: BashOptions): Promise<ToolOutcome>;
+    /** Definition-first lookup for one symbol. See `symbolPatterns.ts`. */
+    findSymbol(symbol: string, opts?: FindSymbolOptions): Promise<ToolOutcome>;
+    getWorkspaceRoot(): string;
+    /**
+     * Inject the human-approval channel for out-of-envelope access. Optional so
+     * test doubles stay small; every adapter extending `BaseFileSystem` has it.
+     */
+    setApproval?(approval: IApproval): void;
+    /** Held credentials read live by the outbound secret check. */
+    setOutboundSecrets?(secrets: () => Iterable<string>): void;
+    /** Where the filesystem tells the session, once, that the planner's shell runs without an OS sandbox here (ADR-0011 B5). */
+    setNotice?(notice: (message: string) => void): void;
+    /** The session ended: its scratch directory is removed, and the next command starts a fresh one (ADR-0011 B2). */
+    endSession?(): void;
+    /** Whether a command can run sealed on this host (ADR-0036 S6); where it cannot, the session's one notice says so. */
+    canSeal?(): Promise<boolean>;
+    /** A read-only task's shell at `site`, held to this session's allowlist and never asking (ADR-0046). */
+    taskShell?(site: TaskShellSite): TaskShell;
+}
+
 declare const taskCompleteInput: z.ZodObject<{
     status: z.ZodEnum<{
         failed: "failed";
-        blocked: "blocked";
         done: "done";
+        blocked: "blocked";
     }>;
     summary: z.ZodString;
     reason: z.ZodOptional<z.ZodString>;
+    commit: z.ZodOptional<z.ZodObject<{
+        subject: z.ZodString;
+        body: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    findings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        severity: z.ZodEnum<{
+            blocker: "blocker";
+            major: "major";
+            minor: "minor";
+            info: "info";
+        }>;
+        title: z.ZodString;
+        detail: z.ZodOptional<z.ZodString>;
+        evidence: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"file">;
+            path: z.ZodString;
+            line: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"commit">;
+            sha: z.ZodString;
+            repo: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"task">;
+            task: z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>, z.ZodString>;
+            finding: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"url">;
+            url: z.ZodString;
+        }, z.core.$strip>]>>>;
+    }, z.core.$strip>>>;
+    artifacts: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"file">;
+        path: z.ZodString;
+        line: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"commit">;
+        sha: z.ZodString;
+        repo: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"task">;
+        task: z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>, z.ZodString>;
+        finding: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"url">;
+        url: z.ZodString;
+    }, z.core.$strip>]>>>;
+    report: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 declare const checkpointInput: z.ZodObject<{
     question: z.ZodString;
@@ -682,6 +939,10 @@ declare const listModelsInput: z.ZodObject<{
 }, z.core.$strip>;
 declare const runCommandInput: z.ZodObject<{
     command: z.ZodString;
+    sealed: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+declare const taskRunCommandInput: z.ZodObject<{
+    command: z.ZodString;
 }, z.core.$strip>;
 declare const fetchInput: z.ZodObject<{
     url: z.ZodString;
@@ -692,6 +953,16 @@ declare const webSearchInput: z.ZodObject<{
 declare const loadSkillInput: z.ZodObject<{
     name: z.ZodString;
 }, z.core.$strip>;
+declare const readTaskInput: z.ZodObject<{
+    task: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    attempt: z.ZodOptional<z.ZodNumber>;
+    include_report: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+declare const savePatchInput: z.ZodObject<{}, z.core.$strip>;
+declare const applyPatchInput: z.ZodObject<{
+    task: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    attempt: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
 declare const submitPlanInput: z.ZodObject<{
     tasks: z.ZodArray<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
@@ -699,8 +970,9 @@ declare const submitPlanInput: z.ZodObject<{
         title: z.ZodString;
         description: z.ZodOptional<z.ZodString>;
         type: z.ZodOptional<z.ZodEnum<{
-            user: "user";
             ai: "ai";
+            user: "user";
+            script: "script";
         }>>;
         dependencies: z.ZodOptional<z.ZodArray<z.ZodString>>;
         prompt: z.ZodOptional<z.ZodString>;
@@ -727,6 +999,14 @@ declare const submitPlanInput: z.ZodObject<{
         userStoriesCovered: z.ZodOptional<z.ZodArray<z.ZodString>>;
         skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
         subtasks: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        commands: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString>>>;
+        script: z.ZodOptional<z.ZodString>;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+        research: z.ZodOptional<z.ZodBoolean>;
+        loop: z.ZodOptional<z.ZodObject<{
+            body: z.ZodArray<z.ZodString>;
+            maxRounds: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$loose>>;
     }, z.core.$loose>>;
 }, z.core.$strip>;
 declare const editPlanInput: z.ZodObject<{
@@ -763,46 +1043,51 @@ declare const editPlanInput: z.ZodObject<{
 declare const taskQueryInput: z.ZodObject<{
     tasks: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
     fields: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        skills: "skills";
+        verdict: "verdict";
         description: "description";
         prompt: "prompt";
         userSteps: "userSteps";
-        verdict: "verdict";
         outputSummary: "outputSummary";
+        handoff: "handoff";
         userStoriesCovered: "userStoriesCovered";
+        skills: "skills";
     }>>>;
     catalog: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 declare const taskOutputInput: z.ZodObject<{
     attempt: z.ZodOptional<z.ZodNumber>;
     kinds: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        text: "text";
         error: "error";
+        handoff: "handoff";
+        text: "text";
         command: "command";
-        thinking: "thinking";
+        task_skills: "task_skills";
+        turn_start: "turn_start";
+        command_output: "command_output";
+        compaction: "compaction";
+        model_switched: "model_switched";
+        runner_loaded: "runner_loaded";
+        turn_end: "turn_end";
+        text_delta: "text_delta";
         thinking_delta: "thinking_delta";
+        thinking: "thinking";
         tool_call: "tool_call";
         tool_result: "tool_result";
-        usage: "usage";
         subagent_started: "subagent_started";
         subagent_finished: "subagent_finished";
-        turn_end: "turn_end";
-        message_delivered: "message_delivered";
-        runner_loaded: "runner_loaded";
-        compaction: "compaction";
-        command_output: "command_output";
-        model_switched: "model_switched";
-        text_delta: "text_delta";
-        turn_start: "turn_start";
+        usage: "usage";
         message_queued: "message_queued";
         message_removed: "message_removed";
         message_undelivered: "message_undelivered";
         message_handed_over: "message_handed_over";
-        task_skills: "task_skills";
+        message_delivered: "message_delivered";
         approval_requested: "approval_requested";
         approval_decided: "approval_decided";
         approval_withdrawn: "approval_withdrawn";
         runner_ended: "runner_ended";
+        script_run: "script_run";
+        script_output: "script_output";
+        script_exit: "script_exit";
     }>>>;
     task: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
     lines: z.ZodOptional<z.ZodNumber>;
@@ -835,18 +1120,37 @@ declare const messageTaskInput: z.ZodObject<{
     task: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
     text: z.ZodString;
 }, z.core.$strip>;
+declare const runScriptInput: z.ZodObject<{
+    title: z.ZodString;
+    commands: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString>>>;
+    script: z.ZodOptional<z.ZodString>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    dependencies: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+}, z.core.$strip>;
 declare const answerApprovalInput: z.ZodObject<{
     task: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
     approval: z.ZodOptional<z.ZodString>;
     answer: z.ZodString;
     note: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+declare const answerCheckpointInput: z.ZodObject<{
+    task: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    answer: z.ZodEnum<{
+        approve: "approve";
+        reject: "reject";
+    }>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 type TaskCompleteArgs = z.infer<typeof taskCompleteInput>;
 type CheckpointArgs = z.infer<typeof checkpointInput>;
+type ReadTaskArgs = z.infer<typeof readTaskInput>;
+type SavePatchArgs = z.infer<typeof savePatchInput>;
+type ApplyPatchArgs = z.infer<typeof applyPatchInput>;
 type ListRunnersArgs = z.infer<typeof listRunnersInput>;
 type ListModelsArgs = z.infer<typeof listModelsInput>;
 type LoadSkillArgs = z.infer<typeof loadSkillInput>;
 type RunCommandArgs = z.infer<typeof runCommandInput>;
+type TaskRunCommandArgs = z.infer<typeof taskRunCommandInput>;
 type FetchArgs = z.infer<typeof fetchInput>;
 type WebSearchArgs = z.infer<typeof webSearchInput>;
 type SubmitPlanArgs = z.infer<typeof submitPlanInput>;
@@ -860,6 +1164,8 @@ type RetryTaskArgs = z.infer<typeof retryTaskInput>;
 type MessageTaskArgs = z.infer<typeof messageTaskInput>;
 type SkipTaskArgs = z.infer<typeof skipTaskInput>;
 type AnswerApprovalArgs = z.infer<typeof answerApprovalInput>;
+type AnswerCheckpointArgs = z.infer<typeof answerCheckpointInput>;
+type RunScriptArgs = z.infer<typeof runScriptInput>;
 /** What a handler answers with. `isError` marks a refusal the caller should act on. */
 interface McpToolReply {
     text: string;
@@ -887,6 +1193,17 @@ type Run<A> = (args: A, context: McpToolContext) => Promise<McpToolReply>;
 interface TaskToolHandler {
     taskComplete?: Run<TaskCompleteArgs>;
     checkpoint?: Run<CheckpointArgs>;
+    /** A handoff the task may read (ADR-0047), from its attempt's log. */
+    readTask?: Run<ReadTaskArgs>;
+    /** A read-only task's shell (ADR-0046); only its token lists `run_command`. */
+    runCommand?: Run<TaskRunCommandArgs>;
+    /** A read-only task's prototype kept as a patch (ADR-0050); only its token lists `save_patch`. */
+    savePatch?: Run<SavePatchArgs>;
+    /** A saved patch applied into the task's own worktree (ADR-0050); a read-only task's token does not list `apply_patch`. */
+    applyPatch?: Run<ApplyPatchArgs>;
+    /** A read-only task's web reads, decided by the session's web-read policy (ADR-0046, ADR-0027); only its token lists `fetch` and `web_search`. */
+    fetch?: Run<FetchArgs>;
+    webSearch?: Run<WebSearchArgs>;
 }
 interface PlannerToolHandler {
     loadSkill?: Run<LoadSkillArgs>;
@@ -908,7 +1225,9 @@ interface PlannerToolHandler {
     skipTask?: Run<SkipTaskArgs>;
     messageTask?: Run<MessageTaskArgs>;
     answerApproval?: Run<AnswerApprovalArgs>;
+    answerCheckpoint?: Run<AnswerCheckpointArgs>;
     mergeAll?: Run<RunPlanArgs>;
+    runScript?: Run<RunScriptArgs>;
 }
 interface McpTool<H> {
     name: string;
@@ -931,7 +1250,24 @@ declare const TASK_COMPLETE_TOOL = "task_complete";
  * message into a summary, while its instructions are re-applied whole.
  */
 declare const TASK_COMPLETION_CONTRACT: string;
+/** The completion contract for one attempt: only one whose work lands as a commit is asked for its message (ADR-0047). */
+declare function taskCompletionContract(opts: {
+    commits?: true;
+}): string;
+/**
+ * A task that works in the tree: the shared tools, and `apply_patch`, which
+ * brings a prototype a read-only task saved (ADR-0050) into its worktree.
+ */
 declare const TASK_TOOLS: readonly McpTool<TaskToolHandler>[];
+/**
+ * A read-only task's tools (ADR-0046): the task tools, `run_command`, its
+ * only shell, `save_patch`, which keeps what that shell changed as a patch
+ * (ADR-0050), and `fetch` and `web_search`, its only web reads, which the
+ * host carries under the session's web-read policy (ADR-0027). Their hints
+ * describe their landing effects: nothing any of them changes reaches the
+ * plan's branches.
+ */
+declare const READ_ONLY_TASK_TOOLS: readonly McpTool<TaskToolHandler>[];
 /**
  * The planner's execution tools (ADR-0029, #91): each call goes to the
  * session's command seam, which checks it, asks the user where consent needs
@@ -955,6 +1291,8 @@ interface TaskTokenScope {
     taskId: string;
     /** The attempt generation the token is good for; a later attempt gets a new token. */
     attempt: number;
+    /** A read-only task's attempt (ADR-0046): its token lists `run_command`, `fetch` and `web_search` too, and no other task's does. */
+    readOnly?: boolean;
 }
 interface PlannerTokenScope {
     sessionId: string;
@@ -971,9 +1309,22 @@ interface McpCredential {
     token: string;
     /** The planner tools the token hides ({@link PlannerTokenScope.hidden}), so the runner is told of and pre-allows only what it is served. */
     hidden?: readonly string[];
+    /** The token serves a read-only task's tools ({@link TaskTokenScope.readOnly}), so the runner is told of and pre-allows `run_command`, `fetch` and `web_search`. */
+    readOnly?: true;
 }
+/**
+ * Why the server refused a request before any tool ran, kept apart in the
+ * count so a planner that lost its link can be told from one that never had
+ * one: an unknown token is a stale URL or a client that was never issued one,
+ * a revoked token is a session that ended or a process that was respawned, and
+ * a wrong path is a client pointed somewhere other than `/mcp`.
+ */
+type McpRefusal = 'unknownToken' | 'revokedToken' | 'wrongPath';
 declare class OrdewellMcpServer {
     private readonly grants;
+    /** Recently revoked tokens, so a request carrying one is told from a token that never existed. */
+    private readonly revokedTokens;
+    private readonly refused;
     private http;
     private listening;
     private boundUrl;
@@ -982,6 +1333,12 @@ declare class OrdewellMcpServer {
     constructor(options?: OrdewellMcpServerOptions);
     /** The listener's URL, once the first token has started it. */
     get url(): string | undefined;
+    /**
+     * How many requests this server refused, by reason, since it started. What
+     * makes a planner whose tools went dead visible after the fact; no token,
+     * path or header is kept here.
+     */
+    refusals(): Readonly<Record<McpRefusal, number>>;
     issueTaskToken(scope: TaskTokenScope, handler?: TaskToolHandler): Promise<McpCredential>;
     issuePlannerToken(scope: PlannerTokenScope, handler?: PlannerToolHandler): Promise<McpCredential>;
     /** Every token still good here: secrets the outbound check keeps out of a URL (ADR-0027). */
@@ -992,6 +1349,8 @@ declare class OrdewellMcpServer {
     private issue;
     private start;
     private handle;
+    /** Count one refusal, and say the first of its kind once: a runner retrying a dead token must not flood the log. */
+    private refuse;
 }
 /** The process's one server, which the daemon and the extension host hand to every session they build. */
 declare function sharedMcpServer(): OrdewellMcpServer;
@@ -1004,6 +1363,8 @@ interface McpClientConfig {
     headers: Record<string, string>;
     /** Planner tools the token hides: a runner must neither pre-allow nor mention them. */
     hidden?: readonly string[];
+    /** A read-only task's token (ADR-0046): `run_command`, `fetch` and `web_search` are among its tools, for the runner to pre-allow and name. */
+    readOnly?: true;
 }
 /**
  * The one shape every runner adapter renders its own MCP configuration from.
@@ -1074,6 +1435,328 @@ interface RunnerMcpServer {
 /** The command `name` names, by its own name or an alias. */
 declare function findRunnerCommand(commands: readonly RunnerCommand[], name: string): RunnerCommand | undefined;
 
+/**
+ * The one seam an OS sandbox sits behind (ADR-0011 B6). A backend turns "run
+ * this POSIX shell" into "run this launcher, which runs the shell under a
+ * policy": the launcher and its policy become the `file` and the leading
+ * `args`, and the caller appends the command string last, exactly as it would
+ * to the bare shell. The string the classifier read is the string that runs.
+ *
+ * A sandbox shares nothing with another: no daemon, no image, no state beyond
+ * what its profile names. A container, microVM or hosted backend for an
+ * execution lease (#97) is another implementation of this interface, and its
+ * callers do not change.
+ */
+/**
+ * A `.git` entry the checkout brought, which a sealed run may not change
+ * (ADR-0046). Whether it is a directory decides how a backend refuses a write
+ * into it: its whole subtree, or just the file.
+ */
+interface SandboxGitEntry {
+    path: string;
+    directory: boolean;
+}
+/**
+ * What one command may touch. Every path is absolute, and canonical
+ * (symlinks resolved) wherever the backend matches the path the kernel
+ * resolves, as Seatbelt does.
+ */
+interface SandboxProfile {
+    /** Directories the command may write, recursively. Nothing else can be written. */
+    write: readonly string[];
+    /**
+     * Of `write`, those the command may not put a symbolic link in, nor move
+     * one into: what is read there outside the sandbox, as the user, would
+     * follow it (ADR-0046). A backend that cannot refuse a link by its type
+     * refuses the profile.
+     */
+    linkless?: readonly string[];
+    /**
+     * Of `write`, the worktree roots whose own `.git` a command may neither
+     * write, replace, rename nor remove (ADR-0046). A worktree's `.git` is a
+     * file pointing into its repository; a command that rewrote it would make
+     * git load a repository of the command's own when it runs there outside the
+     * sandbox, as the user. The root itself is held still too: a command that
+     * renamed it could plant a `.git` outside the profile and move it back.
+     */
+    gitWorktrees?: readonly string[];
+    /**
+     * Of `write`, every `.git` entry the checkout brought — a submodule's file, a
+     * vendored repository — which a command may not change either: the literal
+     * path for a file, everything under it for a directory (ADR-0046).
+     */
+    gitEntries?: readonly SandboxGitEntry[];
+    /**
+     * Of `write`, directories in which a command may not create a `.git`, at
+     * their root or beneath it, for the same reason (ADR-0046). A backend that
+     * cannot refuse a name being created refuses the profile.
+     */
+    gitless?: readonly string[];
+    /**
+     * What the command may read besides `write`. `'host'` is the whole
+     * filesystem: the planner's reads are confined by ADR-0008's path check,
+     * not here (ADR-0011 B2). A list confines reads to those paths, for a
+     * profile that must not see the user's files (ADR-0036 S1). Bubblewrap
+     * mounts a listed link where it is named, so `/bin` still starts programs
+     * on a system where it links to `/usr/bin`.
+     */
+    read: 'host' | readonly string[];
+    /**
+     * Listed directories mounted with a throwaway overlay: a write there
+     * succeeds and is gone when the command ends, so a tool that writes a cache
+     * beside the code still runs (ADR-0036 S1). A backend without one refuses
+     * the profile, a host too old for one fails its probe, and either way the
+     * caller asks again with the directory read-only.
+     */
+    throwaway?: readonly string[];
+    /** Directories the command cannot see into although `read` covers them: where local services listen that would write on its behalf. */
+    masked?: readonly string[];
+    network: boolean;
+    /** The host's `/tmp` out of the command's sight: an empty one of its own where the backend can mount one, none at all where it cannot. */
+    privateTmp?: boolean;
+    /**
+     * Whether a networked command reaches the keychain, where `gh` and git's
+     * credential helpers keep the user's tokens (B3). Defaults to true for an
+     * approved command; a native shell must not have it (ADR-0036 N2.2).
+     */
+    keychain?: boolean;
+    /**
+     * Whether a networked command reaches what listens on this machine itself:
+     * loopback addresses and Unix sockets. Defaults to true. A native shell must
+     * not: the harness's own server and Ordewell's daemon listen there and act
+     * outside the sandbox for whoever holds their password, which a macOS
+     * command can read from their environments (ADR-0036 N2).
+     */
+    localNetwork?: boolean;
+    /** Set over the environment the command inherits. */
+    env: Readonly<Record<string, string>>;
+    /** The variables the command keeps from the host's environment; absent keeps them all. Its credentials live there too. */
+    inheritEnv?: readonly string[];
+    limits?: SandboxLimits;
+}
+/**
+ * Held by the kernel's resource limits, set before the launcher starts, and
+ * by the caller's clock (ADR-0036 S1).
+ */
+interface SandboxLimits {
+    /** Processes the command may start beyond those its user already runs, which the kernel's limit counts too. */
+    processes: number;
+    /**
+     * Bytes of address space any one of its processes may map. On macOS, where
+     * every program maps hundreds of gigabytes as it starts, it is counted on
+     * top of that.
+     */
+    memoryBytes: number;
+    /** Milliseconds before the caller kills the command, and with it every process it started. */
+    wallTimeMs: number;
+}
+/** The unsandboxed shell: a POSIX shell that takes the command string after `shellArgs`. */
+interface SandboxInvocation {
+    shell: string;
+    shellArgs: readonly string[];
+    /** The environment the shell would have run with. */
+    env: NodeJS.ProcessEnv;
+}
+/** What to spawn instead. The command string is appended after `args`. */
+interface SandboxLaunch {
+    file: string;
+    args: string[];
+    env: NodeJS.ProcessEnv;
+    /** The profile's wall-time limit: the caller kills the launch with SIGKILL once it has run this long. */
+    wallTimeMs?: number;
+}
+type SandboxProbe = {
+    ok: true;
+} | {
+    ok: false;
+    detail: string;
+};
+interface SandboxBackend {
+    /** How the notice and a skipped test name it. */
+    readonly name: string;
+    /** Start a trivial command under `profile`: whether this host can run the sandbox at all (ADR-0011 B5). */
+    probe(profile: SandboxProfile): Promise<SandboxProbe>;
+    /** Builds the launch without starting anything, and throws {@link SandboxUnsupportedError} for a profile it cannot enforce. */
+    wrap(invocation: SandboxInvocation, profile: SandboxProfile): SandboxLaunch;
+}
+type ProbeExec = (file: string, args: string[], env: NodeJS.ProcessEnv) => Promise<{
+    code: number | null;
+    output: string;
+}>;
+
+/**
+ * The planner's shell inside an OS sandbox (ADR-0011): every command the
+ * planner's `bash` tool, its research subagents and a harness planner's
+ * `run_command` start runs where nothing outside one scratch directory per
+ * session can be written. It sits underneath the classifier and changes
+ * nothing about which commands are `auto`, `ask` or `refuse` (B1). Where it
+ * runs, a command the envelope would refuse without asking can run sealed
+ * instead, under a stricter profile of its own (ADR-0036 S1, S2).
+ */
+declare const PLANNER_SANDBOX_DOCS = "https://github.com/ordewell/ordewell/blob/main/docs/troubleshooting.md#planner-shell-not-sandboxed";
+/** Where a sealed run starts: the workspace it reads, and the one other directory, if any, it may write (ADR-0036 S1). */
+interface SealedRunOptions {
+    workspace: string;
+    /** None by default, so the workspace stays read-only. A read-only task passes its own throwaway worktree (ADR-0046). */
+    writable?: string;
+    /**
+     * The git worktree roots inside `writable` whose own `.git` a sealed run
+     * must not rewrite into a repository of its own (ADR-0046). A repo group
+     * passes one per repo; left out, the single `writable` worktree is used.
+     */
+    worktrees?: readonly string[];
+    /**
+     * Every `.git` entry the writable directory held before the task's first
+     * sealed run, which a sealed run may not change (ADR-0046). The worktree
+     * roots above cover their own `.git`; this covers a submodule's file and a
+     * vendored repository, whose content a run could otherwise rearm.
+     */
+    gitEntries?: readonly SandboxGitEntry[];
+    /**
+     * A harness's short per-session temporary directory, writable besides the
+     * scratch one (ADR-0036 N2). A native shell needs it: Claude Code writes the
+     * shell's working directory there after every command.
+     */
+    tmpdir?: string;
+    /**
+     * The network the harness gives its own shell (ADR-0036 N3). A sealed run has
+     * none (S1); only the native-shell opt-in asks for this profile with one.
+     */
+    network?: boolean;
+    /**
+     * Whether the keychain is in reach with that network. Defaults to true, as
+     * for an approved command; a native shell passes false (N2.2).
+     */
+    keychain?: boolean;
+    /** Whether that network reaches loopback and this machine's Unix sockets. Defaults to true; a native shell passes false (N2). */
+    localNetwork?: boolean;
+    /**
+     * The limits the sealed run is held to (ADR-0036 S1). {@link SEALED_LIMITS}
+     * by default; a read-only task passes {@link TASK_SEALED_LIMITS}, since its
+     * one shell is where it runs the project's tests (ADR-0046).
+     */
+    limits?: SandboxLimits;
+}
+type SealedAvailability = {
+    available: true;
+    /** The sealed profile on this host; without a scratch directory, nothing is writable. */
+    profile: (opts: SealedRunOptions & {
+        scratch?: string;
+    }) => SandboxProfile;
+}
+/** The session's one notice where the sandbox runs but cannot start a sealed run (S6). */
+ | {
+    available: false;
+    notice: string;
+};
+type PlannerSandboxAvailability = {
+    available: true;
+    backend: SandboxBackend;
+    /** The planner's profile on this host; without a scratch directory, nothing is writable. */
+    profile: (opts: {
+        scratch?: string;
+        network: boolean;
+    }) => SandboxProfile;
+    sealed: SealedAvailability;
+}
+/** The one notice the planner surface shows a session (B5). */
+ | {
+    available: false;
+    notice: string;
+};
+interface PlannerSandboxDeps {
+    platform?: NodeJS.Platform;
+    /** An existing directory a sealed probe can mount as its workspace. */
+    probeWorkspace?: string;
+    env?: NodeJS.ProcessEnv;
+    exists?: (file: string) => boolean;
+    /** An existing path's canonical form and whether it is a directory, or null. */
+    stat?: (p: string) => {
+        canonical: string;
+        directory: boolean;
+    } | null;
+    uid?: number;
+    exec?: ProbeExec;
+}
+/** Enough for a loop over a repository's files, a pipeline or a short script; not for a build. */
+declare const SEALED_LIMITS: SandboxLimits;
+/**
+ * A read-only task's sealed runs (ADR-0046): the same resources, with the ten
+ * minutes a script task gets by default, since its one shell is where the task
+ * runs the project's tests and a suite does not fit in a minute.
+ */
+declare const TASK_SEALED_LIMITS: SandboxLimits;
+/**
+ * Whether this host can sandbox the planner's shell, and how. Probed once per
+ * process with a trivial command (B5): the answer cannot change while
+ * Ordewell runs, and concurrent first commands share one probe. Injected
+ * dependencies bypass the cache, as {@link resolveResearchShell}'s do.
+ */
+declare function resolvePlannerSandbox(deps?: PlannerSandboxDeps): Promise<PlannerSandboxAvailability>;
+/** Test seam: drop the per-process probe so the next call probes again. */
+declare function clearPlannerSandboxCache(): void;
+/** The research shell as one command should start, and whether that is inside the sandbox. */
+interface PlannerShellLaunch {
+    launch: ShellLaunch;
+    sandboxed: boolean;
+}
+/**
+ * One session's view of the sandbox: its scratch directory, made on the first
+ * command and removed when the session ends, and its one notice when the
+ * sandbox, or a sealed run in it, cannot run here.
+ */
+declare class PlannerShellSandbox {
+    private readonly resolve;
+    private scratch;
+    private noticed;
+    private notice;
+    constructor(resolve?: () => Promise<PlannerSandboxAvailability>);
+    setNotice(notice: (message: string) => void): void;
+    /** The same host's sandbox for another caller, with a scratch directory of its own: a read-only task's (ADR-0046). */
+    withOwnScratch(): PlannerShellSandbox;
+    /**
+     * The launch for one command (B6): the research shell wrapped in the
+     * sandbox, with the network as the caller's tier allows (B3), or the shell
+     * itself where no sandbox runs, after saying so once (B5). Throws when the
+     * sandbox runs here but this command cannot be put in it, so a command is
+     * never run outside a sandbox that exists.
+     */
+    launch(shell: ResearchShell, opts: {
+        network: boolean;
+    }): Promise<PlannerShellLaunch>;
+    /** Whether a command can run sealed here (ADR-0036 S6). Where it cannot, the session's one notice says so. */
+    canSeal(): Promise<boolean>;
+    /**
+     * The launch for one sealed run (S1), in this session's scratch directory.
+     * Throws where sealed runs are unavailable, which {@link canSeal} answers
+     * first, and for a shell the sandbox cannot wrap.
+     */
+    launchSealed(shell: ResearchShell, opts: SealedRunOptions): Promise<ShellLaunch>;
+    /**
+     * The launch for a harness's own shell (ADR-0036 N2): the same sealed profile
+     * as a sealed run, with the network the harness gives it (N3), plus the
+     * harness's short temporary directory. The workspace stays read-only. Throws
+     * where the sandbox cannot run, so a caller never falls back to the bare shell.
+     */
+    launchNativeShell(opts: {
+        workspace: string;
+        tmpdir: string;
+        shell: string;
+        shellArgs?: readonly string[];
+        env?: NodeJS.ProcessEnv;
+    }): Promise<SandboxLaunch>;
+    /** The scratch directory every launch here gets as `$TMPDIR` and `$HOME`, made if it is not there. */
+    scratchPath(): string;
+    /** The session ended: its scratch directory goes, and a next session starts with a fresh one and its own notice. */
+    end(): void;
+    private say;
+    private invocation;
+    private scratchDir;
+}
+
+/** A runner's report on the Ordewell server's connection, in one vocabulary for every runner. */
+type AttachState = 'connected' | 'pending' | 'failed';
+
 /**
  * The harness-planner transport contract (ADR-0009).
  *
@@ -1322,6 +2005,12 @@ type PlannerAsk =
     path: string;
     directory: boolean;
 }
+/** A command through the harness's own shell, allowed by the user's opt-in and held in Ordewell's sandbox (ADR-0036 N2, N3). */
+ | {
+    kind: 'native-shell';
+    tool: string;
+    command?: string;
+}
 /** `note` is why, for a tool the runner knows the planner must not use, in place of the envelope's generic refusal. */
  | {
     kind: 'other';
@@ -1358,6 +2047,13 @@ interface PlannerStartOptions extends AgentStartCommon {
      * means off.
      */
     nativeSearch?: boolean;
+    /**
+     * Whether the user let this planner use its harness's own shell beside
+     * Ordewell's tools (ADR-0036 N1). The caller sets it only for a version that
+     * passed N2's live checks (see `nativeShellOffer`); absent means off. When
+     * true, the adapter puts every command in Ordewell's sealed profile (N2).
+     */
+    nativeShell?: boolean;
     /**
      * The repository's own MCP servers this planner may start, as approved
      * (ADR-0028). The runner is launched without the repository's config, so
@@ -1371,6 +2067,8 @@ interface PlannerStartOptions extends AgentStartCommon {
  * The adapter adds only its protocol flags around these.
  */
 interface TaskRunnerFlags {
+    /** Ordewell's read-only profile, independent of the runner's native modes (ADR-0046). */
+    readOnly?: true;
     /** The runner's own permission-mode value for the task's mode. */
     permissionMode: string;
     /** The task's raw effort id, present only alongside a model. Each adapter maps it to its own protocol. */
@@ -1381,9 +2079,13 @@ interface TaskRunnerFlags {
 /** A plan task driven over the runner's programmatic protocol (ADR-0018, C1). */
 interface TaskStartOptions extends AgentStartCommon {
     kind: 'task';
+    /** The session workspace, also readable when cwd is an isolated task worktree (ADR-0046). */
+    workspaceRoot?: string;
     /** The task's runner mode id, as the plan names it. */
     mode: string;
     flags: TaskRunnerFlags;
+    /** The attempt's work lands as a commit (ADR-0047): its completion contract asks for the message. */
+    commits?: true;
     /**
      * The Ordewell MCP server and this attempt's token (ADR-0022), injected
      * with its tools pre-approved. A task is never started without it: its
@@ -1423,6 +2125,13 @@ interface AgentAdapter {
     send(message: string, onEvent: (event: AgentEvent) => void, signal?: AbortSignal, onActivity?: () => void): Promise<void>;
     /** The agent's native session id once it has announced one. Resumption hint only. */
     nativeSessionId(): string | null;
+    /**
+     * The installed version the agent reported, once it has (ADR-0036 N2):
+     * Claude Code's `claude_code_version` on its first `init`, an OpenCode 2.x
+     * server's `/api/info`. Null while unknown, and on OpenCode 1.x, which does
+     * not report one.
+     */
+    version?(): string | null;
     /** What has been counted of the session's running cost, for a runner that reports one; null while unknown. */
     sessionCost?(): RunnerSessionCost | null;
     /** Kill the process and release its resources. Idempotent. */
@@ -1433,8 +2142,17 @@ interface AgentAdapter {
      * Whether the Ordewell MCP server passed in the start options' `mcp` is
      * connected, as the runner itself reports it (ADR-0022, S4). Absent on an
      * adapter that cannot inject the server at all, which cannot run tasks.
+     * `false` is the old boolean answer for "not attached"; a real adapter says
+     * `pending` while its process is still starting, or `failed` when the
+     * runner reports the server cannot connect.
      */
-    mcpAttached?(): Promise<boolean>;
+    mcpAttached?(): Promise<boolean | AttachState>;
+    /**
+     * Registers a listener for the process ending, for any reason; a planner
+     * reads it to tell a runner that exited while it started. Fires at most
+     * once. `lastWords` is how it ended, with its stderr tail.
+     */
+    onProcessExit?(listener: (code: number, lastWords?: string) => void): void;
     /**
      * The approved project servers (ADR-0028) this runner started but cannot
      * give the planner as tools of their own, known once `start` resolved.
@@ -1458,7 +2176,7 @@ interface AgentAdapter {
 }
 /** What an adapter adds to run a task rather than a planner (ADR-0018). */
 interface TaskModeAgentAdapter extends AgentAdapter {
-    mcpAttached(): Promise<boolean>;
+    mcpAttached(): Promise<boolean | AttachState>;
     /**
      * Ask the running turn to stop, keeping the process and its session. Resolves
      * true once the agent acknowledged it; the turn then ends with
@@ -1537,6 +2255,8 @@ interface AgentProcessDeps {
     exists?: (candidate: string) => boolean;
     /** The workspace's own variables for a cwd (ADR-0016). Defaults to {@link resolveWorkspaceEnv}. */
     workspaceEnv?: (cwd: string) => Promise<Record<string, string>>;
+    /** Builds the sandbox around a planner's own shell (ADR-0036 N2). Defaults to the host's probe. */
+    nativeShellSandbox?: () => PlannerShellSandbox;
 }
 /** Builds the adapter for one runner id, or null when that runner cannot plan. */
 type AgentAdapterFactory = (runner: string, deps: AgentProcessDeps) => AgentAdapter | null;
@@ -1563,6 +2283,54 @@ interface RunnerManifest {
     contextFile?: string;
     contextFileAltPath?: string;
     modes?: RunnerMode[];
+    /** How to ask whether the user is signed in. Absent when the runner offers no status command. */
+    auth?: RunnerAuthSpec;
+}
+/** What a runner's status command answered, with both streams kept apart. */
+interface RunnerAuthStatus {
+    /** The exit status; never negative, since a timeout or a failed spawn is not an answer. */
+    code: number;
+    stdout: string;
+    stderr: string;
+    /** stdout and stderr together, for a reader that matches a line on either. */
+    output: string;
+    /** The merged probe environment, so a reader can consult the config the command read. */
+    env: NodeJS.ProcessEnv;
+    /**
+     * What the answer is: the status command's output, or a failed turn's own
+     * words. A reader that parses the status output (JSON, say) cannot parse
+     * the turn's message, and one that judges a turn's words by the runner's
+     * config must not let the probe's exit code guess for it.
+     */
+    kind: 'status' | 'turn';
+}
+/**
+ * A runner's own answer to "is the user signed in?" — the CLI args that ask,
+ * the args that log in, and how to read the answer. Declared here because a
+ * surface must run the same login the runner's own CLI would, with no second
+ * table to drift.
+ */
+interface RunnerAuthSpec {
+    /** The CLI args that answer whether the user is signed in, e.g. `auth status`. */
+    statusArgs: string[];
+    /** The CLI args that run the login, e.g. `auth login`. */
+    loginArgs: string[];
+    /**
+     * Matched against the status command's stdout+stderr when it exits non-zero,
+     * and against a failed turn's own words to tell a signed-out failure from an
+     * unrelated one.
+     */
+    signedOut?: RegExp;
+    /**
+     * A runner-specific reader that overrides the exit-code/regex rule. `null`
+     * means the answer said nothing about the login, which stays `unknown`
+     * rather than guessing from an exit code or from a line meant for another
+     * credential route. The reader owns both kinds of answer — the status
+     * command's output and a failed turn's own words — told apart by
+     * {@link RunnerAuthStatus.kind}; where the reader exists, it is the only
+     * judge of either.
+     */
+    read?: (answer: RunnerAuthStatus) => 'signed-in' | 'signed-out' | null;
 }
 interface RunnerFeatures {
     permissionModeValues?: Record<string, string>;
@@ -1695,6 +2463,16 @@ declare class RunnerRegistry {
     listEnabledIds(config: IConfig): string[];
 }
 
+/**
+ * What a read-only attempt's `fetch` and `web_search` calls are answered from
+ * (ADR-0046). `signal` is the call's: it aborts when the token is revoked or
+ * the caller cancels.
+ */
+interface TaskWebReads {
+    fetch(url: string, signal: AbortSignal): Promise<McpToolReply>;
+    search(query: string, signal: AbortSignal): Promise<McpToolReply>;
+}
+
 /** How a structured turn ended. `failed` carries the agent's own words in the preceding `error` event. */
 type StructuredTurnEnd = 'completed' | 'interrupted' | 'failed';
 /**
@@ -1771,7 +2549,80 @@ type StructuredEvent = Exclude<AgentEvent, {
  | {
     type: 'permission_withdrawn';
     id: string;
+}
+/**
+ * The runner's `task_complete` call was accepted on the attempt's token, with
+ * the status it reported (ADR-0018, L1). A receipt, not evidence: the report
+ * reaches {@link IRunnerSession.onTaskComplete} once its turn closes or the
+ * interrupt grace runs out, and a turn or message the runner reads first voids it.
+ */
+ | {
+    type: 'completion_received';
+    status: TaskCompleteArgs['status'];
+}
+/** A script task's command as it starts (ADR-0035): its argument vector, or its script, once. */
+ | ({
+    type: 'script_run';
+} & ScriptRun)
+/**
+ * What the running command printed, its stdout and stderr as they came.
+ * `omittedChars` is set on the tail of an output too long to keep whole: that
+ * much of its middle was left out.
+ */
+ | {
+    type: 'script_output';
+    text: string;
+    omittedChars?: number;
+}
+/** How the command ended, and after how long; `timedOut` when the task's time limit ended it. */
+ | ({
+    type: 'script_exit';
+    durationMs: number;
+    timedOut?: true;
+} & ScriptStatus);
+/** What one step of a script task runs: an argument vector of its `commands`, or its `script`. */
+type ScriptRun = {
+    argv: string[];
+} | {
+    script: string;
+};
+/** How a script task's process ended: its exit code, or the signal that ended it; `error` when it could not start. */
+interface ScriptStatus {
+    code: number | null;
+    signal: string | null;
+    error?: string;
+}
+/**
+ * How a script task's body ended (ADR-0035): the evidence its session hands
+ * `VerdictEngine`, as a runner's `task_complete` call is handed to it.
+ * `command` names the command of `commands` it ended on, as a reader would
+ * type it; a `script` body is one step and names none. `errorTail` is the end
+ * of what that step wrote to stderr. `fullOutput` is the file that holds all
+ * of the attempt's output, since the task log keeps only its ends.
+ */
+type ScriptExit = ({
+    outcome: 'passed';
+} | {
+    outcome: 'failed';
+    command?: string;
+    status: ScriptStatus;
+    errorTail: string;
+} | {
+    outcome: 'timed-out';
+    command?: string;
+    timeoutMs: number;
+    errorTail: string;
+} | {
+    outcome: 'stopped';
+    command?: string;
+}) & {
+    fullOutput?: ScriptFullOutput;
 };
+/** Where a script task attempt's whole output was saved, and how much of it a hard cap did not keep. */
+interface ScriptFullOutput {
+    file: string;
+    droppedChars: number;
+}
 /** A runner command a user invoked, with its arguments as typed. */
 interface InvokedCommand {
     name: string;
@@ -1873,6 +2724,13 @@ interface IRunnerSession {
      * `signal` aborts when the caller goes away.
      */
     onToolCheckpoint(handler: (question: string, signal: AbortSignal) => Promise<CheckpointAnswer>): void;
+    /**
+     * A script task's end (ADR-0035): its exit status, the attempt's evidence in
+     * place of a `task_complete` call, for `VerdictEngine` to weigh. Handed once,
+     * before the session exits. A runner's session never hands one: its model
+     * reports through `task_complete`.
+     */
+    onScriptExit(listener: (exit: ScriptExit) => void): void;
 }
 interface IRunner {
     spawn(opts: {
@@ -1884,6 +2742,8 @@ interface IRunner {
         modelVariants?: string[];
         mode?: string;
         cwd: string;
+        /** The session workspace, also readable by an isolated read-only task (ADR-0046). */
+        workspaceRoot?: string;
         registry?: RunnerRegistry;
         /** Task order and title — surfaces use these to label task_started/output events. */
         order?: number;
@@ -1925,6 +2785,45 @@ interface IRunner {
         skills?: readonly TaskSkillSnapshot[];
         /** Something the user should know about how the spawn went that did not stop it — a respawn, most often. */
         onNotice?: (message: string) => void;
+        /** The attempt's work lands as a commit (ADR-0047): its runner is told to write the message in `task_complete`. */
+        commits?: true;
+        /** A script task's body (ADR-0035): only the script runner reads it, and it runs nothing else. */
+        script?: ScriptBody;
+        /**
+         * A read-only attempt's shell (ADR-0046): its token serves `run_command`
+         * from it, and only an attempt that has one is given that tool.
+         */
+        shell?: TaskShell;
+        /**
+         * Checks a `task_complete` call's handoff against the plan as the call
+         * arrives (ADR-0047): a refusal is the call's result, and nothing is
+         * recorded. Without one, a `task` reference resolves against no plan.
+         */
+        checkHandoff?: (completion: TaskCompleteArgs) => HandoffCheck<TaskCompleteArgs>;
+        /**
+         * Answers the attempt's `read_task` calls (ADR-0047), against the plan
+         * and the session's task logs. Without one the call says it is not available.
+         */
+        readTask?: (args: ReadTaskArgs) => McpToolReply;
+        /**
+         * Answers a read-only attempt's `save_patch` calls (ADR-0050): its shell
+         * captures the worktree's changes and the attempt keeps them. Without one
+         * the call says it is not available.
+         */
+        savePatch?: (signal: AbortSignal) => Promise<McpToolReply>;
+        /**
+         * Answers a change attempt's `apply_patch` calls (ADR-0050): a saved patch
+         * of a task it may read, applied into its worktree. Without one the call
+         * says it is not available.
+         */
+        applyPatch?: (args: ApplyPatchArgs) => Promise<McpToolReply>;
+        /**
+         * Answers a read-only attempt's `fetch` and `web_search` calls (ADR-0046)
+         * through the session's web-read policy, apart from its shell. Only a
+         * read-only attempt's token lists them; without one they say they are
+         * not available.
+         */
+        webReads?: TaskWebReads;
     }): Promise<IRunnerSession>;
     /** Wind one session down ({@link IRunnerSession.stop}); resolves once its process is gone. */
     stop(sessionId: string): Promise<void>;
@@ -1933,79 +2832,4 @@ interface IRunner {
     activeCount: number;
 }
 
-interface ToolOutcome {
-    success: boolean;
-    output: string;
-    truncated: boolean;
-}
-interface ReadFileOpts {
-    maxBytes?: number;
-    offset?: number;
-    limit?: number;
-}
-/**
- * `content` returns matching lines, `files` only the paths that matched, and
- * `count` a per-file tally. Cheap models otherwise grep and then read whole
- * files to answer "which files touch this", burning rounds against the budget.
- */
-type GrepOutputMode = 'content' | 'files' | 'count';
-interface GrepOptions {
-    /** File glob filter, e.g. `*.ts`. */
-    include?: string;
-    /** Search root. Relative to the workspace unless approved as external. */
-    path?: string;
-    outputMode?: GrepOutputMode;
-    /** Lines of context around each match (`content` mode only). */
-    contextBefore?: number;
-    contextAfter?: number;
-    /** Treat the pattern as a literal string rather than a regex. */
-    literal?: boolean;
-    caseInsensitive?: boolean;
-    /** Global cap on returned rows. Defaults to {@link GREP_DEFAULT_HEAD_LIMIT}. */
-    headLimit?: number;
-}
-interface GlobOptions {
-    /** Search root. Relative to the workspace unless approved as external. */
-    path?: string;
-    headLimit?: number;
-}
-interface FindSymbolOptions {
-    /** Language id or file extension, e.g. `typescript` or `.go`. Narrows the keyword set. */
-    language?: string;
-    /** Search root. Relative to the workspace unless approved as external. */
-    path?: string;
-}
-/** Global row cap for grep. A per-file cap is not a budget — see PoolFileSystem. */
-declare const GREP_DEFAULT_HEAD_LIMIT = 100;
-/**
- * Directories that are never interesting to a planner and would otherwise eat
- * the result budget. Applied by every search entry point, not just `glob` —
- * `dist/` and `.ordewell/` are frequently not gitignored.
- */
-declare const SEARCH_EXCLUSIONS: string[];
-interface IFileSystem {
-    readFile(path: string, opts?: ReadFileOpts): Promise<ToolOutcome>;
-    readFiles(paths: string[]): Promise<ToolOutcome>;
-    glob(pattern: string, opts?: GlobOptions): Promise<ToolOutcome>;
-    grep(pattern: string, opts?: GrepOptions): Promise<ToolOutcome>;
-    listDir(path: string, depth?: number): Promise<ToolOutcome>;
-    /**
-     * `signal` stops the planning turn this command belongs to: adapters kill
-     * the spawned child rather than let it run out its own timeout. The other
-     * tools here are short enough that the loop's between-call abort check is
-     * indistinguishable from cancelling them mid-flight; a `bash` call is not.
-     */
-    bash(command: string, signal?: AbortSignal): Promise<ToolOutcome>;
-    /** Definition-first lookup for one symbol. See `symbolPatterns.ts`. */
-    findSymbol(symbol: string, opts?: FindSymbolOptions): Promise<ToolOutcome>;
-    getWorkspaceRoot(): string;
-    /**
-     * Inject the human-approval channel for out-of-envelope access. Optional so
-     * test doubles stay small; every adapter extending `BaseFileSystem` has it.
-     */
-    setApproval?(approval: IApproval): void;
-    /** Held credentials read live by the outbound secret check. */
-    setOutboundSecrets?(secrets: () => Iterable<string>): void;
-}
-
-export { ORCHESTRATOR_SHORTCUTS as $, AUTO_COMMANDS as A, type GlobOptions as B, type CatalogModel as C, DEFAULT_PLANNER_ALLOWLIST as D, type EditPlanArgs as E, type FetchAllProviderModelsOptions as F, GIT_READONLY_SUBCOMMANDS as G, type GrepOptions as H, type GrepOutputMode as I, type IApproval as J, type IConfig as K, type IFileSystem as L, type IRunner as M, type IRunnerSession as N, type InvokedCommand as O, LineBuffer as P, type ListModelsArgs as Q, type ListRunnersArgs as R, type LoadSkillArgs as S, type McpClientConfig as T, type McpCredential as U, type McpTool as V, type McpToolContext as W, type McpToolReply as X, type MessageTaskArgs as Y, ModelCatalog as Z, type ModelShortcut as _, type AgentAdapter as a, effectiveApprovalMode as a$, ORDEWELL_MCP_PATH as a0, ORDEWELL_MCP_SERVER_NAME as a1, type OneTaskArgs as a2, type OrchestratorOption as a3, OrdewellMcpServer as a4, type OwnerOnlyFile as a5, PLANNER_EXECUTION_TOOLS as a6, PLANNER_TOOLS as a7, type PlannerAllowlist as a8, type PlannerBackendId as a9, type ShellDialect as aA, type SpawnFn as aB, type StandingDecision as aC, type StructuredEvent as aD, type StructuredTurnEnd as aE, type SubmitPlanArgs as aF, TASK_COMPLETE_TOOL as aG, TASK_COMPLETION_CONTRACT as aH, TASK_TOOLS as aI, type TaskCompleteArgs as aJ, type TaskDiffArgs as aK, type TaskMessageFrom as aL, type TaskModeAgentAdapter as aM, TaskModeUnsupportedError as aN, type TaskOutputArgs as aO, type TaskQueryArgs as aP, type TaskRunnerFlags as aQ, type TaskStartOptions as aR, type TaskTokenScope as aS, type TaskToolHandler as aT, type ToolOutcome as aU, type UsageLimitSignal as aV, approvalScopes as aW, classifyCommand as aX, clearResearchShellCache as aY, collectProviderCredentials as aZ, commandAllowedBy as a_, type PlannerStartOptions as aa, type PlannerTokenScope as ab, type PlannerToolHandler as ac, type ProjectMcpServer as ad, type ProviderCredentialSource as ae, type ProviderModelLists as af, type ProviderModelsResult as ag, type QueuedTaskMessage as ah, REFUSED_COMMANDS as ai, type ReadFileOpts as aj, type ResearchShell as ak, type ResearchShellDeps as al, type RetryTaskArgs as am, type RunCommandArgs as an, type RunPlanArgs as ao, type RunnerCommand as ap, type RunnerCommandKind as aq, type RunnerEntry as ar, type RunnerFeatures as as, type RunnerManifest as at, type RunnerMcpServer as au, type RunnerMode as av, type RunnerModelDiscovery as aw, type RunnerModelRef as ax, RunnerRegistry as ay, SEARCH_EXCLUSIONS as az, type AgentAdapterFactory as b, enabledRunners as b0, fetchAllProviderModels as b1, findRunnerCommand as b2, isGranted as b3, isRunnerApproval as b4, knownModelId as b5, mcpClientConfig as b6, ownerOnlyConfigFile as b7, parseAllowlist as b8, parseApprovalModeSetting as b9, researchShellWarning as ba, researchToolsPath as bb, resolveModelShortcut as bc, resolveProvider as bd, resolveResearchShell as be, scopeAllowed as bf, sharedMcpServer as bg, toApprovalDecision as bh, toOrchestratorOptions as bi, toolAllowed as bj, type AgentEvent as c, type AgentProcessDeps as d, type AgentStartOptions as e, type AiProvider as f, type AllProviderModels as g, type AnswerApprovalArgs as h, type ApprovalAnswer as i, type ApprovalDecision as j, type ApprovalKind as k, type ApprovalMode as l, type ApprovalModeSetting as m, ApprovalPolicy as n, type ApprovalPolicyOptions as o, type ApprovalRequest as p, type ApprovalSource as q, type CheckpointAnswer as r, type CheckpointArgs as s, type CommandClassification as t, type CommandTier as u, type CommandWords as v, DENY_ALL as w, type DiscoveryCommand as x, type FindSymbolOptions as y, GREP_DEFAULT_HEAD_LIMIT as z };
+export { type McpToolContext as $, AUTO_COMMANDS as A, type BashOptions as B, type CatalogModel as C, DEFAULT_PLANNER_ALLOWLIST as D, type DiscoveryCommand as E, type EditPlanArgs as F, type FetchAllProviderModelsOptions as G, type FindSymbolOptions as H, GIT_READONLY_SUBCOMMANDS as I, GREP_DEFAULT_HEAD_LIMIT as J, type GlobOptions as K, type GrepOptions as L, type GrepOutputMode as M, type IApproval as N, type IConfig as O, type IFileSystem as P, type IRunner as Q, type IRunnerSession as R, type InvokedCommand as S, LineBuffer as T, type ListModelsArgs as U, type ListRunnersArgs as V, type LoadSkillArgs as W, type McpClientConfig as X, type McpCredential as Y, type McpRefusal as Z, type McpTool as _, type AgentAdapter as a, type SealedRunOptions as a$, type McpToolReply as a0, type MessageTaskArgs as a1, ModelCatalog as a2, type ModelShortcut as a3, ORCHESTRATOR_SHORTCUTS as a4, ORDEWELL_MCP_PATH as a5, ORDEWELL_MCP_SERVER_NAME as a6, type OneTaskArgs as a7, type OrchestratorOption as a8, OrdewellMcpServer as a9, type RunCommandArgs as aA, type RunPlanArgs as aB, type RunnerAuthSpec as aC, type RunnerAuthStatus as aD, type RunnerCommand as aE, type RunnerCommandKind as aF, type RunnerEntry as aG, type RunnerFeatures as aH, type RunnerManifest as aI, type RunnerMcpServer as aJ, type RunnerMode as aK, type RunnerModelDiscovery as aL, type RunnerModelRef as aM, RunnerRegistry as aN, SEALED_LIMITS as aO, SEARCH_EXCLUSIONS as aP, type SandboxBackend as aQ, type SandboxInvocation as aR, type SandboxLaunch as aS, type SandboxLimits as aT, type SandboxProfile as aU, type ScriptBody as aV, type ScriptExit as aW, type ScriptFullOutput as aX, type ScriptRun as aY, type ScriptStatus as aZ, type SealedAvailability as a_, type OwnSealedRuns as aa, type OwnerOnlyFile as ab, PLANNER_EXECUTION_TOOLS as ac, PLANNER_SANDBOX_DOCS as ad, PLANNER_TOOLS as ae, type PlannerAllowlist as af, type PlannerBackendId as ag, type PlannerSandboxAvailability as ah, type PlannerSandboxDeps as ai, PlannerShellSandbox as aj, type PlannerStartOptions as ak, type PlannerTokenScope as al, type PlannerToolHandler as am, type ProjectMcpServer as an, type ProviderCredentialSource as ao, type ProviderModelLists as ap, type ProviderModelsResult as aq, type QueuedTaskMessage as ar, READ_ONLY_TASK_TOOLS as as, REFUSED_COMMANDS as at, type ReadFileOpts as au, type ReadTaskArgs as av, type ResearchShell as aw, type ResearchShellDeps as ax, type RetryTaskArgs as ay, type RuleWord as az, type AgentAdapterFactory as b, type ShellDialect as b0, type ShellLaunch as b1, type SpawnFn as b2, type StandingDecision as b3, type StructuredEvent as b4, type StructuredTurnEnd as b5, type SubmitPlanArgs as b6, TASK_COMPLETE_TOOL as b7, TASK_COMPLETION_CONTRACT as b8, TASK_SEALED_LIMITS as b9, enabledRunners as bA, fetchAllProviderModels as bB, findRunnerCommand as bC, isGranted as bD, isRunnerApproval as bE, knownModelId as bF, mcpClientConfig as bG, ownerOnlyConfigFile as bH, parseAllowlist as bI, parseApprovalModeSetting as bJ, researchShellWarning as bK, researchToolsPath as bL, resolveModelShortcut as bM, resolvePlannerSandbox as bN, resolveProvider as bO, resolveResearchShell as bP, scopeAllowed as bQ, scriptBodyOf as bR, scriptBodyText as bS, scriptTaskText as bT, sharedMcpServer as bU, taskCompletionContract as bV, timeLimitText as bW, toApprovalDecision as bX, toOrchestratorOptions as bY, toolAllowed as bZ, TASK_TOOLS as ba, type TaskCompleteArgs as bb, type TaskDiffArgs as bc, type TaskMessageFrom as bd, type TaskModeAgentAdapter as be, TaskModeUnsupportedError as bf, type TaskOutputArgs as bg, type TaskQueryArgs as bh, type TaskRunCommandArgs as bi, type TaskRunnerFlags as bj, type TaskShell as bk, type TaskShellSite as bl, type TaskStartOptions as bm, type TaskTokenScope as bn, type TaskToolHandler as bo, type TaskWebReads as bp, type ToolOutcome as bq, type UsageLimitSignal as br, approvalScopes as bs, classifyCommand as bt, clearPlannerSandboxCache as bu, clearResearchShellCache as bv, collectProviderCredentials as bw, commandAllowedBy as bx, commandLine as by, effectiveApprovalMode as bz, type AgentEvent as c, type AgentProcessDeps as d, type AgentStartOptions as e, type AiProvider as f, type AllProviderModels as g, type AnswerApprovalArgs as h, type ApplyPatchArgs as i, type ApprovalAnswer as j, type ApprovalDecision as k, type ApprovalKind as l, type ApprovalMode as m, type ApprovalModeSetting as n, ApprovalPolicy as o, type ApprovalPolicyOptions as p, type ApprovalRequest as q, type ApprovalSource as r, type AttachState as s, type CheckpointAnswer as t, type CheckpointArgs as u, type CommandClassification as v, type CommandTier as w, type CommandWords as x, DEFAULT_SCRIPT_TIMEOUT_MS as y, DENY_ALL as z };