@buildaharness/aielia 0.3.0

package/dist/action-approval-service.d.ts

@@ -0,0 +1,52 @@
+import { ILLMClient, MemoryAdapter } from '@buildaharness/runtime';
+import { FileToolsContext } from './file-tools.js';
+import { ShellToolsContext } from './shell-tools.js';
+import { ActionToolsContext } from './action-tools.js';
+import { AssistantTurnResult } from './assistant-types.js';
+import { AssistantSession } from './assistant-session.js';
+import { AgentLoop } from './agent-loop.js';
+import { TraceEvent } from './trace-events.js';
+import { DebugLogEntry } from './debug-log.js';
+/**
+ * Owns the "approval-by-ID" pattern: a staged write/shell/revert/batch-research action resolved
+ * by ID, never re-derived from a second LLM call (see T4 of the file-tools plan). Split out in
+ * Phase 4d of the architecture remediation plan — do not change this behavior when relocating it,
+ * only where the code lives.
+ */
+export declare class ActionApprovalService {
+    private readonly memory;
+    private readonly llmClient;
+    private readonly model;
+    private readonly fileTools;
+    private readonly shellTools;
+    private readonly actionTools;
+    private readonly session;
+    private readonly agentLoop;
+    private readonly onTrace;
+    private readonly onDebugLog;
+    constructor(memory: MemoryAdapter, llmClient: ILLMClient, model: () => string | undefined, fileTools: FileToolsContext | undefined, shellTools: ShellToolsContext | undefined, actionTools: ActionToolsContext | undefined, session: AssistantSession, agentLoop: AgentLoop, onTrace: ((event: TraceEvent) => void) | undefined, onDebugLog: ((entry: DebugLogEntry) => void) | undefined);
+    /** Resumes a staged action by ID instead of re-deriving *what to run* from a second LLM call — see T4 of the file-tools plan. `userMessage` is only used to synthesize an answer from a shell command's real output (see below); the command/content actually applied always comes from the staged record, never from a fresh model call. */
+    resolvePendingAction(sessionId: string, transcriptKey: string, pendingActionId: string, approved: boolean, userMessage: string): Promise<AssistantTurnResult>;
+    /**
+     * After resolvePendingAction resolves one staged action (approved or declined), checks whether
+     * it was chained to a second approval-gated action staged from the same originating turn (see
+     * file-tools-mcp-server.mjs's stagePendingAction doc comment — e.g. a single "run X AND write
+     * Y" request). Without this, the second action sat in `.pending-actions/` forever: never
+     * surfaced for approval, never executed, never even mentioned as still pending.
+     * `previousOutcome` (the reply text already computed for the just-resolved action) is folded
+     * into the next prompt's `reason` so cli.ts's recursive needs_approval → handleTurn flow reads
+     * as one continuous exchange rather than jumping straight to an unexplained second question.
+     * Returns undefined if the linked record is missing or of a kind that's never legitimately
+     * chained ('revert', staged only by /undo-action, alone) — a broken link must never crash the
+     * turn, just stop chaining and fall back to the caller's own `status: 'ok'`.
+     */
+    private loadChainedApproval;
+    /**
+     * Resolves a batch confirmation pause (see AgentLoop.runBatchToolLoop's confirmation gate)
+     * once the caller resumes via `turn(message, { approved, pendingActionId })`. Declining
+     * resolves the turn immediately with only the probed items' real results, explicitly listing
+     * every unprobed item as not attempted. Approving continues resolving the remaining items with
+     * zero re-probing — the probe results loaded from `batchState` are reused as-is.
+     */
+    private resolvePendingBatchConfirmation;
+}

package/dist/action-snapshot.d.ts

