@buildaharness/aielia 0.3.4 → 0.3.6

package/dist/recall-tool.d.ts

@@ -0,0 +1,43 @@
+import { ToolDefinition } from '@buildaharness/runtime';
+import { DigestStore, SessionDigest } from './episodic-digest.js';
+/**
+ * Phase M3 (agent_memory_framework_plan.html), recall half: a read-only `recall_memory` tool over
+ * the episodic digests. v1 is deliberately keyword-free (D2): with no argument it returns an INDEX
+ * of the most recent digests; with a digest id it returns that digest's text. The model decides
+ * which digest to open, so the semantic matching is the model's, not a scorer's.
+ *
+ * Flag: AUDIT_RECALL_TOOL, default OFF, read only in `recallToolEnabled()`.
+ *
+ * The digest writer and store live in episodic-digest.ts. `DigestReader` is the seam; production
+ * wraps the assistant's `DigestStore` (`storeDigestReader`). The id shown in the index is the
+ * digest id exactly as `listDigests` returns it (`<sessionId>:<conversationId>`, in `sessionId`).
+ */
+export interface DigestReader {
+    /** Most recent first, at most `limit`. */
+    list(limit: number): Promise<SessionDigest[]>;
+    get(id: string): Promise<SessionDigest | undefined>;
+}
+export declare const RECALL_INDEX_LIMIT = 20;
+export declare function recallToolEnabled(env?: Record<string, string | undefined>): boolean;
+export declare const RECALL_MEMORY_TOOL: ToolDefinition;
+export declare const RECALL_TOOLS: ToolDefinition[];
+/**
+ * Runs the tool. Never throws for a bad id or a reader failure — those come back as an
+ * `Error: ...` string (the loop's convention for a failed read), so the model sees them.
+ */
+export declare function executeRecallTool(reader: DigestReader, input: Record<string, unknown>): Promise<string>;
+/** Production reader: a thin adapter over the assistant's DigestStore (`memory.digests`). Retention is applied by the store. */
+export declare function storeDigestReader(store: Pick<DigestStore, 'listDigests' | 'getDigest'>): DigestReader;
+/** In-memory fake for tests; takes A's SessionDigest shape. */
+export declare class InMemoryDigestReader implements DigestReader {
+    private readonly digests;
+    constructor(digests?: SessionDigest[]);
+    list(limit: number): Promise<SessionDigest[]>;
+    get(id: string): Promise<SessionDigest | undefined>;
+}
+export declare const RECALL_POINTER_LINE = "\nEarlier sessions are summarised in memory. When the user asks what you worked on before, what was decided, or what the next step was, call the recall_memory tool (no arguments for an index, then an id to open a digest) and answer from it; the facts above are only part of what is recorded.";
+/**
+ * M3: the one-line pointer that tells the model the digests exist. Returned only when AUDIT_RECALL_TOOL is on AND at least one
+ * digest exists, so a flag-off or digest-less run has a byte-identical prompt. No per-turn judgement: a pointer, not content.
+ */
+export declare function recallPointerBlock(reader: Pick<DigestReader, 'list'> | undefined): Promise<string>;

package/dist/recovery-note.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The failure-mode recovery bias (packages/harness's rollback-replan.ts's failureModeHint) only
+ * changes bookkeeping — the chosen strategy is never read by any execution node, so nothing about
+ * what the proposer actually tries next changes on its own. This is what turns a confident
+ * failure-mode switch into something the proposer reads and can act on: a steering note under its
+ * own header, drained the same way review-checker.ts's REVIEW_NOTE_PREFIX notes are (see
+ * agent-loop.ts's createHarnessProposer).
+ */
+export declare const RECOVERY_NOTE_PREFIX = "[recovery] ";
+/**
+ * The proposer-facing steering note for a failure-mode-biased strategy switch — what the
+ * harness's own onFailureModeSwitch event turns into. Kept separate from reviewNoticeText's
+ * user-facing text (see AssistantTurnResult.reviewNotice): this note is for the model, not shown
+ * to the user directly.
+ */
+export declare function recoveryNoteText(failureClass: string, strategy: string): string;
+/**
+ * The proposer-facing note for a switch the experience-learning feed picked (AUDIT_EXPERIENCE_LEARNING): the same hint as a
+ * failure-mode switch, but it says why this approach — it is the one that worked after this kind of failure in earlier runs.
+ * `failureClass` is empty for a failure no curated pattern matched.
+ */
+export declare function learnedRecoveryNoteText(failureClass: string, strategy: string): string;

package/dist/reply-audit.d.ts

