@buildaharness/aielia 0.3.4 → 0.3.6

package/dist/cli-config.d.ts

@@ -18,10 +18,13 @@ export declare function isConfigKey(key: string): key is keyof AssistantConfig;
  * before this module existed (ASSISTANT_ENABLE_WEB/ASSISTANT_ENABLE_SHELL must be exactly "1").
  */
 export declare function envOverridesFromProcessEnv(env: NodeJS.ProcessEnv): Partial<AssistantConfig>;
+export declare function findInvalidNumericSettings(config: AssistantConfig): string[];
 /** Thrown by parseConfigValue on a value that doesn't fit the target key's type — cli.ts reports .message and leaves the config unchanged. */
 export declare class ConfigValueParseError extends Error {
 }
 /** Parses a raw `/config set <key> <value>` string into the type AssistantConfig[key] expects. */
 export declare function parseConfigValue(key: keyof AssistantConfig, raw: string): unknown;
+/** A URL with any user:password, and every query-string value, masked, so a credential embedded in proxyUrl is never printed. Text that is not a URL is returned unchanged. */
+export declare function redactUrlCredentials(text: string): string;
 /** Renders /config's full listing as a single multi-line string — cli.ts just console.logs the result. */
 export declare function formatConfigListing(config: AssistantConfig, overriddenKeys: ReadonlySet<keyof AssistantConfig>): string;

package/dist/cli-session.d.ts

@@ -2,19 +2,23 @@ import { NextStepSuggestion } from './next-step-proposer.js';
 import { ChatMessage, TokenUsage } from '@buildaharness/runtime';
 import { AssistantConfig } from './config.js';
 import { MemorySummary, MemoryExport, TranscriptSearchHit, MemoryPendingOutcome } from './assistant.js';
+import { AuditEntry, MemoryStatus, MemoryInjection } from './memory-service.js';
 import { GoalGraphState } from './goal-graph-service.js';
 import { UndoLogEntry } from './action-snapshot.js';
+import { UserFact } from './fact-extraction.js';
 /**
- * Pure formatting/logic backing cli.ts's session-level commands (/help, /status, /export,
- * /memory, /cost, /doctor) — split out so it's unit-testable without a real readline loop,
- * the same way cli-config.ts already is for the /config family. cli.ts stays thin glue
- * (reading live state, calling these, doing actual file I/O) on top of these functions.
+ * Text that came from the model, a tool result, a file or a web page must not reach the terminal raw: an
+ * embedded escape sequence can clear the screen, rewrite earlier lines (hiding what an approval prompt is
+ * really asking), set the window title or write the clipboard (OSC 52). Newlines and tabs survive; everything
+ * that could drive the terminal is removed. Plain text is returned unchanged.
  */
+export declare function stripTerminalControls(text: string): string;
 export interface CliCommandHelp {
     command: string;
     description: string;
 }