@@ -0,0 +1,173 @@
+import { FsBackend } from '@buildaharness/runtime';
+export type UndoLogEntry = {
+    id: string;
+    appliedActionId: string;
+    kind: 'write';
+    path: string;
+    previousContent: string | null;
+    appliedAt: string;
+    undoable: true;
+} | {
+    id: string;
+    appliedActionId: string;
+    kind: 'write';
+    path: string;
+    appliedAt: string;
+    undoable: false;
+    reason: string;
+} | {
+    id: string;
+    appliedActionId: string;
+    kind: 'shell';
+    command: string;
+    appliedAt: string;
+    undoable: true;
+    added: string[];
+    modified: {
+        path: string;
+        previousContent: string;
+    }[];
+    deleted: {
+        path: string;
+        previousContent: string;
+    }[];
+    unsnapshottableChanges: string[];
+} | {
+    id: string;
+    appliedActionId: string;
+    kind: 'shell';
+    command: string;
+    appliedAt: string;
+    undoable: false;
+    reason: string;
+};
+export type SnapshotBeforeWriteResult = {
+    previousContent: string | null;
+    undoable: true;
+} | {
+    previousContent?: undefined;
+    undoable: false;
+    reason: string;
+};
+/**
+ * Reads a write_file target's current content before it gets overwritten, so an undo-log entry
+ * can later restore it. `path` must already be resolved/verified against the workspace root by
+ * the caller (file-tools.ts's applyPendingAction) — this does no path validation of its own.
+ * `workspaceRoot` is accepted for signature parity with T2's snapshotWorkspaceTree, which does
+ * need it for a recursive walk; a single-file read has no use for it.
+ *
+ * A read error other than "file doesn't exist" (FsBackend.readTextFile resolves `undefined` only
+ * for that case) is intentionally left to propagate rather than caught here, so a genuine I/O
+ * failure surfaces as a failed approval instead of silently producing a wrong/empty snapshot.
+ */
+export declare function snapshotBeforeWrite(backend: FsBackend, workspaceRoot: string, path: string): Promise<SnapshotBeforeWriteResult>;
+/** One shared cap across every entry kind (write, and later shell/revert) — not a per-kind cap. */
+export declare const UNDO_LOG_MAX_ENTRIES = 20;
+/**
+ * Persists an undo-log entry, then prunes the oldest entries once UNDO_LOG_MAX_ENTRIES is
+ * exceeded — mirrors the "cap it, don't let it grow forever" convention already used elsewhere
+ * in this package (e.g. the batch-budget plan's ABSOLUTE_TURN_CEILING).
+ */
+export declare function recordUndoLogEntry(backend: FsBackend, workspaceRoot: string, entry: UndoLogEntry): Promise<void>;
+export declare function loadUndoLogEntry(backend: FsBackend, workspaceRoot: string, id: string): Promise<UndoLogEntry | undefined>;
+/** Newest first (by appliedAt) — feeds /undo-action's no-argument listing view (T3). */
+export declare function listUndoLogEntries(backend: FsBackend, workspaceRoot: string): Promise<UndoLogEntry[]>;
+export declare function deleteUndoLogEntry(backend: FsBackend, workspaceRoot: string, id: string): Promise<void>;
+/** Per-file cap — a file over this size is reported as skipped, never partially captured. */
+export declare const UNDO_SNAPSHOT_MAX_FILE_BYTES = 1000000;
+/** Overall file-count ceiling for one walk — hitting it truncates the whole snapshot (see
+ * WorkspaceSnapshot.truncated), not just the files past the ceiling, since a walk that stops
+ * partway through gives no reliable picture of "everything else is unchanged" either. */
+export declare const UNDO_SNAPSHOT_MAX_FILES = 2000;
+/**
+ * Directory names skipped by default during a workspace walk — this feature's own bookkeeping
+ * plus conventionally-heavy, rarely-hand-edited directories. Without this, a walk would blow
+ * UNDO_SNAPSHOT_MAX_FILES on node_modules/ alone for any real npm-monorepo workspace.
+ */
+export declare const UNDO_SNAPSHOT_EXCLUDED_DIRS: string[];
+export interface WorkspaceSnapshot {
+    files: Map<string, string>;
+    skipped: {
+        path: string;
+        reason: string;
+        size?: number;
+    }[];
+    truncated: boolean;
+    truncationReason?: string;
+    /**
+     * Deviation from the plan's summary interface (which lists only files/skipped/truncated/
+     * truncationReason): a cheap, non-recursive immediate-child-name listing taken once per
+     * excluded directory encountered, keyed by that directory's path. Excluded directories are
+     * never walked into (that's the whole point — see UNDO_SNAPSHOT_EXCLUDED_DIRS's doc comment),
+     * so there is no per-file record of their contents to diff. This one-level signature is the
+     * cheapest available signal that lets diffSnapshots notice "something was added to or removed
+     * from node_modules/ directly" without paying to walk its full subtree. It's necessarily
+     * best-effort — a content-only change to a file already inside an excluded directory, or a
+     * change nested more than one level deep inside it, isn't detected by this signature alone.
+     */
+    excludedDirSignatures: Map<string, string>;
+}
+/**
+ * Recursively snapshots every text file under `workspaceRoot`, for diffing before/after a
+ * run_shell_command execution (T2 step 6) since a shell command has no single known target path
+ * the way write_file does. Skips default-excluded directories, oversized files, and binary
+ * files (see the exported constants above) rather than either blowing past a sane cost ceiling
+ * or silently corrupting a binary file via a lossy UTF-8 round-trip.
+ *
+ * Requires `backend.stat` (optional on FsBackend — only backends doing a recursive walk need
+ * it). A backend without it can't distinguish a file from a directory, so this returns
+ * immediately with `truncated: true` rather than attempting an unreliable walk.
+ */
+export declare function snapshotWorkspaceTree(backend: FsBackend, workspaceRoot: string): Promise<WorkspaceSnapshot>;
+export interface WorkspaceDiff {
+    added: string[];
+    modified: {
+        path: string;
+        previousContent: string;
+    }[];
+    deleted: {
+        path: string;
+        previousContent: string;
+    }[];
+    unsnapshottableChanges: string[];
+}
+/**
+ * Diffs two workspace snapshots taken before/after a shell command ran. Only the actual diff is
+ * meant to be persisted to an undo-log entry, not two full tree copies.
+ */
+export declare function diffSnapshots(before: WorkspaceSnapshot, after: WorkspaceSnapshot): WorkspaceDiff;
+/**
+ * Builds the undo-log entry for a completed run_shell_command approval from its before/after
+ * workspace snapshots (T2 step 7).
+ *
+ * Deviation / judgment call: step 7's prose says a non-empty `unsnapshottableChanges` escalates
+ * the whole entry to `undoable: false`, but the Files tab's own type-level doc comment on the
+ * `undoable: true` shell variant says the opposite ("non-empty here still means undoable: true
+ * for the paths that WERE captured"), and the Test Plan tab's cases for node_modules-only and
+ * binary-file changes describe the command "executing normally" with the change merely
+ * "reported in unsnapshottableChanges" — neither test expects undoable: false for those cases.
+ * Following the type comment and the Test Plan tab (the more precise, mutually-consistent
+ * sources) over the summary prose: only a *truncated* tree walk — meaning the before/after
+ * picture itself is unreliable, not just a subset of paths within it — escalates to
+ * `undoable: false`. A non-empty `unsnapshottableChanges` on an otherwise-complete walk keeps
+ * `undoable: true`, offering a partial revert for the paths that were captured, with the
+ * incompleteness surfaced on the entry for a later /undo-action to warn about (T3).
+ */
+export declare function buildShellUndoLogEntry(appliedActionId: string, command: string, before: WorkspaceSnapshot, after: WorkspaceSnapshot): UndoLogEntry;
+/**
+ * The concrete filesystem operations a revert needs to perform, derived from one undo-log
+ * entry: every path in `restore` gets its `content` written back; every path in `remove` gets
+ * deleted (it didn't exist, or wasn't created, before the original action ran). Kept as its own
+ * plain-data shape (rather than handing the raw UndoLogEntry to applyPendingAction) so the
+ * staged `kind: 'revert'` PendingActionPayload carries exactly what it needs to apply, the same
+ * way `kind: 'write'`/`kind: 'shell'` already carry their own complete, self-sufficient payload.
+ */
+export interface RevertPlan {
+    restore: {
+        path: string;
+        content: string;
+    }[];
+    remove: string[];
+}
+/** `undefined` when `entry.undoable` is false — an undoable:false entry has nothing to revert. */
+export declare function buildRevertPlan(entry: UndoLogEntry): RevertPlan | undefined;

