@buildaharness/aielia 0.3.4 → 0.3.6

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

@@ -4,9 +4,24 @@ 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 { AgentLoop, ToolLoopResult } from './agent-loop.js';
+import { AssistantToolStep } from './tool-step.js';
 import { TraceEvent } from './trace-events.js';
 import { DebugLogEntry } from './debug-log.js';
+/**
+ * Optional hooks for resuming a staged action that a flat tool loop paused on (see
+ * AgentLoop.resumeToolLoop): the live token/tool-step callbacks of the turn being resumed, and how
+ * to turn a *further* pause (another approval, or an escalation) into the turn result — the caller
+ * owns that because auto-approve modes live there, not here.
+ */
+export interface ResumeOptions {
+    onToken?: (token: string) => void;
+    onToolStep?: (step: AssistantToolStep) => void;
+    handleLoopPause?: (result: Extract<ToolLoopResult, {
+        kind: 'needs_approval' | 'escalated';
+    }>) => Promise<AssistantTurnResult>;
+}
+export { actionRecordSuffix } from './action-record.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
@@ -25,8 +40,25 @@ export declare class ActionApprovalService {
     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);
+    /** Every write, command and email carried out through an approval, in order (a turn's slice is what the system recorded for it). */
+    readonly appliedActions: string[];
+    /** Parallel to appliedActions (same indices): for a write, the lines it changed as a short diff, so the reply audit can tell whether a reply's account of the file is true (W1); the same clause as appliedActions for every other kind. */
+    readonly appliedActionDetails: string[];
+    /** The command and the start/end of the output of each shell command run through an approval (for the reply audit). */
+    readonly recentCommandOutputs: {
+        command: string;
+        output: string;
+    }[];
+    /** Sessions in which a command got the network-containment refusal. */
+    private readonly networkDeniedSessions;
+    /** Pending-action ids currently being resolved (see resolvePendingAction). */
+    private readonly inFlightResolutions;
+    networkDenied(sessionId: string): boolean;
     /** 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>;
+    resolvePendingAction(sessionId: string, transcriptKey: string, pendingActionId: string, approved: boolean, userMessage: string, resume?: ResumeOptions): Promise<AssistantTurnResult>;
+    private resolvePendingActionOnce;
+    /** The conversation before the current user message, for the no-tools synthesis call. The current message was already appended to the transcript when the turn paused, so it is dropped here. */
+    private recentHistory;
     /**
      * 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

package/dist/action-record.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The "[Recorded by the system ...]" action list. Only the system writes it, into the stored transcript, from the
+ * approved actions it really carried out. The model sees it in earlier stored replies and was observed imitating it
+ * (benchmark scenarios 05 and 13: a reply listed a test file and writes that never happened), which makes a false
+ * claim look like a system record. Anything shaped like the marker in model-written text is therefore removed.
+ */
+export declare const ACTION_RECORD_MARKER = "[Recorded by the system, not part of the reply";
+export declare function actionRecordSuffix(actions: string[]): string;
+export declare function containsActionRecord(text: string): boolean;
+/** Removes every block that starts at the marker and runs to its closing bracket, with the blank lines before it. */
+export declare function stripActionRecord(text: string): string;
+/** Shown in place of a forged record, so the user knows why the list is gone. */
+export declare const FORGED_ACTION_RECORD_NOTE = "[Note from the system: the reply listed actions as \"recorded by the system\", but the system recorded no such action this turn, so the list was removed.]";

package/dist/activity-log.d.ts

@@ -0,0 +1,4 @@
+import { DebugLogEntry } from './debug-log.js';
+export declare function activityLogEnabled(env: NodeJS.ProcessEnv): boolean;
+/** Returns an `onDebugLog` callback appending `{at, sessionId, kind, content}` lines to `filePath`. Never throws. */
+export declare function createActivityLogger(filePath: string, now?: () => Date): (entry: DebugLogEntry) => void;

package/dist/agent-loop.d.ts

@@ -1,5 +1,5 @@
 import { ToolExecutorContext, HarnessPauseSignal, InvestigationRequestData, InvestigationFinding } from '@buildaharness/harness';
