@ordewell/core 0.4.0

package/dist/index.d.ts

@@ -0,0 +1,2990 @@
+import { h as RunnerId, c as PlanStatus, L as LegacyPlanState, d as ResearchProgress, a as DiscoveredModel, T as Task, R as ResearchLogEntry, C as ConversationMessage, n as TaskSnapshot, Q as QueuedMessage, A as ActiveTaskSession, g as ResearchToolType, u as Verdict, e as ResearchStep, b as PlanState } from './Task-1NwmUImI.js';
+export { D as DiscoveredMode, M as Message, P as PlanModificationWarnings, f as ResearchStepOutcome, S as StreamEvent, i as StreamStepEvent, j as StreamThinkingEvent, k as TaskMode, l as TaskModelAssignment, m as TaskOutputSummary, o as TaskStatus, p as TaskType, q as ThinkingBlock, U as UserPromptEntry, r as UserStep, V as ValidationCheck, s as ValidationContext, t as ValidationResult, v as VerificationCheck, w as addTaskToPlan, x as createEmptyPlan, y as createTask, z as emptyWarnings, B as flattenTasks, E as migrateLegacyPlan, F as migratePlanState, G as migrateTask, H as removeTaskFromPlan, I as renumberTasks, J as updateTaskInPlan, K as validateModifiedPlan, N as warningsText } from './Task-1NwmUImI.js';
+import { n as IFileSystem, I as IApproval, R as ReadFileOpts, T as ToolOutcome, k as GrepOptions, j as GlobOptions, i as FindSymbolOptions, f as ApprovalRequest, m as IConfig, A as AiProvider, y as ProviderModelLists, c as ApprovalMode, q as ITerminalSession, p as ITerminalRunner, J as RunnerRegistry, s as OrchestratorOption, b as ApprovalKind, g as ApprovalSource, E as RunnerInvocation, o as IPluginStore, H as RunnerPluginManifest, B as ResolveContext } from './ITerminalRunner-Bbpe8uts.js';
+export { a as AllProviderModels, d as ApprovalPolicy, e as ApprovalPolicyOptions, C as CatalogModel, D as DENY_ALL, h as DiscoveryCommand, F as FetchAllProviderModelsOptions, G as GREP_DEFAULT_HEAD_LIMIT, l as GrepOutputMode, M as ModelCatalog, r as ModelShortcut, O as ORCHESTRATOR_SHORTCUTS, P as PluginEntry, t as PluginFeatures, u as PluginMode, v as PluginModelDiscovery, w as PluginRunnerDef, x as ProviderCredentialSource, z as ProviderModelsResult, S as SEARCH_EXCLUSIONS, K as collectProviderCredentials, L as enabledRunners, N as fetchAllProviderModels, Q as knownModelId, U as resolveModelShortcut, V as resolveProvider, W as toOrchestratorOptions } from './ITerminalRunner-Bbpe8uts.js';
+import { R as RunnerModeInfo, b as PlanParseError } from './parsing-RjN9JbyG.js';
+export { M as ManifestLookup, P as PLAN_ENVELOPE_KEY, a as PartialPlanTask, T as TASK_OPS_ENVELOPE_KEY, c as buildModeGuide, d as checkDepsResolve, e as checkImmutableLog, f as checkInProgress, g as checkNoCycles, h as checkUniqueIds, i as escapeControlCharsInStrings, j as extractJsonObject, k as extractObjectWithBalance, l as extractObjectsWithKey, m as filteredBuildModes, n as looksLikePlanAttempt, p as parsePartialPlan, o as parsePlanJson, r as resolveDefaultMode, q as resolveTaskMode, s as runnerModesFrom, t as stripModelNoise, u as stripTrailingCommas, v as validatePlanModification } from './parsing-RjN9JbyG.js';
+import { T as TaskOp } from './plan-utils-Cgc0cCH1.js';
+export { A as ApplyTaskOpsResult, a as TaskRef, b as applyTaskOps, c as canMergeTasks, d as canSetDependencies, e as canSplitTask, f as classifyOutcome, g as dependencyCandidates, h as dependentsOf, p as parseTaskOpsJson, s as summarizeToolCall, t as textHasTaskOps } from './plan-utils-Cgc0cCH1.js';
+import { ChildProcess } from 'child_process';
+import { EventEmitter } from 'events';
+
+interface SessionMeta {
+    id: string;
+    goal: string;
+    runners: RunnerId[];
+    taskCount: number;
+    status: PlanStatus;
+    createdAt: string;
+    updatedAt: string;
+}
+interface SessionData {
+    meta: SessionMeta;
+    /** The full plan state — including conversationHistory, prdMarkdown, and queuedMessages. */
+    plan: LegacyPlanState;
+}
+
+/**
+ * Which interpreter runs the planner's `bash` tool, and in which language.
+ *
+ * `AUTO_COMMANDS` — the read-only tier that runs with no prompt — is `ls`, `cat`,
+ * `wc`, `head`, `tail`, `du`, `df`, `file`, `sort`, `uniq`, `basename`, `find`,
+ * `grep`. That set is POSIX, and passing it to `shell: true` on Windows means
+ * cmd.exe, where most of those names do not exist and `find` is an unrelated
+ * program that returns plausible wrong output instead of an error. The planner's
+ * whole research surface degraded to guessing, quietly.
+ *
+ * Rather than write a Windows dialect of every research command — a second
+ * behavior to keep in step forever — this finds a POSIX shell to run the
+ * existing ones in. Git for Windows ships a full one, and git is already a
+ * prerequisite for everything Ordewell does, so in practice it is there. Failing
+ * that, cmd.exe is used and the classifier is told so, because the one thing
+ * that must never happen is classifying a command in one language and running it
+ * in another: `commandPolicy` reads {@link ResearchShell.dialect} for exactly
+ * that reason.
+ *
+ * POSIX resolves to `{ file: null }`, meaning "use `shell: true`" — byte for
+ * byte what the adapters did before this module existed.
+ *
+ * Windows paths are built with `path.win32` explicitly, not the host-flavoured
+ * `path`, so the probe is the same on a Windows host as it is under a Linux
+ * test runner.
+ */
+type ShellDialect = 'posix' | 'cmd';
+interface ResearchShell {
+    /**
+     * Executable that takes a command string, or null to use the host default
+     * via `shell: true`.
+     */
+    file: string | null;
+    /** Arguments preceding the command string. */
+    args: string[];
+    /** The language the command string will be interpreted in. */
+    dialect: ShellDialect;
+    /**
+     * Directory holding this shell's POSIX utilities, when it brings its own.
+     * Prepended to PATH for the search subprocesses (`grep`, `tree`) that
+     * `execFile` starts without a shell, so they resolve too.
+     */
+    utilsDir: string | null;
+}
+interface ResearchShellDeps {
+    platform?: NodeJS.Platform;
+    exists?: (candidate: string) => boolean;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * The shell the planner's `bash` tool should use on this host. Resolved once per
+ * process — the answer cannot change while Ordewell runs, and the probe costs a
+ * handful of `stat` calls.
+ */
+declare function resolveResearchShell(deps?: ResearchShellDeps): ResearchShell;
+/** Test seam: drop the per-process cache so the next call re-probes. */
+declare function clearResearchShellCache(): void;
+/**
+ * PATH for the search subprocesses the adapters start without a shell, with the
+ * research shell's own utilities in front. Without this, `grep` — the fallback
+ * when ripgrep is absent — is unresolvable on a Windows box even when a
+ * perfectly good `grep.exe` sits in the Git tree beside the shell.
+ */
+declare function researchToolsPath(shell: ResearchShell, basePath: string | undefined): string;
+/**
+ * A message explaining a degraded research surface, or null when there is
+ * nothing to explain. Surfaced by the adapters on the first refused command so
+ * the limitation is visible rather than inferred from bad answers.
+ */
+declare function researchShellWarning(shell: ResearchShell): string | null;
+
+/**
+ * Tiered classification for the planner's `bash` tool.
+ *
+ * The planner is a read-only researcher: it never edits files, and the runners
+ * do the real work. But research legitimately means running things — querying a
+ * cloud control plane (`az`, `gh`), reproducing a failure (`npm test`), or
+ * shaping output (`jq`). The old allowlist refused all of that, so the model's
+ * only escape was to guess.
+ *
+ * Three tiers replace the flat allowlist:
+ *
+ *   auto    read-only inspection — runs with no prompt (the historical list)
+ *   ask     anything else that is not obviously destructive — one approval,
+ *           remembered for the rest of the session at `scope` granularity
+ *   refuse  writes, privilege escalation, and anything that would smuggle
+ *           arbitrary code past this classifier — never runs, never prompts
+ *
+ * `refuse` is deliberately not promptable. A planner that can `rm` is a planner
+ * that can silently break the workspace it was asked to reason about, and the
+ * architecture already says mutation belongs to the runners.
+ *
+ * Classification walks every segment of the command line (pipes, `&&`, `;`, and
+ * command substitution) rather than matching substrings against the raw string.
+ * The old substring denylist both over-matched (`ls docs/removed` tripped `rm`)
+ * and under-matched (`$(rm -rf /)` was invisible once chaining was allowed).
+ *
+ * The lexer is dialect-aware, because the interpreter that will actually run
+ * the command decides what the tokens are, and getting that wrong is not a
+ * cosmetic error here — it is the difference between classifying what runs and
+ * classifying something else. See {@link Dialect}.
+ */
+
+declare const AUTO_COMMANDS: string[];
+declare const GIT_READONLY_SUBCOMMANDS: string[];
+/**
+ * Never runs, with or without approval.
+ *
+ * The `cmd.exe` builtins at the end matter as much as the POSIX names above
+ * them. `del`, `rd`, `move`, and friends mutate exactly what `rm` and `mv` do,
+ * and on Windows they are what a model reaches for — so without them the whole
+ * refusal tier was bypassable on that platform by writing the command the way
+ * the platform spells it. Listed unconditionally rather than per-platform: a
+ * POSIX box has no `del` to refuse, so the extra names cost nothing there.
+ */
+declare const REFUSED_COMMANDS: string[];
+/**
+ * Options threaded through classification.
+ *
+ * `dialect` is keyed to the interpreter rather than the OS on purpose: a Windows
+ * host that has Git Bash runs the planner's commands in a POSIX shell (see
+ * {@link resolveResearchShell}), and classifying those under cmd.exe rules
+ * would be the same mismatch in the other direction. Callers pass the dialect of
+ * the shell they are actually going to use; omitting it falls back to the host
+ * default.
+ */
+interface CommandPolicyOptions {
+    dialect?: ShellDialect;
+}
+type CommandTier = 'auto' | 'ask' | 'refuse';
+interface CommandClassification {
+    tier: CommandTier;
+    /** What a grant covers, for `ask`. Derived from the non-auto segments only. */
+    scope: string;
+    /** Populated for `refuse`: why, in a sentence the model can act on. */
+    reason?: string;
+}
+/**
+ * Classify one command line. Output redirection is refused outright: a planner
+ * that writes files has stopped being a planner.
+ */
+declare function classifyCommand(command: string, opts?: CommandPolicyOptions): CommandClassification;
+
+/**
+ * The policy half of the planner's filesystem: path confinement, the tiered
+ * `bash` gate, and the definition-first symbol lookup. Adapters supply only the
+ * mechanics (`*Impl`), so the rules live in one place across the web server and
+ * the VS Code extension rather than being re-derived per surface.
+ *
+ * Every public method resolves and authorizes before delegating, and every
+ * `*Impl` therefore receives an absolute, already-approved path. Previously
+ * each adapter did its own resolution, and `path.isAbsolute(p) ? p : …` meant
+ * an absolute path walked straight out of the workspace with no prompt and no
+ * record.
+ */
+declare abstract class BaseFileSystem implements IFileSystem {
+    private approval;
+    /**
+     * The interpreter `execBashImpl` will hand the command to. Owned here rather
+     * than per-adapter because {@link classifyCommand} has to be told the same
+     * answer: a command lexed under POSIX rules and then run by cmd.exe is a
+     * command this class did not actually classify.
+     */
+    protected readonly researchShell: ResearchShell;
+    /** Surfaces inject the human channel here; without it, external access is denied. */
+    setApproval(approval: IApproval): void;
+    abstract getWorkspaceRoot(): string;
+    protected abstract readFileImpl(absPath: string, opts?: ReadFileOpts): Promise<ToolOutcome>;
+    protected abstract globImpl(pattern: string, absRoot: string, headLimit: number): Promise<ToolOutcome>;
+    protected abstract grepImpl(pattern: string, absRoot: string, opts: GrepOptions): Promise<ToolOutcome>;
+    protected abstract listDirImpl(absPath: string, depth: number): Promise<ToolOutcome>;
+    protected abstract execBashImpl(command: string): Promise<ToolOutcome>;
+    /**
+     * Resolve `p` and confirm the planner may touch it. In-workspace paths pass
+     * silently; anything else needs one approval, remembered per containing
+     * directory so a second file in the same place does not prompt again.
+     */
+    protected authorizePath(p: string, kind?: 'file' | 'directory'): Promise<{
+        ok: true;
+        abs: string;
+    } | {
+        ok: false;
+        outcome: ToolOutcome;
+    }>;
+    readFile(p: 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(p: string, depth?: number): Promise<ToolOutcome>;
+    /**
+     * Definitions first, then a reference tally. Two bounded searches beat one
+     * unbounded `grep` because the 100-row budget gets spent on the rows that
+     * answer the question.
+     */
+    findSymbol(symbol: string, opts?: FindSymbolOptions): Promise<ToolOutcome>;
+    /**
+     * Path confinement for `bash`: an `auto`-tier binary (`cat`, `find`, `rg`, …)
+     * is only auto because *reading* is read-only — its arguments can still
+     * name a path outside the workspace, which is the exact escape confinement
+     * closes for `readFile`/`glob`/`grep`. Each escaping path needs its own
+     * approval (scoped to its containing directory); approving one does not
+     * approve another, so a single command touching two external dirs prompts
+     * once per distinct scope rather than carrying the first grant to the rest.
+     */
+    private authorizeCommandPaths;
+    /**
+     * Three tiers (see `commandPolicy.ts`): read-only inspection runs silently,
+     * anything else asks once and is remembered, and writes are refused outright
+     * because a planner that mutates the workspace has stopped being a planner.
+     */
+    bash(command: string): Promise<ToolOutcome>;
+}
+
+/**
+ * Workspace containment, in one place. Both the filesystem policy layer
+ * (which may ask the user to approve an escape) and the research-subagent
+ * wrapper (which may not, because nothing can prompt on its behalf) need the
+ * same answer to "is this path inside the workspace", so neither re-derives it.
+ *
+ * Symlinks are resolved lexically, not on disk: a symlink inside the workspace
+ * pointing outward still reads as inside. Closing that would mean a `realpath`
+ * syscall on every path check, and the threat model here is an LLM wandering,
+ * not an adversary planting links in a repo the user already trusts enough to
+ * point Ordewell at.
+ */
+interface ResolvedPath {
+    abs: string;
+    inside: boolean;
+}
+declare function resolveWithin(root: string, target: string): ResolvedPath;
+/** The directory a grant covers for `target` — its parent for files, itself for directories. */
+declare function grantScopeFor(abs: string, kind: 'file' | 'directory'): string;
+
+/**
+ * The bridge between "core needs an answer" and "a human somewhere is looking
+ * at a UI". Core cannot prompt: the human may be at a browser, a TUI, a CLI
+ * stream, or a VS Code webview, and on the web server they are on the far end
+ * of a socket. So the Session parks a promise here, announces the request
+ * through the normal broadcast seam, and every surface answers through the
+ * same `resolve(id, granted)` call.
+ *
+ * Timeouts are load-bearing rather than defensive: a planner turn that blocks
+ * forever on an unanswered prompt would hang the whole research loop with no
+ * visible cause. On expiry the request resolves to denied and the model gets a
+ * normal, actionable tool result.
+ */
+interface PendingApproval {
+    id: string;
+    request: ApprovalRequest;
+    createdAt: string;
+}
+interface PendingApprovalsOptions {
+    /** Denies and resolves after this long with no answer. Default 5 minutes. */
+    timeoutMs?: number;
+    /** Announce a new request to the surfaces. */
+    onRequest?: (pending: PendingApproval) => void;
+    /** Announce that a request is no longer actionable (answered or expired). */
+    onSettled?: (id: string, granted: boolean) => void;
+}
+declare class PendingApprovals {
+    private readonly opts;
+    private readonly entries;
+    constructor(opts?: PendingApprovalsOptions);
+    /** Park a request and return the promise the approval policy awaits. */
+    ask(request: ApprovalRequest): Promise<boolean>;
+    /** Answer one request. Returns false when the id is unknown or already settled. */
+    resolve(id: string, granted: boolean): boolean;
+    /** Everything still awaiting an answer — replayed to a surface that connects late. */
+    outstanding(): PendingApproval[];
+    /** Deny everything in flight. Called on abort and on session reset. */
+    clear(): void;
+}
+
+/**
+ * Definition-shaped search patterns for the `find_symbol` tool.
+ *
+ * Plain `grep` is bad at the question the planner actually asks. Searching for
+ * `VerdictEngine` returns every import, call site, comment and string alongside
+ * the one line that defines it, and with a hard result cap the definition is
+ * often not even in the returned page. `find_symbol` spends the budget on
+ * declarations first and reports references as a count plus a sample.
+ *
+ * This is deliberately regex over a real parser. An LSP-grade answer would mean
+ * shipping per-language servers and waiting for them to index — the wrong trade
+ * for the half of the architecture whose whole point is being cheap and fast.
+ * The planner needs to scope tasks ("defined here, used across ~14 files in 3
+ * packages"), not to prove rename-safety; that is the runner's job, and runners
+ * have their own tools.
+ *
+ * Patterns target the Rust regex syntax ripgrep uses: non-capturing groups and
+ * `\b` are available, lookaround and backreferences are not.
+ */
+interface SymbolLanguage {
+    id: string;
+    extensions: string[];
+    /** Keywords that introduce a declaration in `kw Name` position. */
+    keywords: string[];
+}
+declare const SYMBOL_LANGUAGES: SymbolLanguage[];
+declare function languageForId(id: string): SymbolLanguage | undefined;
+/** The `--glob` filter that narrows a search to one language's files. */
+declare function includeGlobFor(language: SymbolLanguage): string;
+/**
+ * Build the definition pattern for `symbol`. Three shapes cover essentially
+ * every mainstream language:
+ *
+ *   1. `keyword Name`            — declarations across all of them
+ *   2. `Name = function|(`       — assigned function expressions and arrows
+ *   3. `… Name(args) {`          — C/Java/Go-style bodies with a return type
+ *
+ * Passing a `language` narrows shape 1 to that language's keywords, which cuts
+ * cross-language noise in polyglot repos.
+ */
+declare function definitionPattern(symbol: string, language?: SymbolLanguage): string;
+/** Every mention of the symbol as a whole word — the reference side of the report. */
+declare function referencePattern(symbol: string): string;
+
+interface GrepInvocation {
+    args: string[];
+    /** Rows beyond this are dropped by the caller — see `applyHeadLimit`. */
+    headLimit: number;
+}
+/**
+ * Build the ripgrep invocation for one grep call.
+ *
+ * `--max-count` is deliberately absent. It caps matches *per file*, so the old
+ * `--max-count 100` on a 300-file hit returned ~30 000 lines, blew the 1 MB
+ * exec buffer, and surfaced as `{ success: false, output: '' }` — a silent
+ * empty result on exactly the broad searches where the model most needed a
+ * signal. The cap belongs at the row level, applied after the fact.
+ */
+declare function buildGrepArgs(pattern: string, opts: GrepOptions, root: string): GrepInvocation;
+/** Build the ripgrep invocation that lists files matching a glob. */
+declare function buildGlobArgs(pattern: string, root: string): string[];
+/**
+ * The POSIX-grep fallback for machines without ripgrep. Ordering and `--sort`
+ * are unavailable.
+ *
+ * `-P` (PCRE) is required, not optional: patterns built in core — most
+ * notably `find_symbol`'s `definitionPattern` — use non-capturing groups and
+ * `\b`, which BRE has no syntax for and ERE (`-E`) still cannot express
+ * ((?:...) is a PCRE construct). Without `-P`, GNU grep either errors
+ * ("Unmatched \{") or, worse, silently treats `(`/`)`/`|` as literal
+ * characters and reports a confident empty result. `-P` and `-F` are
+ * mutually exclusive, so literal mode skips it.
+ */
+declare function buildFallbackGrepArgs(pattern: string, opts: GrepOptions, root: string): string[];
+/**
+ * GNU grep's own `--include` glob only ever matches a basename, so it silently
+ * matches nothing against an anchored pattern like `subdir/*.txt` (there is no
+ * `/` in a basename to match against). The fallback path drops such patterns
+ * from the grep invocation and filters matches by relative path here instead.
+ */
+declare function filterFallbackByAnchoredInclude(stdout: string, include: string, anchor: string, outputMode?: GrepOptions['outputMode']): string;
+interface CappedRows {
+    rows: string[];
+    truncated: boolean;
+    total: number;
+}
+/** Apply the global row cap and report honestly whether anything was dropped. */
+declare function applyHeadLimit(stdout: string, headLimit: number): CappedRows;
+/**
+ * Render capped rows for the model, with paths made workspace-relative and an
+ * explicit note when rows were dropped — a silently truncated list reads as a
+ * complete answer and the model plans against it.
+ */
+declare function formatSearchOutput(capped: CappedRows, root: string, opts: {
+    emptyMessage: string;
+    hint?: string;
+    sep?: string;
+}): string;
+
+declare function normalizeGeminiModel(id: string): string;
+declare abstract class BaseConfig implements IConfig {
+    abstract aiProvider: AiProvider;
+    abstract apiKey: string;
+    abstract planningModel: string;
+    abstract enabledRunners: string[];
+    abstract setProviderModelLists(lists: ProviderModelLists): void;
+    get openAiBaseUrl(): string;
+    get openAiApiKey(): string;
+    get openrouterKey(): string;
+    get geminiKey(): string;
+    get geminiBaseUrl(): string | undefined;
+    get openaiCompatibleBaseUrl(): string;
+    get openaiCompatibleApiKey(): string;
+    get orchestratorModel(): string;
+    get researchSubagentModel(): string;
+    get geminiModel(): string;
+    get plannerThinkingEffort(): string | undefined;
+    get openaiBaseUrl(): string;
+    get openaiApiKey(): string;
+    get xaiBaseUrl(): string;
+    get xaiApiKey(): string;
+    get groqBaseUrl(): string;
+    get groqApiKey(): string;
+    get deepseekBaseUrl(): string;
+    get deepseekApiKey(): string;
+    get togetherBaseUrl(): string;
+    get togetherApiKey(): string;
+    get mistralBaseUrl(): string;
+    get mistralApiKey(): string;
+    get anthropicBaseUrl(): string;
+    get anthropicApiKey(): string;
+    get fireworksBaseUrl(): string;
+    get fireworksApiKey(): string;
+    get perplexityBaseUrl(): string;
+    get perplexityApiKey(): string;
+    get zhipuBaseUrl(): string;
+    get zhipuApiKey(): string;
+    get kimiBaseUrl(): string;
+    get kimiApiKey(): string;
+    get cerebrasBaseUrl(): string;
+    get cerebrasApiKey(): string;
+    get deepinfraBaseUrl(): string;
+    get deepinfraApiKey(): string;
+    get doubaoBaseUrl(): string;
+    get doubaoApiKey(): string;
+    get qwenBaseUrl(): string;
+    get qwenApiKey(): string;
+    get hunyuanBaseUrl(): string;
+    get hunyuanApiKey(): string;
+    get baichuanBaseUrl(): string;
+    get baichuanApiKey(): string;
+    get minimaxBaseUrl(): string;
+    get minimaxApiKey(): string;
+    get yiBaseUrl(): string;
+    get yiApiKey(): string;
+    get stepfunBaseUrl(): string;
+    get stepfunApiKey(): string;
+    get siliconflowBaseUrl(): string;
+    get siliconflowApiKey(): string;
+    get cohereBaseUrl(): string;
+    get cohereApiKey(): string;
+    get novitaBaseUrl(): string;
+    get novitaApiKey(): string;
+    getProviderBaseUrl(provider: AiProvider): string;
+    getProviderApiKey(provider: AiProvider): string;
+    get maxParallelSessions(): number;
+    get researchEnabled(): boolean;
+    get researchMaxSteps(): number;
+    get researchMaxFileSize(): number;
+    get planMapEnabled(): boolean;
+    get autonomousMode(): boolean;
+    get approvalMode(): ApprovalMode;
+    get approvalPreApproved(): string[];
+    protected static detectProvider(fallback: AiProvider): AiProvider;
+}
+
+/**
+ * A fully `process.env`-backed IConfig for headless callers (e.g. the CLI's
+ * `ordewell models` command) that need provider keys/base URLs but have no
+ * editor settings or secret store. All resolution lives in BaseConfig; this
+ * subclass only supplies the abstract members from the environment.
+ */
+declare class EnvConfig extends BaseConfig {
+    get aiProvider(): AiProvider;
+    get apiKey(): string;
+    get planningModel(): string;
+    get enabledRunners(): string[];
+    setProviderModelLists(): void;
+}
+
+type NotificationAction = {
+    label: string;
+    value: string;
+};
+interface INotification {
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+    confirm(msg: string, options: string[]): Promise<string | undefined>;
+}
+
+interface ILogger {
+    warn(scope: string, message: string, err?: unknown): void;
+}
+declare class ConsoleLogger implements ILogger {
+    warn(scope: string, message: string, err?: unknown): void;
+}
+declare const defaultLogger: ILogger;
+
+interface IWebFetcher {
+    confirm(url: string): Promise<boolean>;
+    fetch(url: string): Promise<ToolOutcome>;
+    /**
+     * Optional web search. A fetcher without it makes the `web_search` tool
+     * report itself unavailable rather than failing the turn — the same
+     * degradation `fetch` already uses when no fetcher is wired at all.
+     */
+    search?(query: string): Promise<ToolOutcome>;
+}
+
+interface UserSettings {
+    grillMe: {
+        enabled: boolean;
+    };
+    tdd: {
+        enabled: boolean;
+    };
+    prd: {
+        enabled: boolean;
+    };
+    review: {
+        enabled: boolean;
+    };
+    verification: {
+        enabled: boolean;
+    };
+    researchSubagents: {
+        enabled: boolean;
+    };
+    modelAllowlist?: Record<string, string[]>;
+}
+/**
+ * Where the user's toggles live. `ORDEWELL_SETTINGS_PATH` overrides it so several
+ * Ordewell processes on one machine can hold *different* settings at the same
+ * time. Without it the file is a single shared mutable global: the benchmark
+ * harness runs parallel lanes that each pin the mode toggles, and because
+ * `getAll()` re-reads whenever the mtime moves, a lane needing
+ * `researchSubagents: true` would silently plan with `false` the moment another
+ * lane pinned its own — turning an A/B of that toggle into a comparison of one
+ * condition against itself.
+ */
+declare function getSettingsPath(): string;
+declare class SettingsService {
+    private filePath;
+    private cache;
+    private cachedMtimeMs;
+    constructor(filePath?: string);
+    getAll(): UserSettings;
+    private fileMtimeMs;
+    getGrillMe(): boolean;
+    getTdd(): boolean;
+    getPrd(): boolean;
+    setGrillMe(enabled: boolean): void;
+    setTdd(enabled: boolean): void;
+    setPrd(enabled: boolean): void;
+    getReview(): boolean;
+    setReview(enabled: boolean): void;
+    getVerification(): boolean;
+    setVerification(enabled: boolean): void;
+    getResearchSubagents(): boolean;
+    setResearchSubagents(enabled: boolean): void;
+    getModelAllowlist(runner: string): string[] | undefined;
+    setModelAllowlist(runner: string, ids: string[] | undefined): void;
+    private load;
+    private persist;
+}
+
+/** How the same toggle is named once a host has read it off disk. */
+interface PlannerRuntimeToggles {
+    grillMeEnabled: boolean;
+    tddEnabled: boolean;
+    prdEnabled: boolean;
+    reviewEnabled: boolean;
+    verificationEnabled: boolean;
+    researchSubagentsEnabled: boolean;
+}
+/**
+ * The planner-facing mode set for one operation. Replaces the boolean tail that
+ * every planner signature used to carry positionally — where a thirteenth
+ * parameter was the only place left to put a new toggle.
+ */
+interface PlannerModes {
+    autonomousDefault: boolean;
+    grillMe: boolean;
+    prd: boolean;
+    review: boolean;
+    verification: boolean;
+    researchSubagents: boolean;
+}
+
+declare abstract class AbstractTerminalSession implements ITerminalSession {
+    id: string;
+    taskId: string;
+    protected exited: boolean;
+    protected outputEmitter: EventEmitter<any>;
+    protected exitEmitter: EventEmitter<any>;
+    constructor(id: string, taskId: string);
+    protected baseHandleExit(code: number): void;
+    onOutput(callback: (text: string) => void): void;
+    onExit(callback: (code: number) => void): void;
+    abstract kill(): void;
+    abstract getOutput(): string;
+    abstract write(text: string): void;
+}
+declare abstract class AbstractRunner<S extends ITerminalSession> implements ITerminalRunner {
+    protected sessions: Map<string, S>;
+    get activeCount(): number;
+    stop(sessionId: string): void;
+    stopAll(): void;
+    protected registerSession(id: string, session: S): void;
+    abstract spawn(opts: {
+        taskId: string;
+        runner: string;
+        prompt: string;
+        modelId?: string;
+        thinkingEffort?: string;
+        mode?: string;
+        headless?: boolean;
+        cwd: string;
+        registry?: RunnerRegistry;
+    }): Promise<ITerminalSession>;
+}
+
+/**
+ * cmd.exe's command-line buffer. A longer line is truncated rather than
+ * rejected, which would corrupt a planner's system prompt or a task's prompt
+ * mid-sentence and produce a confident answer to half a question — so the
+ * batch route refuses instead. See {@link CommandLineTooLongError}.
+ */
+declare const CMD_EXE_MAX_COMMAND_LINE = 8191;
+/**
+ * CreateProcess's own ceiling, which the native and PowerShell routes are
+ * bounded by instead. Windows truncates here too, so the same refusal applies —
+ * it is simply four times further away.
+ */
+declare const WINDOWS_MAX_COMMAND_LINE = 32767;
+interface LaunchPlan {
+    /** The executable handed to `spawn()` or `vscode.window.createTerminal`. */
+    file: string;
+    /** Arguments for `file`. Pass verbatim when {@link verbatim} is set. */
+    args: string[];
+    /**
+     * Windows batch route only: `args` is already a quoted command line and must
+     * not be re-quoted. Maps to `windowsVerbatimArguments` for `spawn`, and to
+     * the string form of `shellArgs` for a VS Code terminal.
+     */
+    verbatim?: boolean;
+}
+/** Test seam: every OS touchpoint is injectable, and production uses the defaults. */
+interface LaunchDeps {
+    platform?: NodeJS.Platform;
+    /** The PATH executables are looked up on. Defaults to the augmented PATH. */
+    resolvePath?: () => Promise<string>;
+    /** True when `candidate` names an existing file. */
+    exists?: (candidate: string) => boolean;
+    /** Absolute path to the Windows command interpreter. */
+    comSpec?: () => string;
+    /** Absolute path to Windows PowerShell. */
+    powerShell?: () => string;
+    /** PATHEXT, as the environment reports it. */
+    pathExt?: () => string;
+}
+/**
+ * Thrown when a command's arguments do not fit the buffer of the only
+ * interpreter that can start it. Windows truncates rather than rejecting, and a
+ * system prompt cut off mid-sentence makes the planner answer half a question
+ * confidently — the silent success this repo refuses — so this is raised
+ * instead. `TaskOrchestrator.startTask` catches it and holds the task, so the
+ * message is what the user reads: it names the fix, because they cannot infer
+ * it from a truncated prompt.
+ */
+declare class CommandLineTooLongError extends Error {
+    readonly command: string;
+    readonly length: number;
+    readonly limit: number;
+    constructor(command: string, length: number, limit?: number);
+}
+/**
+ * Thrown when only a batch shim resolved for a multi-line argument. cmd.exe
+ * reads up to the first CR/LF and discards the rest with no error and exit code
+ * 0 — quoting does not help — so the agent would get the first paragraph of its
+ * prompt without the completion marker instruction, then exit looking successful.
+ */
+declare class EmbeddedNewlineError extends Error {
+    readonly command: string;
+    constructor(command: string);
+}
+/** The verbatim command line cmd.exe receives after `/d /s /c`, before wrapping. */
+declare function windowsCommandLine(file: string, args: string[]): string;
+/**
+ * How to start `command` with `args` through `spawn()`, with no shell.
+ *
+ * POSIX returns its input unchanged — execvp already searches PATH, and adding
+ * a resolution step there would be a new way for a working setup to break.
+ *
+ * Windows resolves the command against PATH × PATHEXT, preferring a native
+ * executable (spawned directly) over a batch shim (through cmd.exe) over a
+ * PowerShell script shim (through `powershell.exe -File`). A command that
+ * resolves to nothing is returned unchanged, so the caller's existing ENOENT —
+ * which names what the user typed — is what surfaces rather than a second,
+ * vaguer error from here.
+ *
+ * The tiers are tried in preference order and the first that *fits* wins, with
+ * one deliberate exception: an overflowing batch shim does not fall through to
+ * PowerShell. Overflow means a very large prompt, which is precisely where
+ * `-File` argument fidelity is least worth betting on, and where a clear held
+ * task beats a plausibly-mangled one. So capacity does not reorder the tiers —
+ * a `.ps1` beside a too-long `.cmd` still raises.
+ *
+ * A line break does reorder them: cmd.exe cannot carry one at any length, so a
+ * `.ps1` beside a `.cmd` wins, and a lone `.cmd` raises.
+ *
+ * @throws {CommandLineTooLongError} when the selected route's buffer cannot
+ * carry the arguments.
+ * @throws {EmbeddedNewlineError} when the arguments span lines and only the
+ * batch route resolved.
+ */
+declare function planDirectLaunch(command: string, args: string[], deps?: LaunchDeps): Promise<LaunchPlan>;
+/**
+ * How to start `command` for a surface that hands an executable and arguments
+ * to a terminal — the VS Code runner today, a Windows TUI later.
+ *
+ * On POSIX this is the login shell, unchanged: `bash -lc` runs the user's
+ * profile, which is how nvm/volta/asdf-managed runner binaries resolve at all.
+ * Windows has no login-shell equivalent (its PATH comes from the registry and
+ * is already inherited), so it takes the direct route instead. That is not just
+ * a simplification: it means the runner's own exit code is the terminal's exit
+ * code, rather than a `$LASTEXITCODE` that PowerShell propagates unreliably —
+ * and the exit code is half of what {@link VerdictEngine} judges a task on.
+ */
+declare function planShellLaunch(command: string, args: string[], deps?: LaunchDeps): Promise<LaunchPlan>;
+
+type SpawnFn = (command: string, args: string[], options: {
+    env: NodeJS.ProcessEnv;
+    stdio: ['pipe', 'pipe', 'pipe'];
+    cwd: string;
+    /** Set by the Windows batch route, where `args` is already a quoted command line. */
+    windowsVerbatimArguments?: boolean;
+}) => ChildProcess;
+/** Test seam: every OS touchpoint is injectable; production uses the defaults. */
+interface HeadlessRunnerDeps {
+    spawnImpl?: SpawnFn;
+    hasScriptCmd?: () => boolean;
+    resolvePath?: () => Promise<string>;
+    /**
+     * Overrides for executable resolution ({@link planDirectLaunch}). Only the
+     * Windows branch consults them, so a POSIX test never needs to pass anything.
+     */
+    launchDeps?: LaunchDeps;
+}
+declare class HeadlessSession extends AbstractTerminalSession {
+    private spawnImpl;
+    private process;
+    private outputBuffer;
+    constructor(id: string, taskId: string, spawnImpl: SpawnFn);
+    start(launch: LaunchPlan, cwd: string, resolvedPath: string, env?: Record<string, string>): void;
+    kill(): void;
+    getOutput(): string;
+    write(text: string): void;
+}
+declare class HeadlessRunner extends AbstractRunner<HeadlessSession> {
+    private spawnImpl;
+    private hasScriptCmd;
+    private resolvePath;
+    private launchDeps;
+    constructor(deps?: HeadlessRunnerDeps);
+    spawn(opts: {
+        taskId: string;
+        runner: string;
+        prompt: string;
+        modelId?: string;
+        thinkingEffort?: string;
+        modelVariants?: string[];
+        mode?: string;
+        headless?: boolean;
+        cwd: string;
+        registry?: RunnerRegistry;
+    }): Promise<ITerminalSession>;
+}
+
+/**
+ * The harness-planner transport contract (ADR-0009).
+ *
+ * One adapter per coding agent, each speaking that agent's own programmatic
+ * protocol and normalizing it to the event union below. Everything above this
+ * line — reply classification, the repair loop, plan validation, the four
+ * surfaces — is already provider-agnostic, so an adapter is the entire cost of
+ * teaching Ordewell to plan with another agent.
+ */
+/**
+ * One normalized event from a running agent turn. Deliberately smaller than
+ * any single agent's native protocol: this is the intersection Ordewell can act
+ * on, not a lossless re-encoding. Event fidelity differs by agent — `thinking`
+ * is rich on Claude Code and absent elsewhere — so consumers must tolerate a
+ * turn that emits nothing but `assistant_text` and `turn_end`.
+ */
+type AgentEvent = 
+/** A chunk of the assistant's reply. Concatenated in order to form the turn's text. */
+{
+    type: 'assistant_text';
+    text: string;
+}
+/** Reasoning the agent chose to expose. Never contributes to the reply text. */
+ | {
+    type: 'thinking';
+    text: string;
+} | {
+    type: 'tool_call';
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+} | {
+    type: 'tool_result';
+    id: string;
+    name: string;
+    output: string;
+    success: boolean;
+}
+/**
+ * The agent asked to do something its read-only mode does not cover. Always
+ * auto-denied (T1) — a planner that can mutate is not a planner. The adapter
+ * is responsible for answering the agent so the turn does not hang.
+ */
+ | {
+    type: 'permission_request';
+    id: string;
+    name: string;
+    detail: string;
+}
+/** The agent finished its turn and is waiting for the next user message. */
+ | {
+    type: 'turn_end';
+}
+/** The turn failed. Carries the agent's own words — never a Ordewell paraphrase. */
+ | {
+    type: 'error';
+    message: string;
+};
+interface AgentStartOptions {
+    /** Workspace root. The agent explores from here and, in read-only mode, cannot leave it. */
+    cwd: string;
+    /** The planner system prompt, in its harness variant. */
+    systemPrompt: string;
+    /** Model id from the runner's own discovery catalog. Omitted means the agent's default. */
+    model?: string;
+    /** Variant / reasoning effort id from that model's `variants` list. */
+    effort?: string;
+    /**
+     * The agent's own session id from a previous run. A hint only: Ordewell's
+     * transcript is the source of truth (T4), so a failed resume degrades to a
+     * fresh session seeded from the stored history rather than an error.
+     */
+    resumeSessionId?: string;
+}
+interface AgentAdapter {
+    /** The runner id this adapter drives — `claude-code`, `codex`, `opencode`. */
+    readonly agentId: string;
+    /** Spawn the agent in its read-only mode and get it ready to receive messages. */
+    start(opts: AgentStartOptions): Promise<void>;
+    /**
+     * Send one user message and stream the turn's events until it ends. Resolves
+     * when the agent yields the floor; rejects only when the transport itself
+     * failed in a way no `error` event could describe.
+     */
+    send(message: string, onEvent: (event: AgentEvent) => void, signal?: AbortSignal): Promise<void>;
+    /** The agent's native session id once it has announced one. Resumption hint only. */
+    nativeSessionId(): string | null;
+    /** Kill the process and release its resources. Idempotent. */
+    dispose(): void;
+}
+/**
+ * The single injected boundary between Ordewell and the operating system —
+ * the same pattern `HeadlessRunnerDeps` uses for task execution. Tests feed
+ * recorded agent output through `spawn` (and, for HTTP-transport agents,
+ * `fetch`) so one test exercises adapter parsing, event mapping, reply
+ * classification and the repair loop as a single observable behavior.
+ */
+interface AgentProcessDeps {
+    spawn: SpawnFn;
+    fetch: typeof globalThis.fetch;
+    /** Resolves the PATH agents are spawned under. Defaults to the augmented PATH. */
+    resolvePath?: () => Promise<string>;
+    /** Host platform. Defaults to the real one; injected so OS-specific behavior is testable anywhere. */
+    platform?: NodeJS.Platform;
+}
+/** Builds the adapter for one runner id, or null when that runner cannot plan. */
+type AgentAdapterFactory = (runner: string, deps: AgentProcessDeps) => AgentAdapter | null;
+/**
+ * Split a stream of chunks into complete lines. Every agent transport here is
+ * newline-delimited JSON of some shape, and a chunk boundary lands mid-object
+ * often enough that parsing per-chunk silently drops events.
+ */
+declare class LineBuffer {
+    private buffer;
+    push(chunk: string, onLine: (line: string) => void): void;
+    /** Anything left unterminated when the stream closed. */
+    flush(): string;
+}
+
+interface CliAgentAiServiceDeps extends Partial<AgentProcessDeps> {
+    /** Overrides adapter construction. Tests supply a fake agent; production picks by runner id. */
+    createAdapter?: (runner: string, deps: AgentProcessDeps) => AgentAdapter | null;
+    /** Workspace root the agent explores. Defaults to the host process's cwd. */
+    workspaceRoot?: () => string;
+}
+/**
+ * A coding agent driven as Ordewell's planner (ADR-0009).
+ *
+ * The second transport behind `IAiService`, sitting beside `OpenAiService` and
+ * `GeminiService`. It deliberately does **not** extend {@link BaseAiService}:
+ * that class's body is Ordewell executing research tools on a model's behalf,
+ * which is precisely the part a coding agent replaces. What it reuses instead
+ * is everything above the transport — `classifyPlannerReply`, the bounded
+ * corrective re-emit loop, `parsePlanJson`, the `ResearchProgress` events the
+ * four surfaces already render. That is why this backend reaches VS Code, the
+ * web UI, the CLI and the TUI without any of them learning a coding agent is
+ * on the other end.
+ */
+declare class CliAgentAiService implements IAiService {
+    private config;
+    private readonly runner;
+    private readonly processDeps;
+    private readonly makeAdapter;
+    private readonly workspaceRoot;
+    private adapter;
+    /**
+     * The agent's own session id, kept across a process death so the next turn
+     * can resume warm context instead of re-reading the repository. Cleared at
+     * every session boundary — nothing from one goal may reach the next.
+     */
+    private lastNativeSessionId;
+    private conversation;
+    private activeAbort;
+    constructor(config: IConfig, deps?: CliAgentAiServiceDeps);
+    hasActiveConversation(): boolean;
+    /**
+     * False when the running agent process was spawned under a model/effort the
+     * user has since changed in the picker. Unlike a vendor backend, the model
+     * is a spawn-time argument to the agent CLI (`--model`), not a per-request
+     * field — `continueConversation` sends the next turn to whatever process is
+     * already running, so a plain config read here would silently keep planning
+     * on the old model. No conversation yet is vacuously "current".
+     */
+    conversationMatchesConfig(): boolean;
+    /** The agent's own session id, a resumption hint only — Ordewell's transcript is authoritative (T4). */
+    nativeSessionId(): string | null;
+    reset(): void;
+    startConversation(req: ConversationRequest): Promise<ConversationTurn>;
+    continueConversation(userMessage: string, onProgress: (progress: ResearchProgress) => void, signal?: AbortSignal): Promise<ConversationTurn>;
+    private openingMessage;
+    /**
+     * Drive one user message to a settled planner turn. Same shape as the API
+     * backend's conversation loop minus the tool rounds — those belong to the
+     * agent now — and with the same three policies layered on top: the PRD gate,
+     * the empty-reply nudge, and a bounded corrective re-emit for botched JSON.
+     */
+    private runConversation;
+    /**
+     * Run one agent turn: stream its events into `ResearchProgress`, collect the
+     * reply text, and return the research steps produced. Tool calls are matched
+     * to their results by the agent's own call id — matching by tool name puts
+     * one file's body on another file's row the moment an agent runs two reads
+     * at once, which all three of these do routinely.
+     */
+    private runTurn;
+    private startAdapter;
+    /**
+     * The live agent process, restarted from its own session id if it died
+     * between turns. Resume is a hint: when it fails, the caller's next
+     * `startConversation` reseeds from Ordewell's transcript, which is the same
+     * degradation `restoreChat` already performs on every surface.
+     */
+    private ensureAdapter;
+    private startAbortScope;
+    private plannerModel;
+    /**
+     * A single agent session that answers one prompt and exits. Used by every
+     * non-conversational entry point; the plan is parsed from the reply text by
+     * the same extractor the conversational path uses.
+     */
+    private oneShot;
+    researchAndPlan(userDescription: string, runners: RunnerId[], modelsByRunner: Partial<Record<RunnerId, DiscoveredModel[]>>, fs: IFileSystem, onProgress: (progress: ResearchProgress) => void, _fetcher?: IWebFetcher, runnerModes?: Record<RunnerId, RunnerModeInfo[]>, modes?: PlannerModes, signal?: AbortSignal): Promise<{
+        tasks: Task[];
+        researchLog: ResearchLogEntry[];
+        researchResults: string;
+    }>;
+    generatePlanDirect(userDescription: string, runners?: RunnerId[], modelsByRunner?: Partial<Record<RunnerId, DiscoveredModel[]>>, onToken?: (token: string) => void, _fs?: IFileSystem, _fetcher?: IWebFetcher, runnerModes?: Record<RunnerId, RunnerModeInfo[]>, modes?: PlannerModes, signal?: AbortSignal): Promise<Task[]>;
+    modifyPlan(existingPlan: LegacyPlanState, userRequest: string, modelsByRunner: Partial<Record<RunnerId, DiscoveredModel[]>>, onProgress?: (progress: ResearchProgress) => void, _fs?: IFileSystem, _fetcher?: IWebFetcher, runnerModes?: Record<RunnerId, RunnerModeInfo[]>, modes?: PlannerModes, signal?: AbortSignal): Promise<{
+        tasks: Task[];
+    }>;
+    sendPlanningPrompt(prompt: string, runners: RunnerId[], runnerModes?: Record<RunnerId, RunnerModeInfo[]>, autonomousDefault?: boolean): Promise<Task[]>;
+}
+
+/**
+ * Everything the conversation loop needs to start planning (ADR-0002).
+ * The AI service keeps the tool-use message history internally across turns;
+ * the surfaces only exchange user/assistant messages with it.
+ */
+interface ConversationRequest {
+    goal: string;
+    runners: RunnerId[];
+    modelsByRunner: Partial<Record<RunnerId, DiscoveredModel[]>>;
+    fs: IFileSystem;
+    onProgress: (progress: ResearchProgress) => void;
+    fetcher?: IWebFetcher;
+    runnerModes?: Record<RunnerId, RunnerModeInfo[]>;
+    autonomousDefault?: boolean;
+    grillMeEnabled?: boolean;
+    prdEnabled?: boolean;
+    reviewEnabled?: boolean;
+    verificationEnabled?: boolean;
+    /** Declare the spawn_research_agent tool to the planner (issue #34, default off). */
+    researchSubagentsEnabled?: boolean;
+    signal?: AbortSignal;
+    /**
+     * Persisted dialogue to seed a resumed conversation (session reload). The
+     * turns are injected into the message history verbatim — no LLM call happens
+     * for them; the first call is the turn opened by `initialMessage`.
+     */
+    priorHistory?: ConversationMessage[];
+    /**
+     * The user message that opens this turn. Defaults to `goal` — set it when
+     * resuming so the system prompt keeps the original goal while the turn
+     * carries the user's new message.
+     */
+    initialMessage?: string;
+}
+/**
+ * One planner turn's outcome. The planner talks to the user (`message`),
+ * commits a full plan (`plan`, a `{tasks:[...]}` JSON object), or emits
+ * targeted task edits (`task_ops`, a `{taskOps:[...]}` JSON object). The
+ * Session validates and applies task ops atomically; the AI service only
+ * parses them.
+ */
+type ConversationTurn = {
+    kind: 'message';
+    text: string;
+    researchLog: ResearchLogEntry[];
+} | {
+    kind: 'plan';
+    tasks: Task[];
+    text: string;
+    researchLog: ResearchLogEntry[];
+} | {
+    kind: 'task_ops';
+    ops: TaskOp[];
+    text: string;
+    researchLog: ResearchLogEntry[];
+};
+interface IAiService {
+    /**
+     * Begin the planner conversation: collect workspace context, run the
+     * research/tool loop, and return the first planner turn. The service
+     * retains the full API message history for subsequent
+     * {@link continueConversation} calls.
+     */
+    startConversation(req: ConversationRequest): Promise<ConversationTurn>;
+    /**
+     * Feed the user's reply into the active conversation and return the next
+     * planner turn. Throws if no conversation is active.
+     */
+    continueConversation(userMessage: string, onProgress: (progress: ResearchProgress) => void, signal?: AbortSignal): Promise<ConversationTurn>;
+    /**
+     * Whether a planner conversation is currently held in memory. A branching
+     * predicate only — never a test for whether there is anything to release.
+     * The harness backend holds an OS process that outlives its conversation, so
+     * guarding {@link reset} with this leaks an agent process; call `reset`
+     * unconditionally instead.
+     */
+    hasActiveConversation(): boolean;
+    /**
+     * Whether the active conversation (if any) still matches the planner
+     * model/effort currently configured. Optional, and true when absent: a
+     * vendor backend re-reads its model from config on every turn, so there is
+     * nothing to drift. A harness planner (ADR-0009) is the exception — its
+     * model is baked into the agent process at spawn — so only
+     * {@link CliAgentAiService} answers this for real. False tells the caller
+     * the same thing an absent conversation would: don't call
+     * `continueConversation`, restart instead so the new model takes effect.
+     */
+    conversationMatchesConfig?(): boolean;
+    /**
+     * One-shot research + plan for non-conversational surfaces (CLI `plan --goal`,
+     * web REST). Never asks questions — it plans with what it can find.
+     */
+    researchAndPlan(userDescription: string, runners: RunnerId[], modelsByRunner: Partial<Record<RunnerId, DiscoveredModel[]>>, fs: IFileSystem, onProgress: (progress: ResearchProgress) => void, fetcher?: IWebFetcher, runnerModes?: Record<RunnerId, RunnerModeInfo[]>, modes?: PlannerModes, signal?: AbortSignal): Promise<{
+        tasks: Task[];
+        researchLog: ResearchLogEntry[];
+        researchResults: string;
+    }>;
+    generatePlanDirect(userDescription: string, runners: RunnerId[], modelsByRunner: Partial<Record<RunnerId, DiscoveredModel[]>>, onToken?: (token: string) => void, fs?: IFileSystem, fetcher?: IWebFetcher, runnerModes?: Record<RunnerId, RunnerModeInfo[]>, modes?: PlannerModes, signal?: AbortSignal): Promise<Task[]>;
+    modifyPlan(existingPlan: LegacyPlanState, userRequest: string, modelsByRunner: Partial<Record<RunnerId, DiscoveredModel[]>>, onProgress?: (progress: ResearchProgress) => void, fs?: IFileSystem, fetcher?: IWebFetcher, runnerModes?: Record<RunnerId, RunnerModeInfo[]>, modes?: PlannerModes, signal?: AbortSignal): Promise<{
+        tasks: Task[];
+    }>;
+    /**
+     * Release everything this service holds: the conversation, any in-flight
+     * turn, and — on the harness backend — the agent process itself. Idempotent
+     * and cheap in every implementation, so callers never gate it.
+     */
+    reset(): void;
+    sendPlanningPrompt(prompt: string, runners: RunnerId[], runnerModes?: Record<RunnerId, RunnerModeInfo[]>, autonomousDefault?: boolean): Promise<Task[]>;
+}
+/**
+ * The single branch point between planner transports. Two of them talk HTTP to
+ * an LLM vendor; the third (ADR-0009) drives a coding agent already installed
+ * on the machine. Everything downstream — the plan contract, the research-step
+ * stream, the four surfaces — is shared.
+ */
+declare function createAiService(config: IConfig, deps?: CliAgentAiServiceDeps): IAiService;
+
+interface ToolCall {
+    name: string;
+    args: Record<string, unknown>;
+    id?: string;
+}
+interface ToolResult {
+    name: string;
+    output: string;
+    truncated: boolean;
+    totalChars: number;
+    id?: string;
+}
+interface ResearchTurn {
+    text: string;
+    toolCalls: ToolCall[];
+    hasToolCalls: boolean;
+    /** Reasoning/chain-of-thought captured separately from `text` so it never pollutes plan JSON. */
+    reasoning?: string;
+    /** Provider finish reason, normalized: 'length' means the output-token limit cut the reply mid-stream. */
+    finishReason?: string;
+    /** Exact prompt tokens this turn consumed, when the provider reports usage — drives proactive compaction. */
+    promptTokens?: number;
+}
+interface ResearchChat {
+    sendMessage(text: string, signal?: AbortSignal): Promise<ResearchTurn>;
+    sendToolResults(results: ToolResult[], signal?: AbortSignal): Promise<ResearchTurn>;
+    /**
+     * Optional: prune bulky raw tool outputs from the history in place (subagent
+     * digests are kept) so a follow-up emission has context to spend on output.
+     * Returns the number of characters removed. Providers whose SDK owns the
+     * history (Gemini) may not support it.
+     */
+    compactHistory?(): number;
+}
+/** Everything one conversation turn needs beyond the user message itself. */
+interface ConversationTurnContext {
+    chat: ResearchChat;
+    fs: IFileSystem;
+    runners: RunnerId[];
+    runnerModes?: Record<RunnerId, RunnerModeInfo[]>;
+    autonomousDefault?: boolean;
+    fetcher?: IWebFetcher;
+    /** PRD toggle: a plan must not commit before a PRD block has appeared. */
+    prdEnabled?: boolean;
+    /** Set once any turn carries an ORDEWELL_PRD block; gates the missing-PRD nudge. */
+    prdCaptured?: boolean;
+    /** The missing-PRD corrective nudge is sent at most once per conversation. */
+    prdNudgeSent?: boolean;
+}
+declare abstract class BaseAiService {
+    protected config: IConfig;
+    protected conversation: {
+        ctx: ConversationTurnContext;
+        setProgress: (fn: (p: ResearchProgress) => void) => void;
+    } | null;
+    protected activeAbort: AbortController | null;
+    /** researchSubagents toggle (issue #34): set per operation from the live settings snapshot; off means bit-for-bit sequential behavior. */
+    protected researchSubagentsEnabled: boolean;
+    constructor(config: IConfig);
+    abstract reset(): void;
+    abstract ensureInit(): void;
+    hasActiveConversation(): boolean;
+    protected startAbortScope(callerSignal?: AbortSignal): AbortSignal | undefined;
+    protected stopAbortScope(): void;
+    sendPlanningPrompt(prompt: string, runners: RunnerId[], runnerModes?: Record<RunnerId, RunnerModeInfo[]>, autonomousDefault?: boolean): Promise<Task[]>;
+    continueConversation(userMessage: string, onProgress: (progress: ResearchProgress) => void, signal?: AbortSignal): Promise<ConversationTurn>;
+    protected abstract streamPlanText(prompt: string, repairHint: string | undefined, onToken: (token: string) => void, onReasoning?: (token: string) => void, signal?: AbortSignal): Promise<string>;
+    /**
+     * Build a fresh chat for one research subagent (own history, subagent system
+     * prompt, cheap model). Null means the provider does not support subagents —
+     * the spawn tool then degrades to a steering message. `onReasoning` streams
+     * live reasoning deltas on models that expose them, same as the top-level loop.
+     */
+    protected createSubagentChat(_onReasoning?: (delta: string) => void): ResearchChat | null;
+    /**
+     * One spawn_research_agent tool call, executed at the service layer (not in
+     * executeTool — that would cycle the imports). Every failure path returns a
+     * steering/failed result and the loop continues sequentially: a subagent can
+     * never fail a plan or a turn.
+     */
+    private executeSpawnAgent;
+    /** Collect project context for the planning phase. Shared with the harness backend. */
+    protected static collectResearchContext(fs: IFileSystem, runners: RunnerId[]): Promise<string>;
+    /**
+     * Execute one round of tool calls and report each through onProgress.
+     * Returns the results to feed back plus the log entries produced.
+     */
+    private executeToolCalls;
+    /**
+     * Countdown appended to the last tool result of the final few rounds, so the
+     * model lands the turn on its own terms instead of being cut off exactly at
+     * the budget boundary mid-exploration.
+     */
+    private static appendBudgetCountdown;
+    /**
+     * Run one planner conversation turn (ADR-0002): send the message, satisfy
+     * tool calls until the model answers in prose or JSON, then classify the
+     * result. The model decides transitions — there are no sentinels, no
+     * question tags, and no correction nags. A turn whose final text parses as
+     * a `{tasks:[...]}` object commits the plan; anything else is a message to
+     * the user.
+     */
+    protected runConversationTurn(ctx: ConversationTurnContext, message: string, onProgress: (progress: ResearchProgress) => void, signal?: AbortSignal): Promise<ConversationTurn>;
+    /**
+     * Run the LLM tool-calling research loop for one-shot planning. Returns
+     * parsed tasks if a plan was emitted mid-loop, or null if the loop
+     * exhausted without a valid plan.
+     */
+    protected runResearchLoop(chat: ResearchChat, firstMessage: string, fs: IFileSystem, onProgress: (progress: ResearchProgress) => void, runners: RunnerId[], initialLog?: ResearchLogEntry[], fetcher?: IWebFetcher, userGoal?: string, runnerModes?: Record<RunnerId, RunnerModeInfo[]>, autonomousDefault?: boolean, signal?: AbortSignal): Promise<{
+        tasks: Task[] | null;
+        researchLog: ResearchLogEntry[];
+        researchResults: string;
+    }>;
+    protected generatePlanFallback(userDescription: string, contextStr: string, researchResults: string, modelsByRunner: Partial<Record<RunnerId, DiscoveredModel[]>>, runners: RunnerId[], onProgress: (progress: ResearchProgress) => void, researchLog?: ResearchLogEntry[], runnerModes?: Record<RunnerId, RunnerModeInfo[]>, autonomousDefault?: boolean, signal?: AbortSignal, modes?: PlannerModes): Promise<{
+        tasks: Task[];
+        researchLog: ResearchLogEntry[];
+    }>;
+}
+
+declare class GeminiService extends BaseAiService implements IAiService {
+    private genAI;
+    private model;
+    constructor(config: IConfig);
+    private init;
+    private getPlanningModel;
+    ensureInit(): void;
+    reset(): void;
+    startConversation(req: ConversationRequest): Promise<ConversationTurn>;
+    protected streamPlanText(prompt: string, repairHint: string | undefined, onToken: (token: string) => void, onReasoning?: (token: string) => void, _signal?: AbortSignal): Promise<string>;
+    /**
+     * Drain a Gemini content stream, routing "thought" parts to the reasoning channel
+     * and answer text to the parser. `chunk.text()` throws when a chunk is reasoning-only,
+     * so parts are inspected directly.
+     */
+    private consumePlanStream;
+    /** Gemini-specific stream over raw Parts for generatePlanDirect / modifyPlan. */
+    private streamPlanTextWithParts;
+    researchAndPlan(userDescription: string, runners: RunnerId[], modelsByRunner: Partial<Record<RunnerId, DiscoveredModel[]>>, fs: IFileSystem, onProgress: (progress: ResearchProgress) => void, fetcher?: IWebFetcher, runnerModes?: Record<RunnerId, RunnerModeInfo[]>, modes?: PlannerModes, signal?: AbortSignal): Promise<{
+        tasks: Task[];
+        researchLog: ResearchLogEntry[];
+        researchResults: string;
+    }>;
+    generatePlanDirect(userDescription: string, runners?: RunnerId[], modelsByRunner?: Partial<Record<RunnerId, DiscoveredModel[]>>, onToken?: (token: string) => void, fs?: IFileSystem, _fetcher?: IWebFetcher, runnerModes?: Record<RunnerId, RunnerModeInfo[]>, modes?: PlannerModes, _signal?: AbortSignal): Promise<Task[]>;
+    modifyPlan(existingPlan: LegacyPlanState, userRequest: string, modelsByRunner: Partial<Record<RunnerId, DiscoveredModel[]>>, onProgress?: (progress: ResearchProgress) => void, fs?: IFileSystem, _fetcher?: IWebFetcher, runnerModes?: Record<RunnerId, RunnerModeInfo[]>, modes?: PlannerModes, _signal?: AbortSignal): Promise<{
+        tasks: Task[];
+    }>;
+}
+
+declare class OpenAiService extends BaseAiService implements IAiService {
+    private client;
+    constructor(config: IConfig);
+    private getClient;
+    ensureInit(): void;
+    private requireModel;
+    reset(): void;
+    protected streamPlanText(prompt: string, repairHint: string | undefined, onToken: (token: string) => void, onReasoning?: (token: string) => void, signal?: AbortSignal): Promise<string>;
+    /** A research subagent: fresh history, digest contract, cheap model, read-only tools. */
+    protected createSubagentChat(onReasoning?: (delta: string) => void): ResearchChat | null;
+    startConversation(req: ConversationRequest): Promise<ConversationTurn>;
+    researchAndPlan(userDescription: string, runners: RunnerId[], modelsByRunner: Partial<Record<RunnerId, DiscoveredModel[]>>, fs: IFileSystem, onProgress: (progress: ResearchProgress) => void, fetcher?: IWebFetcher, runnerModes?: Record<RunnerId, RunnerModeInfo[]>, modes?: PlannerModes, signal?: AbortSignal): Promise<{
+        tasks: Task[];
+        researchLog: ResearchLogEntry[];
+        researchResults: string;
+    }>;
+    generatePlanDirect(userDescription: string, runners?: RunnerId[], modelsByRunner?: Partial<Record<RunnerId, DiscoveredModel[]>>, onToken?: (token: string) => void, fs?: IFileSystem, _fetcher?: IWebFetcher, runnerModes?: Record<RunnerId, RunnerModeInfo[]>, modes?: PlannerModes, signal?: AbortSignal): Promise<Task[]>;
+    modifyPlan(existingPlan: LegacyPlanState, userRequest: string, modelsByRunner: Partial<Record<RunnerId, DiscoveredModel[]>>, onProgress?: (progress: ResearchProgress) => void, fs?: IFileSystem, _fetcher?: IWebFetcher, runnerModes?: Record<RunnerId, RunnerModeInfo[]>, modes?: PlannerModes, signal?: AbortSignal): Promise<{
+        tasks: Task[];
+    }>;
+}
+
+/**
+ * The deep module owning all plan-shaped state. Holds `planTasks` (the ordered
+ * tree the user edits), the flattened `allTasks` view, the `taskMap` index, and
+ * the `completedTasks`/`failedTasks` sets the scheduler reads. The orchestrator
+ * calls `markCompleted`/`markFailed`/`markInProgress`/`retry` to update task
+ * status — it never mutates task state directly.
+ *
+ * `rebuild` is the internal seam that keeps the flat views in sync with the
+ * tree. Structural removals (remove/merge/split) additionally prune
+ * `completedTasks`/`failedTasks` for ids that no longer exist; `removeFromActive`
+ * deliberately does not, so a completed task that leaves the active list still
+ * satisfies its dependents' dependency checks.
+ *
+ * `planRunners` lives here because it's part of the plan's identity (the runner
+ * set, carried on the plan). `validateAssignedRunners` is pure store logic.
+ */
+declare class PlanStore {
+    private _planTasks;
+    private _allTasks;
+    private _taskMap;
+    private _completedTasks;
+    private _failedTasks;
+    private _planRunners;
+    private _onMutate;
+    private _executionLog;
+    /** Hook called after every structural mutation (add/remove/update/merge/split/load). */
+    set onMutate(cb: (() => void) | null);
+    get planTasks(): Task[];
+    get allTasks(): Task[];
+    get planRunners(): RunnerId[];
+    get completedCount(): number;
+    get failedCount(): number;
+    isAllComplete(): boolean;
+    isAnyFailed(): boolean;
+    isCompleted(id: string): boolean;
+    isFailed(id: string): boolean;
+    get(taskId: string): Task | undefined;
+    getExecutionLog(): TaskSnapshot[];
+    appendToLog(snapshot: TaskSnapshot): void;
+    /**
+     * Drop a task's archived snapshot. Un-marking a completion has to erase the
+     * "finished" record too — dependent tasks are prompted from the log, so a
+     * left-behind snapshot would keep feeding them a result that no longer exists.
+     */
+    removeFromLog(taskId: string): void;
+    removeFromActive(taskId: string): void;
+    clearLog(): void;
+    private notifyMutate;
+    load(tasks: Task[], runners: RunnerId[]): void;
+    add(partial: Partial<Task>): Task;
+    remove(taskId: string): void;
+    update(taskId: string, changes: Partial<Task>): Task | undefined;
+    mergeMultiple(taskIds: string[]): Task;
+    merge(taskIdA: string, taskIdB: string): Task;
+    split(taskId: string, newTaskSpecs: Partial<Task>[]): Task[];
+    /**
+     * Run preparation as one named op: flip every AI task to 'approved'. By
+     * default completed tasks keep their status so a reloaded half-finished plan
+     * resumes the remainder instead of re-running work that already succeeded;
+     * `preserveCompleted: false` is for a freshly committed plan, where
+     * everything starts over.
+     */
+    resetForRun(opts?: {
+        preserveCompleted?: boolean;
+    }): void;
+    markCompleted(id: string): void;
+    markFailed(id: string): void;
+    markInProgress(id: string): void;
+    markAwaitingUser(id: string): void;
+    markPending(id: string): void;
+    retry(id: string): void;
+    blockDependents(id: string): void;
+    unblockDependents(id: string): void;
+    setTaskVerdict(id: string, verdict: Task['verdict']): void;
+    setTaskOutputSummary(id: string, summary: Task['outputSummary']): void;
+    getPlanVisualization(): {
+        tasks: {
+            id: string;
+            title: string;
+            dependencies: string[];
+            parallelGroups: number[][];
+        }[];
+        parallelGroups: number[][];
+    };
+    /**
+     * Widen the plan's runner set. Retargeting a task onto a runner the plan has
+     * not used before has to land here as well as on the plan state, or
+     * {@link resolveTaskRunner} reads the new runner as foreign and spawns the
+     * plan's first one instead.
+     */
+    admitRunner(runner: RunnerId): void;
+    resolveTaskRunner(task: Task): RunnerId;
+    private rebuild;
+    /**
+     * Drop completed/failed ids that no longer exist in the plan. Called by the
+     * structural removals (remove/merge/split) — but NOT by removeFromActive,
+     * where a completed task leaves the active list yet must still satisfy its
+     * dependents' dependency checks.
+     */
+    private pruneTerminalSets;
+    private validateAssignedRunners;
+}
+
+/**
+ * The one notification channel out of the orchestrator. Everything that used
+ * to travel over separate callbacks (onRefresh, onQueueReady) is an observer
+ * event; the Session subscribes once and turns these into SessionMessages.
+ */
+interface OrchestratorObserver {
+    /** Any task-shaped state changed (store mutation, checkpoint, retry, …). */
+    onTaskChanged?(): void;
+    onTick?(): void;
+    onExecutionComplete?(): void;
+    /** Queued user messages are ready to be processed by the planner. */
+    onQueueReady?(): void;
+    onReviewNeeded?(data: {
+        tasks: Task[];
+        planRunners: RunnerId[];
+    }): void;
+    onReviewApproved?(data: {
+        tasks: Task[];
+    }): void;
+    onCheckpoint?(data: {
+        taskId: string;
+        taskTitle: string;
+        summary: string;
+    }): void;
+}
+/**
+ * The pure scheduler. Owns execution state (`running`, `planStatus`,
+ * `reviewApproved`, `activeTaskSessions`, `messageQueue`) and the verifier.
+ * All task-shaped state — the plan tree, the flat index, the completed set
+ * — lives in {@link PlanStore}, injected at construction. The orchestrator
+ * calls `store.markCompleted(id)` / `store.markFailed(id)` instead of mutating
+ * task state directly. A task completes only after the runner emits its
+ * per-task completion marker; process exit without that evidence is a visible
+ * failure and does not unblock dependent work.
+ */
+declare class TaskOrchestrator {
+    private config;
+    private notifications;
+    private terminalRunner;
+    private store;
+    private activeTaskSessions;
+    private startingTaskIds;
+    private verifier;
+    private running;
+    private planStatus;
+    private messageQueue;
+    private reviewApproved;
+    private retryCounts;
+    /**
+     * Tasks pulled out of auto-scheduling (user-cancelled or failed to spawn).
+     * They stay 'pending' — "not executed" — but the scheduler skips them until
+     * the user retries or force-starts, which would otherwise loop forever on a
+     * task whose spawn always throws.
+     */
+    private onHold;
+    private registry;
+    private workspaceRootFn;
+    private observers;
+    private tddEnabled;
+    constructor(config: IConfig, notifications: INotification, terminalRunner: ITerminalRunner, store?: PlanStore);
+    get storeInstance(): PlanStore;
+    setWorkspaceRoot(fn: () => string): void;
+    setRegistry(registry: RunnerRegistry): void;
+    /**
+     * A getter rather than a value where the caller has one: every task gets its
+     * prompt composed at spawn time, but only a full-plan run passes through a
+     * point where a snapshot could be refreshed — so "Run task", force-start and
+     * retry would compose against whatever the last run happened to set.
+     */
+    setTddEnabled(enabled: boolean | (() => boolean)): void;
+    approveCheckpoint(taskId: string): void;
+    rejectCheckpoint(taskId: string, reason?: string): void;
+    subscribe(observer: OrchestratorObserver): () => void;
+    private emit;
+    get isRunning(): boolean;
+    get isReviewApproved(): boolean;
+    get status(): 'approved' | 'running' | 'completed';
+    get activeTaskIds(): string[];
+    get activeSessionMap(): Map<string, string>;
+    get queuedCount(): number;
+    queueMessage(text: string): void;
+    getQueuedMessages(): QueuedMessage[];
+    setQueuedMessages(messages: QueuedMessage[]): void;
+    clearQueuedMessages(): void;
+    processNextQueuedMessage(): QueuedMessage | null;
+    loadPlan(tasks: Task[], planRunners?: RunnerId[]): void;
+    reconcilePlan(newTasks: Task[], planRunners?: RunnerId[]): void;
+    start(): Promise<void>;
+    stop(): void;
+    onUserTaskComplete(taskId: string): Promise<void>;
+    private onVerdict;
+    getReadyTasks(): Task[];
+    isBlocked(task: Task): boolean;
+    /**
+     * Cancel a running (or scheduled) task: kill its session and return it to
+     * 'pending' — "not executed". The task is put on hold so the scheduler
+     * doesn't immediately restart it; Retry / Force Start release the hold.
+     */
+    cancelTask(taskId: string): Promise<void>;
+    markTaskComplete(taskId: string): Promise<void>;
+    markAiTaskComplete(taskId: string): Promise<void>;
+    /**
+     * Undo a completion: return the task to "not executed" — pending, verdict and
+     * summary dropped, archive entry removed. It is put on hold like a cancel, so
+     * a running plan does not immediately re-spawn the work the user just
+     * un-marked; Retry / Force Start / Run release the hold. Dependents fall back
+     * to waiting on their own, because the scheduler gates on `isCompleted`.
+     */
+    markTaskIncomplete(taskId: string): Promise<void>;
+    private logAndArchive;
+    retryTask(taskId: string): Promise<void>;
+    /**
+     * Manually start a single AI task right now, bypassing dependency/readiness
+     * gating (the "force start" affordance on a task card). Reuses the scheduler's
+     * own startTask so a force-started task gets the same augmented prompt, session
+     * tracking, and exit handling — callers must not re-spawn the runner themselves.
+     * No-op if the task is unknown, not an AI task, or already running.
+     */
+    forceStartTask(taskId: string): Promise<void>;
+    /**
+     * Run exactly one task outside full-plan scheduling. The active/starting
+     * session still contributes to isRunning so every surface exposes Stop and
+     * disables Execute Plan, but onVerdict cannot auto-schedule other tasks
+     * because the plan scheduler's `running` flag remains false.
+     */
+    runTask(taskId: string): Promise<void>;
+    getCompletedCount(): number;
+    getTotalCount(): number;
+    isAllComplete(): boolean;
+    isAnyFailed(): boolean;
+    approveReview(): Promise<void>;
+    getPlanVisualization(): {
+        tasks: {
+            id: string;
+            title: string;
+            dependencies: string[];
+            parallelGroups: number[][];
+        }[];
+        parallelGroups: number[][];
+    };
+    tick(): Promise<void>;
+    private startTask;
+}
+
+/**
+ * Everything needed to produce a plan from a goal. Carries the planning context
+ * that previously threaded through the scheduler as positional args.
+ */
+interface PlanRequest {
+    goal: string;
+    runners: RunnerId[];
+    modelsByRunner: Partial<Record<RunnerId, DiscoveredModel[]>>;
+    fs?: IFileSystem;
+    fetcher?: IWebFetcher;
+    onProgress?: (progress: ResearchProgress) => void;
+    runnerModes?: Record<RunnerId, RunnerModeInfo[]>;
+    autonomousDefault?: boolean;
+    signal?: AbortSignal;
+    perRunnerAllowlist?: Partial<Record<RunnerId, string[]>>;
+    /** The mode toggles this run honours. `modesFor('one-shot', …)` decides which apply. */
+    modes?: PlannerModes;
+}
+interface ModifyPlanRequest {
+    existingPlan: LegacyPlanState;
+    userRequest: string;
+    modelsByRunner: Partial<Record<RunnerId, DiscoveredModel[]>>;
+    fs?: IFileSystem;
+    fetcher?: IWebFetcher;
+    onProgress?: (progress: ResearchProgress) => void;
+    runnerModes?: Record<RunnerId, RunnerModeInfo[]>;
+    autonomousDefault?: boolean;
+    perRunnerAllowlist?: Partial<Record<RunnerId, string[]>>;
+    modes?: PlannerModes;
+}
+interface ModifyDuringExecutionRequest {
+    executionLog: TaskSnapshot[];
+    pendingTasks: Task[];
+    activeSessions: Map<string, ActiveTaskSession>;
+    userMessage: string;
+    modelsByRunner: Partial<Record<RunnerId, DiscoveredModel[]>>;
+    runners: RunnerId[];
+    runnerModes?: Record<RunnerId, RunnerModeInfo[]>;
+    autonomousDefault?: boolean;
+    perRunnerAllowlist?: Partial<Record<RunnerId, string[]>>;
+}
+interface ModifyDuringExecutionResult {
+    pendingTasks: Task[];
+    message: string;
+}
+/**
+ * Owns one-shot plan generation and plan modification — the "planning is a
+ * different workload from execution" thesis, as a module. The conversational
+ * planning loop (ADR-0002) lives on {@link Session}, which talks to the AI
+ * service directly because the conversation state is held there.
+ */
+declare class Planner {
+    private config;
+    /**
+     * Resolved per call, never captured: the planner backend can change while a
+     * surface is open (`/planner`, the webview pills), and a Planner holding the
+     * service it was built with would keep planning on the backend the host has
+     * already switched away from.
+     */
+    private readonly resolveAiService;
+    constructor(config: IConfig, aiService: IAiService | (() => IAiService));
+    private get aiService();
+    /** One-shot plan generation for non-conversational surfaces. Never asks questions. */
+    generate(req: PlanRequest): Promise<LegacyPlanState>;
+    modify(req: ModifyPlanRequest): Promise<{
+        tasks: Task[];
+    }>;
+    modifyDuringExecution(req: ModifyDuringExecutionRequest): Promise<ModifyDuringExecutionResult>;
+}
+
+interface CollectedContext {
+    agentConfig: string | null;
+    agentConfigPath: string | null;
+    dirStructure: string | null;
+    aiflowContext: string | null;
+}
+declare class ContextCollector {
+    private fs;
+    private registry?;
+    constructor(fs: IFileSystem, registry?: RunnerRegistry | undefined);
+    setRegistry(registry: RunnerRegistry): void;
+    collect(runner: string): Promise<CollectedContext>;
+    private readIfExists;
+}
+
+/**
+ * Injectable command runner. Defaults to the real `child_process` exec wrapper;
+ * tests pass a fake so discovery never spawns a process.
+ */
+type ExecImpl = (command: string, options?: {
+    timeout?: number;
+}) => Promise<{
+    stdout: string;
+}>;
+declare function discoverGeminiModels(apiKey: string, baseUrl?: string, fetchImpl?: typeof fetch): Promise<DiscoveredModel[]>;
+
+interface ModelResolverDeps {
+    fetchImpl?: typeof fetch;
+    execImpl?: ExecImpl;
+}
+declare class ModelResolver {
+    private registry;
+    private config;
+    private discovery;
+    private fetchImpl?;
+    private cachedPickerOptions;
+    private lastDiscoveryErrors;
+    constructor(registry: RunnerRegistry, config: IConfig, deps?: ModelResolverDeps);
+    static builtinOptions(): OrchestratorOption[];
+    modelsForRunners(runners: RunnerId[]): Promise<Partial<Record<RunnerId, DiscoveredModel[]>>>;
+    pickerOptions(): Promise<OrchestratorOption[]>;
+    /**
+     * Per-provider failures from the most recent `pickerOptions()` fetch, keyed
+     * by provider id. Empty when every configured provider's catalog loaded (or
+     * before the first fetch). Surfaces consume this to flag a provider whose
+     * key/endpoint is set but whose catalog could not be reached.
+     */
+    getDiscoveryErrors(): Record<string, string>;
+    refresh(): Promise<ProviderModelLists>;
+    refreshRunnerModels(): void;
+    invalidate(): void;
+}
+
+/**
+ * Detects whether a runner's underlying CLI is actually installed on the host,
+ * by invoking `<command> --version`. Mirrors ModelDiscovery: injectable exec,
+ * augmented PATH, per-process cache. A runner that isn't installed should never
+ * be offered for selection in any surface.
+ */
+declare class RunnerInstallation {
+    private cache;
+    private inflight;
+    private registry;
+    private execImpl;
+    constructor(registry: RunnerRegistry, execImpl?: ExecImpl);
+    /** True if the runner's CLI responds to `--version`. Cached per process. */
+    isInstalled(runner: string): Promise<boolean>;
+    /**
+     * Whether this runner can serve as a harness planner (ADR-0009, T9), and why
+     * not when it cannot. Surfaces call this to grey out an unusable agent in the
+     * planner picker with the reason attached — discovering a missing CLI after
+     * typing a real goal is the failure this exists to prevent.
+     *
+     * "Usable" is deliberately shallow: the binary answers `--version`, and the
+     * runner declares a planner transport. Whether the user's subscription is
+     * live cannot be known without spending a turn on it, so an expired login
+     * surfaces where it actually bites — as the agent's own error text on the
+     * first turn.
+     */
+    plannerUsability(runner: string): Promise<{
+        usable: boolean;
+        reason?: string;
+    }>;
+    /**
+     * Whether the CLI can be started the way the harness planner actually starts
+     * it: `spawn` with no shell.
+     *
+     * `isInstalled` probes through `exec`, which goes through cmd.exe on Windows
+     * and so happily resolves a `.cmd` shim — while the planner's own spawn does
+     * not, because CreateProcess performs no PATHEXT lookup. That gap produced
+     * the worst failure shape available: the picker reported the runner healthy,
+     * then the session died on ENOENT with nothing to act on. POSIX has no such
+     * split (`execvp` and `exec` search PATH identically), so this always agrees
+     * with `isInstalled` there.
+     */
+    private isSpawnable;
+    /** Subset of the given runner ids whose CLI is installed. */
+    filterInstalled(runners: string[]): Promise<string[]>;
+    clear(): void;
+}
+
+declare const PROVIDER_LABEL: Record<AiProvider, string>;
+declare const PROVIDER_SHORT_LABEL: Record<AiProvider, string>;
+interface ProviderRegistration {
+    id: AiProvider;
+    label: string;
+    shortLabel: string;
+    /** `cli` is a harness planner (ADR-0009): a local coding agent, not an HTTP vendor. */
+    serviceType: 'openai' | 'google' | 'cli';
+    /** Harness planners only: the runner id whose manifest, models and binary this provider drives. */
+    runnerId?: string;
+    defaultBaseUrl: string;
+    apiKeyEnvVar: string;
+    detectEnvVars: string[];
+    baseUrlEnvVar?: string;
+    secretStoreKey?: string;
+    vscodeBaseUrlKey?: string;
+    vscodeApiKeyKey?: string;
+    discoversModels: boolean;
+    modelPrefix?: string;
+}
+declare const ALL_PROVIDERS: Record<AiProvider, ProviderRegistration>;
+declare function getProviderMeta(id: AiProvider): ProviderRegistration;
+declare function prefixModelId(provider: AiProvider, modelId: string): string;
+declare function stripModelPrefix(id: string, provider: AiProvider): string;
+declare function resolveProviderFromPrefix(id: string): AiProvider | null;
+/**
+ * The harness planners, in display order. Deliberately NOT part of
+ * `PROVIDER_PRIORITY`: that list means "vendors that take an API key", and
+ * every consumer of it — key prompts, catalog fetches, base-URL cache clearing
+ * — would be asking a local binary for a credential it does not have. Surfaces
+ * that offer a planner picker concatenate the two lists and gate these on
+ * `RunnerInstallation.plannerUsability`.
+ */
+declare const CLI_PROVIDERS: AiProvider[];
+declare const PROVIDER_PRIORITY: AiProvider[];
+declare const PROVIDER_DETECT_PRIORITY: AiProvider[];
+declare function isOpenAiProvider(id: AiProvider): boolean;
+/**
+ * The one guard that separates a harness planner from an LLM vendor (ADR-0009).
+ * Three places consult it: API-key resolution (skipped — the subscription is
+ * the credential), provider routing (skipped — there is no HTTP endpoint), and
+ * the planner-model picker (fed by per-runner discovery, not the vendor
+ * catalog).
+ */
+declare function isCliProvider(id: AiProvider): boolean;
+/** The runner a harness planner drives, or null for a vendor provider. */
+declare function runnerForProvider(id: AiProvider): string | null;
+/** The harness planner that wraps a given runner, or null when none does. */
+declare function providerForRunner(runner: string): AiProvider | null;
+/**
+ * The single definition of which providers count as "configured" — one API
+ * key each, or (for `openai_compatible`) an explicit base URL. Every surface
+ * (CLI listing, VS Code picker gating) derives its configured-provider set
+ * from here so they can never diverge on what a user has set up. Order follows
+ * PROVIDER_PRIORITY.
+ */
+declare function configuredProviders(config: {
+    getProviderApiKey(provider: AiProvider): string;
+    openaiCompatibleBaseUrl: string;
+}): AiProvider[];
+
+interface SpawnSpec {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+}
+/**
+ * Shared plumbing for the agents that speak newline-delimited JSON over stdio.
+ *
+ * One long-lived process per planner session (ADR-0009, T3): spawned at
+ * `start`, fed one message per turn, disposed at the session boundary. The
+ * alternative — respawning per turn — pays a cold start on every message
+ * *including each corrective re-emit*, and re-reads the repository from
+ * scratch when it cannot resume.
+ *
+ * Subclasses own their agent's protocol: what to spawn, how to phrase a user
+ * turn, and how to read one protocol line. Everything below — line framing,
+ * turn lifecycle, abort, stderr capture, premature-exit detection — is the
+ * same for all of them.
+ */
+declare abstract class StdioAgentAdapter implements AgentAdapter {
+    protected deps: AgentProcessDeps;
+    abstract readonly agentId: string;
+    protected process: ChildProcess | null;
+    protected sessionId: string | null;
+    private readonly stdout;
+    private stderrTail;
+    private exited;
+    /** Set for the duration of a turn. Outside one, events are buffered rather than dropped. */
+    private turnEmit;
+    /**
+     * Events the agent produced between turns — in practice the startup warnings
+     * that arrive during the handshake. Dropping them hid the one diagnostic
+     * that explains a planner which cannot read the workspace, so they are held
+     * until a turn exists to show them in.
+     */
+    private betweenTurns;
+    private disposed;
+    /** Resolves when the process ends, so a handshake can lose the race instead of waiting out its timeout. */
+    protected processEnded: Promise<void>;
+    /** The environment the agent was spawned under, for any side process a handshake needs. */
+    protected spawnEnv: NodeJS.ProcessEnv;
+    private markEnded;
+    constructor(deps: AgentProcessDeps);
+    /** The command line that starts this agent in its read-only mode. */
+    protected abstract spawnSpec(opts: AgentStartOptions): SpawnSpec;
+    /** The bytes written to stdin to open one user turn. Must end with a newline. */
+    protected abstract turnPayload(message: string): string;
+    /**
+     * Interpret one line of the agent's protocol, emitting normalized events.
+     * Emitting `turn_end` ends the turn; emitting `error` ends it as a failure.
+     */
+    protected abstract handleLine(line: string, emit: (event: AgentEvent) => void): void;
+    /** Protocol handshake, if the agent needs one before it accepts a turn. */
+    protected handshake(_opts: AgentStartOptions): Promise<void>;
+    start(opts: AgentStartOptions): Promise<void>;
+    send(message: string, onEvent: (event: AgentEvent) => void, signal?: AbortSignal): Promise<void>;
+    nativeSessionId(): string | null;
+    dispose(): void;
+    /** Write one raw protocol line to the agent. */
+    protected writeLine(payload: unknown): void;
+    /** Fail-safe contract: a dead agent reports its own last words, never an empty bubble. */
+    protected exitMessage(): string;
+    /** Parse a protocol line, ignoring the non-JSON banners some CLIs print. */
+    protected static parse<T>(line: string): T | null;
+}
+
+/**
+ * Claude Code as a planner, over its bidirectional streaming-JSON transport
+ * (ADR-0009).
+ *
+ * `-p --input-format stream-json --output-format stream-json` keeps one process
+ * alive across turns: user messages go in as JSON lines, and the session's
+ * assistant blocks, tool uses, tool results and turn boundaries come back the
+ * same way. It is the richest of the three streams — partial messages and
+ * separate thinking blocks — which is why this agent went first.
+ */
+declare class ClaudeCodeAdapter extends StdioAgentAdapter {
+    readonly agentId = "claude-code";
+    protected spawnSpec(opts: AgentStartOptions): SpawnSpec;
+    protected turnPayload(message: string): string;
+    protected handleLine(line: string, emit: (event: AgentEvent) => void): void;
+}
+
+/**
+ * Codex as a planner, over its `app-server` stdio JSON-RPC transport
+ * (ADR-0009).
+ *
+ * Ordewell already speaks a slice of this protocol — `ModelDiscovery` drives
+ * `initialize` → `model/list` to build the Codex model catalog — so the
+ * handshake here is that one continued into a thread.
+ *
+ * Codex's own CLI marks `app-server` experimental, and it is the transport
+ * most likely to drift: the method names below (`thread/start`, `turn/start`,
+ * `item/completed`) come from the schema the installed binary generates, and a
+ * version that renames them will surface as a visible dead turn rather than a
+ * hang, because the base class watches the process as well as the protocol.
+ */
+declare class CodexAdapter extends StdioAgentAdapter {
+    readonly agentId = "codex";
+    private threadId;
+    private nextRequestId;
+    private settleHandshake;
+    private handshakeError;
+    private startOpts;
+    /** Whether this turn has already emitted prose — see the `agentMessage` case. */
+    private turnHasText;
+    private resumeAttempted;
+    private resumeFallbackSent;
+    private sandbox;
+    protected spawnSpec(opts: AgentStartOptions): SpawnSpec;
+    /**
+     * `initialize`, then `thread/start`, both before the first user message. The
+     * thread is pinned to the read-only sandbox with approvals set to `never` —
+     * with nobody watching a planner's prompts, "ask" would mean "hang", which is
+     * ADR-0008's absent-is-denial invariant kept by construction.
+     */
+    protected handshake(opts: AgentStartOptions): Promise<void>;
+    /**
+     * Open the thread this session plans in. A resume id means the previous
+     * process died mid-session: `thread/resume` puts the agent back in front of
+     * the context it already paid to read. A failed resume is not an error — the
+     * response handler falls back to a fresh thread, which is the same
+     * degradation `restoreChat` performs on every surface (T4).
+     */
+    private startThread;
+    protected turnPayload(message: string): string;
+    protected handleLine(line: string, emit: (event: AgentEvent) => void): void;
+    /**
+     * Refuse one server→client request. Requests whose result schema can express
+     * a refusal get that payload; everything else — a permission grant, a
+     * question for a user who is not watching, a tool call the client is supposed
+     * to run — gets a JSON-RPC error, which Codex surfaces to the model as a
+     * failed request and plans around, rather than waiting on.
+     */
+    private answerServerRequest;
+    /** A tool item entering `inProgress` — announce the call so the timeline moves. */
+    private emitItemStart;
+    private emitItemDone;
+}
+
+/**
+ * OpenCode as a planner, over its headless HTTP server (ADR-0009).
+ *
+ * The odd one out: `opencode serve` is a real server rather than a stdio
+ * protocol, so this adapter owns both halves of the boundary — it spawns the
+ * process through the same injected `spawn` every other adapter uses, then
+ * talks to it through the injected `fetch`. Both are part of the one seam the
+ * tests drive.
+ *
+ * The turn ends when the message POST resolves. Live events stream from the
+ * server's `/event` channel, but the POST is what settles the turn: an event
+ * name that changes between OpenCode versions then costs liveness, not
+ * correctness.
+ */
+declare class OpenCodeAdapter implements AgentAdapter {
+    private deps;
+    readonly agentId = "opencode";
+    private process;
+    private baseUrl;
+    private sessionId;
+    private stderrTail;
+    private exited;
+    private disposed;
+    private opts;
+    constructor(deps: AgentProcessDeps);
+    start(opts: AgentStartOptions): Promise<void>;
+    send(message: string, onEvent: (event: AgentEvent) => void, signal?: AbortSignal): Promise<void>;
+    /**
+     * Emit one message part, once. OpenCode reports a tool part repeatedly as it
+     * moves through pending → running → completed, so parts are keyed by id and
+     * only the terminal state produces a result.
+     */
+    private emitPart;
+    /**
+     * Deny one permission request (T1). OpenCode blocks the turn until the
+     * request is answered, so this must answer — `reject` rather than a silent
+     * drop, which is the same "absent answer is a denial" invariant ADR-0008
+     * states for Ordewell's own tools. The refusal is announced so the timeline
+     * shows the planner reaching for something it may not have.
+     */
+    private denyPermission;
+    /**
+     * Server-sent events from `/event`. Tool activity on it is liveness only —
+     * the settled POST repeats it — but permission requests arrive nowhere else,
+     * so the stream is load-bearing for {@link denyPermission}.
+     */
+    private streamEvents;
+    private json;
+    nativeSessionId(): string | null;
+    dispose(): void;
+    private exitMessage;
+}
+
+interface MappedTool {
+    tool: ResearchToolType;
+    /** The agent's own name, kept whenever it differs from the member it mapped to. */
+    toolLabel?: string;
+}
+/**
+ * Classify one agent tool name. Case- and separator-insensitive, because the
+ * three agents disagree on `Read` vs `read` vs `read_file` for the same thing.
+ */
+declare function mapAgentTool(name: string): MappedTool;
+/**
+ * Normalize an agent's tool arguments into the shapes `summarizeToolCall`
+ * already knows how to read, so a harness `Read` gets a one-line summary
+ * instead of a bare tool name. Unknown keys are preserved — the raw args stay
+ * visible under the surfaces' output chevron.
+ */
+declare function normalizeAgentArgs(tool: ResearchToolType, args: Record<string, unknown>): Record<string, unknown>;
+
+type SerializedTaskStatus = {
+    id: string;
+    status: string;
+    verdict: {
+        outcome: 'pass' | 'fail';
+        reason: string;
+        checks: Verdict['checks'];
+    } | null;
+};
+type SerializedTask = {
+    id: string;
+    order: number;
+    title: string;
+    type: string;
+    description: string;
+    dependencies: string[];
+    assignedRunner: RunnerId;
+    assignedModel: Task['assignedModel'] | null;
+    taskMode: string;
+    prompt: string | null;
+    subtasks: SerializedTask[];
+    userSteps: Task['userSteps'];
+    thinkingEffort: Task['thinkingEffort'];
+    autonomy: Task['autonomy'];
+    sliceType: Task['sliceType'];
+    userStoriesCovered: Task['userStoriesCovered'];
+};
+type SerializedPlan = {
+    tasks: SerializedTask[];
+    runners: RunnerId[];
+    generatedAt: string;
+    conversationHistory?: LegacyPlanState['conversationHistory'];
+    prdMarkdown?: string;
+    queuedMessages?: QueuedMessage[];
+};
+type SessionMessage = {
+    type: 'plan_generated';
+    plan: SerializedPlan;
+    goal: string;
+    runners: RunnerId[];
+} | {
+    type: 'planner_message';
+    content: string;
+    timestamp: string;
+} | {
+    type: 'status_update';
+    tasks: SerializedTaskStatus[];
+} | {
+    type: 'review_needed';
+    tasks: SerializedTask[];
+} | {
+    type: 'review_approved';
+} | {
+    type: 'checkpoint';
+    taskId: string;
+    taskTitle: string;
+    summary: string;
+} | {
+    type: 'execution_complete';
+    summary: {
+        total: number;
+        completed: number;
+        failed: number;
+    };
+} | {
+    type: 'execution_stopped';
+} | {
+    type: 'queue_ready';
+} | {
+    type: 'task_updated';
+    taskId: string;
+    changes: Record<string, unknown>;
+} | {
+    type: 'task_started';
+    taskId: string;
+    order: number;
+    title: string;
+    runner: RunnerId;
+    modelId?: string;
+} | {
+    type: 'task_output';
+    taskId: string;
+    text: string;
+} | {
+    type: 'plan_thinking';
+    text: string;
+} | {
+    type: 'research_step';
+    tool: string;
+    toolLabel?: string;
+    args: string;
+    subagentId?: string;
+    toolCallId?: string;
+} | {
+    type: 'plan_token';
+    token: string;
+} | {
+    type: 'research_step_done';
+    step: ResearchStep;
+    subagentId?: string;
+} | {
+    type: 'approval_request';
+    id: string;
+    kind: ApprovalKind;
+    subject: string;
+    scope: string;
+    detail?: string;
+} | {
+    type: 'approval_settled';
+    id: string;
+    granted: boolean;
+} | {
+    type: 'approval_decided';
+    kind: ApprovalKind;
+    subject: string;
+    scope: string;
+    detail?: string;
+    granted: boolean;
+    source: Exclude<ApprovalSource, 'asked'>;
+};
+type SessionBroadcaster = (msg: SessionMessage) => void;
+declare function serializeTask(t: Task): SerializedTask;
+declare function serializeTaskStatus(t: Task): SerializedTaskStatus;
+declare function serializePlan(plan: LegacyPlanState): SerializedPlan;
+declare function executionSummary(tasks: Task[]): {
+    total: number;
+    completed: number;
+    failed: number;
+};
+
+/**
+ * Options for plan generation. Progress is not overridable: every planner
+ * progress event is translated to a SessionMessage inside the Session and
+ * emitted through the broadcast seam, so all surfaces consume one union.
+ */
+interface GeneratePlanOptions {
+    signal?: AbortSignal;
+}
+/** The slice of Planner the Session drives — the injection seam for tests. */
+type SessionPlanner = Pick<Planner, 'generate' | 'modify' | 'modifyDuringExecution'>;
+/** Runtime prefs read live — may toggle between operations. */
+interface SessionRuntimeSettings {
+    tddEnabled: boolean;
+    grillMeEnabled: boolean;
+    prdEnabled?: boolean;
+    reviewEnabled?: boolean;
+    verificationEnabled?: boolean;
+    researchSubagentsEnabled?: boolean;
+    modelAllowlist?: Record<string, string[]>;
+}
+/**
+ * The whole of what a host reads off disk for a Session. Both hosts used to
+ * assemble this by hand, mapping each toggle's settings key to its runtime key
+ * in two blocks nothing kept in step — which is how one toggle came to be
+ * dropped. `MODE_TOGGLES` holds the mapping now; this adds the one field that
+ * is not a toggle.
+ */
+declare function sessionRuntimeSettings(settings: UserSettings): SessionRuntimeSettings;
+/**
+ * Everything a delivery surface constructs to host a session. Structural config
+ * (enabledRunners, orchestratorModel, providerModelLists) is snapshotted inside
+ * `config` at construction and never re-read from the environment. Runtime
+ * settings (tdd, grillMe) are read live via the `settings` callback so a toggle
+ * between generate and execute takes effect.
+ */
+interface SessionDeps {
+    config: IConfig;
+    notifications: INotification;
+    runner: ITerminalRunner;
+    registry: RunnerRegistry;
+    /** Resolves the workspace root for the orchestrator (lazy — VS Code can change it). */
+    workspaceRoot: () => string;
+    /** Filesystem adapter for planner research. */
+    fsAdapter: IFileSystem;
+    /** Emits plan-lifecycle events to the surface. Transport-agnostic. */
+    broadcast: SessionBroadcaster;
+    /** Shared across sessions — sole producer of model catalogs and routing lists. */
+    modelResolver: ModelResolver;
+    /** Live runtime settings (tdd, grillMe). Read at each operation that needs them. */
+    settings: () => SessionRuntimeSettings;
+    /**
+     * Host-assigned session id. When set, every persist writes under this id so
+     * the host's REST/UI ids match the saved-session store. When omitted, the
+     * Session mints a fresh id per plan (generatePlan/startPlanning).
+     */
+    sessionId?: string;
+    /**
+     * Planner-conversation seam. Defaults to the provider service for
+     * `config.aiProvider`; inject a fake to test the conversation half without
+     * an LLM.
+     */
+    aiService?: IAiService;
+    /** Plan-generation seam. Defaults to a Planner over the session's aiService. */
+    planner?: SessionPlanner;
+}
+/**
+ * The per-session execution stack — deepened from a wiring bag into the
+ * lifecycle owner. Owns plan generation, execution, mutation, persistence, and
+ * the orchestrator observer wiring. The orchestrator's observer is subscribed
+ * once for the session's lifetime (not per-operation), which kills the
+ * double-subscribe class of bug. Persistence is an internal seam: every plan
+ * mutation routes through `persist()`, so the obligation has a home instead of
+ * being scattered across 11 call sites.
+ *
+ * The broadcast seam carries {@link SessionMessage} — the 15 plan-lifecycle
+ * events. Catalog/config messages (setModels, setRunnerList, …) stay on the
+ * host; Session never emits them.
+ */
+declare class Session {
+    /** Injected by a test; when present it is the service, forever. */
+    private readonly pinnedAiService?;
+    private liveAiService;
+    private liveAiProvider;
+    private readonly workspaceRootFn;
+    private planner;
+    private orchestrator;
+    private store;
+    private config;
+    private registry;
+    private plan;
+    private goal;
+    private workspace;
+    private broadcast;
+    private modelResolver;
+    private fsAdapter;
+    private approvals;
+    private approvalPolicy;
+    private fetcher;
+    private settingsFn;
+    private currentAllowlist;
+    /** Last discovered model catalog — lets sync plan commits clamp thinking efforts to real variants. */
+    private modelsCache;
+    private unsubObserver;
+    private readonly hostSessionId?;
+    private currentSessionId;
+    constructor(deps: SessionDeps);
+    /**
+     * The planner transport for the provider configured *right now* (ADR-0009).
+     *
+     * Resolved on every read rather than once in the constructor, because a
+     * Session outlives the choice: VS Code hosts exactly one for the whole
+     * window, and the webview pills and `/planner` switch backends underneath it.
+     * The model id was already read live, so a service captured at construction
+     * meant a switched planner kept the old backend and got handed the new one's
+     * model — an OpenCode model id spawned as `claude --model opencode/…`, which
+     * the agent rejects as nonexistent.
+     *
+     * Switching releases the outgoing service: a harness planner holds an OS
+     * process, so dropping the reference without `reset()` leaks an agent.
+     */
+    private get aiService();
+    /**
+     * Answer an outstanding approval. Every surface funnels here — the web
+     * server's HTTP route, the VS Code webview, the TUI prompt — so the decision
+     * path is identical regardless of who is looking.
+     */
+    resolveApproval(id: string, granted: boolean): boolean;
+    /** Requests still waiting for an answer, replayed to a surface that connects mid-prompt. */
+    outstandingApprovals(): PendingApproval[];
+    /** Scopes the user granted this session — surfaced so a UI can show what is already allowed. */
+    approvedScopes(): string[];
+    /** The stable id this session persists under — matches the host's id when one was provided. */
+    get sessionId(): string;
+    get executionLog(): TaskSnapshot[];
+    /** Tasks always read from PlanStore — the single source of truth. */
+    get planTasks(): Task[];
+    private attachObserver;
+    private buildObserver;
+    private translateProgress;
+    /** Persists PlanStore state to disk. PlanStore is the single authority;
+     * LegacyPlanState.tasks is populated only here, at persist time. */
+    private persist;
+    /** A new plan on a long-lived Session gets its own persisted identity (unless the host fixed one). */
+    private remintSessionId;
+    /**
+     * A new plan starts from zero: drop the live planner conversation and every
+     * task, log, and queued message left over from a previous plan on this
+     * Session. Without this, a long-lived Session (VS Code hosts exactly one)
+     * leaks the previous session's tasks into `planContextBlock()` — the model
+     * is told they are the CURRENT plan and re-presents them as its draft.
+     */
+    private beginFreshPlan;
+    /**
+     * Return the Session to a blank slate — hosts call this on "new session".
+     * Everything scoped to the old session goes: the live AI conversation, plan,
+     * goal, tasks, execution log, queued messages, model cache, and (unless the
+     * host fixed one) the persisted identity, so nothing can bleed into the next
+     * session.
+     */
+    reset(): void;
+    private runnerModesFor;
+    get planState(): LegacyPlanState | null;
+    /**
+     * The live plan in the shape a saved session is read back as. The disk
+     * boundary rewrites `in_progress` to `pending` — nothing is running when a
+     * session comes off a file — so a surface that re-reads the plan mid-run must
+     * come here instead, or every task it is watching reads as never started.
+     */
+    get currentPlanState(): PlanState | null;
+    get currentGoal(): string;
+    get isPlanning(): boolean;
+    get isExecuting(): boolean;
+    get status(): 'approved' | 'running' | 'completed';
+    get sessionConfig(): IConfig;
+    startExecution(): Promise<void>;
+    generatePlan(goal: string, runners: RunnerId[], options?: GeneratePlanOptions): Promise<LegacyPlanState>;
+    /**
+     * Kick off the planner conversation (ADR-0002): research + the first planner
+     * message. The AI service retains the tool-use history; the Session persists
+     * the user/assistant dialogue on the plan state.
+     */
+    startPlanning(goal: string, runners: RunnerId[], options?: GeneratePlanOptions): Promise<LegacyPlanState>;
+    /**
+     * Every subsequent user reply in the planning conversation — grill-me
+     * answers, PRD accept/adjust, outline confirm. One branch, no phase ladder.
+     */
+    continueConversation(userMessage: string, options?: GeneratePlanOptions): Promise<LegacyPlanState>;
+    /**
+     * Drive a planner turn to a persisted, broadcast outcome. Task edits apply
+     * atomically; validation failures are fed back to the model for up to 2
+     * silent retries, then surfaced as a message with the plan untouched. The
+     * first turn (startPlanning) and every later turn route through here — one
+     * path, not two.
+     */
+    private settleTurn;
+    /**
+     * The "you are here" block for post-plan chat: current tasks with stable
+     * references, plus the task-ops protocol. Injected per turn (never
+     * persisted) so the model always sees live statuses — including which tasks
+     * are locked by a running execution.
+     */
+    private planContextBlock;
+    /** Validate + commit a task_ops turn atomically. Returns the errors on rejection (plan untouched). */
+    private applyTaskOpsTurn;
+    /**
+     * Resume a persisted dialogue onto a fresh AI-service conversation — either
+     * because the in-memory one is gone (session reload, extension restart), or
+     * because {@link continueConversation} found it stale against the planner
+     * config now in effect (a harness planner's model/effort switched mid-chat).
+     * The saved transcript seeds the new conversation; no LLM call happens
+     * before the user's message is sent.
+     */
+    private resumeConversation;
+    /** Whether the planner conversation is live (started and not yet committed to a plan). */
+    get isConversationActive(): boolean;
+    /** Append one dialogue entry to the persisted transcript. Callers persist via the mutatePlan ritual. */
+    private appendTranscript;
+    /** Commit a settled (non-task_ops) turn. Both branches run the mutatePlan ritual. */
+    private applyConversationTurn;
+    /**
+     * PRD mode: when the planner writes the full markdown PRD, save it to
+     * .scratch/<slug>/PRD.md (Matt Pocock to-prd convention) and keep it on the plan.
+     */
+    private capturePrd;
+    executePlan(): Promise<void>;
+    approveReview(): Promise<LegacyPlanState>;
+    forceStartTask(taskId: string): Promise<void>;
+    runTask(taskId: string): Promise<void>;
+    retryTask(taskId: string): Promise<void>;
+    cancelTask(taskId: string): Promise<void>;
+    markAiTaskComplete(taskId: string): Promise<void>;
+    markTaskComplete(taskId: string): Promise<void>;
+    markTaskIncomplete(taskId: string): Promise<void>;
+    tick(): Promise<void>;
+    processQueuedMessages(): Promise<void>;
+    approveCheckpoint(taskId: string): void;
+    rejectCheckpoint(taskId: string, reason?: string): void;
+    queueMessage(text: string): void;
+    getQueuedMessages(): QueuedMessage[];
+    setQueuedMessages(msgs: ReturnType<TaskOrchestrator['getQueuedMessages']>): void;
+    processNextQueuedMessage(): QueuedMessage | null;
+    get queuedCount(): number;
+    getTask(taskId: string): Task | undefined;
+    get isReviewApproved(): boolean;
+    stopExecution(): void;
+    /**
+     * The one mutation seam: every structural plan mutation runs the same
+     * ritual — store op → persist (which snapshots tasks from PlanStore) →
+     * broadcast — in that order, once. A store op returning false aborts
+     * before anything is persisted. PlanStore is the single authority for
+     * task state; LegacyPlanState.tasks is populated only at persist time.
+     */
+    private mutatePlan;
+    updateTask(taskId: string, changes: Partial<Task>): LegacyPlanState | null;
+    /**
+     * Move one task onto a different runner. Distinct from {@link updateTask}
+     * because a runner change is never a single-field edit: the task's model,
+     * thinking effort and mode are all scoped to its runner, so they are
+     * re-derived from the new runner's catalog (see {@link retargetTaskRunner}).
+     * That needs discovery, which is async — hence a method of its own rather
+     * than a branch inside the sync `updateTask`.
+     *
+     * The runner is also admitted into `plan.runners` — see {@link admitRunner}.
+     */
+    setTaskRunner(taskId: string, runner: RunnerId): Promise<LegacyPlanState | null>;
+    /** What a runner offers, as {@link runnerAssignment} needs it. Spawns the runner's CLI to list models. */
+    private catalogFor;
+    /**
+     * What a *derived* assignment may draw from: the runner's catalog narrowed to
+     * the user's allowlist. Deriving from the full catalog would hand a task the
+     * runner's first model regardless of a restriction the user set — the next
+     * planner turn's `coerceAssignments` would snap it back anyway, so the user
+     * would see their pick silently change instead of never being offered.
+     *
+     * `catalogFor` stays unnarrowed because {@link admitRunner} caches it as what
+     * the runner really offers, which is what effort clamping needs.
+     */
+    private allowedCatalog;
+    /**
+     * Make a runner a first-class member of this plan. Without this, the next
+     * planner turn's `coerceAssignments` would treat it as disallowed and snap
+     * every task on it back, silently undoing the user's choice; and that same
+     * pass clamps efforts against `modelsCache`, so a catalog missing from there
+     * makes the effort we just derived read as unverifiable.
+     */
+    private admitRunner;
+    /**
+     * Replace one task's dependency list. Separate from {@link updateTask}
+     * because a hand-edited graph is the one task edit that can leave a plan
+     * unschedulable: `canSetDependencies` is the guard, and it lives behind this
+     * one method so the API and both surfaces' pickers reject the same edits
+     * rather than each carrying a copy of the rule. Throws so a surface can say
+     * why the edit was refused.
+     */
+    setTaskDependencies(taskId: string, dependencies: string[]): LegacyPlanState | null;
+    completeTask(taskId: string): Promise<void>;
+    removeTask(taskId: string): LegacyPlanState | null;
+    /**
+     * Add one task, filling in whatever the caller left unset. A task with no
+     * runnable assignment is not a lighter task but an unspawnable one, so the
+     * runner falls back to the plan's first and the model, effort and mode are
+     * derived from that runner's catalog — the same derivation a runner change
+     * uses ({@link runnerAssignment}), which is why this is async like
+     * {@link setTaskRunner}. Anything the caller did choose survives when the
+     * runner offers it.
+     *
+     * Dependencies naming tasks that don't exist are dropped rather than rejected:
+     * the caller is a picker over the current plan, so a stale id means the plan
+     * moved on, not that the whole task should be refused.
+     */
+    addTask(draft: Partial<Task>): Promise<LegacyPlanState | null>;
+    mergeTasks(taskIdA: string, taskIdB: string): LegacyPlanState | null;
+    mergeMultipleTasks(taskIds: string[]): LegacyPlanState | null;
+    splitTask(taskId: string, newTasks: Partial<Task>[]): LegacyPlanState | null;
+    /**
+     * Planner-driven merge: validate compatibility up front, then ask the planner
+     * LLM to produce a single "merge" taskOps op combining the selected tasks.
+     * Goes through the same conversation loop + validated-atomic-edit + corrective
+     * retry flow as every other task_ops edit (ADR-0002). Throws on a
+     * pre-flight compatibility failure so the host surfaces an inline error
+     * before any LLM call.
+     */
+    requestMerge(taskIds: string[], options?: GeneratePlanOptions): Promise<LegacyPlanState>;
+    /**
+     * Planner-driven split: ask the planner LLM to decompose one task into a
+     * sequence of smaller tasks. The model generates the breakdown (no manual
+     * per-task specs from the user). Same conversation-loop/repair path as merge.
+     */
+    requestSplit(taskId: string, options?: GeneratePlanOptions): Promise<LegacyPlanState>;
+    loadPlan(plan: LegacyPlanState, goal: string, workspace: string, opts?: {
+        sessionId?: string;
+        persist?: boolean;
+    }): void;
+    modifyPlan(userRequest: string): Promise<Task[]>;
+    destroy(): void;
+    private broadcastPlan;
+    get aiServiceInstance(): IAiService;
+}
+
+type VerdictListener = (taskId: string, verdict: Verdict, output: string) => void;
+type CheckpointListener = (taskId: string, summary: string) => void;
+declare class VerdictEngine {
+    private markerSeen;
+    private buffers;
+    private checkpointCounts;
+    private pausedSessions;
+    private listeners;
+    private checkpointListeners;
+    /**
+     * Per-task generation counter. Incremented on every watch() and clear().
+     * Stale callbacks (from a prior session whose generation doesn't match
+     * the current one) bail out instead of delivering a verdict for the
+     * wrong session.
+     */
+    private generations;
+    onVerdict(listener: VerdictListener): void;
+    onCheckpoint(listener: CheckpointListener): void;
+    approveCheckpoint(taskId: string): void;
+    rejectCheckpoint(taskId: string, reason: string): void;
+    /**
+     * Attach to a spawned session: buffer output, scan for the task's completion
+     * marker (delivering a verdict immediately while leaving interactive sessions
+     * open), scan for checkpoint markers, and on exit produce a failed verdict
+     * when the marker was never observed.
+     */
+    watch(task: Task, session: ITerminalSession): void;
+    /** Manual "Mark complete" override: a pass verdict that bypasses evidence. */
+    markComplete(task: Task): Verdict;
+    /** Clear verification state for a task (used on retry). */
+    clear(task: Task): void;
+    /** Drop all tracking state (used on stop / loadPlan). */
+    reset(): void;
+    private decide;
+}
+
+/**
+ * The ids a runner may actually run: the user's allowlist with the ids that
+ * provably belong to a *different* runner dropped. `undefined` means no
+ * restriction.
+ *
+ * Model ids are scoped to the agent that lists them, so an OpenRouter slug
+ * allowlisted for Claude Code does not limit it — it points it at something it
+ * cannot spawn, and the plan only dies once a task is already running. But
+ * "this runner didn't list it" is not enough to call an id wrong: discovery can
+ * be stale, and a plugin runner may have no list at all. What settles it is
+ * whether *another* runner listed the id. So:
+ *
+ * - listed for this runner → keep;
+ * - listed for no runner → unknown, and the user said it explicitly, so keep it
+ *   and let the runner validate last (the same call `coerceAssignments` and
+ *   `TaskRetarget` make);
+ * - listed only for other runners → provably not this runner's, so drop it.
+ *
+ * When that leaves nothing, the whole allowlist was about some other runner
+ * (a settings file written before a surface scoped its picker to one). No
+ * restriction is the only safe reading — the alternative is handing the planner
+ * a list of models that cannot run.
+ */
+declare function effectiveAllowlist(allowlist: string[] | undefined, runner: string, modelsByRunner: Partial<Record<RunnerId, DiscoveredModel[]>> | undefined): string[] | undefined;
+declare function filterModelsForPrompt(modelsByRunner: Partial<Record<RunnerId, DiscoveredModel[]>>, perRunnerAllowlist: Partial<Record<RunnerId, string[]>>): Partial<Record<RunnerId, DiscoveredModel[]>>;
+/**
+ * Clamp a planner/user-supplied thinking effort to what the model actually
+ * offers. Invalid values map to the nearest rung the model supports (so a
+ * Claude-style "xhigh" on a low/medium/high model becomes "high") and fall
+ * back to undefined — the runner's own default — when no mapping exists.
+ */
+declare function clampThinkingEffort(effort: string | undefined, variants: {
+    id: string;
+}[]): string | undefined;
+declare function coerceAssignments(tasks: Task[], perRunnerAllowlist: Partial<Record<RunnerId, string[]>>, allowedRunners?: RunnerId[], modelsByRunner?: Partial<Record<RunnerId, DiscoveredModel[]>>): Task[];
+
+/** What a runner offers a task: the models discovered for it and the modes its manifest declares. */
+interface RunnerCatalog {
+    models: DiscoveredModel[];
+    modes: RunnerModeInfo[];
+}
+/**
+ * The model, thinking effort and mode a runner offers for a task.
+ *
+ * A task's model, effort and mode are all scoped to its runner:
+ * `claude-sonnet-4-5` on Codex, or `acceptEdits` on OpenCode, are not degraded
+ * choices but unspawnable ones. So this is where any task acquires a runnable
+ * assignment — a runner change (below) and a hand-added task derive it the same
+ * way. Each field in `current` is preserved when the runner also offers it, and
+ * otherwise snapped to that runner's preferred entry (discovery already sorts
+ * models by the manifest's `preferredPatterns`; `modes[0]` is the manifest's own
+ * first choice).
+ *
+ * An empty catalog means discovery failed or the runner is a plugin we have no
+ * list for — not that the runner offers nothing. That field is left out of the
+ * patch and the runner validates last, matching `coerceAssignments`.
+ */
+declare function runnerAssignment(catalog: RunnerCatalog, current?: Pick<Task, 'assignedModel' | 'taskMode'>): Partial<Task>;
+/**
+ * Move a task onto a different runner, carrying its model, thinking effort and
+ * mode over to values that runner actually offers. A runner change is never a
+ * single-field edit — it either brings the other three with it or leaves the
+ * task unrunnable.
+ *
+ * Returns the patch to apply, or `{}` when there is nothing to change.
+ */
+declare function retargetTaskRunner(task: Task, runner: RunnerId, catalog: RunnerCatalog): Partial<Task>;
+
+declare function buildResearchToolsPrompt(subagentsEnabled?: boolean): string;
+/**
+ * System prompt for one read-only research subagent (issue #34). The digest
+ * contract matters: the reply goes back to the planner as a tool result, so it
+ * must be dense, self-contained, and carry exact file paths — never questions,
+ * never a task plan.
+ */
+declare function buildSubagentSystemPrompt(): string;
+declare function buildConversationSystemPrompt(goal: string, context: string, modelsByRunner: Partial<Record<RunnerId, DiscoveredModel[]>>, runners: RunnerId[], runnerModes?: Record<RunnerId, RunnerModeInfo[]>, autonomousDefault?: boolean, grillMeEnabled?: boolean, prdEnabled?: boolean, reviewEnabled?: boolean, verificationEnabled?: boolean, 
+/** Harness planner (ADR-0009): the agent owns its own tools and research budget. */
+harnessMode?: boolean): string;
+declare const CORE_PLANNER_PROMPT: string;
+declare function buildResearchPrompt(userGoal: string, context: string, modelsByRunner: Partial<Record<RunnerId, DiscoveredModel[]>>, runners: RunnerId[], runnerModes?: Record<RunnerId, RunnerModeInfo[]>, modes?: PlannerModes): string;
+declare function buildPlanWithResults(userGoal: string, context: string, researchResults: string, modelsByRunner: Partial<Record<RunnerId, DiscoveredModel[]>>, runners: RunnerId[], runnerModes?: Record<RunnerId, RunnerModeInfo[]>, modes?: PlannerModes): string;
+declare function buildModifyPlanPrompt(existingPlan: LegacyPlanState, userRequest: string, modelsByRunner: Partial<Record<RunnerId, DiscoveredModel[]>>, aiflowContext?: string, runnerModes?: Record<RunnerId, RunnerModeInfo[]>, autonomousDefault?: boolean): string;
+declare function modelContextBlock(modelsByRunner: Partial<Record<RunnerId, DiscoveredModel[]>>, runners: RunnerId[], runnerModes?: Record<RunnerId, RunnerModeInfo[]>, autonomousDefault?: boolean): string;
+declare function executionLogBlock(executionLog: TaskSnapshot[]): string;
+declare function pendingEditRulesBlock(): string;
+declare function buildModifyDuringExecutionPrompt(executionLog: TaskSnapshot[], pendingTasks: string, userMessage: string, modelsByRunner: Partial<Record<RunnerId, DiscoveredModel[]>>, runners: RunnerId[], runnerModes?: Record<RunnerId, RunnerModeInfo[]>, autonomousDefault?: boolean): string;
+/**
+ * User-message prompt for a planner-driven merge: asks the model to combine the
+ * selected tasks into one. Routed through the conversation loop, so the
+ * task-ops protocol (with the "merge" op) is injected alongside it by
+ * `planContextBlock`. The model emits a single taskOps merge op.
+ */
+declare function buildMergePrompt(taskIds: string[], tasks: Task[]): string;
+/**
+ * User-message prompt for a planner-driven split: asks the model to decompose
+ * one task into a sequence of smaller tasks. The model decides the breakdown —
+ * the user does not hand-type the parts.
+ */
+declare function buildSplitPrompt(taskId: string, tasks: Task[]): string;
+
+/**
+ * The one owner of "the model emitted something unusable — correct it and
+ * retry". Every repair path in the planner routes through this module:
+ *
+ * - {@link repairLoop} is the bounded driver (first reply → interpret →
+ *   corrective re-send), used by plan generation ({@link generatePlanWithRepair}),
+ *   the Session's task-ops settlement, and Planner.modifyDuringExecution.
+ * - {@link classifyPlannerReply} decides what a planner reply *is* — a plan,
+ *   targeted task edits, a botched attempt at either (worth a corrective
+ *   retry), or prose. The conversation loop in BaseAiService keeps its own
+ *   driver (it also runs the tool rounds) but delegates classification here.
+ * - The corrective prompt texts live here, once.
+ *
+ * Policies stay at the call sites (PRD nudge, ops validation, abort guards) —
+ * they are inputs to the loop, not part of it.
+ */
+type RepairVerdict<T> = {
+    done: T;
+} | {
+    retry: {
+        errors: string[];
+        corrective: string;
+        cause?: unknown;
+    };
+};
+interface RepairLoopOpts<R, T> {
+    /** Produce the first reply (attempt 0) — often already in hand. */
+    first: () => R | Promise<R>;
+    /** Ask the model again with a corrective prompt after a retryable failure. */
+    resend: (corrective: string) => Promise<R>;
+    /**
+     * Judge one reply: `done` with the settled value, or `retry` with the
+     * errors and the corrective prompt to send. Throw for non-retryable
+     * failures — those propagate immediately.
+     */
+    interpret: (reply: R) => RepairVerdict<T> | Promise<RepairVerdict<T>>;
+    /** Corrective re-sends allowed after the first attempt (N repairs = N+1 attempts). */
+    maxRepairs: number;
+    /** Budget exhausted: receives the last reply and its errors; return a fallback or throw. */
+    onExhausted: (last: {
+        reply: R;
+        errors: string[];
+        cause?: unknown;
+    }) => T;
+}
+declare function repairLoop<R, T>(opts: RepairLoopOpts<R, T>): Promise<T>;
+/** Instruction appended to a follow-up request asking the model to re-emit strict JSON. */
+declare const JSON_REPAIR_INSTRUCTION: string;
+/**
+ * The emission hit the output-token limit: a plain "re-send the JSON" retry
+ * would be cut off at the same point, so this one asks for terser output.
+ */
+declare const TRUNCATED_PLAN_REPAIR_INSTRUCTION: string;
+/** A plan attempt was botched (invalid or truncated JSON): re-emit the whole plan. */
+declare function reEmitPlanPrompt(detail: string): string;
+/** A plan emission was truncated mid-JSON; the caller may also have compacted the history to free input context. */
+declare function truncatedPlanReEmitPrompt(historyCompacted: boolean): string;
+/** A task-ops attempt was botched (unparseable JSON): re-emit the ops object. */
+declare function reEmitTaskOpsPrompt(detail: string): string;
+/** Task ops parsed but failed semantic validation (cycles, unknown refs, locked tasks). */
+declare function taskOpsRejectedPrompt(errors: string[]): string;
+/** A modified plan failed validation during execution: full re-prompt feedback block. */
+declare function modifyValidationFeedback(errors: string[]): string;
+type PlannerReplyClassification = {
+    kind: 'plan';
+    tasks: Task[];
+} | {
+    kind: 'task_ops';
+    ops: TaskOp[];
+}
+/** Clearly attempted a plan (tasks-keyed object, or JSON cut off mid-stream) and botched it — worth a corrective retry. */
+ | {
+    kind: 'broken_plan';
+    error: PlanParseError;
+}
+/** Clearly attempted an ops object and botched it — worth a corrective retry. */
+ | {
+    kind: 'broken_task_ops';
+    error: PlanParseError;
+} | {
+    kind: 'prose';
+};
+/**
+ * Classify one planner reply. Task ops are checked before the plan key — an
+ * ops object never carries a top-level tasks array, but a model may mention
+ * the word in prose around it. "Broken" is deliberately narrower than "failed
+ * to parse": prose that merely mentions the envelope key is left alone.
+ */
+declare function classifyPlannerReply(text: string, opts: {
+    runners: RunnerId[];
+    runnerModes?: Record<RunnerId, RunnerModeInfo[]>;
+    autonomousDefault?: boolean;
+}): PlannerReplyClassification;
+/**
+ * Generate a plan, retrying on unparseable JSON. `generate` is called with an
+ * optional repair hint (undefined on the first attempt, {@link JSON_REPAIR_INSTRUCTION}
+ * thereafter) and must return the model's raw text. Only {@link PlanParseError} is
+ * retried; transport/other errors propagate immediately. The last parse error is
+ * re-thrown if every attempt fails.
+ */
+declare function generatePlanWithRepair(generate: (repairHint?: string) => Promise<string>, runners: RunnerId[], maxAttempts?: number, runnerModes?: Record<RunnerId, RunnerModeInfo[]>, autonomousDefault?: boolean): Promise<Task[]>;
+
+type RunnerMode = string;
+
+declare function buildRunnerInvocation(opts: {
+    runner: string;
+    prompt: string;
+    modelId?: string;
+    thinkingEffort?: string;
+    modelVariants?: string[];
+    mode?: RunnerMode;
+    headless?: boolean;
+    registry: RunnerRegistry;
+}): RunnerInvocation;
+
+type ExecFileFn = (command: string, args: string[]) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+/** Test seam: every OS touchpoint is injectable; production uses the defaults. */
+interface TmuxRunnerDeps {
+    port: number;
+    execFileImpl?: ExecFileFn;
+    resolvePath?: () => Promise<string>;
+    pollIntervalMs?: number;
+    logDir?: string;
+}
+declare class TmuxSession extends AbstractTerminalSession {
+    private tmuxSession;
+    private windowName;
+    private execFileImpl;
+    private pollIntervalMs;
+    private logPath;
+    private socket;
+    private outputBuffer;
+    private offset;
+    private timer;
+    constructor(id: string, taskId: string, tmuxSession: string, windowName: string, execFileImpl: ExecFileFn, pollIntervalMs: number, logPath: string, socket: string);
+    private get target();
+    /** Every tmux call must name the daemon's own socket; an unprefixed one
+     * silently targets the shared default server (see `tmuxSocketName`). */
+    private tmux;
+    /**
+     * Runs the invocation in a fresh tmux window, tailed via `pipe-pane` into a
+     * log file rather than polling `capture-pane` snapshots — a byte-exact
+     * stream needs no diff/resync heuristics. The command is wrapped so the
+     * window survives its own exit (an `exec`'d login shell), which is what
+     * lets the user keep poking at a finished task's terminal.
+     */
+    start(command: string, args: string[], cwd: string, env?: Record<string, string>): Promise<void>;
+    private poll;
+    /**
+     * A task finishing (or being killed) stops observation, but never the
+     * window itself on the sentinel path — only `kill()` closes the window.
+     * Piping is turned off and the log file removed either way, so a finished
+     * task doesn't leave a `cat` process appending to it for the rest of the
+     * daemon's life.
+     */
+    private finish;
+    kill(): void;
+    getOutput(): string;
+    write(text: string): void;
+}
+/**
+ * Runs tasks in a real tmux window instead of a piped subprocess, so a user
+ * can open a genuine, interactive terminal on any task (running or
+ * finished) from outside Ordewell's own process. `ITerminalSession` hides the
+ * transport from `VerdictEngine`/`PoolAwareRunner`, so orchestration is
+ * unchanged — this is a drop-in replacement for `HeadlessRunner`.
+ */
+declare class TmuxRunner extends AbstractRunner<TmuxSession> {
+    private sessionName;
+    private socket;
+    private execFileImpl;
+    private resolvePath;
+    private pollIntervalMs;
+    private logDir;
+    /** Retries get a freshly named window so a failed attempt's output stays inspectable. */
+    private attempts;
+    private ready;
+    constructor(deps: TmuxRunnerDeps);
+    /**
+     * Reaps a session orphaned by a crashed prior daemon on the same port, then
+     * creates a fresh one. Memoized: `spawn` awaits it too, so a task spawned
+     * before startup's own call has settled never lands in a missing session —
+     * and a settled failure clears the memo so the next spawn can retry.
+     */
+    ensureSession(): Promise<void>;
+    /** Every tmux call must name this daemon's socket; see `tmuxSocketName`. */
+    private tmux;
+    private createFreshSession;
+    /**
+     * Makes an attached runner terminal scrollable with the mouse wheel and
+     * Page Up/Down. A fresh tmux session ships with `mouse off`, a 2000-line
+     * scrollback, and no PageUp binding — none of which lets a user page back
+     * through a finished task's output, which is the whole point of opening its
+     * window. Scoping is harmless: the daemon owns a private socket
+     * (`tmuxSocketName`), so these server-wide options touch nothing but its
+     * own session. Best-effort so an ancient or stripped tmux cannot stop tasks
+     * from spawning — the session still works without the scroll comforts.
+     */
+    private configureScrolling;
+    /**
+     * Called on daemon shutdown — the one guarantee against leaked tmux
+     * processes. Kills the whole server, not just the session: the socket
+     * belongs to this daemon alone, so nothing else can be on it, and a runner
+     * that somehow escaped its session would otherwise keep running (and keep
+     * billing) unattached for as long as the server lived.
+     */
+    killSession(): Promise<void>;
+    spawn(opts: {
+        taskId: string;
+        runner: string;
+        prompt: string;
+        modelId?: string;
+        thinkingEffort?: string;
+        modelVariants?: string[];
+        mode?: string;
+        headless?: boolean;
+        cwd: string;
+        registry?: RunnerRegistry;
+        planSessionId?: string;
+    }): Promise<ITerminalSession>;
+}
+
+declare function stripAnsi(text: string): string;
+declare function posixShellQuote(s: string): string;
+/**
+ * Wrap a command for execution inside a POSIX login shell, which is what
+ * resolves runner binaries managed by nvm/volta/asdf.
+ *
+ * Deliberately POSIX-only. This used to take a `platform` and emit
+ * `powershell.exe -Command "'claude' '-p' '…'"` for Windows, which PowerShell
+ * cannot run at all: a quoted string in leading position is parsed in
+ * expression mode, so the invocation died with a parse error before the runner
+ * started — a task that failed instantly, every time, on that platform. Windows
+ * has no login-shell equivalent to emulate (its PATH comes from the registry
+ * and is already inherited), so {@link planShellLaunch} starts the runner
+ * directly there instead of routing it through a shell. Platform choice belongs
+ * to that function; this one only knows how to phrase the POSIX half.
+ */
+declare function buildShellInvocation(command: string, args: string[]): {
+    shellPath: string;
+    shellArgs: string[];
+};
+/**
+ * Wrap a command in `script` to allocate the PTY some runners require when
+ * headless; `-e` propagates the child's exit code so verification still works.
+ *
+ * POSIX-only by nature — there is no `script` on Windows, which
+ * `HeadlessRunner`'s `hasScriptCmd` probe already discovers, so this is never
+ * reached there.
+ */
+declare function wrapWithPty(command: string, args: string[]): {
+    command: string;
+    args: string[];
+};
+
+interface KillTreeDeps {
+    platform?: NodeJS.Platform;
+    /** Runs `taskkill`. Injected so the Windows path is testable off Windows. */
+    execFileImpl?: (file: string, args: string[], cb: (err: Error | null) => void) => void;
+    /** Schedules the forced kill. Injected so tests need no timers. */
+    setTimeoutImpl?: (fn: () => void, ms: number) => {
+        unref?: () => void;
+    };
+    clearTimeoutImpl?: (handle: unknown) => void;
+}
+/**
+ * Terminate `proc` and everything it started.
+ *
+ * Returns immediately; the forced follow-up (SIGKILL, or `taskkill /F`) is
+ * scheduled and unref'd, so a disposed session is never the reason the host
+ * process refuses to exit.
+ */
+declare function killTree(proc: ChildProcess | null, deps?: KillTreeDeps): void;
+
+type ExecFn = (command: string, options?: {
+    timeout?: number;
+}) => Promise<{
+    stdout: string;
+}>;
+/**
+ * Exported for test: the Windows arm cannot be exercised from a Linux CI box
+ * through {@link augmentedPath}, which reads `process.platform` and the real
+ * environment. Production always calls it through the no-argument form.
+ */
+declare function wellKnownBinDirs(deps?: {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+}): string[];
+/**
+ * The augmented PATH for spawning user-installed CLI tools. Resolved once per
+ * process and cached (the login shell query costs ~50-200ms).
+ */
+declare function augmentedPath(execImpl?: ExecFn): Promise<string>;
+/** Test seam: drop the per-process cache so the next call re-resolves. */
+declare function clearAugmentedPathCache(): void;
+/**
+ * Build a child environment whose PATH is `resolvedPath`, with exactly one
+ * PATH-ish key in it.
+ *
+ * `{ ...process.env, PATH }` is the obvious spelling and it is wrong on
+ * Windows. Node's `process.env` is a case-insensitive proxy, but spreading it
+ * yields the OS's actual casing — `Path` — so adding `PATH` produces an
+ * environment block carrying both. Which one the child sees is undefined, and
+ * the loser is silently discarded. Every existing site passed the same value
+ * under both keys, so the bug was latent rather than live; this makes it
+ * impossible instead of unlikely.
+ */
+declare function withPath(base: NodeJS.ProcessEnv, resolvedPath: string, overrides?: Record<string, string>): NodeJS.ProcessEnv;
+
+/** One shared tmux session per daemon, scoped by port so multiple daemons never collide. */
+declare function tmuxSessionName(port: number): string;
+/**
+ * Each daemon gets its own tmux *server*, not just its own session name.
+ *
+ * A plain `tmux new-session` attaches to whatever server already owns the
+ * default socket, and a session created on an existing server inherits that
+ * **server's** environment — not the environment of the process that asked for
+ * it (tmux only refreshes `update-environment` vars, and only on attach). So a
+ * daemon started with, say, a particular provider API key would silently hand
+ * its runners a stale key left behind by whoever started the server first,
+ * possibly hours earlier under a different configuration entirely.
+ *
+ * A private socket makes the server a child of this daemon, so the runner
+ * inherits the daemon's environment the way any child process would, and
+ * `kill-server` at shutdown is authoritative — a runner cannot outlive the
+ * daemon by hiding on a shared server. Users attaching by hand need the same
+ * flag: `tmux -L ordewell-<port> attach -t ordewell-<port>`.
+ */
+declare function tmuxSocketName(port: number): string;
+/**
+ * tmux window targeting breaks on `:` and other punctuation, so ids are
+ * slugged. Task ids are only unique within one plan ("task-1" is every
+ * planner's favourite), so the window is also scoped by the plan session id —
+ * without it, the second plan run in a daemon's lifetime would collide with
+ * the first plan's still-open windows and pipe its output into the wrong one.
+ */
+declare function tmuxWindowName(taskId: string, planSessionId?: string): string;
+type ProbeFn = () => void;
+/** Feature-detects tmux the same way `HeadlessRunner` detects `script`. */
+declare function hasTmux(probe?: ProbeFn): boolean;
+
+declare class FsPluginStore implements IPluginStore {
+    getUserPluginsDir(): string;
+    listUserPluginDirs(): string[];
+    loadManifest(pluginDir: string): RunnerPluginManifest | null;
+    copyDir(sourceDir: string, destDir: string): void;
+    removeDir(dir: string): void;
+    ensureDir(dir: string): void;
+    writeFile(filePath: string, content: string): void;
+    readFile(filePath: string): string | null;
+    dirExists(path: string): boolean;
+    exists(path: string): boolean;
+}
+
+declare function resolveArgs(manifest: RunnerPluginManifest, ctx: ResolveContext): RunnerInvocation;
+
+declare const CLAUDE_CODE_MANIFEST: RunnerPluginManifest;
+
+declare const OPENCODE_MANIFEST: RunnerPluginManifest;
+
+declare const STATE_DIR = ".ordewell";
+declare function ensureDir(dir: string): void;
+declare function getStateDir(baseDir?: string): string;
+
+declare function saveState(plan: LegacyPlanState, baseDir?: string): void;
+declare function loadState(baseDir?: string, logger?: ILogger): LegacyPlanState | null;
+declare function clearState(baseDir?: string): void;
+declare function stateExists(baseDir?: string): boolean;
+
+declare function saveSession(plan: LegacyPlanState, goal: string, baseDir?: string, id?: string): SessionMeta;
+declare function listSessions(baseDir?: string, logger?: ILogger): SessionMeta[];
+declare function loadSession(sessionId: string, baseDir?: string, logger?: ILogger): {
+    meta: SessionMeta;
+    plan: LegacyPlanState;
+} | null;
+declare function loadSessionPlanState(sessionId: string, baseDir?: string, logger?: ILogger): {
+    meta: SessionMeta;
+    plan: PlanState;
+} | null;
+declare function getLatestSession(baseDir?: string, logger?: ILogger): {
+    meta: SessionMeta;
+    plan: LegacyPlanState;
+} | null;
+declare function deleteSession(sessionId: string, baseDir?: string, logger?: ILogger): boolean;
+
+interface PrdBlock {
+    slug: string;
+    markdown: string;
+}
+/**
+ * Detect a full markdown PRD in a planner message. The markers are the only
+ * structured artifact left in the conversation loop — they exist so the PRD
+ * can be saved to disk, not to drive any state machine.
+ */
+declare function extractPrdBlock(text: string): PrdBlock | null;
+/** Kebab-case, path-safe feature slug. */
+declare function sanitizeSlug(raw: string): string;
+/** Save the PRD to `<workspace>/.scratch/<slug>/PRD.md` (to-prd native convention). */
+declare function savePrdMarkdown(workspace: string, slug: string, markdown: string): string;
+
+export { ALL_PROVIDERS, AUTO_COMMANDS, AbstractRunner, AbstractTerminalSession, ActiveTaskSession, type AgentAdapter, type AgentAdapterFactory, type AgentEvent, type AgentProcessDeps, type AgentStartOptions, AiProvider, ApprovalKind, ApprovalMode, ApprovalRequest, ApprovalSource, BaseAiService, BaseConfig, BaseFileSystem, CLAUDE_CODE_MANIFEST, CLI_PROVIDERS, CMD_EXE_MAX_COMMAND_LINE, CORE_PLANNER_PROMPT, type CappedRows, type CheckpointListener, ClaudeCodeAdapter, CliAgentAiService, type CliAgentAiServiceDeps, CodexAdapter, type CommandClassification, CommandLineTooLongError, type CommandTier, ConsoleLogger, ContextCollector, ConversationMessage, type ConversationRequest, type ConversationTurn, DiscoveredModel, EmbeddedNewlineError, EnvConfig, type ExecFileFn, type ExecImpl, FindSymbolOptions, FsPluginStore, GIT_READONLY_SUBCOMMANDS, GeminiService, GlobOptions, type GrepInvocation, GrepOptions, HeadlessRunner, type HeadlessRunnerDeps, type IAiService, IApproval, IConfig, IFileSystem, type ILogger, type INotification, IPluginStore, ITerminalRunner, ITerminalSession, JSON_REPAIR_INSTRUCTION, type KillTreeDeps, type LaunchDeps, type LaunchPlan, LegacyPlanState, LineBuffer, type MappedTool, ModelResolver, type ModelResolverDeps, type ModifyPlanRequest, type NotificationAction, OPENCODE_MANIFEST, OpenAiService, OpenCodeAdapter, type OrchestratorObserver, OrchestratorOption, PROVIDER_DETECT_PRIORITY, PROVIDER_LABEL, PROVIDER_PRIORITY, PROVIDER_SHORT_LABEL, type PendingApproval, PendingApprovals, type PendingApprovalsOptions, PlanParseError, type PlanRequest, PlanState, PlanStatus, PlanStore, Planner, type PlannerReplyClassification, type PlannerRuntimeToggles, type PrdBlock, type ProbeFn, ProviderModelLists, type ProviderRegistration, QueuedMessage, REFUSED_COMMANDS, ReadFileOpts, type RepairLoopOpts, type RepairVerdict, type ResearchChat, ResearchLogEntry, ResearchProgress, type ResearchShell, type ResearchShellDeps, ResearchStep, ResearchToolType, type ResearchTurn, ResolveContext, type RunnerCatalog, RunnerId, RunnerInstallation, RunnerInvocation, type RunnerMode, RunnerModeInfo, RunnerPluginManifest, RunnerRegistry, STATE_DIR, SYMBOL_LANGUAGES, type SerializedPlan, type SerializedTask, type SerializedTaskStatus, Session, type SessionBroadcaster, type SessionData, type SessionDeps, type SessionMessage, type SessionMeta, type SessionPlanner, type SessionRuntimeSettings, SettingsService, type ShellDialect, type SpawnSpec, StdioAgentAdapter, TRUNCATED_PLAN_REPAIR_INSTRUCTION, Task, TaskOp, TaskOrchestrator, TaskSnapshot, TmuxRunner, type TmuxRunnerDeps, type ToolCall, ToolOutcome, type ToolResult, type UserSettings, Verdict, VerdictEngine, type VerdictListener, WINDOWS_MAX_COMMAND_LINE, applyHeadLimit, augmentedPath, buildConversationSystemPrompt, buildFallbackGrepArgs, buildGlobArgs, buildGrepArgs, buildMergePrompt, buildModifyDuringExecutionPrompt, buildModifyPlanPrompt, buildPlanWithResults, buildResearchPrompt, buildResearchToolsPrompt, buildRunnerInvocation, buildShellInvocation, buildSplitPrompt, buildSubagentSystemPrompt, clampThinkingEffort, classifyCommand, classifyPlannerReply, clearAugmentedPathCache, clearResearchShellCache, clearState, coerceAssignments, configuredProviders, createAiService, defaultLogger, definitionPattern, deleteSession, discoverGeminiModels, effectiveAllowlist, ensureDir, executionLogBlock, executionSummary, extractPrdBlock, filterFallbackByAnchoredInclude, filterModelsForPrompt, formatSearchOutput, generatePlanWithRepair, getLatestSession, getProviderMeta, getSettingsPath, getStateDir, grantScopeFor, hasTmux, includeGlobFor, isCliProvider, isOpenAiProvider, killTree, languageForId, listSessions, loadSession, loadSessionPlanState, loadState, mapAgentTool, modelContextBlock, modifyValidationFeedback, normalizeAgentArgs, normalizeGeminiModel, pendingEditRulesBlock, planDirectLaunch, planShellLaunch, posixShellQuote, prefixModelId, providerForRunner, reEmitPlanPrompt, reEmitTaskOpsPrompt, referencePattern, repairLoop, researchShellWarning, researchToolsPath, resolveArgs, resolveProviderFromPrefix, resolveResearchShell, resolveWithin, retargetTaskRunner, runnerAssignment, runnerForProvider, sanitizeSlug, savePrdMarkdown, saveSession, saveState, serializePlan, serializeTask, serializeTaskStatus, sessionRuntimeSettings, stateExists, stripAnsi, stripModelPrefix, taskOpsRejectedPrompt, tmuxSessionName, tmuxSocketName, tmuxWindowName, truncatedPlanReEmitPrompt, wellKnownBinDirs, windowsCommandLine, withPath, wrapWithPty };