-/** Kept as a hand-maintained list rather than derived from cli.ts's dispatch table — see /help's task note on why this can drift and needs manual upkeep when a command is added. */
+/** A bare `exit` / `quit` (with or without a leading slash, any case) ends the session; anything longer is an ordinary message. An exact command match, not a reading of the message. */
+export declare function isQuitCommand(message: string): boolean;
 export declare const CLI_COMMANDS_HELP: CliCommandHelp[];
 export declare function formatHelp(): string;
 export interface StatusInfo {
@@ -32,6 +36,16 @@ export declare function formatStatus(info: StatusInfo): string;
 /** Renders the result of `/memory confirm`/`/memory reject` — cli.ts's handleMemoryConfirm/handleMemoryReject print this directly. */
 export declare function formatMemoryPendingOutcome(action: 'confirmed' | 'rejected' | 'forgotten', outcome: MemoryPendingOutcome): string;
 export declare function formatMemorySummary(summary: MemorySummary): string;
+/** `/memory history` — one line per audit entry. */
+export declare function formatMemoryHistory(entries: AuditEntry[]): string;
+/** `/memory archive` — facts a newer keyed statement replaced. */
+export declare function formatMemoryArchive(facts: UserFact[], restorableCount?: number): string;
+/** The "Why?" / `/why` line: which stored facts the last reply could have known, and how many were left out. Says "in the prompt", not "used". */
+export declare function formatMemoryInjection(injection: MemoryInjection | undefined): string;
+/** `/memory status` and the memory panel header. */
+export declare function formatMemoryStatus(status: MemoryStatus): string;
+/** `/doctor` entries for memory (CLI via doctor-checks.ts, chat-ui directly — same pure function on both surfaces). */
+export declare function memoryStatusChecks(status: MemoryStatus): DoctorCheck[];
 /** Renders `/memory export`'s full, unbounded contents as pretty-printed JSON — a plain formatting function so it's unit-testable the same way as every other cli-session.ts formatter; cli.ts does the actual file write. */
 export declare function formatMemoryExport(data: MemoryExport): string;
 /** Renders `/search <query>`'s results — each hit is one message (session id short form, timestamp, role, snippet), ranked by relevance, never the whole session it came from. An empty list is an explicit "no results" line, never a silent blank output. */

package/dist/cli.d.ts

@@ -2,6 +2,8 @@ import { FsBackend } from '@buildaharness/runtime';
 import { PersonalAssistant } from './assistant.js';
 import { AssistantConfig, ConfigStore } from './config.js';
 import { NonInteractiveApprovalMode } from './non-interactive-mode.js';
+import { VizNode } from './plan-viz/types.js';
+import { TaskStatus } from '@buildaharness/harness';
 import { KeyedBackend, KeyTestResult } from './provider-setup.js';
 /**
  * One choice in a structured multi-option prompt (Phase 7 of the internal plan
@@ -16,6 +18,22 @@ export interface SelectOption {
     label: string;
 }
 export interface RunCliOptions {
+    /**
+     * The Ink shell's seam for `/plan graph` (planGraphMode enabled): called with the drawable nodes to open the
+     * full-screen pane. Without it (plain REPL, piped input) `/plan graph` prints one static render instead.
+     */
+    openPlanGraph?: (nodes: VizNode[]) => void;
+    /** Live per-task statuses from a running turn, forwarded for the open plan graph pane. */
+    onPlanProgress?: (tasks: {
+        id: string;
+        status: TaskStatus;
+    }[]) => void;
+    /**
+     * Called with true when a conversational turn starts being worked on and false when it has finished (in a
+     * `finally`, so also after an error) — including turns run as deferred follow-ups, which no `dispatchLine()`
+     * promise covers. The TUI's liveness indicator follows this rather than guessing from output events.
+     */
+    onTurnBusyChange?: (busy: boolean) => void;
     dataDir?: string;
     configStore?: ConfigStore;
     backend?: FsBackend;
@@ -39,8 +57,6 @@ export interface RunCliOptions {
     askSelect?: (question: string, options: SelectOption[]) => Promise<string>;
     /** Test seam: skip the interactive first-run setup regardless of TTY state (also implied when `assistant` is passed). */
     skipFirstRunSetup?: boolean;
-    /** Test seam: stub `claude` binary detection for the first-run setup. */
-    detectClaudeCli?: () => Promise<boolean>;
     /** Test seam: script the first-run setup's line reads. */
     firstRunAsk?: (question: string) => Promise<string>;
     /** Test seam: stub the live API-key check in the first-run setup (defaults to a real call to the provider). */
@@ -59,6 +75,11 @@ export interface CliInstance {
      * readline REPL or by non-interactive/piped mode — only the TUI shell polls this.
      */
     getStatusIndicators(): Promise<string[]>;
+    /** Read-only: the plan graph's drawable nodes (with `live` statuses overlaid), or undefined when planGraphMode is disabled or there is no plan. Feeds the TUI's open plan graph pane. */
+    getPlanGraphNodes(live?: {
+        id: string;
+        status: TaskStatus;
+    }[]): Promise<VizNode[] | undefined>;
 }
 /**
  * The CLI's REPL, parameterized so cli.test.ts can import and drive it directly instead of only
@@ -82,6 +103,9 @@ export declare function runCli(options?: RunCliOptions): Promise<CliInstance>;
  * `runTuiApp` is imported dynamically so a disabled (the default) or non-TTY run never loads Ink
  * at all — `main()` behaves byte-for-byte as it does today in both those cases.
  */
+/** A reason the assistant refuses to start (invalid configuration, unusable environment): shown to the user verbatim, exit code 1. */
+export declare class StartupError extends Error {
+}
 export declare function main(argv?: readonly string[]): Promise<void>;
 /**
  * True when `entryArg` (a `process.argv[1]` value) refers to the same file as

package/dist/cli.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import "./bin-CdVTAe7j.js";
+import "./bin-BYRl4xXM.js";
 //# sourceMappingURL=cli.js.map

package/dist/code-plan-templates.d.ts

@@ -0,0 +1,21 @@
+import { ProcessConcept } from '@buildaharness/harness';
+import { PlanTemplate } from './plan-templates/index.js';
+/**
+ * `AUDIT_CODE_PLAN_TEMPLATES` gate. Default **OFF**: the plan templates are the seven general-purpose ones, exactly as
+ * before. On, the harness's four bundled process concepts (debug a failing test, implement a feature, review code,
+ * refactor a module — `packages/harness/src/concepts/`) are offered as plan templates too, so the turn-intent
+ * classifier can match a code-shaped request to one and the request goes through the ordinary plan path (approval,
+ * persistence, per-step prompts, criteria). Until now nothing in aielia could reach those concepts. A truthy value
+ * (`1` / `true` / `on` / `yes` / `enabled`) enables it. Read where `plan-templates` builds its list.
+ */
+export declare function codePlanTemplatesEnabled(env?: Record<string, string | undefined>): boolean;
+/**
+ * A process concept as a plan template. Step order, dependencies, risk and abstraction level come from the harness's
+ * own `seedTaskGraph` (so the level mapping is not copied here); a step's success criteria are appended to its
+ * text as "Done when …" because a plan task has no criteria field of its own. Dropped on purpose: the
+ * concept's `expectedTools` (their names — `run_tests`, … — are not aielia's tools and would mislead the model) and
+ * `strategyHint` (a plan task has nowhere to carry it).
+ */
+export declare function conceptToPlanTemplate(concept: ProcessConcept): PlanTemplate;
+/** The bundled process concepts as plan templates, keyed by concept id. Built once. */
+export declare function codePlanTemplates(): Record<string, PlanTemplate>;

package/dist/config.d.ts

@@ -1,10 +1,14 @@
 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 { TuiMode } from './tui-mode-flag.js';
 import { UpdateCheckMode } from './update-check-flag.js';
 import { GoalGraphMode } from './goal-graph-flag.js';
+import { PlanGraphMode } from './plan-graph-flag.js';
+import { LayerPolicyMode } from './layer-policy-flag.js';
 import { GoalGraphSuggestMode } from './goal-graph-suggest-flag.js';
+import { MemoryWriteMode } from './memory-governance.js';
 export interface AssistantConfig {
     llmBackend: 'proxy' | 'claude-cli' | 'anthropic' | 'openai' | 'openrouter';
     proxyUrl: string;
@@ -92,6 +96,10 @@ export interface AssistantConfig {
     sessionCostLimitUsd?: number;
     /** Secondary ceiling on completed turns this session — see SpendCapConfig's doc comment in spend-cap.ts for why this counts turns, not raw internal LLM calls. */
     sessionCallLimit?: number;
+    /** M1: character budget for the per-turn facts block under `AUDIT_MEMORY_BUDGETED_RENDER`. Undefined = DEFAULT_MEMORY_BUDGET_CHARS (memory-service.ts). */
+    memoryBudgetChars?: number;
+    /** M6: where model-originated memory writes may land — `auto` | `staged` (default) | `user_only`; see memory-governance.ts. */
+    memoryWriteMode?: MemoryWriteMode;
     /**
      * R5 of the internal plan — the rollout flag for the harness-driven
      * one-loop proposer (see one-loop-flag.ts's doc comment for the full rationale). Undefined (the
@@ -127,6 +135,8 @@ export interface AssistantConfig {
      * out of DEFAULT_CONFIG so an unset value stays undefined.
      */
     planMode?: PlanRolloutMode;
+    /** AL3a — ask a clarifying question before staging an under-specified consequential request. See ambiguity-guard-flag.ts. Undefined = 'disabled'. */
+    ambiguityGuardMode?: AmbiguityGuardMode;
     /**
      * Phase 4 of the internal plan — the rollout flag for the
      * Ink-driven pinned-bottom-input interactive shell (tui-app.ts's runTuiApp()). Undefined (the
@@ -147,6 +157,8 @@ export interface AssistantConfig {
      * check, never the explicit `aielia update` command. CLI-only, like `tuiMode`.
      */
     updateCheck?: UpdateCheckMode;
+    /** Colour theme of the chat-ui/desktop window: 'system' (default, follows the OS), 'dark' or 'light'. The CLI ignores it. */
+    theme?: 'system' | 'dark' | 'light';
     /**
      * The project label newly captured project-scoped facts are tagged with, and the one
      * project-scoped facts are filtered against when building a turn's context (see
@@ -170,6 +182,19 @@ export interface AssistantConfig {
      * comment for why that was deliberate up to now.
      */
     goalGraphMode?: GoalGraphMode;
+    /**
+     * Read-only plan-graph view (plans/plan_visualization_plan.html). 'disabled' (the package default,
+     * kept out of DEFAULT_CONFIG like goalGraphMode) leaves every surface byte-identical to before.
+     * Presentation only — never added to LAYER_SETTINGS.
+     */
+    planGraphMode?: PlanGraphMode;
+    /**
+     * AL7b of plans/adaptive_layer_selection_plan.html — 'static' (default; also the kill switch) |
+     * 'shadow' (record what adaptive would decide, execute static) | 'adaptive'. Undefined falls back
+     * to `DEFAULT_LAYER_POLICY_MODE`. Chain: `ASSISTANT_LAYER_POLICY`, `VITE_ASSISTANT_LAYER_POLICY`,
+     * `/config set layerPolicyMode`; consumed via `isAdaptivePolicyEnabled()`.
+     */
+    layerPolicyMode?: LayerPolicyMode;
     /**
      * Phase 8 — the same shared config seam as `goalGraphMode` above, for the next-step proposer's
      * (Tier 1.5) independent gate (Q8: a regression there shouldn't block Tier 0/1). Undefined
@@ -177,6 +202,12 @@ export interface AssistantConfig {
      * set` chain, via `ASSISTANT_GOAL_GRAPH_SUGGEST`/`VITE_ASSISTANT_GOAL_GRAPH_SUGGEST`.
      */
     goalGraphSuggestMode?: GoalGraphSuggestMode;
+    /**
+     * Per-layer on/off choices for the reasoning layers (layer-settings.ts's LAYER_SETTINGS), keyed by layer id. An absent id means
+     * "the layer's own default". Applied onto the layers' `AUDIT_*` env flags by `applyLayerSettings`; a flag already set in the real
+     * environment wins and renders pinned. Edited with the CLI's `/layers` and the Settings screen's Layers section, not `/config set`.
+     */
+    layers?: Record<string, boolean>;
 }
 /** Every AssistantConfig key, in the order every surface's settings UI/listing renders them. */
 export declare const CONFIG_KEYS: readonly (keyof AssistantConfig)[];

package/dist/constraint-check.d.ts

@@ -0,0 +1,35 @@
+import { ILLMClient, TokenUsage } from '@buildaharness/runtime';
+export interface ConstraintViolation {
+    constraint: string;
+    reason?: string;
+}
+/**
+ * `AUDIT_SEMANTIC_CONSTRAINT_CHECK` gate. Default **ON**: the harness's lexical caller-constraint check throws on any
+ * reply that names the constraint's subject — including one that obeys it — so this replaces it rather than adding
+ * to it, and only runs when the caller has set a constraint (the lexical check's own precondition). Set to a falsy
+ * value (`0` / `false` / `off` / `no` / `disabled`) to keep the lexical check. Read at exactly one site: harness-bridge.ts.
+ */
+export declare function semanticConstraintCheckEnabled(env?: Record<string, string | undefined>): boolean;
+/**
+ * What to append to a reply the judge still found breaking a constraint after the one revision (the harness hands the answer
+ * back with the violation instead of failing the turn). Empty when nothing is unresolved.
+ */
+export declare function renderUnresolvedConstraintNote(violations: ReadonlyArray<ConstraintViolation> | undefined): string;
+/** Most standing constraints kept per session; the oldest drop first. */
+export declare const MAX_STANDING_CONSTRAINTS = 8;
+/**
+ * Standing constraints plus the ones stated now: trimmed, de-duplicated (case-insensitive), the newest last, capped at
+ * MAX_STANDING_CONSTRAINTS (oldest dropped). A constraint restated moves to the end rather than appearing twice.
+ */
+export declare function mergeStandingConstraints(existing: readonly string[], incoming: readonly string[]): string[];
+/**
+ * One bounded LLM call: does this reply break any of these constraints? Fails open — an error, an empty reply or an
+ * unparseable answer is "no violations", so a broken check can never fail a turn that would have passed. Only
+ * constraints the caller actually set are reported (a constraint the model invented is dropped).
+ */
+export declare function checkConstraints(input: {
+    constraints: string[];
+    reply: string;
+}, llmClient: ILLMClient, model?: string, onUsage?: (usage: TokenUsage) => void): Promise<{
+    violated: ConstraintViolation[];
+}>;

package/dist/contradiction-checker.d.ts

@@ -15,6 +15,13 @@ export declare function looksLikeCodingFact(statement: string): boolean;
  * site — `harness-bridge.ts`, where the `contradictionChecker` host hook is wired.
  */
 export declare function semanticContradictionEnabled(env?: Record<string, string | undefined>): boolean;
+/**
+ * `AUDIT_SEMANTIC_CONTRADICTION_SEVERITY` (default OFF). The checker used to set no severity, so every semantic
+ * contradiction recorded as MEDIUM and Tier 1 (DENY) was unreachable through it. On: the judgment also grades each
+ * contradiction, and only "HIGH" (two claims that directly and explicitly cannot both hold) is passed on — anything
+ * else, or a missing/unknown value, stays MEDIUM. Never LOW or SYSTEM_BREAKING.
+ */
+export declare function semanticContradictionSeverityEnabled(env?: Record<string, string | undefined>): boolean;
 /** A newBelief restating/reinforcing an uncertainFacts or rejectedFacts entry in different words — see checkForContradictions' doc comment. Caller resolves which pool `existingId` came from by id membership (both ids are always from this call's own known-id set, filtered below). */
 export interface Corroboration {
     existingId: string;

package/dist/debug-log.d.ts

@@ -5,12 +5,21 @@
  * caller opts into this explicitly (see PersonalAssistantOptions.onDebugLog) knowing it
  * carries real content, not just metadata.
  *
+ * `approval_request` is a state-changing action (write/shell/email) staged for the user's yes/no, and
+ * `approval_decision` is how that was resolved ('approved' or 'declined'); the executed result of an
+ * approved action is the separate `tool_call` entry, so a log reader can reconstruct the whole exchange.
+ *
+ * `next_steps` is the numbered list of suggestions printed under a reply (one entry per turn that produced any).
+ *
+ * `note` records a robustness action the loop took on its own (an empty final answer retried, or replaced by a
+ * deterministic fallback), so a log reader can see why a reply is not what the model first returned.
+ *
  * Split into its own file so both assistant.ts (user_message/assistant_reply kinds, emitted from
  * `turn()`) and agent-loop.ts (tool_call kind, emitted from the ReAct loop) can depend on it
  * without either owning the other.
  */
 export interface DebugLogEntry {
-    kind: 'user_message' | 'assistant_reply' | 'tool_call';
+    kind: 'user_message' | 'user_message_queued' | 'assistant_reply' | 'tool_call' | 'approval_request' | 'approval_decision' | 'note' | 'next_steps';
     sessionId: string;
     content: string;
 }

package/dist/decomposed-answer.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `AUDIT_DECOMPOSED_ANSWER_ONCE` gate. Default **ON**: an ordinary turn the classifier split into several
+ * subtasks answers the user once, and the later subtasks reuse that answer. A falsy value (`0` / `false` /
+ * `off` / `no` / `disabled`) restores the one-answer-per-subtask behaviour. Read at exactly one site:
+ * assistant.ts, where the proposer is wired.
+ *
+ * Why: the harness runs each subtask through the same proposer, and every call was given only the user's
+ * message, so a request split into nine subtasks produced the complete answer thirteen times and returned
+ * the last one. (The pre-one-loop path computed one reply and handed it to every task; this restores that.)
+ * A plan's steps are different — each is real work and gets its own instruction (plan-step-prompt.ts) — so
+ * they are not affected.
+ */
+export declare function decomposedAnswerOnceEnabled(env?: Record<string, string | undefined>): boolean;

package/dist/decomposition-classifier.d.ts

@@ -7,6 +7,8 @@ import { ILLMClient, TokenUsage } from '@buildaharness/runtime';
  * silently create several reminders in one turn.
  */
 export declare function looksLikeEnumeratedItems(message: string): boolean;
+/** The raw lexical enumeration check, used inside `classifyRisk`'s bulk-reminder gate — which is itself switched by lexicalMode's `risk` family. */
+export declare function looksLikeEnumeratedItemsLexical(message: string): boolean;
 export interface DecomposedTaskSpec {
     id: string;
     description: string;

package/dist/doctor-checks.d.ts

@@ -1,8 +1,11 @@
 import { FsBackend } from '@buildaharness/runtime';
 import { DoctorCheck } from './cli-session.js';
+import { MemoryStatus } from './memory-service.js';
 /** GET <proxyUrl>/health, expecting {status:'ok'} (see packages/proxy/src/index.ts) — hard-timed so a dead proxy can't hang /doctor. */
 export declare function checkProxyHealth(proxyUrl: string): Promise<DoctorCheck>;
 /** Spawns `<claudePath> --version`, same path resolution ClaudeCliLLMClient uses — hard-timed so a hung/missing binary can't hang /doctor. */
 export declare function checkClaudeCli(claudePath: string): Promise<DoctorCheck>;
+/** M6: memory store size vs budget, pending count, last consolidation, audit-log size. The rendering is the shared pure `memoryStatusChecks` (chat-ui calls it too). */
+export declare function checkMemoryHealth(status: MemoryStatus): DoctorCheck[];
 export declare function checkWorkspaceRoot(workspaceRoot: string): Promise<DoctorCheck>;
 export declare function checkDataDirWritable(backend: FsBackend, dataDir: string): Promise<DoctorCheck>;

package/dist/email.d.ts

@@ -53,8 +53,10 @@ export interface ResendSenderOptions {
  */
 export declare function createResendSender(options: ResendSenderOptions): SendEmail;
 /**
- * One-line human-readable summary of a staged email, for the approval prompt and trace. Kept here
+ * Human-readable summary of a staged email, for the approval prompt and trace. Kept here
  * (not in agent-loop.ts) so the MCP server (file-tools-mcp-server.mjs) and the CLI can format the
- * same way without importing the loop.
+ * same way without importing the loop. The approver must see everything that will be sent: every
+ * recipient (Cc/Bcc included, since a hidden Bcc is a silent exfiltration channel) and the whole
+ * body, never a truncated preview.
  */
-export declare function formatEmailApprovalReason(message: Pick<EmailMessage, 'to' | 'subject' | 'body'>): string;
+export declare function formatEmailApprovalReason(message: Pick<EmailMessage, 'to' | 'subject' | 'body' | 'cc' | 'bcc'>): string;

package/dist/episodic-digest.d.ts

@@ -0,0 +1,89 @@
+import { ChatMessage, ILLMClient, MemoryAdapter, TokenUsage } from '@buildaharness/runtime';
+import { UserFact } from './fact-extraction.js';
+/**
+ * Episodic tier (M3 of the agent memory framework plan): one rolling handoff digest per conversation,
+ * kept apart from durable facts. Never injected into the prompt; read by the recall tool.
+ *
+ * STORAGE CONTRACT (the recall tool codes against this): a digest lives at `episodic:<digestId>` as a
+ * `SessionDigest`. `digestId` is `<sessionId>:<conversationId>` because a CLI/chat-ui session id is
+ * reused across `/new`, so a bare session id would overwrite the previous conversation's digest.
+ * The id of every live digest is listed in `episodic-index` (the MemoryAdapter has no key listing).
+ */
+export interface SessionDigest {
+    /** The digest id (the key suffix), not necessarily the raw session id: `<sessionId>:<conversationId>`. */
+    sessionId: string;
+    /** ISO time of the last write (the digest is rolling; retention counts from here). */
+    createdAt: string;
+    oneLine: string;
+    objective: string;
+    done: string[];
+    decisions: string[];
+    openItems: string[];
+    nextStep: string;
+    /** Set when the judge found the digest instruction-shaped. It is still untrusted context; the recall tool wraps it either way. */
+    flagged?: boolean;
+}
+export declare const EPISODIC_KEY_PREFIX = "episodic:";
+export declare const EPISODIC_INDEX_KEY = "episodic-index";
+/** D4: start at 90 days, calibrate. `AUDIT_EPISODIC_RETENTION_DAYS` overrides. */
+export declare const DEFAULT_RETENTION_DAYS = 90;
+/** `AUDIT_EPISODIC_DIGEST`: the digest writer and the pre-compaction flush. Default OFF; `1/true/on/yes/enabled` enables. Read where the writer is invoked (assistant.ts). */
+export declare function episodicDigestEnabled(env?: Record<string, string | undefined>): boolean;
+export declare function episodicRetentionDays(env?: Record<string, string | undefined>): number;
+/** Read side, and the owner of the digest keys. The recall tool builds one of these over the same MemoryAdapter. */
+export declare class DigestStore {
+    private readonly memory;
+    constructor(memory: MemoryAdapter);
+    private ids;
+    /** One digest by id, or undefined when absent or past retention. Never writes. */
+    getDigest(id: string): Promise<SessionDigest | undefined>;
+    /** The most recent `limit` digests (default 10), newest first, past-retention ones excluded. Never writes. */
+    listDigests(limit?: number): Promise<SessionDigest[]>;
+    /** Writes one digest and prunes past-retention ones (D4). The only place episodic keys are written. */
+    put(digest: SessionDigest): Promise<void>;
+    pruneExpired(): Promise<number>;
+    /** `/memory forget digest <id>` / `/memory forget digests` (no id). Returns how many were removed, expired ones included. */
+    forget(id?: string): Promise<number>;
+    /** Every stored digest, unbounded and ignoring retention, for `/memory export`. */
+    exportAll(): Promise<SessionDigest[]>;
+}
+export declare function listDigests(memory: MemoryAdapter, limit?: number): Promise<SessionDigest[]>;
+export declare function getDigest(memory: MemoryAdapter, id: string): Promise<SessionDigest | undefined>;
+/** The id of `sessionId`'s current conversation, minted on first need and cleared by `endConversation` (after the final digest). */
+export declare function conversationDigestId(memory: MemoryAdapter, sessionId: string): Promise<string>;
+export declare function endConversation(memory: MemoryAdapter, sessionId: string): Promise<void>;
+/** The marker scripted-llm-client.ts's SIDE_CALL_MARKERS keys on. */
+export declare const DIGEST_SYSTEM_MARKER = "You write a session handoff digest";
+type DigestBody = Omit<SessionDigest, 'sessionId' | 'createdAt' | 'flagged'>;
+export interface DigestCallResult {
+    body: DigestBody;
+    flagged: boolean;
+    facts: UserFact[];
+}
+/**
+ * One bounded call. Returns null on any error, unparseable output, empty digest, or a MISSING secret/instruction
+ * judgement — this write fails closed (a missed secret would reach disk), the one deliberate exception to "side
+ * calls fail open"; the consequence of null is only that no digest is written. The whole digest goes through
+ * `admitCandidate` with the gate forced on (independent of AUDIT_MEMORY_WRITE_GATE): a flagged secret is
+ * replaced by the model's `redactedDigest` (an unusable redaction drops the digest).
+ */
+export declare function callDigest(llm: ILLMClient, input: {
+    messages: ChatMessage[];
+    prior?: SessionDigest;
+    extractFacts: boolean;
+    digestId: string;
+    sessionId: string;
+}, model?: string, onUsage?: (usage: TokenUsage) => void): Promise<DigestCallResult | null>;
+/**
+ * Writes/refreshes the conversation's digest from `messages`, folding in whatever digest already exists. Fails open for
+ * the caller (returns null, writes nothing, no partial entry). Never touches DURABLE_FACTS_KEY.
+ */
+export declare function writeDigest(memory: MemoryAdapter, llm: ILLMClient, args: {
+    sessionId: string;
+    messages: ChatMessage[];
+    extractFacts: boolean;
+}, model?: string, onUsage?: (usage: TokenUsage) => void): Promise<{
+    digest: SessionDigest;
+    facts: UserFact[];
+} | null>;
+export {};

package/dist/fact-extraction.d.ts

@@ -70,6 +70,37 @@ export interface UserFact {
      * project is currently active.
      */
     project?: string;
+    /**
+     * M1 (agent memory framework): a model-chosen stable key for a fact naming a single-valued
+     * attribute ("home_city", "preferred_editor"). A new fact with the same key replaces the old
+     * one (see `MemoryService.recordFacts()`). Never derived from wording in code; undefined for
+     * a fact that names no single-valued attribute, which keeps today's accumulate behaviour.
+     */
+    key?: string;
+    /** M1: set on the replacing fact — the text of the entry it retired. */
+    supersedes?: string;
+    /** M1: set on an entry moved to `facts:retired` when a keyed fact replaced it. */
+    retiredAt?: string;
+    /** M1 usage fields, updated lazily (batched, flushed from `recordFacts()`) when the fact is rendered into a prompt. */
+    injectedCount?: number;
+    lastInjectedAt?: string;
+    /** M2: where the claim came from. Undefined = `user`. A non-`user` origin can only ever be episodic (see `tierForFact`). */
+    origin?: FactOrigin;
+    /** M2: the user's own supporting words for a `model_inferred` claim, returned by the classifier. Stored for audit/`/memory` display, never string-matched. */
+    evidence?: string;
+    /** M2: set on a pending entry the write gate's semantic injection judgement flagged as instruction-shaped; never auto-promoted. */
+    flagged?: boolean;
+    /** M2: transient classifier judgement carried from `buildTurnFacts` to the write gate; stripped before anything is persisted. */
+    judgement?: CandidateJudgement;
+}
+/** M2: structured provenance next to `FactSource`; only `user` may reach a Knowledge tier. */
+export type FactOrigin = 'user' | 'agent' | 'tool' | 'web';
+/** M2: the classifier's per-fact judgement. Either field undefined means the judgement is missing (the gate fails closed). */
+export interface CandidateJudgement {
+    containsSecret?: boolean;
+    /** Fact text with the secret removed; empty/undefined when the whole claim is the secret. */
+    redactedText?: string;
+    looksLikeInstruction?: boolean;
 }
 /** Every fact has a certainty for `/memory` display purposes, even one with no `confidence` gradient (user_asserted/observed/externally_verified) — those are exactly as certain as a stated fact gets, so they display as 'high' rather than blank. Never used for promotion/tier logic, which still reads `fact.confidence` directly and treats undefined as "no LLM confidence signal" (see that field's own doc comment) — this is purely a rendering convenience. */
 export declare function certaintyLabel(fact: UserFact): FactConfidence;
@@ -126,6 +157,14 @@ export declare const TIER_RULES: Record<MemoryTier, TierRule>;
  * `procedural`/`commitment` are never returned (see `TIER_RULES`'s doc comment).
  */
 export declare function tierForFact(fact: UserFact): MemoryTier;
+/**
+ * The reliability the harness's world model should give this fact's belief — 'HIGH' (confidence
+ * 1.0, the >= 0.8 bar the change reviewer and contradiction severity read) for a fact the user
+ * stated directly or that has been externally verified, and for a `model_inferred` one that
+ * cleared the same durable + high-confidence bar `tierForFact` uses to treat it as Knowledge;
+ * everything else stays 'MEDIUM' (0.5), so an unconfirmed guess never reads as an established fact.
+ */
+export declare function factReliability(fact: UserFact): 'HIGH' | 'MEDIUM';
 /** Whether `tier` counts as the Knowledge tier for contradiction-detection purposes — see harness-bridge.ts's factExtractor and TIER_RULES.*.contradictionChecked. */
 export declare function isKnowledgeTier(tier: MemoryTier): boolean;
 /**