@buildaharness/aielia 0.3.5 → 0.3.7

package/README.md

@@ -7,6 +7,30 @@ what it may do, what it may believe, and what a job may cost — light enough fo
 "what's the weather", and it stages anything that can't be undone (`write_file`,
 `run_shell_command`, `send_email`) for your approval. Website: https://myaielia.com.
 
+## Install
+
+```bash
+# macOS / Linux — standalone binary, installed to ~/.local/bin (override with AIELIA_INSTALL_DIR)
+curl -fsSL https://myaielia.com/install.sh | sh
+curl -fsSL https://myaielia.com/install.sh | sh -s -- --force   # replace a non-aielia file at the target path
+
+# Windows (PowerShell) — installs to %LOCALAPPDATA%\Aielia\aielia.exe and adds it to your user PATH
+irm https://myaielia.com/install.ps1 | iex                       # set $env:AIELIA_FORCE = '1' first to force
+
+# or from npm
+npm install -g @buildaharness/aielia
+```
+
+Both installers read the manifest at `https://myaielia.com/aielia-latest.json`, download
+the binary for your platform over HTTPS only, verify its SHA-256 against the manifest and
+install it; re-running upgrades in place, or says it is already up to date. They refuse
+to overwrite an unrelated file (or a symlink, such as an npm-linked `aielia`) without
+`--force`. `aielia update` does the same upgrade later (see "Updates and the update check"
+below). On the first interactive launch with nothing configured, the CLI asks which
+provider to use and for its API key (live-checked with a free read-only call) and saves
+the choice to the persisted config; piped/scripted stdin skips this and keeps the
+`proxy` default.
+
 ## Design
 
 The harness here is a governance and reliability control plane, not just a