package/dist/action-tools.d.ts

@@ -0,0 +1,38 @@
+import { FsBackend, ToolDefinition } from '@buildaharness/runtime';
+import { SendEmail } from './email.js';
+export declare const SEND_EMAIL_TOOL: ToolDefinition;
+export declare const ACTION_TOOLS: ToolDefinition[];
+/** Everything executeActionTool needs to validate + stage a proposal — no delivery capability required. */
+export interface ActionStagingContext {
+    backend: FsBackend;
+    workspaceRoot: string;
+}
+/**
+ * Everything PersonalAssistant needs to both stage and, once approved, actually deliver an effect
+ * action. `sendEmail` is the injected transport (email.ts's createResendSender / email-smtp.ts's
+ * createSmtpSender) — required, not optional, for the same reason ShellToolsContext.executeCommand
+ * is: assistant.ts/index.ts is bundled into the browser build and must never import a transport
+ * directly, so a Node caller (cli.ts) wires the real one in.
+ */
+export interface ActionToolsContext extends ActionStagingContext {
+    sendEmail: SendEmail;
+}
+export type ActionToolResult = {
+    kind: 'staged_email';
+    id: string;
+    to: string;
+    subject: string;
+    body: string;
+    cc?: string;
+    bcc?: string;
+};
+export declare class InvalidEmailArgsError extends Error {
+    constructor(detail: string);
+}
+/**
+ * Executes send_email by name. Never delivers anything itself — only stages, exactly like
+ * write_file / run_shell_command. Validation (recipient address shape) runs unconditionally on the
+ * call's own concrete arguments, independent of whatever risk-classifier.ts concluded about the
+ * user's phrasing — see stagePendingAction's doc comment in file-tools.ts.
+ */
+export declare function executeActionTool(ctx: ActionStagingContext, toolName: string, input: Record<string, unknown>): Promise<ActionToolResult>;

package/dist/agent-loop.d.ts

