@buildaharness/aielia 0.3.4 → 0.3.5

package/dist/memory-service.d.ts

@@ -1,10 +1,58 @@
 import { ExperienceStore, StrategyWeightKey, DecompositionEntry, RecoverySequenceEntry, ExperienceStoreData, ExternalContradictionInput } from '@buildaharness/harness';
-import { MemoryAdapter, ReminderStore, ReminderRecord, ILLMClient, TokenUsage } from '@buildaharness/runtime';
+import { MemoryAdapter, ReminderStore, ReminderRecord, ILLMClient, TokenUsage, ChatMessage } from '@buildaharness/runtime';
 import { UserFact } from './fact-extraction.js';
 import { Corroboration } from './contradiction-checker.js';
+import { DigestStore, SessionDigest } from './episodic-digest.js';
 import { StatedFact, FactCategory } from './turn-intent-classifier.js';
+import { MemoryWriteMode, CrossTurnWriter } from './memory-governance.js';
+import { ConsolidationProposal } from './memory-consolidation.js';
+import { VerifiedReviewOp } from './memory-reviewer.js';
 export declare const FACT_CAP = 20;
-export declare const DURABLE_FACTS_KEY = "facts:durable";
+/** Default character budget for the rendered facts block under `AUDIT_MEMORY_BUDGETED_RENDER` (M0 measured ~195 tokens ≈ 800 chars for 20 facts; this leaves room for roughly 5x that). */
+export declare const DEFAULT_MEMORY_BUDGET_CHARS: number;
+/** Append-only store of entries a keyed fact replaced (M1); the M2 audit log will subsume it. */
+export declare const RETIRED_FACTS_KEY: string;
+/** M2: append-only change log with pre-images. Global, never cleared by `/new` (same convention as DURABLE_FACTS_KEY). */
+export declare const AUDIT_LOG_KEY: string;
+/** M2/M5: highest audit `seq` already consolidated; the audit log never rotates away an entry newer than this. Absent until M5 writes it. */
+export declare const CONSOLIDATION_STATE_KEY: string;
+/** M2: how many audit entries rotation keeps (plus any newer than the consolidation watermark). */
+export declare const AUDIT_LOG_KEEP: number;
+/**
+ * M6: `/memory off` — when `{ off: true }`, nothing writes memory for this install (facts, pending
+ * queue, and every later writer: M3 digests, M4 reviewer, M5 consolidation must check
+ * `MemoryService.isMemoryOff()` first). Reads, forget, reject and undo still work: switching writes
+ * off never traps the user's existing data. Global, never cleared by `/new`.
+ */
+export declare const MEMORY_OFF_KEY: string;
+/** M5: staged proposals awaiting the user (`/memory consolidate`). Global, never cleared by `/new`. */
+export declare const CONSOLIDATION_PROPOSALS_KEY: string;
+/** M5: entries the user accepted an archive proposal for. Recoverable (`/memory archive restore`), never deleted by this phase. */
+export declare const ARCHIVED_FACTS_KEY: string;
+export type AuditOp = 'add' | 'replace' | 'retire' | 'remove' | 'confirm' | 'reject' | 'undo' | 'archive' | 'restore';
+export interface AuditEntry {
+    seq: number;
+    at: string;
+    op: AuditOp;
+    /** `text|extractedAt` of the fact the entry concerns (M1's id convention). */
+    factId: string;
+    /** Pre-image (redacted text only — the gate redacts before anything reaches the log). */
+    before?: UserFact;
+    after?: UserFact;
+    /** Which store the change was made to. */
+    store: 'durable' | 'pending' | 'rejected';
+    writer: string;
+    turn: string;
+    /** Set on an `undo` entry: the seq it reverted. */
+    undoes?: number;
+    /** M6: the user erased this fact from history (`/memory archive forget`); before/after were removed and the entry can no longer be undone. */
+    erased?: boolean;
+    /** M5: entries applied together (one consolidation proposal) share a group; undoing one undoes the group. */
+    group?: string;
+    /** M5: position the pre-image held in the durable list, so undo restores order exactly. */
+    index?: number;
+}
+export declare const DURABLE_FACTS_KEY: string;
 /**
  * Global, never cleared by `/new` — same retention shape as DURABLE_FACTS_KEY (a pending fact
  * shouldn't vanish just because the session changed). Phase 3 of
@@ -13,7 +61,7 @@ export declare const DURABLE_FACTS_KEY = "facts:durable";
  * promoted or silently dropped — see `recordFacts()`'s promotion policy and
  * `confirmPendingFact()`/`rejectPendingFact()` below.
  */
-export declare const PENDING_CONFIRMATION_KEY = "facts:pending-confirmation";
+export declare const PENDING_CONFIRMATION_KEY: string;
 /**
  * Global, never cleared by `/new`. Holds facts removed from `facts:${sessionId}`/
  * PENDING_CONFIRMATION_KEY either by an entry-time retraction (a later statement contradicts an
@@ -22,7 +70,7 @@ export declare const PENDING_CONFIRMATION_KEY = "facts:pending-confirmation";
  * too, so a matching restatement can re-enter PENDING_CONFIRMATION_KEY tagged
  * `previouslyRejected` instead of being silently re-asked forever or silently refused forever.
  */