-import { MemoryAdapter, ILLMClient, ChatMessage, TokenUsage, ToolDefinition, ReminderStore } from '@buildaharness/runtime';
+import { MemoryAdapter, ILLMClient, ChatMessage, ToolCallResult, TokenUsage, ToolDefinition, ReminderStore } from '@buildaharness/runtime';
 import { AssistantSource } from './assistant-source.js';
 import { DebugLogEntry } from './debug-log.js';
 import { TraceEvent } from './trace-events.js';
@@ -10,7 +10,9 @@ 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 { DigestReader } from './recall-tool.js';
 import { AssistantToolStep } from './tool-step.js';
+import { EscalationPlan } from './layer-policy-wiring.js';
 export type ToolLoopResult = {
     kind: 'final';
     content: string;
@@ -21,10 +23,54 @@ export type ToolLoopResult = {
     reason: string;
     pendingActionId: string;
     pendingActionKind: 'write' | 'shell' | 'email' | 'batch';
+    resume?: StagedCallResume;
 } | {
     kind: 'escalated';
     reason: string;
 };
+/**
+ * Set on a needs_approval result when the pause came from a tool call this loop dispatched itself
+ * (a proxy-backend `write_file`/`run_shell_command`/`send_email` call): the exact call the model
+ * made, so the loop can be continued once the staged action resolves instead of ending the turn.
+ * Absent for a pause whose call lives inside a backend's own agentic loop (claude-cli's
+ * `__staged_action`) — there is no message history to continue from.
+ */
+export interface StagedCallResume {
+    toolCall: ToolCallResult;
+    assistantContent: string;
+}
+/**
+ * Persisted under `loop-pending:<pendingActionId>` while a flat tool loop waits on an approval, so
+ * an approved action's result can be folded back into the same conversation (see
+ * AgentLoop.resumeToolLoop). `messages` is everything sent to the model so far, system prompt
+ * included, *excluding* the assistant message holding the staged call (rebuilt on resume).
+ */
+export interface ToolLoopPendingState {
+    sessionId: string;
+    userMessage: string;
+    riskHint: TurnIntentClassification['riskLevel'];
+    messages: ChatMessage[];
+    sources: AssistantSource[];
+    iterationsUsed: number;
+    toolCall: ToolCallResult;
+    assistantContent: string;
+    /** Approved actions already carried out earlier in this same turn (see describeAppliedAction) — recorded in the transcript with the turn's final reply so later turns know what was done. */
+    actions?: string[];
+}
+/** Sent when the model returns an empty final answer, before the one retry. */
+/** For a reply that held only a line shaped like the system's action record: the actions it listed were not run, so unlike the blank-reply nudge this one sends the model back to its tools. */
+export declare const RECORD_ONLY_REPLY_NUDGE = "Your last reply held only a line shaped like the system's action record, no answer, and the system ran nothing it listed. Do what the user asked now with your tools if it is still wanted, then reply in plain text with what you did and found. Never write a \"Recorded by the system\" line yourself.";
+export declare const EMPTY_REPLY_NUDGE = "Your last reply was empty. This check is automatic and is not from the user. Answer the user's message now in plain text: if you did work this turn, say what you did and what you found; if the message needs no work, just answer it. Do not call a tool unless something is still unfinished.";
+/** The nudge with the user's message quoted, so the model answers that message and not the nudge (benchmark scenario 12 turn 1: told to "summarize", it answered a summary request the user never made). */
+export declare function withUserMessage(nudge: string, userMessage: string): string;
+/** Sent when a turn used all its tool steps, before the one tool-less summary call. */
+export declare const OUT_OF_STEPS_NUDGE = "You have used all the tool steps available for this turn. Reply now in plain text: say what you did, what worked, and what is still unfinished. Do not call any tool.";
+/**
+ * The reply used when the model returns nothing twice in a row: built only from what is on record, so the user
+ * never gets an empty message. `actions` is the turn's list of carried-out approved actions (see describeAppliedAction).
+ */
+export declare function fallbackFinalReply(actions: string[] | undefined): string;
+export declare const toolLoopPendingKey: (pendingActionId: string) => string;
 /**
  * R2 of the internal plan: thrown by a harness-driven proposer
  * (createHarnessProposer, below) when runToolIterationStep produces a 'needs_approval' or
@@ -133,13 +179,6 @@ export interface BatchBudgetTrace {
  * 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;
@@ -204,6 +243,19 @@ export declare class AgentLoop {
          * caller-constraint output contract.
          */
         takeSteeringNotes?: () => string[];
+        /**
+         * Plan steps: the instruction to give the model when the harness starts working on `taskId`, or
+         * undefined for a task that is just "answer the user's message" (every ordinary turn). Sent once per
+         * task; the step's final answer is then kept in the conversation so a later step can build on it.
+         */
+        stepInstruction?: (taskId: string) => string | undefined;
+        /**
+         * True while the harness is running several subtasks that all stand for ONE answer to the user's
+         * message (an ordinary decomposed turn, not a plan). The first subtask to finish produces the answer;
+         * the rest reuse it instead of asking the model the same question again. A task the harness runs a
+         * second time (a retry after a rejection) gets a fresh call, never the answer that was rejected.
+         */
+        shareAnswer?: () => boolean;
     }): (toolCtx: ToolExecutorContext) => Promise<unknown>;
     /**
      * R3 of the internal plan: the wiring-level counterpart to
@@ -216,7 +268,7 @@ export declare class AgentLoop {
      * 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'], takeSteeringNotes?: () => string[]): {
+    createOneLoopProposer(sessionId: string, transcript: ChatMessage[], userMessage: string, systemPrompt: string, onToken?: (token: string) => void, onToolStep?: (step: AssistantToolStep) => void, onUsage?: (usage: TokenUsage) => void, riskHint?: TurnIntentClassification['riskLevel'], takeSteeringNotes?: () => string[], stepInstruction?: (taskId: string) => string | undefined, shareAnswer?: () => boolean): {
         proposer: (toolCtx: ToolExecutorContext) => Promise<unknown>;
         sources: AssistantSource[];
     };
@@ -266,6 +318,25 @@ export declare class AgentLoop {
      * 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>;
+    /** One last model call without tools after the step budget ran out; undefined if it fails or returns nothing. */
+    private summarizeWhenOutOfSteps;
+    /** Replaces an empty final answer (the model returned nothing twice) with fallbackFinalReply, shown through onToken like any answer. */
+    private withFallbackReply;
+    private flatLoopTools;
+    /**
+     * When the flat loop pauses on a staged call it dispatched itself, saves what is needed to keep
+     * going after the approval (see ToolLoopPendingState) and strips the in-memory `resume` handle
+     * from the result the caller sees. Any other result is returned untouched.
+     */
+    private persistPausedLoop;
+    /**
+     * Continues a flat tool loop that paused on an approval-gated call, after that call's staged
+     * action has been resolved: `toolResultText` (the command's output, a write confirmation, ...)
+     * goes back to the model as the tool result for the exact call it made, and the loop runs on —
+     * more reads, further approvals (which pause again and persist again), then a final answer —
+     * within whatever iteration budget the turn had left.
+     */
+    resumeToolLoop(state: ToolLoopPendingState, toolResultText: string, onToken?: (token: string) => void, onToolStep?: (step: AssistantToolStep) => void, onUsage?: (usage: TokenUsage) => void, actions?: string[] | undefined): 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
@@ -301,7 +372,21 @@ export declare class AgentLoop {
      * the result, since it's a plain accumulator shared by reference across every step call for
      * the same loop.
      */
+    /**
+     * The tool error for a write_file over an existing file the session has not read, or undefined when the write may go ahead (a new
+     * file, or one this session read or wrote). Benchmark scenario 13 turn 4: after a turn with no tool call at all, the model answered
+     * "fix that too" with a write_file that replaced `calculate_priority` with an invented function of a different signature, never having
+     * read the file. A write is a full replacement, so it has to be based on what the file really holds.
+     */
+    private unreadExistingFile;
     private runToolIterationStep;
+    /**
+     * A staging call (write_file / run_shell_command / send_email) was rejected before anything was staged — a path or
+     * cwd outside the workspace, a malformed recipient. The tool descriptions promise "rejected immediately": that is a
+     * tool error the model sees and can correct, exactly like a failed read, not an exception that ends the turn.
+     * Every tool call in the response gets a result (the provider requires one per call id).
+     */
+    private stagingRejected;
     /**
      * 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
@@ -355,6 +440,18 @@ export declare class AgentLoop {
      * 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.
      */
+    /** AL8b: optional policy gate for LLM injection detection; `undefined` (default) ⇒ always detect. */
+    injectionDetectionGate?: () => boolean;
+    /** Episodic digest source for `recall_memory` (M3); set by the assistant. The tool is offered only when this is set AND AUDIT_RECALL_TOOL is on. */
+    digestReader?: DigestReader;
+    /**
+     * Set by the assistant: whether this session has already read (or itself written) a workspace file. A write over an existing file
+     * that the session never read is refused (see unreadExistingFile), so the model cannot replace a file with contents it guessed.
+     */
+    sessionKnowsFile?: (sessionId: string, workspaceRelativePath: string) => boolean;
+    private recallTools;
+    /** The opt-in layers' plan for the turn in flight (adaptive mode only), set by the assistant each turn; see resolveOptInPlan. */
+    optInPlan?: EscalationPlan;
     private executeToolCall;
     /**
      * Trajectory Supervisor GATHER_EVIDENCE host (S5 of

package/dist/ambiguity-guard-flag.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Flag for the AL3a ambiguity guard — same shape as ask-mode-flag.ts (module-level default, value-level
+ * normalizer that warns on a typo, env resolver). 'disabled' (the default, AL-8) keeps every turn on the
+ * pre-AL3a routing byte-for-byte: an under-specified consequential request still reaches `needs_approval`
+ * with a guessed action. 'enabled' runs one bounded scope check (ambiguity-guard.ts) on consequential
+ * turns and answers with a clarifying question *before* anything is staged when the request does not
+ * determine the action.
+ */
+export type AmbiguityGuardMode = 'enabled' | 'disabled';
+export declare const DEFAULT_AMBIGUITY_GUARD_MODE: AmbiguityGuardMode;
+export declare function normalizeAmbiguityGuardMode(raw: string | undefined, varName?: string): AmbiguityGuardMode;
+export declare function resolveAmbiguityGuardMode(env: NodeJS.ProcessEnv): AmbiguityGuardMode;

package/dist/ambiguity-guard.d.ts

@@ -0,0 +1,20 @@
+import { ChatMessage, ILLMClient, TokenUsage } from '@buildaharness/runtime';
+/**
+ * AL3a — semantic pre-staging scope check. Root cause it addresses: the classifier gates a
+ * consequential request on *risk*, never on whether the request is *determinate*, and the tool loop
+ * stages whatever action the proposer guesses (write_file/run_shell_command stage unconditionally). So
+ * "Clear out the old ones." reached `needs_approval` with a guessed deletion — the approval prompt then
+ * authorizes a guess instead of resolving it. The system prompt's "ask when genuinely ambiguous" is
+ * advisory and the proposer ignores it once a tool is in reach.
+ *
+ * This is one bounded LLM call, made only on consequential turns and only when the guard flag is
+ * enabled — a semantic judgment, not a lexical gate (AL-2). It fails open to "not ambiguous": staging
+ * and the approval gate remain the safety net, so a failed check never blocks a clear request.
+ */
+export interface AmbiguityCheck {
+    ambiguous: boolean;
+    /** One concrete clarifying question; only meaningful when `ambiguous`. */
+    question: string;
+}
+export declare function parseAmbiguityCheck(content: string): AmbiguityCheck | null;
+export declare function checkRequestAmbiguity(message: string, llmClient: ILLMClient, recentTranscript: ChatMessage[], model?: string, onUsage?: (usage: TokenUsage) => void): Promise<AmbiguityCheck>;

package/dist/answer-claim.d.ts

@@ -1,4 +1,5 @@
 import { Evidence, VerificationResult } from '@buildaharness/harness';
+import { GroundingResult } from './grounding-check.js';
 /**
  * Where the evidence backing a reply actually came from — 'tool_evidence' when at least one
  * real observation (a gather_evidence call, a real read_file/web_search result, ...) was
@@ -10,7 +11,9 @@ export type AnswerClaimSourceType = 'tool_evidence' | 'model_reasoning';
  * The four branches this plan's Validation section names explicitly — each backed by a real,
  * mechanically-derived signal (see buildAnswerClaim), never guessed from the reply text itself:
  * - 'verified': the verification layer found no critical failure and at least one layer
- *   actually PASSed (not just SKIPPED) against real evidence.
+ *   actually PASSed (not just SKIPPED) against real evidence — and, when the grounding check is
+ *   on, the reply itself was compared against the raw tool results and matched them. The
+ *   mechanical layers alone never look at the reply's content, so they cannot earn this.
  * - 'unverified_attempted': evidence was gathered, but no layer could independently confirm it
  *   (all SKIPPED/no tool to check with) — an honest "couldn't verify," not a fake PASS.
  * - 'contradicted': the Contradiction layer flagged a conflict with an existing belief this turn.
@@ -32,6 +35,8 @@ export interface AnswerClaim {
     freshness: string | null;
     source_type: AnswerClaimSourceType;
     verification_status: AnswerClaimVerificationStatus;
+    /** One sentence naming what in the reply didn't match the tool results — set only when the grounding check found a discrepancy. */
+    grounding_note?: string;
 }
 /**
  * Builds an AnswerClaim from one turn's real harness output. `verification` is the last
@@ -48,4 +53,11 @@ export declare function buildAnswerClaim(input: {
         strength: number;
         feasibility: number;
     };
+    /**
+     * The reply-vs-tool-results check (grounding-check.ts). `undefined` means the check is switched
+     * off (`AUDIT_SEMANTIC_GROUNDING`) and `verified` keeps its mechanical-only meaning; any
+     * `GroundingResult` — including `not_checked` — means the check is on, so `verified` requires
+     * `grounded`.
+     */
+    grounding?: GroundingResult;
 }): AnswerClaim;