@@ -0,0 +1,67 @@
+import { ILLMClient, TokenUsage } from '@buildaharness/runtime';
+/**
+ * A reply can say things the turn did not do (benchmark scenarios 13, 15 and 10): "Done, I added the type hints"
+ * with no write behind it, "let me fix all of it" followed by nothing, or facts about a changelog the assistant
+ * never read because the network was unavailable. The reply is already on screen when this runs (it is streamed),
+ * so the result is a separate notice, like `reviewNotice`.
+ */
+export interface ReplyAuditInput {
+    userMessage: string;
+    reply: string;
+    /** What the system recorded as carried out this turn (write/shell/email), see describeAppliedAction. */
+    actions: string[];
+    /** Parallel to `actions`: for a write, what it changed (a short diff), so a reply's account of the file can be checked against it. */
+    actionDetails?: string[];
+    /** What it recorded in earlier turns of this session (most recent last), so restating old results is not mistaken for new work. */
+    earlierActions?: string[];
+    /** Recent shell commands with the start and end of their output (most recent last). */
+    recentCommandOutputs?: {
+        command: string;
+        output: string;
+    }[];
+    /** Files and pages the turn read (tool and target). */
+    sourcesRead: string[];
+    /** Files, directories and pages read in EARLIER turns of this session (most recent last): an answer about them is not an outside fact, and a statement about which tools were used must be checked against them too. */
+    earlierSourcesRead?: string[];
+    /** A command this session already got the network-containment refusal for. */
+    lookupUnavailable: boolean;
+}
+export interface ReplyAudit {
+    claimsUnrecordedWork: boolean;
+    promisesWorkNotDone: boolean;
+    unverifiedOutsideFacts: boolean;
+    contradictsCommandOutput: boolean;
+    /** The reply denies or contradicts what the system recorded: says it did not touch, run or use something that a recorded write, command or read shows it did (benchmark scenarios 12 and 08). */
+    contradictsRecordedWork: boolean;
+    /** The reply thinks aloud: it starts a statement, then corrects or retracts it inside the answer, instead of one clean answer (benchmark scenarios 08 and 14). */
+    leaksSelfCorrection: boolean;
+    /** The reply does not respond to the user's message at all: placeholder text, a stray JSON object, an unrelated topic (benchmark scenario 13 turn 3: the whole reply was `{"favorite_marble":"... the response ..."}`). */
+    nonAnswer: boolean;
+}
+export declare const CLEAN_AUDIT: Readonly<ReplyAudit>;
+/** Replies longer than this are never checked for being a non-answer: junk such as a stray JSON object or placeholder text is short, and the extra calls are not worth making for a long reply. */
+export declare const NON_ANSWER_CHECK_MAX_CHARS = 300;
+/**
+ * Two audit calls at once, and a third only when they disagree about a category: a category stands when at least two of the calls
+ * raise it. One sample of a classifier is noisy both ways: a false flag costs the user a pointless correction turn, a miss lets an
+ * invented claim stand (benchmark scenario 10 turn 2: the same reply was flagged by 6 of 8 production audits and passed by the
+ * rest). Asking the second call only after a flag made a miss on the first call final; asking both together also takes less time
+ * when the endpoint is slow. Fewer than two usable answers (an error or unparseable reply) returns a clean audit: a failed check
+ * must never flag a reply.
+ */
+export declare function auditReply(input: ReplyAuditInput, llmClient: ILLMClient, model?: string, onUsage?: (usage: TokenUsage) => void, options?: {
+    checkNonAnswer?: boolean;
+}): Promise<ReplyAudit>;
+/** The user-facing lines for what the audit found; undefined when it found nothing. */
+export declare function replyAuditNotice(audit: ReplyAudit, actions: string[]): string | undefined;
+/**
+ * `AIELIA_REPLY_AUDIT` gate. Default ON outside vitest (one extra bounded LLM call per successful turn); `0`/`false`/`off`/`no`/`disabled`
+ * turns it off. Same shape as `semanticGroundingEnabled()`.
+ */
+export declare function replyAuditEnabled(env?: Record<string, string | undefined>): boolean;
+/**
+ * The message for the one automatic retry, or undefined when the reply needs none. A claim or promise of work the system
+ * did not record asks for the work to be done now or the claim withdrawn; details that disagree with the command output
+ * or outside facts stated as verified ask for a corrected answer.
+ */
+export declare function auditRetryNudge(audit: ReplyAudit, recorded: string[], userMessage?: string): string | undefined;

package/dist/response-service.d.ts

@@ -1,5 +1,6 @@
 import { EscalationHalt, HarnessCheckpoint, VerificationResult, LayerActivityEvent, HarnessRunResult } from '@buildaharness/harness';
 import { MemoryAdapter, TokenUsage } from '@buildaharness/runtime';
+import { GroundingResult } from './grounding-check.js';
 import { TurnIntentClassification } from './turn-intent-classifier.js';
 import { PlanRecord } from './plan-store.js';
 import { PlanService } from './plan-service.js';
