@buildaharness/aielia 0.3.3 → 0.3.5

package/dist/agent-loop.d.ts

@@ -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;
@@ -133,13 +135,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;
@@ -196,6 +191,27 @@ export declare class AgentLoop {
         onToolStep?: (step: AssistantToolStep) => void;
         onUsage?: (usage: TokenUsage) => void;
         riskHint?: TurnIntentClassification['riskLevel'];
+        /**
+         * Mid-turn steering (goalGraphMode): messages the user sent while this turn runs that the
+         * scope×urgency classifier judged apply to the answer being produced right now. Called once
+         * per iteration, immediately before the LLM call; anything returned is spliced in as a user
+         * turn so the model itself applies it — no lexical matching, unlike the harness's
+         * 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
@@ -208,7 +224,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']): {
+    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[];
     };
@@ -347,6 +363,13 @@ 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;
+    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'
@@ -99,8 +106,8 @@ export declare class AssistantSession {
      * isn't set.
      */
     recordSpend(sessionId: string, usage: TokenUsage | undefined): Promise<void>;
-    /** Read-only — null means plan mode has never been entered (or was already exited/cancelled) for this session. */
-    getPlanModeState(sessionId: string): Promise<PlanModeState | null>;
+    /** 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>;
     /**
      * The one place `planMode.active` ever flips true — a fresh `draftId` per entry, even if a
      * prior drafting session was cancelled without ever reaching approval, so a stale draftId can
@@ -108,9 +115,9 @@ export declare class AssistantSession {
      * a new state, same as a fresh entry) — callers that only ever call this once per drafting
      * session (P3's future auto-trigger) never observe that.
      */
-    enterPlanMode(sessionId: string): Promise<PlanModeState>;
+    enterPlanMode(sessionId: string, threadId?: string): Promise<PlanModeState>;
     /** Clears `planMode.active` — the only two designed callers are an explicit cancel phrase (PlanDraftingService) and P2's future approval resolution. */
-    exitPlanMode(sessionId: string): Promise<void>;
+    exitPlanMode(sessionId: string, threadId?: string): Promise<void>;
     /** The session's conversation transcript, oldest first — same array `turn()` reads/appends to. Used by `/export`. */
     getTranscript(sessionId: string): Promise<ChatMessage[]>;
     /**
@@ -120,7 +127,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

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,4 +1,5 @@
-import { RiskState, LayerActivityEvent, AskQuestion } from '@buildaharness/harness';
+import { NextStepSuggestion } from './next-step-proposer.js';
+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';
@@ -63,6 +64,13 @@ export interface AssistantTurnResult {
      */
     status: 'ok' | 'needs_approval' | 'escalated' | 'needs_clarification' | 'needs_plan_approval';
     reply: string | null;
+    /**
+     * Up to three concrete next steps proposed after a full (non-trivial, `ok`) turn, most confident
+     * first — for the front end to show under the reply. Advisory only: never executed, never
+     * persisted from here. Present only when the caller enabled `goalGraphSuggestMode`
+     * (PersonalAssistantOptions) and the proposer returned at least one; absent otherwise.
+     */
+    nextSteps?: NextStepSuggestion[];
     reason?: string;
     /** See ProposerKind. Always set (defaults to 'posthoc'), on every status. */
     proposerKind?: ProposerKind;
@@ -93,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';
         }[];
     };
     /**
@@ -109,6 +122,8 @@ 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;
     /**
      * 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
@@ -155,4 +170,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;
+    }[];
 }

package/dist/assistant.d.ts

@@ -1,4 +1,4 @@
-import { ExperienceStore, CheckpointStore, AskResponse } from '@buildaharness/harness';
+import { ExperienceStore, CheckpointStore, AskResponse, LayerPolicyMode } from '@buildaharness/harness';
 import { MemoryAdapter, ILLMClient, ChatMessage, ReminderStore } from '@buildaharness/runtime';
 import { FileToolsContext } from './file-tools.js';
 import { UndoLogEntry } from './action-snapshot.js';
@@ -8,19 +8,28 @@ import { ActionToolsContext } from './action-tools.js';
 import { SpendCapConfig, SpendState } from './spend-cap.js';
 import { TraceEvent } from './trace-events.js';
 import { AssistantToolStep } from './tool-step.js';
-import { MemorySummary, MemoryExport } from './memory-service.js';
+import { MemoryService, MemorySummary, MemoryExport, AuditEntry, MemoryStatus, MemoryInjection, ConsolidationOutcome } from './memory-service.js';
+import { MemoryWriteMode } from './memory-governance.js';
+import { ConsolidationProposal } from './memory-consolidation.js';
 import { UserFact } from './fact-extraction.js';
 import { TranscriptSearchHit } from './assistant-session.js';
+import { SessionDigest } from './episodic-digest.js';
 import { PlanDecision, PlanApprovalEdits } from './plan-approval-service.js';
 import { PlanRecord } from './plan-store.js';
+import { GoalGraphRecord } from './goal-graph-store.js';
 import { OneLoopMode } from './one-loop-flag.js';
 import { AskMode } from './ask-mode-flag.js';
+import { AmbiguityGuardMode } from './ambiguity-guard-flag.js';
 import { PlanRolloutMode } from './plan-mode-flag.js';
+import { GoalGraphSuggestMode } from './goal-graph-suggest-flag.js';
+import { GoalGraphState } from './goal-graph-service.js';
+import { LiveSteeringChannel } from './live-steering-channel.js';
 import { DebugLogEntry } from './debug-log.js';
 import { AssistantTurnResult, AssistantProgress } from './assistant-types.js';
 export type { MemorySummary, MemoryExport, PendingFact } from './memory-service.js';
 export type { FactCategory } from './turn-intent-classifier.js';
 export type { IndexedMessage, TranscriptSearchHit } from './assistant-session.js';
+export type { GoalGraphState, GoalThreadView, GoalThreadVisibility, GoalTaskSummary } from './goal-graph-service.js';
 export type { BatchBudgetState } from './agent-loop.js';
 export { trimmedAverage, nextItemBudget } from './agent-loop.js';
 export type { AssistantSource } from './assistant-source.js';
@@ -39,6 +48,8 @@ export type MemoryPendingOutcome = {
 };
 export interface TurnOptions {
     sessionId?: string;
+    /** M4: a scripted / piped / batch caller. The post-turn memory reviewer is skipped for it (it only runs for an interactive session). */
+    nonInteractive?: boolean;
     approved?: boolean;
     pendingActionId?: string;
     /**
@@ -93,7 +104,7 @@ export interface TurnOptions {
      */
     onToolStep?: (step: AssistantToolStep) => void;
     /**
-     * **Eval harness only** (`packages/aielia/eval/`). Wraps the one-loop
+     * **Benchmark harness only.** Wraps the one-loop
      * proposer so its first `failIterations` harness iterations report a failed execution
      * and `seedFailures` recurring same-class records are seeded into the run's
      * `failureDiagnostics` — enough to trip `cannotMakeProgress()` on iteration 1 and
@@ -104,7 +115,23 @@ export interface TurnOptions {
         failIterations: number;
         seedFailures: number;
         onInjected?: () => void;
+        symptom?: string;
     };
+    /**
+     * Phase 4 of plans/hierarchical_goal_tree_and_steering_plan.html (R1/R4) — the session-scoped
+     * LiveSteeringChannel a caller (cli.ts/App.tsx, Phase 3) built for mid-task steering. When
+     * present, `turn()` wraps it in a scope×urgency-classifying UpdateChannel
+     * (goal-graph-reconcile.ts) and threads it into harnessBridge.run() so queued messages are
+     * absorbed at the harness's own checkCallerUpdates iteration boundary instead of waiting for
+     * the turn to finish. PersonalAssistant never reads goalGraphMode itself (same convention as
+     * oneLoopMode/askMode/planMode) — the caller decides whether to pass this at all; when absent,
+     * behavior is exactly today's (INV-43). Whatever this turn's harness run doesn't get around to
+     * classifying (it ends before the queue drains, or never calls harnessBridge.run() at all — a
+     * trivial turn) is pushed back onto this same channel in a `finally`, so the caller's own
+     * post-turn fallback drain (built in Phase 3) still picks it up — R4's "never silently drop"
+     * holds either way.
+     */
+    steeringChannel?: LiveSteeringChannel;
 }
 export interface PersonalAssistantOptions {
     llmClient: ILLMClient;
@@ -118,6 +145,14 @@ export interface PersonalAssistantOptions {
      * fresh install with no workspace concept at all.
      */
     activeProject?: string;
+    /** M1: character budget for the facts block under `AUDIT_MEMORY_BUDGETED_RENDER` — see config.ts's `memoryBudgetChars`. */
+    memoryBudgetChars?: number;
+    /** M6: where model-originated memory writes may land (`auto`/`staged`/`user_only`, default `staged`) — see memory-governance.ts. Changeable live via `setMemoryWriteMode`. */
+    memoryWriteMode?: MemoryWriteMode;
+    /**
+     * M5: run memory consolidation in the background on `/new` (`clearSession`). Off unless the host sets it: the CLI does; chat-ui must not until M6's pending-queue controls exist (D1 stages every proposal, and a browser user could not review one). Still gated by `AUDIT_MEMORY_CONSOLIDATION`.
+     */
+    consolidateOnNewSession?: boolean;
     /** Conversation transcript storage — defaults to an in-process Map, swap for IndexedDBAdapter in the browser. */
     memory?: MemoryAdapter;
     /** Learning-layer store — persist and pass the same instance back in across sessions to retain strategy weights. */
@@ -207,6 +242,18 @@ export interface PersonalAssistantOptions {
      * call resolveOneLoopMode(process.env) and pass the result here.
      */
     oneLoopMode?: OneLoopMode;
+    /** AL8a — layer policy mode ('static' default = today's behaviour). Resolved by the surface via resolveLayerPolicyMode; PersonalAssistant never reads process.env for it. */
+    layerPolicyMode?: LayerPolicyMode;
+    /**
+     * R7 (Tier 1.5) — next-step suggestions, one bounded LLM call each: after every full
+     * (non-trivial, `ok`) turn, up to three options are attached to the result as `nextSteps` for
+     * the front end to show under the reply; and when a GoalThread finishes its last task, its own
+     * suggestions are persisted on the thread for `/goals`. Defaults to 'disabled' — like
+     * oneLoopMode/askMode/planMode, the front end resolves the flag (cli.ts / App.tsx pass
+     * `config.goalGraphSuggestMode`, which defaults to enabled), so a library or benchmark caller
+     * that never asks for suggestions makes no extra call and sees no new field (INV-43).
+     */
+    goalGraphSuggestMode?: GoalGraphSuggestMode;
     /**
      * Q2 of the internal plan — global-flag control point (tier 1 of
      * INV-29) for the ask-question mechanism. Undefined (the default) falls back to
@@ -227,6 +274,13 @@ export interface PersonalAssistantOptions {
      * resolvePlanMode(process.env)/normalizePlanMode(import.meta.env...) and pass the result here.
      */
     planMode?: PlanRolloutMode;
+    /**
+     * AL3a — see ambiguity-guard-flag.ts. Absent/'disabled' (the default): routing is byte-identical to
+     * before. 'enabled': a consequential turn whose request doesn't determine the action gets a
+     * clarifying question instead of a staged guess. PersonalAssistant never reads process.env; the
+     * surface entry point resolves ASSISTANT_AMBIGUITY_GUARD / `/config set ambiguityGuardMode`.
+     */
+    ambiguityGuardMode?: AmbiguityGuardMode;
 }
 /**
  * A light, everyday-use wrapper around HarnessRuntime: one harness run per chat turn,
@@ -248,6 +302,9 @@ export declare class PersonalAssistant {
     private readonly llmClient;
     private model?;
     private activeProject?;
+    private memoryBudgetChars?;
+    private memoryWriteMode;
+    private consolidateOnNewSession;
     private readonly memory;
     private readonly webTools?;
     private readonly onTrace?;
@@ -257,6 +314,7 @@ export declare class PersonalAssistant {
     private readonly toolLoopWillRun;
     /** R3 of the internal plan — mirrors the same flag HarnessBridge was given at construction, kept here too so runTurn can decide whether to defer the tool loop into a harness-driven proposer instead of precomputing draftReply. See PersonalAssistantOptions.oneLoopMode's doc comment. */
     private readonly oneLoopMode;
+    private readonly layerPolicyMode;
     /** Q2 — global-flag tier of the ask-question mechanism's three-tier INV-29 resolution. See PersonalAssistantOptions.askMode's doc comment. */
     private readonly askMode;
     /** P11 — gates whether P3's auto-trigger below can ever enter plan mode for real traffic. See PersonalAssistantOptions.planMode's doc comment. */
@@ -269,7 +327,11 @@ export declare class PersonalAssistant {
      * the internal plan phase B1.
      */
     private lastProposerKind;
+    /** See PersonalAssistantOptions.goalGraphSuggestMode. */
+    private readonly goalGraphSuggestMode;
     private readonly memoryService;
+    /** M4 post-turn cross-turn memory reviewer; inert unless `AUDIT_MEMORY_REVIEWER` is on. */
+    private readonly memoryReviewer;
     private readonly session;
     private readonly agentLoop;
     private readonly actionApproval;
@@ -290,12 +352,29 @@ export declare class PersonalAssistant {
      * PersonalAssistant(...)` outside a browser (e.g. the CLI).
      */
     static create(options: PersonalAssistantOptions): Promise<PersonalAssistant>;
+    /**
+     * The bigger picture both next-step proposers get (see next-step-context.ts): earlier
+     * conversation, the steps taken this turn, and every goal thread the session tracks. Best-effort —
+     * any read failure just yields no extra context, never a failed turn. At turn end the focus
+     * thread is the one the graph currently marks active; for a thread that just finished it is that
+     * thread.
+     */
+    private nextStepContext;
     /**
      * Thin wrapper around runTurn(): emits turn_start/turn_end/error trace events
      * around the actual logic, so every one of runTurn's return paths gets a
      * matching turn_end without instrumenting each one individually.
      */
     turn(userMessage: string, options?: TurnOptions): Promise<AssistantTurnResult>;
+    /**
+     * M4: after a delivered, ordinary interactive reply, counts the turn and (every N turns without a memory write) starts the
+     * cross-turn memory review in the background. Not awaited: the reply is already on its way. Skipped for non-interactive and
+     * batch-research turns, and when the layer policy switched the layer off. Its spend is recorded through the same
+     * `recordSpend` path as the turn's own, so `/cost` and the spend cap include it.
+     */
+    private maybeStartMemoryReview;
+    /** Resolves when any in-flight background memory review has finished (a host about to exit, or a test). */
+    awaitMemoryReview(): Promise<void>;
     /** Persisted alongside transcript/facts/plan — survives a process restart, same as everything else keyed by sessionId, so the ceiling is genuinely cross-session, not just cross-turn within one process lifetime. */
     getSpendState(sessionId: string): Promise<SpendState>;
     /** The session's conversation transcript, oldest first — same array `turn()` reads/appends to. Used by `/export`. */
@@ -308,6 +387,45 @@ export declare class PersonalAssistant {
     recordDeclinedRequest(sessionId: string, userMessage: string, reason: string): Promise<void>;
     /** Ends the current conversation — see AssistantSession.clearSession's doc comment for exactly what is and isn't cleared. */
     clearSession(sessionId: string): Promise<void>;
+    /** M5: propose memory consolidation (applies nothing). `manual` forces the model pass past the cost gate. Usage is recorded against the spend state like any other call. */
+    proposeMemoryConsolidation(sessionId: string, manual?: boolean): Promise<Awaited<ReturnType<MemoryService['runConsolidation']>>>;
+    /** The consolidator MemoryService.consolidate() runs for `/memory consolidate` (chat-ui's button): runs the proposal pass now and reports; applying anything is still the user's accept. */
+    private runRegisteredConsolidation;
+    /** M5: staged proposals awaiting the user. */
+    memoryProposals(): Promise<ConsolidationProposal[]>;
+    /** M5: `/memory consolidate accept <n>` (1-based). */
+    acceptMemoryProposal(selector: string, sessionId: string): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+    /** M5: `/memory consolidate dismiss <n>` (1-based). */
+    dismissMemoryProposal(selector: string): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+    /** How many entries at the head of `listArchivedFacts()` were set aside by staged forgetting (M5) and can be restored; the rest were replaced by a newer statement. */
+    restorableArchiveCount(): Promise<number>;
+    /** `/memory archive restore <n>` (1-based, over the same numbered listing as `/memory archive`). */
+    restoreArchivedMemory(selector: string, sessionId: string): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+    /**
+     * M3 session edge: with AUDIT_EPISODIC_DIGEST on, writes the conversation's handoff digest (one bounded call, fail-open)
+     * for the current conversation (the rolling digest is refreshed, not duplicated, if the same conversation is digested again). `clearSession` (/new) calls it, then ends the conversation's digest identity; the CLI calls it on exit; never from inside a turn.
+     * With the flag off this does nothing, so the old behaviour is untouched.
+     */
+    endSession(sessionId: string): Promise<void>;
+    /** Stored episodic digests (newest first), for the memory panel and `/memory`; read-only. */
+    listSessionDigests(): Promise<SessionDigest[]>;
+    /** Which optional memory writers are switched on for this process (their `AUDIT_*` flags): hosts use it to show or hide the matching controls. A writer that is off makes no model call and no write. */
+    memoryWriterFlags(): {
+        reviewer: boolean;
+        consolidation: boolean;
+        digest: boolean;
+    };
+    /** M3 (D4): `/memory forget digest <id>` or all digests when `id` is omitted; returns how many were removed. */
+    forgetDigests(id?: string): Promise<number>;
     /**
      * P1 of the internal plan — explicit entry point into plan mode's
      * exclusive drafting state. No production caller yet: P3 will later set this automatically from
@@ -330,6 +448,19 @@ export declare class PersonalAssistant {
      * all). Returns `null` when no plan record exists for this session yet.
      */
     getPlanState(sessionId: string): Promise<PlanRecord | null>;
+    /**
+     * Phase 7 of plans/hierarchical_goal_tree_and_steering_plan.html (R5, "Visibility") — the shared
+     * read surface behind the CLI's `/goals` and chat-ui's GoalsPanel, analogous to `searchTranscript`
+     * above. A pure query over whatever Phases 4-5 already populate in this session's
+     * `GoalGraphRecord`; never mints or mutates one. Returns the empty state for a session with no
+     * goal graph yet, same "nothing to show" convention `getGoalGraphState` itself documents.
+     */
+    getGoalGraphState(sessionId: string): Promise<GoalGraphState>;
+    /**
+     * Read-only source for the plan graph view: the session's goal graph when it has threads, else its
+     * plan record, else `null`. Never throws and never creates a record.
+     */
+    getPlanGraph(sessionId: string): Promise<PlanRecord | GoalGraphRecord | null>;
     /**
      * P9 of the internal plan — the lightweight plan-sketch delegate: a
      * cheaper "just go research and draft an approach" path than plan mode's durable task-graph
@@ -388,9 +519,39 @@ export declare class PersonalAssistant {
      * facts first, then session facts — the same order `getMemorySummary()` returns). Unlike
      * confirm/reject, there's no category form: a durable/session fact carries no `category` field,
      * only pending model-inferred guesses do. Hard-deletes rather than routing through
-     * REJECTED_FACTS_KEY — see MemoryService.forgetFact's doc comment.
+     * REJECTED_FACTS_KEY — see MemoryService.forgetFact's doc comment. By default the removal is recorded
+     * in the audit log with the fact's text (so `/memory undo` can restore it); `erase` also scrubs that text.
      */
-    forgetFact(selector: string, sessionId: string): Promise<MemoryPendingOutcome>;
+    forgetFact(selector: string, sessionId: string, erase?: boolean): Promise<MemoryPendingOutcome>;
+    /** `/memory history` — the newest audit-log entries (M2). Empty unless `AUDIT_MEMORY_AUDIT_LOG` is on. */
+    memoryHistory(limit?: number): Promise<AuditEntry[]>;
+    /** `/memory undo <seq>` — restores the pre-image of one audit entry (M2). */
+    undoMemoryChange(selector: string, sessionId: string): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+    /** `/memory` governance mode (M6) — takes effect on the next write. */
+    getMemoryWriteMode(): MemoryWriteMode;
+    /** Live mode change (CLI `/config set` reloads the assistant; chat-ui calls this directly). Unknown values keep the default rather than widening write authority. */
+    setMemoryWriteMode(mode: MemoryWriteMode | string): void;
+    /** `/memory off` / `/memory on` — stop or resume all memory writes (facts, pending queue, digests, reviewer, consolidation) for this install. Existing data stays readable and removable. */
+    setMemoryEnabled(enabled: boolean): Promise<void>;
+    isMemoryEnabled(): Promise<boolean>;
+    /** Store size vs budget, pending/audit counts, last consolidation, governance state — `/doctor` and the memory panel. Read-only. */
+    getMemoryStatus(sessionId: string): Promise<MemoryStatus>;
+    /** The facts the last turn's prompt actually contained, plus how many were left out — the "Why?" panel / `/why` line. Undefined before the first turn. */
+    getLastMemoryInjection(): MemoryInjection | undefined;
+    /** `/memory archive` — entries set aside by staged forgetting (restorable, first) then entries a keyed update replaced (newest first). */
+    listArchivedFacts(): Promise<UserFact[]>;
+    /** `/memory archive forget <n>` — permanently erases one archived entry and its history pre-images. */
+    forgetArchivedFact(selector: string): Promise<MemoryPendingOutcome>;
+    /** `/memory consolidate` — runs the registered consolidator (M5). Until M5 registers one this reports `unavailable`. */
+    consolidateMemory(sessionId: string): Promise<ConsolidationOutcome | {
+        status: 'unavailable' | 'blocked';
+        message: string;
+    }>;
+    /** M5 hook: lets the consolidation phase plug in without touching the surfaces. */
+    registerMemoryConsolidator(fn: Parameters<MemoryService['registerConsolidator']>[0]): void;
     /** Ranked search over the per-message index — see AssistantSession.searchTranscript's doc comment. Used by `/search`. */
     searchTranscript(query: string, topK?: number): Promise<TranscriptSearchHit[]>;
     /** Changes the model used by every subsequent `turn()` call, mid-session — no reconstruction needed. Used by `/model`. Every collaborator constructed above reads this field through a getter closure, never a captured string, so this takes effect for all of them immediately. */

package/dist/benchmark-injected-failure.d.ts

@@ -21,6 +21,12 @@ export interface InjectedFailureOptions {
      * the internal plan F2).
      */
     onInjected?: () => void;
+    /**
+     * The failure symptom text (a paraphrase of a known class, a missing resource, a rate limit…).
+     * Becomes the seeded records' description, the observation and the failed execution's error, so
+     * failure matching sees the task's own wording. Absent = the generic ETIMEDOUT text.
+     */
+    symptom?: string;
 }
 type Proposer = (toolCtx: ToolExecutorContext) => unknown | Promise<unknown>;
 export declare function wrapProposerWithInjectedFailure(realProposer: Proposer, opts: InjectedFailureOptions): (toolCtx: ToolExecutorContext) => Promise<unknown>;