@@ -307,8 +331,9 @@ await assistant.turn('Summarize this into notes.md', { approved: true, pendingAc
 
 Declining (`{ approved: false, pendingActionId }`) discards the staged record
 without writing. A pending action left over from a crashed/abandoned turn sits
-in `.pending-actions/` indefinitely — harmless (never applied without an explicit
-`approved: true` with the matching ID) but not currently auto-swept. This same
+in `.pending-actions/` — harmless (never applied without an explicit
+`approved: true` with the matching ID), and swept on the next startup unless a
+session still has a resumable checkpoint (`sweepAbandonedPendingActionsOnStartup`). This same
 staging record shape (a `kind` discriminator) is shared with `run_shell_command`
 (see "Shell access via tools" below) and `send_email`.
 
@@ -348,7 +373,7 @@ Both backends enforce the same "never write inline" rule, by different
 mechanisms:
 
 - **Proxy/Anthropic backend** (`LLMClient`): `PersonalAssistant`'s tool loop
-  (capped at 5 iterations) calls `callChatStructured` directly, executes
+  (bounded by `maxSteps`, default 15, minus a few steps held back for recovery) calls `callChatStructured` directly, executes
   non-mutating tool calls for real, and intercepts `write_file` itself before
   it ever reaches `file-tools.ts`'s staging code.
 - **Claude CLI backend** (`ClaudeCliLLMClient`): Claude Code's own agentic loop
@@ -365,8 +390,10 @@ mechanisms:
 
 v1 is deliberately read/list/write only — no delete/move tool (higher
 consequence than a write, no "undo" via re-approval). One workspace root per
-assistant instance; no multi-root or per-request override. chat-ui doesn't have
-a write-approval UI yet — file tools are CLI/desktop-only for now.
+assistant instance; no multi-root or per-request override. File tools need a
+real workspace directory, so they are CLI/desktop-only; chat-ui's approval card
+(with the exact change shown) is what resolves a staged write or shell command
+on the desktop build.
 
 ## Clarifying questions
 
@@ -404,8 +431,8 @@ follow-up `needs_clarification` batch if it's still unresolved once the first ba
 folded in, resolved through this exact same path.
 
 Two kinds of sites can raise a `questions` batch: the Trajectory Supervisor's `ASK_USER` directive
-(see ADR-005 — currently inert by default, since
-`HARNESS_TRAJECTORY_SUPERVISOR` stays off) and a handful of deterministic sites with a genuinely
+(see ADR-005 — the supervisor is on by default in Aielia;
+`HARNESS_TRAJECTORY_SUPERVISOR=0` turns it off) and a handful of deterministic sites with a genuinely
 enumerable option set, e.g. a batch-research budget running out ("continue with N more steps" /
 "stop and summarize" / "let me clarify the goal"). A site with no discrete option set keeps
 today's plain `missing_info` halt unchanged — this mechanism never forces a multiple-choice
@@ -742,8 +769,9 @@ non-functional `web_search`. The active state is shown in the startup banner
 running session with `/config set` instead of an env var — see
 "Configuration" below.
 
-Skip the proxy and call a provider directly with your own API key — `ASSISTANT_LLM_BACKEND=anthropic|openai|openrouter` plus
-`ASSISTANT_API_KEY`:
+`ASSISTANT_LLM_BACKEND` also accepts `claude-cli` (shells out to the `claude` CLI already on
+your PATH, no API key needed; CLI and desktop only). Skip the proxy and call a provider directly with your own API
+key — `ASSISTANT_LLM_BACKEND=anthropic|openai|openrouter` plus `ASSISTANT_API_KEY`:
 
 ```bash
 ASSISTANT_LLM_BACKEND=anthropic ASSISTANT_API_KEY=sk-ant-... \
@@ -761,11 +789,12 @@ These three go straight from this process to the provider's own API
 — no proxy deployment needed, but unlike `authToken` (a self-hosted proxy's
 own bearer token), `ASSISTANT_API_KEY`/`apiKey` is a *real* provider key.
 It's stored the same way as every other secret field here — plaintext in
-`config.json`, not an OS keychain — so treat that file accordingly. When
+`config.json` (written with mode `0600`, in a `0700` directory), not an OS
+keychain — so treat that file accordingly. When
 `ASSISTANT_MODEL`/`/config set model` isn't set, each backend falls back to the
 current-generation default id exported from `@buildaharness/runtime`'s
 `model-defaults.ts` (`openai` → `gpt-5-mini`, `openrouter` →
-`anthropic/claude-sonnet-5`, `anthropic` and `proxy` → `claude-sonnet-5`).
+`deepseek/deepseek-v4-flash`, `anthropic` and `proxy` → `claude-sonnet-5`).
 
 Transcript, learned experience, reminders, and any in-flight turn's checkpoint
 persist as real files under `~/.buildaharness/personal-assistant/`
@@ -794,9 +823,13 @@ you> /config
   model          (not set)
   enableWeb      false
   braveApiKey    (not set)
+  webBackend     direct
   enableShell    false
   shellTimeoutMs (not set)
+  shellNetworkAllowlist (not set)
   workspaceRoot  (not set)
+  enableEmail    false
+  ...            (one line per key; the full list is `CONFIG_KEYS` in config.ts)
   dangerouslySkipPermissions false
 
 you> /config set enableWeb true
@@ -812,7 +845,9 @@ you> /config reset enableWeb
 ✓ Reset enableWeb to default
 ```
 
-- `/config` lists every field's current (resolved) value. A field currently
+- `/config` lists every field's current (resolved) value; secret fields
+  (`authToken`, `apiKey`, `braveApiKey`, `resendApiKey`, `smtpPass`) print as
+  `********`, and credentials or query strings inside `proxyUrl` are masked. A field currently
   pinned by an env var shows `(env-pinned: VAR_NAME)` and cannot be changed
   with `/config set` — unset the env var first.
 - `/config set <key> <value>` validates the change (e.g. `enableWeb true`
@@ -825,11 +860,40 @@ you> /config reset enableWeb
 
 **Precedence**: env var > persisted config > built-in default, evaluated
 independently per field. Settings persist as plain JSON at
-`~/.buildaharness/personal-assistant/config.json` — like the rest of this
-package's persistence, it's a real file, not encrypted, so `authToken` and
-`braveApiKey` are stored in plaintext there. This is the same trust boundary
+`~/.buildaharness/personal-assistant/config.json` (created `0600` inside a
+`0700` directory) — like the rest of this
+package's persistence, it's a real file, not encrypted, so `authToken`,
+`apiKey`, `braveApiKey` and the email credentials are stored in plaintext there. This is the same trust boundary
 the repo's root `.env` already has, not a new one.
 
+Settings beyond those above (each has an env var, a `/config set` key, and a built-in default;
+mode flags take `enabled`/`disabled`):
+
+| Key (env var) | Default | What it does |
+|---|---|---|
+| `webBackend` | `direct` | Browser build only (see chat-ui README); the CLI always calls Brave directly |
+| `shellNetworkAllowlist` (`ASSISTANT_SHELL_NETWORK_ALLOWLIST`) | none (deny all) | Hosts an approved shell command may reach |
+| `enableEmail`, `emailProvider` (`resend`/`smtp`), `emailFrom`, `resendApiKey`, `smtpHost`/`smtpPort`/`smtpUser`/`smtpPass` (`ASSISTANT_ENABLE_EMAIL`, `ASSISTANT_EMAIL_*`, `ASSISTANT_RESEND_API_KEY`, `ASSISTANT_SMTP_*`) | off | Registers the staged `send_email` tool; `enableEmail` needs `emailFrom` and the provider's credentials |
+| `sessionCostLimitUsd`, `sessionCallLimit` (`ASSISTANT_SESSION_COST_LIMIT_USD`, `ASSISTANT_SESSION_CALL_LIMIT`) | unbounded | Refuses a new turn once the cross-session estimated spend or completed-turn count reaches the ceiling; shown in `/status` and `/cost` |
+| `memoryBudgetChars` (`ASSISTANT_MEMORY_BUDGET_CHARS`) | 4000 | Character budget for the facts block in the prompt |
+| `memoryWriteMode` (`ASSISTANT_MEMORY_WRITE_MODE`) | `staged` | `auto`, `staged` or `user_only`; see "Memory tiers" |
+| `oneLoopMode` (`ASSISTANT_ONE_LOOP`) | `enabled` | See "Design" |
+| `askMode` (`ASSISTANT_ASK_MODE`) | `disabled` | See "Clarifying questions" |
+| `planMode` (`ASSISTANT_PLAN_MODE`) | `legacy` | `gated` or `legacy` plan rollout |
+| `ambiguityGuardMode` (`ASSISTANT_AMBIGUITY_GUARD`) | `disabled` | Ambiguity guard |
+| `tuiMode` (`ASSISTANT_TUI`) | `enabled` | Full-screen terminal UI (Ink); only on a real TTY |
+| `updateCheck` (`ASSISTANT_UPDATE_CHECK`) | `enabled` | Passive update check |
+| `activeProject` (`ASSISTANT_ACTIVE_PROJECT`) | none | Project new project-scoped facts are tagged with (`/project`) |
+| `goalGraphMode`, `goalGraphSuggestMode` (`ASSISTANT_GOAL_GRAPH`, `ASSISTANT_GOAL_GRAPH_SUGGEST`) | `enabled` in the CLI | Goal tree, steering and next-step options |
+| `planGraphMode` (`ASSISTANT_PLAN_GRAPH`) | `disabled` | `/plan graph` |
+| `layerPolicyMode` (`ASSISTANT_LAYER_POLICY`) | `static` | `static`, `shadow` or `adaptive` |
+| `layers` | `{}` | Per-layer on/off, edited with `/layers`, not `/config set` |
+
+`ASSISTANT_ACTIVITY_LOG=1` additionally appends a debug activity log to
+`activity-log.jsonl` in the data directory (created `0600`). All CLI output has
+terminal escape sequences stripped, so text echoed from a fetched page or file
+cannot rewrite what an approval prompt shows.
+
 ### Lexical checks (off by default)
 
 Every lexical pass in this package (regex / keyword / phrase-list checks over natural-language text) sits
@@ -853,8 +917,10 @@ plan step saved without its own risk level is treated as HIGH.
 
 ## REPL commands
 
-Type `/help` inside a running CLI session for this list. All of them read or
-change local session/config state — none of them make an LLM call themselves.
+Type `/help` inside a running CLI session for this list. Almost all of them read or
+change local session/config state without an LLM call; the exceptions are `/plan sketch`
+and `/memory consolidate`, each of which makes one. `/exit` (also `/quit`, `exit`, `quit`)
+ends the session.
 
 | Command | What it does |
 |---|---|
@@ -863,15 +929,27 @@ change local session/config state — none of them make an LLM call themselves.
 | `/status` | Show the resolved config (model, backend, workspace, enabled capabilities — same as the startup banner) plus this session's transcript length and whether a plan is active |
 | `/export [file]` | Save this session's transcript to a markdown file (default: `assistant-transcript-<timestamp>.md` in the current directory) |
 | `/undo` | Remove the last exchange from conversation history — a completed turn drops both the user message and the reply; a turn still awaiting approval drops just the pending message. Only affects what the model remembers: a real `write_file`/`run_shell_command` effect from that turn is **not** reversed |
-| `/memory` | Show facts learned about you, reminders created so far, and the learning-layer `ExperienceStore`'s real content — every strategy weight, plus the 20 most recently learned decompositions/recovery sequences (newest first), not just counts |
+| `/undo-action [id]` | List the real filesystem effects of approved actions that can still be reverted (see `/status`'s undo-log line), or stage a revert of one for your approval |
+| `/memory` | Show facts learned about you, pending-confirmation guesses, reminders created so far, and the learning-layer `ExperienceStore`'s real content — every strategy weight, plus the 20 most recently learned decompositions/recovery sequences (newest first), not just counts |
+| `/memory confirm <n\|category>` / `/memory reject <n\|category>` | Promote a pending-confirmation guess (or a whole category) to durable memory, or discard it |
+| `/memory forget <n> [erase]` | Remove a learned fact by its number in "Facts I know". It stays restorable through the audit log (`/memory undo`) unless you add `erase`, which scrubs its text from the log too. `/memory forget digest [id]` erases one stored session digest, or all of them |
+| `/memory history` / `/memory undo <seq>` | Show recent memory changes with their sequence numbers, and restore one change's pre-image (needs `AUDIT_MEMORY_AUDIT_LOG`) |
+| `/memory status` | Store size vs budget, pending count, write mode, last consolidation |
+| `/memory archive [restore <n> \| forget <n>]` | List facts set aside or replaced by a newer statement; restore one, or erase one for good |
+| `/memory consolidate [accept\|dismiss <n>]` | Propose merging or retiring overlapping facts; nothing changes until you accept (needs `AUDIT_MEMORY_CONSOLIDATION`) |
+| `/memory off` / `/memory on` | Stop or resume all memory writes for this install; existing facts stay readable and removable |
 | `/memory export [file]` | Write the full, unbounded `ExperienceStore` contents (every strategy weight/decomposition/recovery sequence, not the 20-entry preview `/memory` prints) plus facts/reminders to a JSON file (default: `assistant-memory-<timestamp>.json`). Read-only: there's no matching import path, so exported data can't be hand-edited and loaded back in |
 | `/search <query>` | Ranked search over past messages, across every session in this install — a hit is the one message that matched, not the whole session transcript around it. Read-only: never an LLM call or network request. Scoring is tokenized/graduated, not exact-substring-only (see "Conversation history" above), and a query matching nothing returns an explicit "no results" line |
+| `/project [name]` | Show or switch the project new project-scoped facts are tagged with; `/project clear` reverts to the workspace default |
 | `/model [name]` | Show the active model, or switch it — a thin alias over `/config set model <name>` (see "Configuration" above); rejected the same way if `model` is pinned by `ASSISTANT_MODEL` |
 | `/cost` | Show token usage for the last turn and the running session total |
-| `/doctor` | Check proxy reachability (proxy backend), plus workspace root and data dir health — no dedicated check yet for the anthropic/openai/openrouter backends, only the backend-agnostic checks run for those |
+| `/doctor` | Check proxy reachability (proxy backend) or the `claude` binary (claude-cli backend), plus workspace root and data dir health — no dedicated check yet for the anthropic/openai/openrouter backends, only the backend-agnostic checks run for those |
 | `/why` | Explain the harness path the last turn took (verification confidence + node sequence) |
+| `/layers` | Show all 11 harness layers: fired or skipped, and why, for the last turn. `/layers settings` lists the reasoning layers with their cost/evidence; `/layers on\|off\|reset <id>` changes a layer's persisted on/off choice (an operator-set `AUDIT_*` env flag wins and shows as pinned) |
 | `/sources` | List files/URLs the last turn actually consulted |
 | `/plan` | Show the active structured plan's task status |
+| `/plan sketch <request>` | One-shot, advisory plan sketch: no plan record, nothing staged, cannot execute |
+| `/goals` | Review every known goal thread this session: status, tasks and visibility (freshly computed, carried over, done, suggested) |
 | `/plan graph [thread-id]` | Draw the active plan as a read-only dependency graph (needs `planGraphMode` enabled; full-screen pane in the terminal UI with arrows/Tab/Enter/q, one static render in the plain REPL). Glyphs, mapping and keys: `docs/plan-visualization.md` |
 | `/checkpoint [clear]` | Inspect a stuck in-progress harness checkpoint (step, node, failed-resume count so far), or `/checkpoint clear` to discard it — see "Recovering a stuck checkpoint" above. Scoped to just the checkpoint: unlike `/clear`, transcript/facts/plan are untouched |
 

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

@@ -4,9 +4,24 @@ import { ShellToolsContext } from './shell-tools.js';
 import { ActionToolsContext } from './action-tools.js';
 import { AssistantTurnResult } from './assistant-types.js';
 import { AssistantSession } from './assistant-session.js';
-import { AgentLoop } from './agent-loop.js';
+import { AgentLoop, ToolLoopResult } from './agent-loop.js';
+import { AssistantToolStep } from './tool-step.js';
 import { TraceEvent } from './trace-events.js';
 import { DebugLogEntry } from './debug-log.js';
+/**
+ * Optional hooks for resuming a staged action that a flat tool loop paused on (see
+ * AgentLoop.resumeToolLoop): the live token/tool-step callbacks of the turn being resumed, and how
+ * to turn a *further* pause (another approval, or an escalation) into the turn result — the caller
+ * owns that because auto-approve modes live there, not here.
+ */
+export interface ResumeOptions {
+    onToken?: (token: string) => void;
+    onToolStep?: (step: AssistantToolStep) => void;
+    handleLoopPause?: (result: Extract<ToolLoopResult, {
+        kind: 'needs_approval' | 'escalated';
+    }>) => Promise<AssistantTurnResult>;
+}
+export { actionRecordSuffix } from './action-record.js';
 /**
  * Owns the "approval-by-ID" pattern: a staged write/shell/revert/batch-research action resolved
  * by ID, never re-derived from a second LLM call (see T4 of the file-tools plan). Split out in
@@ -25,8 +40,25 @@ export declare class ActionApprovalService {
     private readonly onTrace;
     private readonly onDebugLog;
     constructor(memory: MemoryAdapter, llmClient: ILLMClient, model: () => string | undefined, fileTools: FileToolsContext | undefined, shellTools: ShellToolsContext | undefined, actionTools: ActionToolsContext | undefined, session: AssistantSession, agentLoop: AgentLoop, onTrace: ((event: TraceEvent) => void) | undefined, onDebugLog: ((entry: DebugLogEntry) => void) | undefined);
+    /** Every write, command and email carried out through an approval, in order (a turn's slice is what the system recorded for it). */
+    readonly appliedActions: string[];
+    /** Parallel to appliedActions (same indices): for a write, the lines it changed as a short diff, so the reply audit can tell whether a reply's account of the file is true (W1); the same clause as appliedActions for every other kind. */
+    readonly appliedActionDetails: string[];
+    /** The command and the start/end of the output of each shell command run through an approval (for the reply audit). */
+    readonly recentCommandOutputs: {
+        command: string;
+        output: string;
+    }[];
+    /** Sessions in which a command got the network-containment refusal. */
+    private readonly networkDeniedSessions;
+    /** Pending-action ids currently being resolved (see resolvePendingAction). */
+    private readonly inFlightResolutions;
+    networkDenied(sessionId: string): boolean;
     /** Resumes a staged action by ID instead of re-deriving *what to run* from a second LLM call — see T4 of the file-tools plan. `userMessage` is only used to synthesize an answer from a shell command's real output (see below); the command/content actually applied always comes from the staged record, never from a fresh model call. */
-    resolvePendingAction(sessionId: string, transcriptKey: string, pendingActionId: string, approved: boolean, userMessage: string): Promise<AssistantTurnResult>;
+    resolvePendingAction(sessionId: string, transcriptKey: string, pendingActionId: string, approved: boolean, userMessage: string, resume?: ResumeOptions): Promise<AssistantTurnResult>;
+    private resolvePendingActionOnce;
+    /** The conversation before the current user message, for the no-tools synthesis call. The current message was already appended to the transcript when the turn paused, so it is dropped here. */
+    private recentHistory;
     /**
      * After resolvePendingAction resolves one staged action (approved or declined), checks whether
      * it was chained to a second approval-gated action staged from the same originating turn (see

package/dist/action-record.d.ts

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

package/dist/activity-log.d.ts

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

package/dist/agent-loop.d.ts

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

package/dist/assistant-session.d.ts

@@ -105,7 +105,10 @@ export declare class AssistantSession {
      * already correctly no-ops whenever no cap is configured, so this never enforces a cap that
      * isn't set.
      */
+    /** Tail of the chain serialising recordSpend's read-modify-write: the background memory reviewer records spend while a turn does, and the later write used to drop the other's cost. */
+    private spendChain;
     recordSpend(sessionId: string, usage: TokenUsage | undefined): Promise<void>;
+    private recordSpendNow;
     /** Read-only — null means plan mode has never been entered (or was already exited/cancelled) for this session (or this `threadId`, once Phase 5's per-thread rescoping applies — see `planModeKey`). */
     getPlanModeState(sessionId: string, threadId?: string): Promise<PlanModeState | null>;
     /**
@@ -140,9 +143,25 @@ export declare class AssistantSession {
      * caught and logged, never thrown — a search-indexing problem must never be able to break an
      * ordinary turn or lose the transcript message itself.
      */
-    appendTranscriptMessage(sessionId: string, transcriptKey: string, message: {
+    /**
+     * A message the user sent while a turn was running that the turn's model call already took into account
+     * (a mid-turn steering note). It belongs in the conversation as its own user message, in order: held here
+     * and written just before the next assistant message, i.e. after the running turn's own user message and
+     * before the reply it shaped. Without this the note vanished from the transcript.
+     */
+    recordAbsorbedSteering(sessionId: string, message: string): void;
+    private readonly absorbedSteering;
+    /**
+     * Called by ResponseService the moment a turn's final reply is stored, before the slower post-reply work
+     * (fact recording, goal evidence, grounding check) that still has to finish inside the turn. The assistant uses it
+     * to put the reply in the activity log right away (benchmark issue N2).
+     */
+    replyReadyHook?: (sessionId: string, reply: string) => void;
+    replyReady(sessionId: string, reply: string): void;
+    appendTranscriptMessage(sessionId: string, transcriptKey: string, input: {
         role: 'user' | 'assistant';
         content: string;
+        actionRecord?: string[];
     }): Promise<void>;
     /**
      * One-off, idempotent backfill for installs that already had transcript history before the

package/dist/assistant-types.d.ts

@@ -62,7 +62,7 @@ export interface AssistantTurnResult {
      * passes through this exactly once, regardless of risk (no risk-tiered skip — see
      * PlanApprovalService's doc comment).
      */
-    status: 'ok' | 'needs_approval' | 'escalated' | 'needs_clarification' | 'needs_plan_approval';
+    status: 'ok' | 'needs_approval' | 'escalated' | 'needs_clarification' | 'needs_plan_approval' | 'cancelled';
     reply: string | null;
     /**
      * Up to three concrete next steps proposed after a full (non-trivial, `ok`) turn, most confident
@@ -124,6 +124,8 @@ export interface AssistantTurnResult {
     contradictionNotice?: string;
     /** Set when the semantic change reviewer found the request conflicts with something the user stated earlier AND the answer could not be told so directly (a tool-less turn's draft already exists, so the proposer never reads the review note). Advisory only — the turn still completed. Mirrors `contradictionNotice`: a separate field, not folded into `reply`, because the CLI streams `reply` before the check runs. */
     reviewNotice?: string;
+    /** Set when the reply audit (reply-audit.ts) found a claim of work the system did not record, a promise of work not done, or unverified facts about outside sources. Separate from `reply` for the same reason as `reviewNotice`. */
+    auditNotice?: string;
     /**
      * An epistemic-honesty signal for replies that went through the harness loop (absent on the
      * triviality fast path, same "absent when unused" convention as trace/sources — a

package/dist/assistant.d.ts

@@ -48,6 +48,8 @@ export type MemoryPendingOutcome = {
 };
 export interface TurnOptions {
     sessionId?: string;
+    /** Internal: this turn is the one-time correction the reply audit asked for; it is not a user message and is never retried again. */
+    auditRetry?: boolean;
     /** 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;
@@ -80,6 +82,12 @@ export interface TurnOptions {
      * flag is off.
      */
     askMode?: AskMode;
+    /**
+     * Stops the turn: once it fires, no further model call starts or is kept, the transcript is left as it was before
+     * the turn, and `turn()` resolves with `status: 'cancelled'` right away. Ignored when resuming a staged action
+     * (`pendingActionId`), because that applies a write/shell/email the user already approved and must not be half-done.
+     */
+    signal?: AbortSignal;
     onProgress?: (progress: AssistantProgress) => void;
     /**
      * Called with each token as the model's reply streams in. On the plain chat
@@ -254,6 +262,8 @@ export interface PersonalAssistantOptions {
      * that never asks for suggestions makes no extra call and sees no new field (INV-43).
      */
     goalGraphSuggestMode?: GoalGraphSuggestMode;
+    /** Run the reply audit (reply-audit.ts) after each successful turn; defaults to the AIELIA_REPLY_AUDIT env gate (on). */
+    replyAudit?: boolean;
     /**
      * 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
@@ -300,6 +310,9 @@ export interface PersonalAssistantOptions {
  */
 export declare class PersonalAssistant {
     private readonly llmClient;
+    private readonly abortGate;
+    /** A stopped turn whose in-flight model call has not come back yet. Its gate stays armed until it settles, so it cannot write the transcript late. */
+    private stoppedWork?;
     private model?;
     private activeProject?;
     private memoryBudgetChars?;
@@ -335,6 +348,19 @@ export declare class PersonalAssistant {
     private readonly session;
     private readonly agentLoop;
     private readonly actionApproval;
+    /** Set when the reply was already logged by the reply-ready hook this turn (see AssistantSession.replyReadyHook). */
+    private replyLoggedEarly;
+    /** Automatic correction retries still allowed for the current user message; resumed (approval) turns share it so a retry cannot chain. */
+    private auditRetryBudget;
+    /** The session of the turn in progress, for log lines written by code that has no session of its own (the side-call retry note). */
+    private lastSessionId;
+    /** The last real (not fail-safe) risk classification of a user message, per session, for the audit retry that may correct its reply. */
+    private readonly lastClassifiedBySession;
+    /** Files, directories and pages each session's turns have read (tool and target, oldest first, capped): the reply audit needs reads from EARLIER turns too, or a correct answer about a file read last turn looks like an unverified outside fact (V1). In memory only; cleared with the session. */
+    private readonly sourcesReadBySession;
+    /** Index into the action list where the current user message's actions start; an approval resume is a separate turn() call but the same user message. */
+    private userMessageActionsStart;
+    private readonly replyAuditOn;
     private readonly planService;
     private readonly planApproval;
     private readonly planDrafting;
@@ -360,6 +386,8 @@ export declare class PersonalAssistant {
      * thread.
      */
     private nextStepContext;
+    /** Logs a message that arrived while a turn was running, at receipt time (its `user_message` is only logged when it is processed). */
+    logQueuedMessage(sessionId: string, message: string): void;
     /**
      * 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
@@ -386,6 +414,8 @@ 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. */
+    /** Remembers what a turn read (tool and target) for the reply audit of later turns; oldest entries drop first. */
+    private noteSourcesRead;
     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']>>>;
@@ -569,6 +599,8 @@ export declare class PersonalAssistant {
      * plan-cancel bypass, the triviality fast path) actually lives now.
      */
     private runTurn;
+    /** What ActionApprovalService needs to continue a paused tool loop after an approval: the live callbacks, and how a further pause becomes a turn result. */
+    private loopResumeOptions;
     /**
      * Shared by the flag-OFF flat/batch tool loop's own needs_approval/escalated ToolLoopResult and
      * the flag-ON harness-driven proposer's equivalent OneLoopPause (R3 of