package/dist/ask-clarification-service.d.ts

@@ -66,5 +66,16 @@ export declare class AskClarificationService {
      * back through `stageAndRespond` exactly like the first, via the same catch this resume goes
      * through.
      */
-    resolvePendingClarification(sessionId: string, transcriptKey: string, pendingClarificationId: string, response: AskResponse | undefined, askModeEnabled: boolean): Promise<AssistantTurnResult>;
+    resolvePendingClarification(sessionId: string, transcriptKey: string, pendingClarificationId: string, response: AskResponse | undefined, askModeEnabled: boolean, 
+    /**
+     * True when tool turns run through the one-loop proposer (the default). A resumed harness run has NO proposer, so it
+     * could only return the stored draft reply — empty for a tool turn, which is what the user got — and the answer,
+     * fed into the constraint pipeline, is never read by the proposer's model. In that mode the validated answer is
+     * handed to the ordinary turn pipeline instead (`{ fallThrough: true }`, the same shape a plan approval uses), and
+     * the paused run is discarded.
+     */
+    handOffToOrdinaryTurn?: boolean): Promise<AssistantTurnResult | {
+        fallThrough: true;
+        answerText: string;
+    }>;
 }

package/dist/ask-response-format.d.ts

@@ -5,4 +5,10 @@ import { AskQuestion, AskResponse } from '@buildaharness/harness';
  * resolution (P8, continuing a plan draft), both of which fold the user's answer into a plain-text
  * follow-up message for their own "next call" rather than duplicating this formatting logic.
  */