@@ -24,7 +25,12 @@ export declare class ResponseService {
     private readonly onTrace;
     private readonly memory?;
     private readonly nextStepProposer?;
-    constructor(memoryService: MemoryService, session: AssistantSession, planService: PlanService, onTrace: ((event: TraceEvent) => void) | undefined, memory?: MemoryAdapter | undefined, nextStepProposer?: ((thread: GoalThread, onUsage?: (usage: TokenUsage) => void) => Promise<ThreadSuggestion[]>) | undefined);
+    private readonly groundingChecker?;
+    constructor(memoryService: MemoryService, session: AssistantSession, planService: PlanService, onTrace: ((event: TraceEvent) => void) | undefined, memory?: MemoryAdapter | undefined, nextStepProposer?: ((thread: GoalThread, onUsage: ((usage: TokenUsage) => void) | undefined, sessionId: string) => Promise<ThreadSuggestion[]>) | undefined, groundingChecker?: ((input: {
+        question: string;
+        reply: string;
+        sources: AssistantSource[] | undefined;
+    }, onUsage: ((usage: TokenUsage) => void) | undefined) => Promise<GroundingResult>) | undefined);
     /**
      * INV-42's concrete mechanism: mirrors the `activePlan`-based `saveAndSummarize` sync just
      * above/below each call site, but onto `threadId`'s own `GoalThread.tasks` via
@@ -62,6 +68,8 @@ export declare class ResponseService {
         usageTotal: TokenUsage | undefined;
         onUsage?: (usage: TokenUsage) => void;
         goalThreadId?: string;
+        /** Task id → why the completion check judged it not done, from this run; persisted on the plan. */
+        taskNotes?: Record<string, string>;
     }): Promise<AssistantTurnResult>;
     buildSuccessResult(params: {
         sessionId: string;
@@ -78,6 +86,8 @@ export declare class ResponseService {
         usageTotal: TokenUsage | undefined;
         onUsage?: (usage: TokenUsage) => void;
         goalThreadId?: string;
+        /** Task id → why the completion check judged it not done, from this run; persisted on the plan. */
+        taskNotes?: Record<string, string>;
     }): Promise<AssistantTurnResult>;
     buildEscalatedResult(params: {
         sessionId: string;

package/dist/review-checker.d.ts

@@ -10,6 +10,10 @@ import { BeliefCandidate } from './contradiction-checker.js';
  * (contradiction-checker.ts).
  */
 export declare function semanticChangeReviewEnabled(env?: Record<string, string | undefined>): boolean;
+/** Marks a steering note as coming from the change reviewer rather than from the user — agent-loop.ts gives it its own header so the proposer isn't told the user said it. */
+export declare const REVIEW_NOTE_PREFIX = "[review] ";
+/** The user-facing line for a conflict the reviewer found — see AssistantTurnResult.reviewNotice. */
+export declare function reviewNoticeText(reasons: string[]): string;
 /**
  * One LLM call checking a proposed change against everything relevant at once (never one call
  * per belief/prediction) — layered on top of review-proposed-change.ts's lexical `isNegation`
@@ -19,10 +23,12 @@ export declare function semanticChangeReviewEnabled(env?: Record<string, string
  * which is why decomposition-classifier.ts and plan-builder.ts prompt task descriptions to lead
  * with their subject. A
  * paraphrased conflict ("we're dropping the login feature" vs. a belief that login is required)
- * slips past that phrase list entirely. Skipped when the change description itself reads like a
- * structured/technical (coding) action — see looksLikeCodingFact's doc comment for why that's
- * exactly the domain the lexical check already handles reasonably well; this is worth spending a
- * call on for a natural-language-shaped change instead. Falls back to "no conflict" on any parse
+ * slips past that phrase list entirely. It runs for every change, coding-shaped or not: it used to
+ * skip a description that looked like a coding action on the theory that the lexical check
+ * covers that domain, but that gate was a keyword list ("build", "test"…) that also matched
+ * ordinary requests ("Build the offsite catering plan…"), and the lexical checks are being rolled
+ * back — the semantic check must not depend on them. The host only wires this when there is a
+ * trusted fact or prediction to check against, which is what bounds its cost. Falls back to "no conflict" on any parse
  * failure or LLM error, matching this codebase's other LLM-backed classifiers — a missed conflict
  * costs nothing worse than the lexical-only behavior this is layered on top of.
  */

package/dist/reviewer-revision.d.ts

@@ -0,0 +1,23 @@
+import { ReviewerVerdict } from '@buildaharness/harness';
+/** Marks a proposer-facing note that carries a reviewer finding to revise the answer against (see AgentLoop.createHarnessProposer). */
+export declare const REVISION_NOTE_PREFIX = "[revision] ";
+/**
+ * `AUDIT_REVIEWER_REVISION` gate. Default **OFF**: the reviewer pass's verdict only feeds the resolver's next call, exactly as
+ * before. A truthy value (`1` / `true` / `on` / `yes` / `enabled`) lets a finding at the END of a run send the last answer back
+ * to the proposer once, with the finding in front of it. It also stops the implementer lens reporting the generic default
+ * criterion as "not covered" — which it does on nearly every turn, since no belief can ever state a meta-instruction. It changes
+ * what the assistant says and costs a second answer when it fires, so it ships off until a benchmark shows it helps. Read at
+ * one site: harness-bridge.ts.
+ */
+export declare function reviewerRevisionEnabled(env?: Record<string, string | undefined>): boolean;
+/** A success criterion a belief could state or paraphrase — everything except the generic "respond helpfully" default. */
+export declare function isCheckableCriterion(criterion: string): boolean;
+/**
+ * Which verdicts are worth a second answer. HIGH always (an unresolved contradiction, a contradicted high-reliability belief).
+ * MEDIUM only from the implementer lens — a real success criterion no belief covers at the end of the run. The reviewer and
+ * adversarial lens's MEDIUM findings ("most beliefs are low confidence", "high prior for a failure class") say something about the
+ * run's state, not about what the answer should say, so they are not acted on.
+ */
+export declare function reviewerRevisionNote(verdict: ReviewerVerdict): string | null;
+/** The user turn the proposer sees for a revision note (the note text without its prefix). */
+export declare function revisionContextMessage(noteBody: string): string;

package/dist/risk-classifier.d.ts

@@ -4,4 +4,11 @@ export interface RiskClassification {
     requiresApproval: boolean;
     reason: string;
 }
+/**
+ * The lexical risk judgment, gated by lexicalMode's `risk` family (off by default). Off → no judgment
+ * is made and the answer is the conservative one an unknown risk gets: HIGH, requiring approval. Its
+ * only production caller is a durable plan step persisted without its own risk level.
+ */
 export declare function classifyRisk(message: string): RiskClassification;
+/** The raw keyword judgment, never switched off — for test doubles standing in for the classifier model (scripted-llm-client.ts). */
+export declare function classifyRiskLexical(message: string): RiskClassification;

package/dist/scripted-llm-client.d.ts

@@ -11,10 +11,21 @@ import { ILLMClient, LLMStructuredResponse } from '@buildaharness/runtime';
  * answers on its own from a lightweight, deterministic default — so `responses` only has to
  * script the *tool loop / one-loop proposer's* own calls, not that bookkeeping call.
  *
- * `responses` entries are consumed in order, one per non-classifier `callChatStructured` call:
+ * `responses` entries are consumed in order, one per non-classifier, non-side-call
+ * `callChatStructured` call:
  *   - a plain `string` → `{ content: string }` (a final answer, no tool calls)
  *   - an `LLMStructuredResponse` → use as-is (set `toolCalls` to simulate the model calling a tool)
  *
+ * A handful of other calls are auxiliary semantic escalations (the change reviewer, the failure
+ * matcher, the LLM injection classifier) that a tool-using turn can trigger without any script
+ * author asking for them — with lexicalMode's default now `disabled`, the lexical checks these
+ * sit on top of never short-circuit them, so they fire on every qualifying call, not just ones a
+ * scenario is specifically testing. Answered from a safe, inert default (see SIDE_CALL_MARKERS)
+ * so they never silently consume a `responses` slot meant for the real tool loop — the exact
+ * silent-consumption bug that broke chat-ui's W5 proxy e2e test when the default flipped. Override
+ * or add to this list via `sideResponses` for a test that specifically wants one of these calls to
+ * answer something else (e.g. a genuine injection flag).
+ *
  * `callChat`/`callChatSync` (the no-tools reply path, and post-approval synthesis) stream
  * `streamChunks` (default: `['']`).
  */
@@ -29,7 +40,21 @@ export interface ScriptedLLMClientScript {
      * `undefined` to keep the derived default for that message.
      */
     classify?: (userMessage: string) => Record<string, unknown> | undefined;
+    /**
+     * Overrides/extends SIDE_CALL_MARKERS' default answers for a system-prompt substring — checked
+     * before the built-in defaults, so a test can make the change reviewer/failure matcher/injection
+     * classifier answer something other than "nothing to see here" without it consuming a
+     * `responses` slot either way. `[marker, rawJsonContent]` pairs, same shape as the built-ins.
+     */
+    sideResponses?: Array<[string, string]>;
 }
+/**
+ * Known auxiliary semantic-escalation system prompts and their safe, inert default answer — see
+ * ScriptedLLMClientScript's doc comment. Kept in sync by hand with each check's own system prompt
+ * (review-checker.ts, failure-mode-matcher.ts, trust-tagging.ts, grounding-check.ts, task-completion-check.ts, constraint-check.ts, semantic-compaction.ts, source-reliability.ts, semantic-hypotheses.ts, episodic-digest.ts, memory-consolidation.ts, memory-reviewer.ts) since there's no shared constant
+ * to import without a circular dependency back into this package's own public surface.
+ */
+export declare const SIDE_CALL_MARKERS: Array<[string, string]>;
 /**
  * Builds a scripted {@link ILLMClient}. See {@link ScriptedLLMClientScript}. The returned value
  * is a plain `ILLMClient` — pass it straight to `PersonalAssistant.create({ llmClient })`.

package/dist/semantic-compaction.d.ts

@@ -0,0 +1,15 @@
+import { ChatMessage, ILLMClient, TokenUsage } from '@buildaharness/runtime';
+/**
+ * `AUDIT_SEMANTIC_COMPACTION` gate. Default **OFF**: once a transcript is long, transcript-compaction.ts keeps the
+ * first 200 characters of each older message and nothing else, so a detail deep in an earlier message (a pasted
+ * document, a long answer) is gone from what the model sees — and the model has no tool to search the message index.
+ * On, ONE bounded call writes the summary instead (see summarizeOlderMessages); any failure falls back to the
+ * truncated form. Costs one call each time the thresholds trip. A truthy value (`1` / `true` / `on` / `yes` /
+ * `enabled`) enables it. Read at exactly one site: assistant.ts.
+ */
+export declare function semanticCompactionEnabled(env?: Record<string, string | undefined>): boolean;
+/**
+ * One bounded LLM call: the older messages of a long conversation, condensed with their specifics kept. Returns null
+ * — the caller then uses the truncated form — on any error, an empty or unparseable answer, or input too large.
+ */
+export declare function summarizeOlderMessages(older: ChatMessage[], llmClient: ILLMClient, model?: string, onUsage?: (usage: TokenUsage) => void): Promise<string | null>;

package/dist/semantic-hypotheses.d.ts

@@ -0,0 +1,40 @@
+import { ILLMClient, TokenUsage } from '@buildaharness/runtime';
+import { SemanticHypothesisProposal } from '@buildaharness/harness';
+/** Marks a proposer-facing note that carries competing explanations (see AgentLoop.createHarnessProposer). */
+export declare const HYPOTHESIS_NOTE_PREFIX = "[hypotheses] ";
+/**
+ * `AUDIT_SEMANTIC_HYPOTHESES` gate. Default **OFF**: hypotheses stay the template seeds the harness generates and
+ * nothing is shown to the model. A truthy value (`1` / `true` / `on` / `yes` / `enabled`) lets the harness ask, once
+ * per turn, for competing explanations of a request the classifier judged underdetermined, judge them against the
+ * evidence each execution gathers, and put them in front of the proposer. It changes what the assistant says, so it
+ * ships off until a benchmark shows it helps. Read at one site: harness-bridge.ts.
+ */
+export declare function semanticHypothesesEnabled(env?: Record<string, string | undefined>): boolean;
+/** One bounded LLM call: 2-4 competing explanations, or none. Fails open — any error or unusable answer is null. */
+export declare function proposeCompetingExplanations(input: {
+    request: string;
+    observations: string[];
+    beliefs: string[];
+}, llmClient: ILLMClient, model?: string, onUsage?: (usage: TokenUsage) => void): Promise<SemanticHypothesisProposal[] | null>;
+/** One bounded LLM call: which of the explanations do these observations rule out? Fails open — null. */
+export declare function judgeHypothesesAgainstEvidence(input: {
+    hypotheses: Array<{
+        id: string;
+        explanation: string;
+        predicted_observations: string[];
+    }>;
+    observations: string[];
+}, llmClient: ILLMClient, model?: string, onUsage?: (usage: TokenUsage) => void): Promise<{
+    contradicted: Array<{
+        id: string;
+        reason?: string;
+    }>;
+} | null>;
+/** The proposer-facing note: the competing explanations and what would tell them apart. */
+export declare function renderHypothesisNote(hypotheses: Array<{
+    explanation: string;
+    predicted_observations: string[];
+    separating_check?: string;
+}>): string;
+/** The user turn the proposer sees for a hypothesis note (the note text without its prefix). */
+export declare function hypothesisContextMessage(noteBody: string): string;

package/dist/side-call-policy.d.ts

@@ -0,0 +1,30 @@
+import { ILLMClient } from '@buildaharness/runtime';
+/**
+ * The small structured JSON calls a turn makes around its reply (risk classification, scope and goal-thread matching, the reply
+ * audit and its extra samples, next steps) are quick on a healthy endpoint, but a few simply never answer, and a turn waits on all of
+ * them: in the benchmark a finished-looking reply stayed busy for minutes and a queued message started late (scenarios 05, 06, 09, 10,
+ * 13, 15). Measured on the benchmark's model through OpenRouter with the real risk-classifier prompt (16 calls, 4 at a time): median
+ * 12 s, 75th percentile 27 s, 90th percentile 59 s, and one call that had not answered after 300 s. So a legitimate answer can take
+ * about a minute, and a fixed short bound kills those (a 45 s bound did: two turns of benchmark scenario 03 ended as "risk
+ * classification failed" and were never answered), while a long bound makes every hang cost minutes.
+ *
+ * So the call is hedged instead of cut off: when the first attempt has not answered after HEDGE_AFTER_MS a second identical attempt
+ * starts beside it, and whichever answers first is used. A slow answer is never discarded, a hung call costs about the hedge delay
+ * plus a normal response, and each attempt keeps its own hard bound. A failure waits for the other attempt if one is running; after that a
+ * transient one (a timeout, 408, 429, 5xx: benchmark scenarios 02, 08 and 10 each ended a classification on "The LLM proxy returned an error")
+ * gets one more attempt, while a refusal or a malformed answer would come back the same and is returned at once.
+ */
+export declare const SIDE_CALL_HEDGE_AFTER_MS = 25000;
+export declare const SIDE_CALL_TIMEOUT_MS = 120000;
+/** A failure worth one more attempt: a request that timed out, or an endpoint status that comes and goes (408, 429, any 5xx). A 4xx refusal or a bad answer is final. */
+export declare function isTransientFailure(err: unknown): boolean;
+export interface SideCallPolicyOptions {
+    /** Called once when a second attempt is started because the first has not answered yet. */
+    onHedge?: (info: {
+        afterMs: number;
+    }) => void;
+    /** Test hook: how long the first attempt gets before the second starts. */
+    hedgeAfterMs?: number;
+}
+/** Wraps a client so every structuredOutput call (never a main chat or tool-loop call) is hedged as described above. */
+export declare function withSideCallPolicy(client: ILLMClient, policy?: SideCallPolicyOptions): ILLMClient;

package/dist/source-reliability.d.ts

@@ -0,0 +1,71 @@
+import { ILLMClient, TokenUsage } from '@buildaharness/runtime';
+import { AssistantSource } from './assistant-source.js';
+export type SourceReliability = 'HIGH' | 'MEDIUM' | 'LOW';
+export interface SourceAssessment {
+    path: string;
+    reliability: SourceReliability;
+    reason: string;
+}
+export interface SourceWeighing {
+    assessments: SourceAssessment[];
+    /**
+     * `false` only when the sources materially disagree or differ in reliability AND the reply leans on a
+     * lower-reliability one, or presents them as equal without saying so. Everything else is `true`.
+     */
+    weighed: boolean;
+    /** One or two sentences telling the assistant how to weigh the sources — used only when `weighed` is false. */
+    note?: string;
+}
+/** Prefix of the evidence ids this module writes, so a reader can tell an assessment from a tool observation. */
+export declare const SOURCE_RELIABILITY_EVIDENCE_PREFIX = "source-reliability:";
+/**
+ * `AUDIT_SEMANTIC_SOURCE_RELIABILITY` gate. Default **OFF**: a turn's sources are never assessed and the
+ * reply is never revised, exactly as before. A truthy value (`1` / `true` / `on` / `yes` / `enabled`)
+ * turns on one bounded LLM call per multi-source turn, and one revision of an answer the call judged not to
+ * have weighed its sources. It changes what the assistant says, so it ships off until a benchmark shows it
+ * helps. Read at one site: `AgentLoop.createHarnessProposer`.
+ */
+export declare function sourceReliabilityEnabled(env?: Record<string, string | undefined>): boolean;
+/** The distinct read sources a turn used (a directory listing is not a source of facts). Deduplicated by tool + path. */
+export declare function distinctSources(sources: AssistantSource[]): AssistantSource[];
+/**
+ * One bounded LLM call over a turn that read two or more distinct sources. Fails open: fewer than two
+ * sources, no reply, an error or an unparseable response all return null, so a broken check can never
+ * change a reply that would have gone out today.
+ */
+export declare function assessSourceReliability(input: {
+    question: string;
+    sources: AssistantSource[];
+    reply: string;
+}, llmClient: ILLMClient, model?: string, onUsage?: (usage: TokenUsage) => void): Promise<SourceWeighing | null>;
+/** The minimal evidence-store surface this module writes to — both the harness's and the turn-local store satisfy it. */
+export interface EvidenceSink {
+    addObservation(evidence: {
+        id: string;
+        obs: string;
+        reliability: SourceReliability;
+        source: string;
+        evidence_type: 'OBSERVATION';
+        freshness: string;
+    }): void;
+}
+/**
+ * Records each assessment as an observation carrying the assessed reliability. Written straight to the
+ * store's `observations` — deliberately NOT through updateWorldModel: a LOW belief weighs 0 in
+ * `belief_health.support`, which could push a run into the resolver's Tier 2 DENY for a source the
+ * assistant merely judged less reliable.
+ */
+export declare function recordSourceAssessments(store: EvidenceSink, assessments: SourceAssessment[], now?: string): void;
+/** The user turn that asks the assistant to answer again with the sources weighed. */
+export declare function renderSourceNote(weighing: SourceWeighing): string;
+/**
+ * The "Why?" lines for the sources a turn judged less reliable — one per LOW assessment recorded in the
+ * claim's evidence. Empty when the check did not run or nothing was judged LOW, so a quiet turn stays quiet.
+ */
+export declare function lowerConfidenceSourceLines(claim: {
+    evidence: Array<{
+        id: string;
+        obs: string;
+        reliability: SourceReliability;
+    }>;
+}): string[];

package/dist/task-completion-check.d.ts

@@ -0,0 +1,24 @@
+import { ILLMClient, TokenUsage } from '@buildaharness/runtime';
+export interface TaskCompletionResult {
+    /** `false` only when the check positively judged the output did not accomplish the task. */
+    done: boolean;
+    reason?: string;
+}
+/**
+ * `AUDIT_SEMANTIC_TASK_COMPLETION` gate. Default **OFF**: the harness marks a plan task COMPLETE as
+ * soon as the reply is produced, exactly as before. A truthy value (`1` / `true` / `on` / `yes` /
+ * `enabled`) turns on the per-task check for a durable plan's execution. Unlike the other semantic
+ * hooks this one changes plan behaviour (a task judged not done fails instead of completing), so it
+ * ships off until a benchmark shows it helps. Read at exactly one site: harness-bridge.ts.
+ */
+export declare function semanticTaskCompletionEnabled(env?: Record<string, string | undefined>): boolean;
+export declare function shortenForCheck(text: string): string;
+/**
+ * One bounded LLM call: did this output accomplish the task? Fails open — any error, empty output or
+ * unparseable response is `done: true`, so a broken check can never strand a plan that would have
+ * completed today; only a positive "not done" changes anything.
+ */
+export declare function checkTaskCompletion(input: {
+    taskDescription: string;
+    output: unknown;
+}, llmClient: ILLMClient, model?: string, onUsage?: (usage: TokenUsage) => void): Promise<TaskCompletionResult>;

package/dist/tool-control-plane.d.ts

@@ -37,17 +37,49 @@ export interface TurnControlPlaneState {
     readonly diagnostics: Diagnostics;
     readonly failureDiagnostics: FailureDiagnostics;
     controlState: ControlState;
+    /** How many times each identical call has already come back negative or failed this turn (see `ToolOutcome.callKey`). */
+    readonly unproductiveCalls: Map<string, number>;
+    /**
+     * EVAL-ONLY ablation (see `controlStateToolPolicyEnabled`): when true this state stays at its
+     * default ALLOW/NORMAL — `recordToolOutcome` still records evidence but never re-resolves, and
+     * agent-loop does not fold the harness's per-iteration state in — so tool policy never sees a DENY.
+     */
+    readonly pinNormal?: boolean;
 }
+/**
+ * `AUDIT_CONTROL_STATE_TOOL_POLICY` gate — feature-value audit, EVAL-ONLY: default **ON** (unset /
+ * empty / truthy keeps today's behaviour). Only the benchmark's `controlStateToolPolicyOff` and
+ * `controlStateOff` arms set a falsy value (`0` / `false` / `off` / `no` / `disabled`), which pins the
+ * ControlState that `evaluateToolPolicy` reads at ALLOW/NORMAL. Read at exactly one call site
+ * (`createControlPlaneState`); the harness's own gate is a separate switch (`AUDIT_CONTROL_STATE_GATE`).
+ */
+export declare function controlStateToolPolicyEnabled(env?: Record<string, string | undefined>): boolean;
+/**
+ * `AUDIT_CONTROL_STATE_GATE` gate — feature-value audit, EVAL-ONLY: default **ON**. Only the
+ * `controlStateOff` arm sets a falsy value, which makes `HarnessBridge.run` pass
+ * `skipControlState: true` to HarnessRuntime so `resolveAndStamp` leaves the harness's own state at
+ * ALLOW/NORMAL (no gate BLOCK/ESCALATE, no reviewer-verdict CAUTIOUS). Read at one call site.
+ */
+export declare function controlStateGateEnabled(env?: Record<string, string | undefined>): boolean;
 /**
  * A fresh EvidenceStore defaults to an EMPTY tool_availability_manifest, which makes
  * gatherEvidence() silently no-op for every tool. Seed it with every tool name this turn's
  * config actually enables, so tool outcomes are never silently dropped.
  */
 export declare function toolAvailabilityManifest(toolNames: string[]): Record<string, ToolAvailability>;
-export declare function createTurnControlPlaneState(toolNames: string[]): TurnControlPlaneState;
+export declare function createTurnControlPlaneState(toolNames: string[], opts?: {
+    pinNormal?: boolean;
+}): TurnControlPlaneState;
 export interface ToolOutcome {
     toolName: string;
     ok: boolean;
+    /**
+     * The call worked and the answer was "not there" (a missing file). Not a fault, so it does not count as a failure —
+     * unless the identical call has already come back negative twice (`callKey`), which is a retry of a known answer.
+     */
+    negative?: boolean;
+    /** Identifies the call (tool + arguments) so repeats of an already-negative or failed call can be recognised. */
+    callKey?: string;
     /** Short, human-readable — never the full resultText (can be large/untrusted). */
     summary: string;
 }

package/dist/tool-effect-class.d.ts

@@ -0,0 +1,9 @@
+import { ToolEffectClass } from '@buildaharness/harness';
+/**
+ * AL5a: each tool's effect class — a non-linguistic source for which tools a turn may use to
+ * change the world. Feeds `deriveConsequentialTools` (write / execute are consequential; `network`
+ * here is outbound read-only egress and is not). Keep in step with the tool definitions in
+ * file-tools.ts, web-tools.ts, shell-tools.ts, reminder-tools.ts and action-tools.ts; a tool
+ * missing here is treated as consequential by `deriveConsequentialTools`.
+ */
+export declare const TOOL_EFFECT_CLASS: Record<string, ToolEffectClass>;

package/dist/tool-step.d.ts

@@ -31,3 +31,9 @@ export declare function stripMcpToolPrefix(name: string): string;
  * parsing) so "what step is this" reads identically no matter where it's rendered.
  */
 export declare function summarizeToolStep(tool: string, input: Record<string, unknown>): string;
+/**
+ * The same step once its turn has finished: a write or command that was only "proposed" while the model was working is
+ * reported as done ("Wrote …", "Ran: …"), so the transcript never says "Proposing" about something that already happened.
+ * Only call this for a step of a completed turn that was not denied (`deniedReason` unset); every other tool reads the same.
+ */
+export declare function summarizeSettledToolStep(tool: string, input: Record<string, unknown>): string;

package/dist/trace-events.d.ts

@@ -14,7 +14,7 @@ export type TraceEvent = {
 } | {
     kind: 'turn_end';
     sessionId: string;
-    status: 'ok' | 'needs_approval' | 'escalated' | 'needs_clarification' | 'needs_plan_approval';
+    status: 'ok' | 'needs_approval' | 'escalated' | 'needs_clarification' | 'needs_plan_approval' | 'cancelled';
 } | {
     kind: 'risk_classified';
     riskLevel: RiskLevel;

package/dist/transcript-compaction.d.ts

@@ -10,4 +10,13 @@ export interface CompactionResult {
  * summary — keeps compaction free instead of costing an extra call every time
  * a long session crosses the threshold.
  */
+export declare const SUMMARY_HEADER = "[Earlier conversation summary]";
+/** The messages compaction would drop for `transcript` right now (the older part), or null when it would not compact. M3's pre-compaction flush reads exactly these. Same threshold, no new trigger. */
+export declare function messagesAboutToBeCompacted(transcript: ChatMessage[]): ChatMessage[] | null;
 export declare function compactTranscript(transcript: ChatMessage[]): CompactionResult;
+/**
+ * Same thresholds and same messages kept as `compactTranscript`, but the older part is summarized by `summarize`
+ * (semantic-compaction.ts) instead of truncated to 200 characters each. A `summarize` that returns null or throws
+ * falls back to the truncated form, so this can never lose more than `compactTranscript` would have.
+ */
+export declare function compactTranscriptSemantic(transcript: ChatMessage[], summarize: (older: ChatMessage[]) => Promise<string | null>): Promise<CompactionResult>;

package/dist/trust-tagging.d.ts

@@ -7,6 +7,8 @@ import { ILLMClient, TokenUsage } from '@buildaharness/runtime';
  * instruction that content in this tag is data, never instructions.
  */
 export declare function wrapUntrusted(text: string): string;
+/** A literal delimiter tag inside text is neutralised (`<`) so the text cannot close or re-open the untrusted boundary. String scan, not a regex: a structural delimiter check, not a natural-language gate. */
+export declare function defangUntrustedTags(text: string): string;
 export interface InjectionDetection {
     flagged: boolean;
     reason?: string;