@@ -0,0 +1,372 @@
+import { ToolExecutorContext, HarnessPauseSignal, InvestigationRequestData, InvestigationFinding } from '@buildaharness/harness';
+import { MemoryAdapter, ILLMClient, ChatMessage, TokenUsage, ToolDefinition, ReminderStore } from '@buildaharness/runtime';
+import { AssistantSource } from './assistant-source.js';
+import { DebugLogEntry } from './debug-log.js';
+import { TraceEvent } from './trace-events.js';
+import { TurnIntentClassification, RiskLevel } from './turn-intent-classifier.js';
+import { evaluateToolPolicy } from './tool-policy.js';
+import { TurnControlPlaneState } from './tool-control-plane.js';
+import { FileToolsContext } from './file-tools.js';
+import { WebToolsContext } from './web-tools.js';
+import { ShellToolsContext } from './shell-tools.js';
+import { ActionToolsContext } from './action-tools.js';
+import { AssistantToolStep } from './tool-step.js';
+export type ToolLoopResult = {
+    kind: 'final';
+    content: string;
+    sources: AssistantSource[];
+    batchBudget?: BatchBudgetTrace;
+} | {
+    kind: 'needs_approval';
+    reason: string;
+    pendingActionId: string;
+    pendingActionKind: 'write' | 'shell' | 'email' | 'batch';
+} | {
+    kind: 'escalated';
+    reason: string;
+};
+/**
+ * R2 of plans/harness_d2_one_loop_rewire_plan.html: thrown by a harness-driven proposer
+ * (createHarnessProposer, below) when runToolIterationStep produces a 'needs_approval' or
+ * 'escalated' ToolLoopResult — the harness's own execute() rethrows anything satisfying
+ * isHarnessPauseSignal unexamined (no SYSTEM_ERROR evidence, no task-FAILED transition), so this
+ * is never misclassified as a tool failure. Carries the original ToolLoopResult so the eventual
+ * catcher (assistant.ts's runTurn, alongside its existing `catch (err) { if (err instanceof
+ * EscalationHalt) ... }` branch — see R3) can build the exact same needs_approval/escalated
+ * AssistantTurnResult it already builds from a flag-OFF ToolLoopResult, without re-deriving it.
+ */
+export declare class OneLoopPause extends Error implements HarnessPauseSignal {
+    readonly result: Extract<ToolLoopResult, {
+        kind: 'needs_approval' | 'escalated';
+    }>;
+    /**
+     * P10 of plans/ask_question_and_plan_mode_plan.html: the plan task (if any) that was RUNNING
+     * — i.e. whichever task `execute()` was calling this proposer for — when `result` was
+     * produced, threaded from `ToolExecutorContext.currentTaskId`. Lets the catcher
+     * (assistant.ts's `buildToolLoopPauseResult`) check INV-36's trust condition without
+     * re-deriving "which task was this" from anything else. `undefined` for the batch proposer's
+     * own confirmation-gate throw (not a write/shell/email action, so trust mode never applies to
+     * it) and for any pre-P10 construction.
+     */
+    readonly currentTaskId?: string | undefined;
+    readonly __harnessPause: true;
+    constructor(result: Extract<ToolLoopResult, {
+        kind: 'needs_approval' | 'escalated';
+    }>, 
+    /**
+     * P10 of plans/ask_question_and_plan_mode_plan.html: the plan task (if any) that was RUNNING
+     * — i.e. whichever task `execute()` was calling this proposer for — when `result` was
+     * produced, threaded from `ToolExecutorContext.currentTaskId`. Lets the catcher
+     * (assistant.ts's `buildToolLoopPauseResult`) check INV-36's trust condition without
+     * re-deriving "which task was this" from anything else. `undefined` for the batch proposer's
+     * own confirmation-gate throw (not a write/shell/email action, so trust mode never applies to
+     * it) and for any pre-P10 construction.
+     */
+    currentTaskId?: string | undefined);
+}
+/** Per-item calibration inputs — see nextItemBudget. */
+export interface BatchBudgetState {
+    callsPerItemHistory: number[];
+    perItemFloor: number;
+    slackFactor: number;
+    absoluteTurnCeiling: number;
+}
+/**
+ * Drops one min and one max before averaging once there are enough samples for that to be
+ * meaningful (fewer than 3 just averages plain) — so a single unusually cheap or expensive item
+ * can't swing the projection to either extreme on its own.
+ */
+export declare function trimmedAverage(counts: number[]): number;
+/** Budget for the next item to resolve — floored so a suspiciously cheap item can't starve the
+ * rest, with slack headroom on top of the calibrated average. */
+export declare function nextItemBudget(state: BatchBudgetState): number;
+/**
+ * One batch item's outcome from its own per-item sub-loop (see resolveBatchItem). `exhausted`
+ * means the sub-loop ran out of its budget without the model producing a final answer for this
+ * item. `status` distinguishes *why* a non-'found' outcome happened: 'not_found' covers both the
+ * item-scoped dead-end window tripping early (BATCH_DEAD_END_WINDOW consecutive dead_end tool
+ * results) and a needs_approval bail-out; 'truncated_while_productive' means the budget ran out
+ * while the trailing window was still turning up plausibly-relevant content.
+ */
+export interface BatchItemResolution {
+    item: string;
+    content: string;
+    callsUsed: number;
+    exhausted: boolean;
+    status: 'found' | 'not_found' | 'truncated_while_productive';
+    sources: AssistantSource[];
+}
+/**
+ * Persisted across the confirmation round trip (see runBatchToolLoop's confirmation gate and
+ * ActionApprovalService.resolvePendingBatchConfirmation) so approving resumes with the probe
+ * items' real results intact instead of re-probing them, and declining can still return those
+ * real results instead of discarding them.
+ */
+export interface BatchPendingState {
+    userMessage: string;
+    systemPrompt: string;
+    sessionId: string;
+    probedResults: BatchItemResolution[];
+    remainingItems: string[];
+    /** The projection computed at the confirmation gate — carried across the round trip so the
+     * resume/decline paths can report the same number in the batch trace instead of re-deriving
+     * it (or leaving it absent) after the fact. */
+    projectedTotal: number;
+}
+/**
+ * Present only when the batch-research path (batch-list-detector.ts / runBatchToolLoop) drove
+ * this turn — absent otherwise, same "absent when unused" convention as sources/usage. Turns
+ * `should we raise the ceiling/floor/slack factor` from a guess into a measurement.
+ */
+export interface BatchBudgetTrace {
+    itemCount: number;
+    callsPerItemHistory: number[];
+    projectedTotal: number;
+    totalCallsUsed: number;
+    perItemOutcomes: {
+        item: string;
+        status: 'found' | 'not_found' | 'truncated_while_productive';
+        callsUsed: number;
+    }[];
+}
+/** Builds a batch trace from a batch turn's resolved items — shared by runBatchToolLoop's direct
+ * path and both resolvePendingBatchConfirmation outcomes (see ActionApprovalService). */
+export declare function buildBatchBudgetTrace(itemCount: number, projectedTotal: number, resolutions: BatchItemResolution[]): BatchBudgetTrace;
+export declare function looksLikeUnparsedToolCall(content: string): boolean;
+/**
+ * Bounded ReAct loop plus the batch-research sub-loop — the "actually call the model and its
+ * tools" half of PersonalAssistant, split out in Phase 4d of the architecture remediation plan.
+ * Owns tool-control-plane enforcement (checkToolPolicy, below) as part of the same loop it gates,
+ * per Phase 4's design: a deterministic, harness-state-informed check before each call executes,
+ * not just advisory classification checked after the fact.
+ */
+export declare class AgentLoop {
+    private readonly memory;
+    private readonly llmClient;
+    private readonly model;
+    private readonly fileTools;
+    private readonly webTools;
+    private readonly shellTools;
+    private readonly actionTools;
+    private readonly reminderStore;
+    private readonly maxSteps;
+    private readonly onTrace;
+    private readonly onDebugLog;
+    constructor(memory: MemoryAdapter, llmClient: ILLMClient, model: () => string | undefined, fileTools: FileToolsContext | undefined, webTools: WebToolsContext | undefined, shellTools: ShellToolsContext | undefined, actionTools: ActionToolsContext | undefined, reminderStore: ReminderStore, maxSteps: number, onTrace: ((event: TraceEvent) => void) | undefined, onDebugLog: ((entry: DebugLogEntry) => void) | undefined);
+    /**
+     * Phase 4c: builds one fresh, turn-scoped live ControlState (tool-control-plane.ts), seeded
+     * with the same tool-name list runToolLoop/resolveBatchItem already build internally — kept
+     * here rather than in the sequencer (assistant.ts) so the caller never needs to re-import
+     * FILE_TOOLS/WEB_TOOLS/SHELL_TOOLS/REMINDER_TOOLS just to construct this; AgentLoop already
+     * privately owns which tools are configured. Call once per turn (when a tool loop will run)
+     * and thread the result through runToolLoop/runBatchToolLoop so it's shared across every tool
+     * call the turn makes, including across batch items.
+     */
+    createControlPlaneState(): TurnControlPlaneState;
+    /**
+     * R2 of plans/harness_d2_one_loop_rewire_plan.html: builds the real toolExecutors['default']
+     * entry HarnessBridge.run() swaps in when the one-loop flag is enabled — a proposer that calls
+     * runToolIterationStep once per driveMainLoop iteration and translates its discriminated result
+     * into the primitives D0/D1 already built: a plain return (status 'continue', no output yet) for
+     * `{ done: false }`, the final answer text for a `{ done: true, result: { kind: 'final' } }`
+     * step, or a thrown OneLoopPause for `needs_approval`/`escalated` — never a thrown plain Error,
+     * so execute() never misclassifies this as a tool failure.
+     *
+     * Control-plane state: the proposer holds one real, turn-scoped `TurnControlPlaneState`
+     * (`createControlPlaneState`, the exact object the flag-OFF flat path threads through
+     * `runToolLoop`) for its whole lifetime — so `runToolIterationStep`'s `recordToolOutcome` has
+     * real evidence/worldModel/diagnostics/failureDiagnostics stores to write each dispatched call's
+     * outcome into, and same-turn tool-failure-pattern gating behaves identically to flag-OFF. On
+     * top of that, the harness's own live per-iteration `toolCtx.controlState` is pinned onto that
+     * state at the start of every iteration as the gate's floor (D2's "one composition, not two"
+     * intent): a harness DENY / HUMAN_REQUIRED escalation is honored by `checkToolPolicy` before the
+     * iteration's first call executes. `recordToolOutcome` re-resolves `.controlState` from the
+     * turn-local stores after each recorded outcome — that only ever escalates further (8+ same-turn
+     * failures) and `evaluateToolPolicy` ignores `execution_mode`, so it never downgrades a harness
+     * escalation that would have mattered.
+     */
+    createHarnessProposer(input: {
+        messages: ChatMessage[];
+        tools: ToolDefinition[];
+        sessionId: string;
+        userMessage: string;
+        maxIterations: number;
+        sources: AssistantSource[];
+        onToken?: (token: string) => void;
+        onToolStep?: (step: AssistantToolStep) => void;
+        onUsage?: (usage: TokenUsage) => void;
+        riskHint?: TurnIntentClassification['riskLevel'];
+    }): (toolCtx: ToolExecutorContext) => Promise<unknown>;
+    /**
+     * R3 of plans/harness_d2_one_loop_rewire_plan.html: the wiring-level counterpart to
+     * `createHarnessProposer` above — builds the same `messages`/`tools` shape `runToolLoop` builds
+     * (system prompt + transcript + user message; whichever of FILE_TOOLS/WEB_TOOLS/SHELL_TOOLS/
+     * ACTION_TOOLS/REMINDER_TOOLS are configured) so `assistant.ts`'s `runTurn` doesn't need to
+     * duplicate that list-building just to wire the flag-ON path, and caps iterations at
+     * `this.maxSteps` — the same cap `runToolLoop` applies — rather than something the caller has to
+     * choose. Returns the mutable `sources` array threaded into the proposer so the caller can read
+     * back whatever got pushed to it once the harness run using this proposer has finished (mirrors
+     * `ToolLoopResult`'s `sources` field on the flag-OFF path).
+     */
+    createOneLoopProposer(sessionId: string, transcript: ChatMessage[], userMessage: string, systemPrompt: string, onToken?: (token: string) => void, onToolStep?: (step: AssistantToolStep) => void, onUsage?: (usage: TokenUsage) => void, riskHint?: TurnIntentClassification['riskLevel']): {
+        proposer: (toolCtx: ToolExecutorContext) => Promise<unknown>;
+        sources: AssistantSource[];
+    };
+    /**
+     * R4 of plans/harness_d2_one_loop_rewire_plan.html: the batch-research counterpart to
+     * `createOneLoopProposer` above — routes `runBatchToolLoop`'s probe → calibrate → confirm-gate
+     * → resolve-remaining → synthesize sequence through the same harness-driven proposer mechanism,
+     * instead of batch research remaining a second code path that (per R3) never reached the
+     * harness regardless of the flag. Reuses `resolveBatchItem`/`resolveRemainingBatchItems`/
+     * `synthesizeBatchReply` verbatim — the exact same methods the flag-OFF path calls — so the
+     * dead-end window (local `toolYields`, scoped inside `resolveBatchItem`) and the calibrated
+     * per-item budget (`resolveRemainingBatchItems`'s own `Budget`/`nextItemBudget` logic) keep
+     * bounding a hard item's spend identically; nothing here reimplements that math.
+     *
+     * The closure advances through three phases, one per `driveMainLoop` iteration (i.e. one
+     * `__harnessExecutionStatus: 'continue'` per phase transition) rather than one per underlying
+     * tool call the way the flat proposer does: 'probe' (resolve every probe item, calibrate, and
+     * either throw a `needs_approval` OneLoopPause — mirroring `runBatchToolLoop`'s own confirmation
+     * gate, including persisting the same `BatchPendingState` so the existing, flag-independent
+     * `resolvePendingBatchConfirmation` resume path needs no changes — or fall through), 'resolve'
+     * (resolve every remaining item in one `resolveRemainingBatchItems` call), and 'synthesize'
+     * (stream the final reply via `synthesizeBatchReply`, preserving its existing token-by-token
+     * `onToken` semantics, then return `'complete'`). This is coarser-grained resumability than the
+     * flat proposer's per-tool-call steps — a deliberate scope decision (see this phase's
+     * implementation note) rather than reimplementing `resolveRemainingBatchItems`'s calibration
+     * loop one item at a time just to get finer-grained checkpoints.
+     */
+    createBatchOneLoopProposer(items: string[], sessionId: string, userMessage: string, systemPrompt: string, onToken?: (token: string) => void, onToolStep?: (step: AssistantToolStep) => void, onUsage?: (usage: TokenUsage) => void): {
+        proposer: (toolCtx: ToolExecutorContext) => Promise<unknown>;
+        sources: AssistantSource[];
+        getBatchBudget: () => BatchBudgetTrace | undefined;
+    };
+    /**
+     * Phase 4/4c: the deterministic, harness-state-informed authority for whether `toolName` may
+     * proceed — see tool-policy.ts. `controlState` is the live, per-turn ControlState built by
+     * tool-control-plane.ts and threaded down from runTurn (see createTurnControlPlaneState);
+     * `undefined` at the very first tool call of a turn (nothing recorded yet — the pre-evidence
+     * baseline tool-policy.ts's own doc comment describes) or for a caller that never wired one in.
+     */
+    private checkToolPolicy;
+    /**
+     * Bounded ReAct loop: calls callChatStructured with whichever of file/web/shell/reminder
+     * tools are configured, executing real (non-mutating) tool calls and looping, until
+     * either a final text reply comes back, a write_file/run_shell_command call needs
+     * staging + approval, or the iteration cap is hit. Only ever invoked when `fileTools`,
+     * `webTools`, or `shellTools` is configured (reminder tools ride along whenever any of
+     * those does, since `reminderStore` always exists).
+     */
+    runToolLoop(sessionId: string, transcript: ChatMessage[], userMessage: string, systemPrompt: string, onToken?: (token: string) => void, onToolStep?: (step: AssistantToolStep) => void, onUsage?: (usage: TokenUsage) => void, riskHint?: TurnIntentClassification['riskLevel'], controlPlaneState?: TurnControlPlaneState): Promise<ToolLoopResult>;
+    /**
+     * The actual ReAct-style tool-calling loop, factored out of runToolLoop so a batch sub-loop
+     * (resolveBatchItem, below) can run the exact same iteration logic — including the
+     * looksLikeUnparsedToolCall retry guard and write/shell staging — scoped to its own message
+     * history and its own (usually much smaller) iteration budget, instead of duplicating it.
+     * `maxIterations` replaces runToolLoop's former direct use of `this.maxSteps`; passing
+     * `this.maxSteps` here reproduces that method's exact prior behavior unchanged.
+     *
+     * `onToolResult`, when provided, is called after every tool result is folded into `messages`
+     * and may return `'stop'` to end the loop immediately (see resolveBatchItem's item-scoped
+     * dead-end window) — a caller that never passes it (runToolLoop, the flat non-batch path)
+     * gets today's unmodified behavior: the loop only ever ends via a final answer, an
+     * needs_approval bail-out, or maxIterations.
+     *
+     * Thin wrapper (R1 of the D2 one-loop-rewire follow-up plan) around
+     * `runToolIterationStep`, which does one iteration's worth of work and returns a discriminated
+     * `done`/`not done` result — the shape a harness-driven `driveMainLoop` can call once per its
+     * own iteration (R2), instead of only ever being driven by this method's own `for` loop.
+     */
+    private runToolIterations;
+    /**
+     * One iteration's worth of `runToolIterations`' ReAct loop, extracted (R1 of the D2
+     * one-loop-rewire follow-up plan, `plans/harness_d2_one_loop_rewire_plan.html`) so a
+     * harness-driven proposer (R2) can call this directly, once per `driveMainLoop` iteration,
+     * instead of only ever being driven by `runToolIterations`' own `for` loop. Preserves every
+     * early-return branch of the original loop body exactly — the unparsed-tool-call retry,
+     * `__staged_action` adoption, write/shell/email staging, cached-shell replay, per-call
+     * `tool-policy.ts` DENY/REQUIRE_APPROVAL, and the `onToolResult` dead-end-window stop — as a
+     * `{ done: true, result }` return; the two cases that used to `continue` the outer `for` loop
+     * (the unparsed-tool-call retry and a cached-shell replay) become `{ done: false, ... }`
+     * instead, with `dispatchedAnyToolCall` threaded back to the caller since it must persist
+     * across iterations. `sources` is mutated in place (pushed to) rather than threaded through
+     * the result, since it's a plain accumulator shared by reference across every step call for
+     * the same loop.
+     */
+    private runToolIterationStep;
+    /**
+     * Resolves one batch item in its own bounded sub-loop — structurally the same
+     * runToolIterations call the flat loop uses, just seeded with a single-item-focused user
+     * message and a per-item budget instead of the whole conversation and `this.maxSteps`.
+     *
+     * The dead-end window (`toolYields`) is a local array, created fresh on every call to this
+     * method — never shared across items: a hard item that trips BATCH_DEAD_END_WINDOW
+     * consecutive dead_end results only stops *this* item's sub-loop early (rather than spending
+     * the rest of its budget on a dead page) and can never poison an easier item queued behind it.
+     */
+    private resolveBatchItem;
+    /**
+     * Resolves every item in `remainingItems` in its own sub-loop, recalibrating the per-item
+     * budget after each one via nextItemBudget instead of freezing it at the initial probe
+     * average, and stopping once the running total hits BATCH_ABSOLUTE_TURN_CEILING regardless of
+     * how favorable calibration still looks. Returns every resolution so far (probed + newly
+     * resolved) plus the names of any items never attempted because the ceiling was hit first.
+     * Public — also called by ActionApprovalService.resolvePendingBatchConfirmation on the
+     * approved-continuation path.
+     */
+    resolveRemainingBatchItems(probedResults: BatchItemResolution[], remainingItems: string[], systemPrompt: string, sessionId: string, onToolStep?: (step: AssistantToolStep) => void, onUsage?: (usage: TokenUsage) => void, controlPlaneState?: TurnControlPlaneState): Promise<{
+        resolutions: BatchItemResolution[];
+        notAttempted: string[];
+    }>;
+    /**
+     * Synthesizes one final reply from every item's per-item findings — same shape as the flat
+     * loop's own final-answer call, just seeded with structured per-item results instead of raw
+     * tool-call history for every item at once.
+     *
+     * Any item in `notAttempted` (the absolute ceiling was hit before it was ever reached) is
+     * appended as a deterministic, guaranteed-present list rather than left to the synthesis
+     * call's prose — an LLM asked to "write one well-organized reply" over many items can drop one
+     * from its summary the same way it can drop one from a longer todo list; the per-item
+     * `resolutions` themselves stay inside the model's synthesis (their found/not_found/
+     * truncated_while_productive wording is already baked into `content` by resolveBatchItem, so
+     * the model has no need to invent that part), but which items were never even attempted this
+     * turn is a plain fact, not something worth trusting to how well the model followed
+     * instructions. Public — also called by ActionApprovalService.
+     */
+    synthesizeBatchReply(userMessage: string, systemPrompt: string, resolutions: BatchItemResolution[], notAttempted: string[], onToken?: (token: string) => void, onUsage?: (usage: TokenUsage) => void): Promise<string>;
+    /**
+     * Gated entry point for the batch-research path: probes the first 1-2 items (keeping at least
+     * one item unprobed so a single sample can't swing the whole projection), calibrates a
+     * per-item budget off their real cost, and either pauses for confirmation (a large projection)
+     * or resolves every remaining item and synthesizes the final reply.
+     */
+    runBatchToolLoop(items: string[], sessionId: string, userMessage: string, systemPrompt: string, onToken?: (token: string) => void, onToolStep?: (step: AssistantToolStep) => void, onUsage?: (usage: TokenUsage) => void, controlPlaneState?: TurnControlPlaneState): Promise<ToolLoopResult>;
+    /**
+     * Dispatches one tool call by name to its executor. web_search/fetch_url results
+     * are wrapped as untrusted external content (and flagged if they look like an
+     * injection attempt) before they ever reach the model — file and reminder results
+     * are not, since they're the assistant's own workspace/state, not adversarial input.
+     */
+    private executeToolCall;
+    /**
+     * Trajectory Supervisor GATHER_EVIDENCE host (S5 of
+     * plans/harness_trajectory_supervisor_plan.html). A bounded, strictly read-only tool
+     * loop the harness calls (via HarnessRunOptions.runInvestigation) when the supervisor
+     * decides the run is stuck for lack of a fact.
+     *
+     * - Read-only only: suggested_tools is filtered through validateInvestigationTools()
+     *   (INV-23) and then further to the subset this loop knows how to invoke from just a
+     *   question string. write_file / run_shell_command / send_email are never in the
+     *   allowlist and executeToolCall() has no branch for them here — no __staged_action
+     *   path is reachable.
+     * - Its own Budget (INV-25), independent of the turn's batch ceiling: maxCalls =
+     *   min(req.budget, allowed tools). Exhaustion returns whatever was found.
+     * - Every call is gated by the same evaluateToolPolicy() the manual dispatch loop uses;
+     *   a DENY / REQUIRE_APPROVAL skips that tool (an investigation never prompts).
+     * - Faults are isolated: a throwing / empty tool call is skipped, never propagated.
+     */
+    runSupervisorInvestigation(req: InvestigationRequestData, opts?: {
+        riskHint: RiskLevel;
+        controlState?: Parameters<typeof evaluateToolPolicy>[0]['controlState'];
+    }): Promise<InvestigationFinding[]>;
+}