+/**
+ * The user-visible text of a batch of structured questions: each question, then its numbered options. Used for the
+ * debug log (a `needs_clarification` turn has `reply: null`, so its log line used to read "(no reply)") and by the
+ * eval arm, so the transcript a judge reads carries what the user was actually asked.
+ */
+export declare function formatAskQuestions(questions: AskQuestion[]): string;
 export declare function formatAskResponse(questions: AskQuestion[], response: AskResponse): string;

package/dist/assistant-session.d.ts

@@ -64,6 +64,13 @@ export declare class AssistantSession {
     private readonly notifiedContradictions;
     constructor(memory: MemoryAdapter, checkpointStore: CheckpointStore, spendCap: SpendCapConfig | undefined, model: () => string | undefined, fileTools: FileToolsContext | undefined, shellTools: ShellToolsContext | undefined, actionTools: ActionToolsContext | undefined);
     private static notifiedContradictionsKey;
+    private static standingConstraintsKey;
+    /** Constraints the user stated earlier in this session ("Do not use tabs") — they govern later turns too. */
+    getStandingConstraints(sessionId: string): Promise<string[]>;
+    /** Drops the standing constraints at these 1-based positions (as shown to the classifier); returns what remains. */
+    liftStandingConstraints(sessionId: string, positions: readonly number[]): Promise<string[]>;
+    /** Adds constraints stated this turn to the session's standing list; returns the merged list. */
+    recordStandingConstraints(sessionId: string, stated: readonly string[]): Promise<string[]>;
     getNotifiedContradictions(sessionId: string): Promise<Set<string>>;
     recordNotifiedContradiction(sessionId: string, seen: Set<string>, value: string): Promise<void>;
     /** findContradictionNotice's own text, deduped once per session — see notifiedContradictions'
@@ -98,7 +105,10 @@ export declare class AssistantSession {
      * already correctly no-ops whenever no cap is configured, so this never enforces a cap that
      * isn't set.
      */
+    /** Tail of the chain serialising recordSpend's read-modify-write: the background memory reviewer records spend while a turn does, and the later write used to drop the other's cost. */
+    private spendChain;
     recordSpend(sessionId: string, usage: TokenUsage | undefined): Promise<void>;
+    private recordSpendNow;
     /** Read-only — null means plan mode has never been entered (or was already exited/cancelled) for this session (or this `threadId`, once Phase 5's per-thread rescoping applies — see `planModeKey`). */
     getPlanModeState(sessionId: string, threadId?: string): Promise<PlanModeState | null>;
     /**
@@ -120,7 +130,11 @@ export declare class AssistantSession {
      * (rather than the sequencer reading `memory` directly) so this remains the one place that reads
      * `transcript:${sessionId}` for a live turn.
      */
-    loadAndCompactTranscript(sessionId: string): Promise<ChatMessage[]>;
+    loadAndCompactTranscript(sessionId: string, 
+    /** AUDIT_SEMANTIC_COMPACTION: summarizes the older messages instead of truncating them (semantic-compaction.ts). */
+    summarize?: (older: ChatMessage[]) => Promise<string | null>, 
+    /** AUDIT_EPISODIC_DIGEST: called with exactly the messages about to be dropped, before they are (M3 pre-compaction flush). Fail-open: a throw never blocks compaction. */
+    flush?: (older: ChatMessage[]) => Promise<unknown>): Promise<ChatMessage[]>;
     /**
      * Appends `message` to `transcriptKey`'s array — every site that used to call
      * `this.memory.set(transcriptKey, message, 'append')` directly now goes through here instead, so
@@ -129,9 +143,25 @@ export declare class AssistantSession {
      * caught and logged, never thrown — a search-indexing problem must never be able to break an
      * ordinary turn or lose the transcript message itself.
      */
-    appendTranscriptMessage(sessionId: string, transcriptKey: string, message: {
+    /**
+     * A message the user sent while a turn was running that the turn's model call already took into account
+     * (a mid-turn steering note). It belongs in the conversation as its own user message, in order: held here
+     * and written just before the next assistant message, i.e. after the running turn's own user message and
+     * before the reply it shaped. Without this the note vanished from the transcript.
+     */
+    recordAbsorbedSteering(sessionId: string, message: string): void;
+    private readonly absorbedSteering;
+    /**
+     * Called by ResponseService the moment a turn's final reply is stored, before the slower post-reply work
+     * (fact recording, goal evidence, grounding check) that still has to finish inside the turn. The assistant uses it
+     * to put the reply in the activity log right away (benchmark issue N2).
+     */
+    replyReadyHook?: (sessionId: string, reply: string) => void;
+    replyReady(sessionId: string, reply: string): void;
+    appendTranscriptMessage(sessionId: string, transcriptKey: string, input: {
         role: 'user' | 'assistant';
         content: string;
+        actionRecord?: string[];
     }): Promise<void>;
     /**
      * One-off, idempotent backfill for installs that already had transcript history before the

package/dist/assistant-source.d.ts

@@ -11,4 +11,11 @@
 export interface AssistantSource {
     tool: 'read_file' | 'list_directory' | 'web_search' | 'fetch_url';
     path: string;
+    /**
+     * The (truncated) raw text the tool returned — what the answer-claim grounding check compares the reply against
+     * (grounding-check.ts). Internal only: ResponseService strips it before a source reaches AssistantTurnResult, so it
+     * never lands in a transcript, a trace or the UI. Absent when the result text isn't visible to the parent process
+     * (claude-cli runs the tool loop inside its own subprocess).
+     */
+    excerpt?: string;
 }

package/dist/assistant-types.d.ts

@@ -1,5 +1,5 @@
 import { NextStepSuggestion } from './next-step-proposer.js';
-import { RiskState, LayerActivityEvent, AskQuestion } from '@buildaharness/harness';
+import { RiskState, LayerActivityEvent, AskQuestion, TaskStatus } from '@buildaharness/harness';
 import { TokenUsage } from '@buildaharness/runtime';
 import { AnswerClaim } from './answer-claim.js';
 import { TurnIntentClassification } from './turn-intent-classifier.js';
@@ -62,7 +62,7 @@ export interface AssistantTurnResult {
      * passes through this exactly once, regardless of risk (no risk-tiered skip — see
      * PlanApprovalService's doc comment).
      */
-    status: 'ok' | 'needs_approval' | 'escalated' | 'needs_clarification' | 'needs_plan_approval';
+    status: 'ok' | 'needs_approval' | 'escalated' | 'needs_clarification' | 'needs_plan_approval' | 'cancelled';
     reply: string | null;
     /**
      * Up to three concrete next steps proposed after a full (non-trivial, `ok`) turn, most confident
@@ -101,10 +101,15 @@ export interface AssistantTurnResult {
         templateName: string | null;
         successCriteria: string;
         completionPct: number;
+        /** `note`: why a FAILED task did not count as done (set only by the semantic task-completion check). */
         tasks: {
             id: string;
             description: string;
             status: string;
+            note?: string;
+            dependsOn?: string[];
+            cancelled?: boolean;
+            riskLevel?: 'LOW' | 'MEDIUM' | 'HIGH';
         }[];
     };
     /**
@@ -117,6 +122,10 @@ export interface AssistantTurnResult {
     usage?: TokenUsage;
     /** Set when the Contradiction layer flagged a conflict with an existing belief this turn — see assistant-session.ts's findContradictionNotice doc comment for why this is a separate field instead of folded into `reply`. */
     contradictionNotice?: string;
+    /** Set when the semantic change reviewer found the request conflicts with something the user stated earlier AND the answer could not be told so directly (a tool-less turn's draft already exists, so the proposer never reads the review note). Advisory only — the turn still completed. Mirrors `contradictionNotice`: a separate field, not folded into `reply`, because the CLI streams `reply` before the check runs. */
+    reviewNotice?: string;
+    /** Set when the reply audit (reply-audit.ts) found a claim of work the system did not record, a promise of work not done, or unverified facts about outside sources. Separate from `reply` for the same reason as `reviewNotice`. */
+    auditNotice?: string;
     /**
      * An epistemic-honesty signal for replies that went through the harness loop (absent on the
      * triviality fast path, same "absent when unused" convention as trace/sources — a
@@ -163,4 +172,13 @@ export interface AssistantProgress {
     currentNode?: string;
     /** Live, mid-run position within a durable plan — set only while a plan is actually driving this turn. Absent for an ad hoc single-task/decomposed turn, same "absent when unused" convention as AssistantTurnResult.planStatus. */
     planPosition?: PlanPosition;
+    /**
+     * Live per-task statuses of the plan driving this turn, for the plan graph view. Present only while a
+     * plan drives the turn (same "absent when unused" convention as `planPosition`). Granularity is per
+     * harness checkpoint (once per task), not per token: it changes when a task starts or finishes.
+     */
+    planTasks?: {
+        id: string;
+        status: TaskStatus;
+    }[];
 }