-export declare const REJECTED_FACTS_KEY = "facts:rejected";
+export declare const REJECTED_FACTS_KEY: string;
 /** Bound on how many learned decompositions/recovery sequences `getMemorySummary()` includes — see MemorySummary's doc comment. */
 export declare const MEMORY_SUMMARY_PREVIEW_LIMIT = 20;
 /** A `model_inferred` fact sitting in PENDING_CONFIRMATION_KEY, awaiting `/memory confirm`/`/memory reject`. */
@@ -30,6 +78,22 @@ export interface PendingFact extends UserFact {
     category: FactCategory;
     /** True when this exact fact previously lived in REJECTED_FACTS_KEY and was corroborated back in by a later, differently-phrased restatement — see `recordFacts()`'s corroboration handling. `/memory` surfaces this so the user sees the prior rejection instead of the fact looking brand new. */
     previouslyRejected?: boolean;
+    /** M4: `retire` marks a reviewer proposal to retire an existing durable fact (`retireTargetId` = its `text|extractedAt`) rather than add one; confirming it retires, never adds. */
+    proposedOp?: 'retire';
+    retireTargetId?: string;
+    /** M4: who staged this entry and what the semantic verifier said, shown in `/memory`. */
+    stagedBy?: 'reviewer';
+    verification?: 'supported' | 'unsupported' | 'not_checked';
+}
+/** What `stageReviewerOps()` did with a batch, for tests and `/memory` diagnostics. */
+export interface StageReviewerResult {
+    staged: number;
+    /** Unsupported by the verifier, kept session-scoped only. */
+    sessionScoped: number;
+    /** Refused by a plain-code gate (retire of a user_asserted fact, unknown target) or dropped by the write gate. */
+    refused: number;
+    /** The signal fired before the write: nothing was written. */
+    aborted: boolean;
 }
 /** An entry in REJECTED_FACTS_KEY — see that constant's doc comment. */
 export interface RejectedFact {
@@ -63,7 +127,60 @@ export interface MemoryExport {
     reminders: ReminderRecord[];
     pending: PendingFact[];
     experience: ExperienceStoreData;
+    /** M3: every stored episodic digest, unbounded and regardless of retention. */
+    digests?: SessionDigest[];
+    /** M6: facts a keyed update replaced (and, after M5, archived) — covered by export so nothing the assistant holds about the user is missing from it. */
+    retired?: UserFact[];
+    /** M6: the audit log (redacted text only, by the M2 gate). Empty when the audit-log flag is off. */
+    audit?: AuditEntry[];
+    /** M6: governance state at export time. */
+    governance?: {
+        mode: MemoryWriteMode;
+        off: boolean;
+    };
+}
+/** M6: what the facts block of the most recent turn actually contained ("Why?" panel, `/why`). */
+export interface MemoryInjection {
+    /** Facts placed in the prompt, in render order. */
+    facts: {
+        text: string;
+        unconfirmed: boolean;
+    }[];
+    /** In-scope live facts that did NOT make it into the prompt (budget or the legacy 20-fact cap). */
+    notShown: number;
 }
+/** M6: store-health snapshot for `/doctor` and the memory panel. Read-only; never touches usage counters. */
+export interface MemoryStatus {
+    mode: MemoryWriteMode;
+    off: boolean;
+    budgetedRender: boolean;
+    budgetChars: number;
+    /** Characters the in-scope live facts would need if all were rendered. */
+    storeChars: number;
+    liveFacts: number;
+    pending: number;
+    flaggedPending: number;
+    retired: number;
+    auditEnabled: boolean;
+    auditEntries: number;
+    /** Highest audit seq already consolidated (M5 writes `memory:consolidation-state`); undefined until then. */
+    lastConsolidatedSeq?: number;
+    lastConsolidationAt?: string;
+    lastInjection?: MemoryInjection;
+}
+/** M6 extension point for M5: what a consolidation run reports back to `/memory consolidate`. */
+export type ConsolidationOutcome = {
+    status: 'done';
+    message: string;
+} | {
+    status: 'nothing_to_do';
+    message: string;
+};
+/** M5 registers one of these via `MemoryService.registerConsolidator()`; it proposes through `submit` so governance, the gate and the audit log apply. */
+export type MemoryConsolidator = (ctx: {
+    submit: MemoryService['submitCandidate'];
+    sessionId: string;
+}) => Promise<ConsolidationOutcome>;
 /** Result of a single fact's promotion-time (`/memory confirm`) or corroboration-driven (medium→high) admission into DURABLE_FACTS_KEY — see `confirmPendingFact()`. */
 export interface PendingConfirmationOutcome {
     fact: UserFact;
@@ -75,6 +192,47 @@ export interface RecordFactsResult {
     contradictions: ExternalContradictionInput[];
     corroborations: Corroboration[];
 }
+/**
+ * `AUDIT_MEMORY_BUDGETED_RENDER` gate (M1 of the agent memory framework plan). Gates budgeted/
+ * priority rendering, keyed supersession and usage fields. `=0`/`off` restores `slice(-FACT_CAP)`
+ * and append-only writes. Default **ON** (M7 corrections scenario, 2 of 2 seeds: lexicalOff FAIL, memoryM12On PASS);
+ * `0`/`false`/`off`/`no`/`disabled` restores the legacy path. Read fresh each call; this is the one read point.
+ */
+export declare function memoryBudgetedRenderEnabled(env?: Record<string, string | undefined>): boolean;
+/** `AUDIT_MEMORY_WRITE_GATE`: semantic secret redaction + injection judgement before promotion, failing closed. Default OFF until the real-model pilot (plan defaults rule); `1/true/on/yes/enabled` enables. */
+export declare function memoryWriteGateEnabled(env?: Record<string, string | undefined>): boolean;
+/** `AUDIT_MEMORY_AUDIT_LOG`: append-only `memory:audit`. Default OFF until the pilot; `=0` restores the unlogged path. */
+export declare function memoryAuditLogEnabled(env?: Record<string, string | undefined>): boolean;
+/** Outcome of `admitCandidate()` for one candidate. `session` = kept session-scoped only, never durable or pending. */
+export interface AdmitDecision {
+    action: 'admit' | 'session' | 'flag' | 'drop';
+    fact: UserFact;
+}
+/**
+ * The single judgement step every writer's candidate passes through before it can be promoted (M2).
+ * Pure: the judgements were produced by the same LLM call that produced the fact. Always strips the
+ * transient `judgement`. With the gate off the candidate is returned unchanged (`admit`). With it on,
+ * for a `model_inferred` candidate: a missing judgement fails closed (`session`, durable bit cleared);
+ * a secret is replaced by the model's secret-free text, or dropped when the claim is the secret; an
+ * instruction-shaped claim is `flag`ged for the pending queue. A non-`user` origin never promotes.
+ */
+export declare function admitCandidate(candidate: UserFact, gateOn: boolean): AdmitDecision;
+/** Removes verbatim copies of the injected memory block from text bound for candidate extraction (feedback-loop prevention). Structural: it removes the exact block this service rendered, not a pattern. */
+export declare function excludeInjectedBlock(text: string, injectedBlock: string): string;
+export interface RenderedFacts {
+    block: string;
+    /** Facts actually placed in the block, in render order. */
+    shown: UserFact[];
+    /** In-scope live facts that did not fit the budget. */
+    droppedCount: number;
+}
+/**
+ * Renders facts by priority and character budget, not by position: identity/preference first, then
+ * semantic, then episodic/session facts; within a tier newest statement first, then most recently
+ * injected. A fact is dropped only when the budget is spent, and the drop is counted. No
+ * query-relevance ranking (D2: no lexical scoring). Pure.
+ */
+export declare function renderFactsBlock(inScope: UserFact[], budgetChars: number): RenderedFacts;
 /**
  * `AUDIT_MODEL_INFERRED_FACTS` gate — feature-value audit (Phase C3 of the internal plan).
  * Default **ON**: `classifyTurnIntent`'s `statesDurableFacts` (source `model_inferred`) reach
@@ -96,7 +254,7 @@ export declare function modelInferredFactsEnabled(env?: Record<string, string |
  * it) each stamp their own `extractedAt` — harmless, since neither call's result is compared
  * against the other's by identity.
  */
-export declare function buildTurnFacts(sessionId: string, userMessage: string, statedFacts: StatedFact[]): UserFact[];
+export declare function buildTurnFacts(sessionId: string, userMessage: string, statedFacts: StatedFact[], policyEnabled?: boolean, now?: () => string): UserFact[];
 /**
  * Owns fact/reminder/experience reads that feed each turn's system prompt, fact capture, and the
  * `/memory`/`/memory export` read-only snapshots — the "what has this assistant learned" surface
@@ -114,9 +272,99 @@ export declare class MemoryService {
     private readonly model;
     /** Resolves to `config.activeProject` if the user set one via `/project <name>`, else the workspace root — read through a getter (same convention as `model` above) so a mid-session `/project`/`/config set activeProject` change takes effect on the very next turn. See UserFact.project's doc comment for how this is used. */
     private readonly currentProject;
+    /** M1: character budget for the facts block under `AUDIT_MEMORY_BUDGETED_RENDER` (config `memoryBudgetChars`). */
+    private readonly memoryBudgetChars;
+    /** M6: governance mode (config `memoryWriteMode`), read through a getter like the others so a live change applies on the next write. Resolved here and nowhere else. */
+    private readonly writeMode;
+    /** Time source for every timestamp this service writes (extractedAt of stated facts, audit `at`, retiredAt, usage flush). Injectable so the cross-runtime conformance fixtures are byte-reproducible; default is wall-clock, i.e. no behaviour change. */
+    private readonly clock;
     constructor(memory: MemoryAdapter, reminderStore: ReminderStore, experienceStore: ExperienceStore, llmClient: ILLMClient, model: () => string | undefined, 
     /** Resolves to `config.activeProject` if the user set one via `/project <name>`, else the workspace root — read through a getter (same convention as `model` above) so a mid-session `/project`/`/config set activeProject` change takes effect on the very next turn. See UserFact.project's doc comment for how this is used. */
-    currentProject?: () => string);
+    currentProject?: () => string, 
+    /** M1: character budget for the facts block under `AUDIT_MEMORY_BUDGETED_RENDER` (config `memoryBudgetChars`). */
+    memoryBudgetChars?: () => number, 
+    /** M6: governance mode (config `memoryWriteMode`), read through a getter like the others so a live change applies on the next write. Resolved here and nowhere else. */
+    writeMode?: () => MemoryWriteMode, 
+    /** Time source for every timestamp this service writes (extractedAt of stated facts, audit `at`, retiredAt, usage flush). Injectable so the cross-runtime conformance fixtures are byte-reproducible; default is wall-clock, i.e. no behaviour change. */
+    clock?: () => string);
+    private consolidator?;
+    private lastInjection?;
+    /** `/memory off` state — M3/M4/M5 writers must call this before any write or LLM spend. */
+    isMemoryOff(): Promise<boolean>;
+    setMemoryOff(off: boolean): Promise<void>;
+    /** M5 extension point (not built here): until a consolidator is registered `/memory consolidate` says so instead of pretending. */
+    registerConsolidator(fn: MemoryConsolidator | undefined): void;
+    consolidate(sessionId: string): Promise<ConsolidationOutcome | {
+        status: 'unavailable' | 'blocked';
+        message: string;
+    }>;
+    /**
+     * M6 extension point for M3 (digest), M4 (reviewer) and M5 (consolidation) writers: the ONE way a
+     * cross-turn candidate enters memory. It applies, in order: `/memory off`, the M2 gate
+     * (`admitCandidate`: redaction, injection flag, fail-closed judgement, non-user origin), then the
+     * governance route for `memoryWriteMode` (`resolveWriteRoute`), and writes through the same
+     * single durable commit point / pending queue / audit log as every other writer. Add-only: removal
+     * and retirement stay with the user or a staged proposal.
+     */
+    submitCandidate(writer: CrossTurnWriter, candidate: UserFact, sessionId: string, opts?: {
+        pendingExtras?: Partial<PendingFact>;
+        forceGate?: boolean;
+    }): Promise<{
+        route: 'durable' | 'pending' | 'session' | 'dropped' | 'blocked';
+        fact?: UserFact;
+    }>;
+    /** Facts rendered since the last flush, keyed by `text|extractedAt`; written lazily so loadFacts() stays read-only (M1). */
+    private pendingInjections;
+    /** Number of in-scope facts the last budgeted render could not show — `/memory` says "N facts not shown this turn". */
+    lastDroppedCount: number;
+    /** The facts block most recently rendered into a prompt; excluded verbatim from candidate extraction (M2 feedback-loop prevention). */
+    private lastInjectedBlock;
+    private digestStoreInstance?;
+    /** Incremented whenever recordFacts() or stageReviewerOps() changes any memory store; the M4 trigger compares it before and after a turn. */
+    writeCount: number;
+    /** The facts block most recently injected into a prompt (what the M4 reviewer must strip from its input). */
+    getInjectedBlock(): string;
+    /**
+     * Keys of the live durable facts, with their text, for the classifier prompt (M1 key stability:
+     * the model reuses a stored key for a new value of the same attribute instead of inventing a
+     * variant that would miss supersession). Newest first, capped so the prompt stays small. Empty
+     * when keyed supersession is off.
+     */
+    getKnownFactKeys(limit?: number): Promise<{
+        key: string;
+        text: string;
+    }[]>;
+    /** Durable facts in stored order — the list a reviewer `retire` op's `targetId` indexes into. */
+    getDurableFacts(): Promise<UserFact[]>;
+    /**
+     * M4: stages the post-turn reviewer's operations. Per decision D1 nothing here reaches durable memory: surviving ops
+     * wait in the pending queue with their evidence (shown by `/memory`). Plain-code gates, no language judgement:
+     * a `retire` of a `user_asserted` fact (or of an unknown target) is refused; every op passes `admitCandidate()`;
+     * an op the verifier called unsupported is kept session-scoped only. All writes happen after the abort check, in one
+     * batch per store, so an abort leaves no partial write. `durableSnapshot` is the list the reviewer's `targetId`s index.
+     */
+    stageReviewerOps(sessionId: string, ops: readonly VerifiedReviewOp[], durableSnapshot: readonly UserFact[], signal?: AbortSignal): Promise<StageReviewerResult>;
+    /**
+     * M2: the ONLY place `DURABLE_FACTS_KEY` is written. Every add, replace, retire, remove, confirm
+     * and usage-flush goes through here, so a new writer cannot skip the audit log. A structural test
+     * (memory-write-gate.test.ts) asserts this is the only call in the file that writes the durable key.
+     */
+    private commitDurable;
+    private appendAudit;
+    /** `/memory history` — newest last; the last `limit` entries. */
+    getAuditLog(limit?: number): Promise<AuditEntry[]>;
+    /**
+     * `/memory undo <seq>` — restores the pre-image of one audit entry exactly (and removes what that
+     * entry added), then appends an `undo` entry. An entry can be undone once. Returns a message for
+     * the caller, or undefined when the seq is unknown.
+     */
+    undoAudit(seq: number, sessionId?: string): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+    /** Undo of the change that created a side store must leave it absent again, not an empty array (exact restoration). */
+    private setOrClear;
+    private undoEntry;
     /**
      * Durable + session facts for `sessionId`, plus the ready-to-splice system-prompt block — see
      * runTurn's former factsBlock. `facts` is the full inventory, unfiltered by project — `/memory`
@@ -125,9 +373,15 @@ export declare class MemoryService {
      * global-or-current-project only, so an unrelated project's facts don't leak into context (see
      * UserFact.project's doc comment).
      */
-    loadFacts(sessionId: string): Promise<{
+    loadFacts(sessionId: string, opts?: {
+        record?: boolean;
+    }): Promise<{
         facts: UserFact[];
         factsBlock: string;
+        knownFactKeys: {
+            key: string;
+            text: string;
+        }[];
     }>;
     /**
      * `/memory forget <n>` — removes the nth entry (1-based in `/memory`'s "Facts I know" display,
@@ -139,7 +393,7 @@ export declare class MemoryService {
      * happened to win the display dedup. Returns undefined for an out-of-range index (the caller's
      * `/memory` view is stale — nothing to forget).
      */
-    forgetFact(index: number, sessionId: string): Promise<UserFact | undefined>;
+    forgetFact(index: number, sessionId: string, erase?: boolean): Promise<UserFact | undefined>;
     /**
      * reminderStore is cross-session durable (clearSession() never touches it, same tier as
      * DURABLE_FACTS_KEY) but, unlike facts, was never actually surfaced into context: a plain
@@ -157,7 +411,7 @@ export declare class MemoryService {
     }>;
     /**
      * Captures this turn's durable/session facts into the session's fact store. A no-op when
-     * neither pass finds anything. Facts that clear `shouldAutoPromote()` (see that function's doc
+     * neither pass finds anything. Facts routed to durable by `resolveWriteRoute()` (memory-governance.ts; see its doc
      * comment for the current three-way policy) are ALSO appended to DURABLE_FACTS_KEY, a store
      * clearSession() never touches, so they survive /new instead of vanishing with the rest of the
      * session's facts. A `model_inferred` fact at `durable: true, confidence: 'medium'` is queued
@@ -190,6 +444,49 @@ export declare class MemoryService {
      * computed but never surfaced in the turn's own reply.
      */
     recordFacts(sessionId: string, userMessage: string, statedFacts: StatedFact[], onUsage?: (usage: TokenUsage) => void): Promise<RecordFactsResult>;
+    private consolidating;
+    /**
+     * M5: proposes consolidation and archive changes; applies NOTHING (D1: staged). Work is for the
+     * stores as the previous session left them: callers run it at session start or `/new`, or on the
+     * manual `/memory consolidate` (`manual` forces the model pass).
+     *
+     * Cost gate, deterministic and before any model call: the model pass runs only when the audit log
+     * has entries newer than `memory:consolidation-state.lastSeq` or the curated (durable) store is
+     * over the character budget, and there are at least two live facts; otherwise zero model calls.
+     * Archive proposals use no model: only M1's usage timestamps and the retention window. A failed
+     * or unusable model call changes nothing (the watermark does not move, so the next run retries).
+     * Requires the audit log: a change that cannot be undone is never proposed.
+     */
+    runConsolidation(opts?: {
+        manual?: boolean;
+        onUsage?: (usage: TokenUsage) => void;
+    }): Promise<{
+        status: 'disabled' | 'needs_audit_log' | 'busy' | 'skipped' | 'ran' | 'failed';
+        proposed: number;
+        modelCalls: number;
+        projectedChars?: number;
+        usedChars?: number;
+    }>;
+    getConsolidationProposals(): Promise<ConsolidationProposal[]>;
+    /** `/memory archive` — what staged forgetting has set aside. Nothing in it is deleted. */
+    getArchivedFacts(): Promise<UserFact[]>;
+    /** `/memory consolidate dismiss <n>`: drops the proposal and remembers its signature so it is not raised again. */
+    dismissProposal(index: number): Promise<ConsolidationProposal | undefined>;
+    /**
+     * `/memory consolidate accept <n>`: the user's explicit yes. Applies one staged proposal to the
+     * durable store through `commitDurable` as one audit group (`/memory undo <seq>` reverts all of it,
+     * restoring the store and its order exactly). Merged/superseded originals go to the retired store,
+     * archived ones to the archive store; nothing is deleted. Refuses without the audit log, and treats
+     * a proposal whose facts changed since it was staged as stale.
+     */
+    acceptProposal(index: number, sessionId?: string): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+    /** `/memory archive restore <n>`: puts an archived entry back among the live facts (audited; undoable). */
+    restoreArchivedFact(listIndex: number, sessionId?: string): Promise<UserFact | undefined>;
+    /** Writes the batched `injectedCount`/`lastInjectedAt` updates collected by budgeted renders, to whichever store(s) hold each fact. A no-op (no writes) when nothing was rendered. */
+    private flushInjectionUsage;
     /**
      * `/memory confirm <n>` — promotes the nth (1-based in `/memory`'s display, 0-based here) entry
      * in PENDING_CONFIRMATION_KEY to DURABLE_FACTS_KEY. Runs the same promotion-time check as
@@ -226,4 +523,46 @@ export declare class MemoryService {
      * export`.
      */
     exportMemory(sessionId: string): Promise<MemoryExport>;
+    /** What the most recent turn's facts block contained (undefined before the first turn). Set only by the turn path, never by read-only views. */
+    getLastInjection(): MemoryInjection | undefined;
+    /** `/memory archive`: entries a keyed update replaced, newest first. M5 EXTENSION POINT: its archive store joins here (and in `exportMemory`) when it exists. */
+    listArchive(): Promise<UserFact[]>;
+    /**
+     * `/memory archive forget <n>`: permanently erases one archived entry (index over `listArchive()`),
+     * including its pre-images in the audit log (those entries stay, marked `erased`, and can no longer
+     * be undone). The only path that edits the audit log other than appending, and only on an explicit user request.
+     */
+    forgetArchived(index: number): Promise<UserFact | undefined>;
+    /** Strips one fact's pre/post-images from the audit log (entries stay, marked `erased`, and can no longer be undone) and unlinks `supersedes` references to it. */
+    private eraseFromAuditLog;
+    /** Read-only health snapshot (`/doctor`, memory panel). Never touches usage counters or the last-injection record. */
+    getMemoryStatus(sessionId: string): Promise<MemoryStatus>;
+    /** M3 (D4): `/memory forget digest <id>` or, with no id, every digest. Returns how many were removed. */
+    forgetDigests(id?: string): Promise<number>;
+    /** M3: read-only digest reader over the same store the recall tool uses. */
+    get digests(): DigestStore;
+    /** Token usage of the most recent digest/flush calls made by this service (cost per session edge). */
+    digestUsage: {
+        inputTokens: number;
+        outputTokens: number;
+        costUsd: number;
+    };
+    private trackDigestUsage;
+    /**
+     * M3 session-edge digest (`/new`, exit). One bounded call, fail-open: any failure leaves the previous digest (if any)
+     * untouched. Skipped when the conversation has no user message. Output is judged and redacted by `admitCandidate`
+     * (see episodic-digest.ts) and stored at `episodic:<id>`; it never touches durable facts. Callers gate on
+     * `episodicDigestEnabled()`; never call from inside a turn.
+     */
+    writeSessionDigest(sessionId: string, transcript: ChatMessage[], onUsage?: (usage: TokenUsage) => void): Promise<SessionDigest | null>;
+    /** M3: ends the conversation's digest identity so the next conversation under the same session id gets a new digest. Call after `writeSessionDigest`. */
+    endDigestConversation(sessionId: string): Promise<void>;
+    /**
+     * M3 pre-compaction flush: called with exactly the messages compaction is about to drop. One call extracts candidate
+     * facts and a digest delta (folded into the conversation's digest). Candidates are judged by `admitCandidate` and go
+     * to the pending queue only, never durable. Fail-open: returns 0 on any failure and compaction proceeds regardless.
+     */
+    flushBeforeCompaction(sessionId: string, older: ChatMessage[], onUsage?: (usage: TokenUsage) => void): Promise<number>;
+    /** Judges flush candidates (gate forced on: a missing judgement drops the candidate) and appends the survivors to the pending queue. Exact-text duplicates of anything pending, durable or rejected are skipped. */
+    private queueFlushCandidates;
 }

package/dist/model-json.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Tolerant parsing of JSON a model was asked to return.
+ *
+ * A backend that can't enforce a schema (claude-cli in particular) sometimes wraps the JSON in a code
+ * fence, puts a stray tag or a sentence of reasoning in front of it, or trails prose after it. A strict
+ * `JSON.parse` then throws, and every classifier in this package fails open — silently losing the
+ * check. This is the one place that recovers the JSON from that, so no call site needs its own copy.
+ *
+ * It is a strict superset of `JSON.parse`: text that already parses parses to exactly the same value,
+ * and only text that would have thrown is looked at further.
+ */
+/**
+ * Parses `text` as JSON, or, failing that, the first (outermost, leftmost) JSON object/array embedded in
+ * it. Throws a `SyntaxError` when there is none — the same failure a plain `JSON.parse` gives, so a
+ * caller's existing `catch` keeps working.
+ */
+export declare function parseModelJson(text: string): unknown;

package/dist/next-step-context.d.ts

@@ -0,0 +1,51 @@
+import { ChatMessage } from '@buildaharness/runtime';
+import { GoalGraphRecord } from './goal-graph-store.js';
+import { AssistantSource } from './assistant-source.js';
+export interface NextStepConversationTurn {
+    role: 'user' | 'assistant';
+    content: string;
+}
+export interface NextStepGoalOverview {
+    goal: string;
+    status: string;
+    /** True for the thread the suggestion is about (the finished thread, or the active one at turn end). */
+    focus: boolean;
+    tasks: {
+        description: string;
+        status: string;
+    }[];
+    /**
+     * Next steps already proposed for this goal when it finished (the high/medium-confidence ones the
+     * thread persisted), for goals other than the focus one. They are how an open item of an earlier
+     * goal survives after that goal has left the conversation window. Absent when there are none.
+     */
+    openSuggestions?: string[];
+}
+export interface NextStepContext {
+    /** Earlier user/assistant messages, oldest first, excluding the exchange the suggestion is about. */
+    conversation?: NextStepConversationTurn[];
+    /** Every goal thread the session tracks, unfinished ones first. */
+    goals?: NextStepGoalOverview[];
+    /** Files read / searches made while producing this turn's reply. */
+    stepsThisTurn?: string[];
+}
+/**
+ * The last few user/assistant messages, oldest first. `currentExchange`, when given, drops the
+ * trailing user+assistant pair that is the exchange being suggested for (the proposer already gets
+ * it in full), so it is not sent twice. Tool messages and empty messages are skipped.
+ */
+export declare function summarizeConversation(transcript: ChatMessage[], currentExchange?: {
+    userMessage: string;
+}): NextStepConversationTurn[];
+/** Every goal thread with its tasks, the focus thread and unfinished threads first. Abandoned threads are left out. */
+export declare function summarizeGoalGraph(record: GoalGraphRecord | undefined, focusThreadId?: string): NextStepGoalOverview[];
+export declare function summarizeSteps(sources: AssistantSource[] | undefined): string[];
+export declare function buildNextStepContext(parts: {
+    transcript?: ChatMessage[];
+    currentExchange?: {
+        userMessage: string;
+    };
+    goalGraph?: GoalGraphRecord;
+    focusThreadId?: string;
+    sources?: AssistantSource[];
+}): NextStepContext;

package/dist/next-step-proposer.d.ts

@@ -1,6 +1,7 @@
 import { ILLMClient, TokenUsage } from '@buildaharness/runtime';
 import { GoalThread } from './goal-graph-store.js';
 import { GoalGraphSuggestMode } from './goal-graph-suggest-flag.js';
+import { NextStepContext } from './next-step-context.js';
 export type SuggestionConfidence = 'high' | 'medium' | 'low';
 /** Mirrors `shouldAutoPromote()`'s three-way policy *shape* (memory-service.ts) — not its bands, since Q10 found no numeric threshold to reuse: `high` auto-promotes, `medium` queues for explicit confirmation, `low` stays advisory-only and is never persisted past the turn that produced it. */
 export type SuggestionPromotion = 'auto' | 'pending_confirm' | 'session_only';
@@ -35,7 +36,7 @@ export declare function classifySuggestionPromotion(confidence: SuggestionConfid
  * `thread` hasn't actually reached `DONE` yet, since a suggestion only makes sense once the goal
  * it follows from is finished.
  */
-export declare function proposeNextSteps(thread: GoalThread, llmClient: ILLMClient, suggestMode: GoalGraphSuggestMode, model?: string, onUsage?: (usage: TokenUsage) => void): Promise<SuggestedNextStepNode[]>;
+export declare function proposeNextSteps(thread: GoalThread, llmClient: ILLMClient, suggestMode: GoalGraphSuggestMode, model?: string, onUsage?: (usage: TokenUsage) => void, bigPicture?: NextStepContext): Promise<SuggestedNextStepNode[]>;
 /**
  * The turn-end entry point: after a full (non-trivial) turn completes, propose up to three
  * concrete next steps for the user to pick from — shown under the reply, like Claude Code's prompt
@@ -49,4 +50,4 @@ export declare function proposeNextSteps(thread: GoalThread, llmClient: ILLMClie
 export declare function proposeTurnNextSteps(turn: {
     userMessage: string;
     reply: string;
-}, llmClient: ILLMClient, suggestMode: GoalGraphSuggestMode, model?: string, onUsage?: (usage: TokenUsage) => void): Promise<NextStepSuggestion[]>;
+}, llmClient: ILLMClient, suggestMode: GoalGraphSuggestMode, model?: string, onUsage?: (usage: TokenUsage) => void, bigPicture?: NextStepContext): Promise<NextStepSuggestion[]>;

package/dist/plan-graph-flag.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Pure logic backing the plan-graph visualization (read-only plan view on the CLI and desktop/web
+ * surfaces) — see plans/plan_visualization_plan.html. Same pattern as goal-graph-flag.ts.
+ *
+ * Presentation only: the flag never changes a plan, the harness or any persisted state, so it is
+ * deliberately NOT in LAYER_SETTINGS. 'disabled' (the default) leaves every surface byte-identical
+ * to the behaviour before the feature existed (INV-43). `AssistantConfig.planGraphMode` stays out of
+ * DEFAULT_CONFIG (undefined = "the package owns the default"), so consumers go through
+ * `isPlanGraphEnabled` rather than comparing against a possibly-undefined value.
+ */
+export type PlanGraphMode = 'enabled' | 'disabled';
+export declare const DEFAULT_PLAN_GRAPH_MODE: PlanGraphMode;
+export declare function isPlanGraphEnabled(mode: PlanGraphMode | undefined): boolean;
+/**
+ * Shared by cli-config.ts (via `resolvePlanGraphMode`) and chat-ui's browser-config.ts (Vite's
+ * `import.meta.env.VITE_ASSISTANT_PLAN_GRAPH`, which has no `process`). An unset or empty value
+ * falls back silently; an unrecognized value falls back with a warning naming `varName`.
+ */
+export declare function normalizePlanGraphMode(raw: string | undefined, varName?: string): PlanGraphMode;
+export declare function resolvePlanGraphMode(env: NodeJS.ProcessEnv): PlanGraphMode;

package/dist/plan-question.d.ts

@@ -0,0 +1,60 @@
+import { PlanRecord, PlanTaskRecord } from './plan-store.js';
+/**
+ * How a message that only asks about the active plan (the classifier's `isPlanQuestion`) is handled:
+ * - `stuck` (default): answered from the plan's recorded state ONLY while the plan is stuck on a failed
+ *   task — exactly where re-driving the plan is known to go wrong. A healthy plan behaves as it always
+ *   has, so this default changes nothing for it.
+ * - `always`: any plan question is answered from the recorded state, healthy plan or not.
+ * - `off`: an active plan drives every non-trivial turn (the pre-routing behaviour).
+ * `AUDIT_PLAN_QUESTION_ROUTING`: `always`/`on`/`1`/`true` → always; `0`/`false`/`off`/`no`/`disabled` → off;
+ * empty or `stuck` → stuck. Read at exactly one site: assistant.ts, where the turn is routed.
+ */
+export type PlanQuestionRouting = 'off' | 'stuck' | 'always';
+export declare function planQuestionRoutingMode(env?: Record<string, string | undefined>): PlanQuestionRouting;
+/** A plan is stuck when a step failed and was not skipped: the harness cannot advance past it on its own. */
+export declare function isPlanStuck(plan: PlanRecord): boolean;
+export declare function shouldRoutePlanQuestion(input: {
+    mode: PlanQuestionRouting;
+    plan: PlanRecord | null;
+    isPlanQuestion: boolean | undefined;
+}): boolean;
+/**
+ * `AUDIT_STUCK_PLAN_RESUME` (default ON): a plan stuck on a failed step is resumed only by a message that says to carry it
+ * on (the classifier's `continuesPlan`). Any other message is answered on its own terms — the plan is not handed to the
+ * harness, so the failed step is not silently retried — and the reply ends by asking whether to retry it. `0`/`false`/
+ * `off`/`no`/`disabled` restores the old behaviour (any non-trivial message on a stuck plan retries the step).
+ */
+export declare function stuckPlanResumeEnabled(env?: Record<string, string | undefined>): boolean;
+/**
+ * True when the turn should set the stuck plan aside: the plan is stuck, the message is not a question about it (that is
+ * routed separately) and the classifier said explicitly that it does not continue it. A missing `continuesPlan` is not
+ * "no" — it keeps today's behaviour.
+ */
+export declare function shouldSetAsideStuckPlan(input: {
+    enabled: boolean;
+    plan: PlanRecord | null;
+    isPlanQuestion: boolean | undefined;
+    continuesPlan: boolean | undefined;
+}): boolean;
+/** Prompt addendum for a turn that set a stuck plan aside: answer the message, then ask about the failed step. */
+export declare function renderStuckPlanNudge(plan: PlanRecord): string;
+/**
+ * The plan's tasks as the harness should see them for a turn that moves the plan forward. A step that
+ * failed is put back to pending so it gets another attempt (left as FAILED it would strand the run on
+ * every later turn), and its description carries why the last attempt was rejected so the retry can
+ * address that instead of repeating it. Only the harness's copy changes: the stored plan keeps its
+ * original description, and its status is rewritten from the run's outcome afterwards.
+ */
+export declare function planTasksForRun(tasks: PlanTaskRecord[]): PlanTaskRecord[];
+/**
+ * What to add to the reply of a turn that ran an approved plan and stopped because a step was not
+ * accepted as done. Without it the reply is just the last step that DID complete, and the user only finds
+ * out the plan stalled by asking. Empty when nothing was rejected this turn.
+ */
+export declare function renderPlanStopNote(plan: PlanRecord, taskNotes: Record<string, string> | undefined): string;
+/**
+ * The plan's real state, rendered for the prompt of a turn that only asks about it. Grounds the answer
+ * in what the task graph actually recorded (a task is "done" only if it completed; a failed one carries
+ * the reason it was not accepted) so the reply can't drift into describing the plan as it was drafted.
+ */
+export declare function renderPlanStateBlock(plan: PlanRecord): string;