@namzu/cli 23.0.0 → 25.0.0

package/CHANGELOG.md

@@ -1,5 +1,850 @@
 # @namzu/cli
 
+## 25.0.0
+
+### Major Changes
+
+- 9463b6f: Background job `read` and `list` calls now count as read-only observations by default; starting commands and `job kill` retain their existing approval requirements. SDK `defineTool` accepts an input predicate for `readOnly`.
+
+  Explicit CLI `ask` rules are now enforced rather than omitted, so they can request review ahead of a wildcard allowance or the read-only default. SDK custom-pattern rules support `decision: 'review'`, with an `authorization.explicitReview` marker on review summaries. Read-only and accept-edits exemptions honor it; explicit auto modes and prior approvals keep their meaning.
+
+  To keep reviewing every background-job operation in prompt mode, configure `permissions: { job: ask }`, or supply a matching SDK custom-pattern review rule. If an old `ask` entry was intended to inherit default behavior, remove that entry instead. Deny rules, plan-mode mutation restrictions, job ownership and sandbox boundaries remain enforced.
+
+- b2e5551: Default CLI main runs and built-in delegated agents to unlimited token usage,
+  iterations and run duration. Previously main runs defaulted to 50 iterations,
+  children to 40, and both to a one-hour deadline. To keep bounded execution, set
+  positive `limits.maxIterations` and `limits.timeoutMs` in your configuration;
+  explicit values apply to both the main run and built-in children. SDK embedding
+  defaults and file-defined specialist iteration settings remain unchanged.
+
+  Add Run limits to `/config`: edit tokens, model turns and duration, or remove all
+  three caps. Changes apply to new turns and their children for the current TUI
+  session; running work retains its captured limits and usage ledger. Resuming a paused
+  CLI run reloads its own saved limits instead of replacing them with launch defaults. Persistent
+  limits still come from the configuration files. Usage accounting, cancellation,
+  permissions and provider quotas continue to apply in unlimited mode.
+
+- fe6e0fb: Avoid reading and parsing a shared compaction record once for every removed
+  message. A search reuses one authenticated record within that operation; later
+  calls revalidate it. Text manifests, integrity checks, cancellation and page
+  limits remain in effect.
+
+  CLI manual compaction now stores one `compaction_shed` event containing all
+  removed messages, matching automatic compaction, instead of one event per message.
+  Consumers of raw manual-maintenance events must iterate the `messages` array
+  and use search results' `seq` and `part` addresses, rather than assuming `part: 0`
+  or one sequence per message. Existing archives and SDK event readers remain
+  supported. No config change is required for ordinary CLI use.
+
+- 64b3da9: New `search_conversation` calls now exclude successful outputs of `search_conversation` and `read_conversation` by default. Previously, explicit searches included them and could find their own earlier results as repeated evidence.
+
+  To keep the previous unfiltered behavior or inspect retrieval outputs themselves, pass `includeRetrievalResults: true` on a new search. Omit the option when continuing a cursor: its source filter is preserved, and incompatible changes are rejected. Failed retrievals and records with unknown tool names or success status remain searchable. Exact reads of known authorized records remain available. SDK evidence-source defaults are unchanged.
+
+- cff2b6a: Conversation search now ignores letter case by default: searching for `destination` also finds `Destination`. Pass `caseSensitive: true` to `search_conversation` to keep the former behavior. Continue pages with the same query and case setting.
+
+  SDK run-evidence search adds optional `caseSensitive` (default `true`, unchanged). Active and closed run sources now return distinct matching passages within one text chunk, with continuation at the match limit, rather than hiding later passages in that chunk. Exact retained text, UTF-8/UTF-16 offsets, integrity verification and per-call I/O limits remain intact. Case-insensitive searches bypass exact-case filters and may read more bytes or require more pages.
+
+- 32080b1: Durable `drain` now mounts `search_conversation` and `read_conversation` under
+  the persisted conversation's ownership and honors configured compaction,
+  memory and web options. These options were previously omitted from its host.
+  It can recover original retained command output without running the command
+  again or treating an internal backing file as workspace content.
+
+  The retained-output preview default on this entrypoint now follows the CLI's
+  4,000-character setting instead of its previous 40,000-character preview. Set
+  `compaction.retainedToolPreviewChars: 0` to preserve the former preview behavior.
+  Previously ignored compaction, memory and web configuration now takes effect;
+  review those keys when upgrading an unattended drainer.
+
+  A resumed run that ends as failed or cancelled is now reported in `failed`
+  with exit code 1 instead of being reported as a successful drain.
+
+- b2d5b01: Support explicit unlimited run guards while retaining measured token usage.
+  Set `tokenBudget: 0`, `maxIterations: 0` and `timeoutMs: 0` in SDK run options,
+  or in the CLI's `limits` configuration, to disable those three caps. The CLI's
+  `--token-budget 0` and `--max-iterations 0` now override configured caps; blank,
+  negative and unsafe numeric values are refused. Omitted defaults are unchanged.
+
+  SDK breaking change: `maxIterations: 0` and `timeoutMs: 0` previously prevented
+  progress; they now disable those guards, consistently with the token limit.
+  Hosts that used zero to prevent a run from starting must refuse admission or
+  pass an already-aborted signal instead. Use positive values for finite guards.
+
+  CLI breaking change: an explicitly configured `limits.maxIterations` now applies
+  to built-in subagents too, instead of always giving them 40 iterations. Existing
+  configurations with a smaller value can stop children earlier; larger values
+  permit more work. Omit that setting to retain the previous child default (40)
+  and parent default (50), or define a specialist agent with its own iteration
+  configuration when the two must differ. The new `limits.timeoutMs` setting also
+  reaches child runs and blocking delegation tools. `0` does not bypass a finite
+  ancestor token cap, permissions, operator cancellation or unresolved usage.
+
+- f49a4b8: Add optional run-metered, tool-free `PrepareStepContext.generateText` and
+  `createEvidenceRecallStep({ resolveQuery: true })` for resolving historical
+  follow-ups against bounded visible conversation. Generated search terms must
+  occur in the question or exact cited history. SDK query resolution defaults off.
+
+  In the CLI, conversations with `compaction.recallEvidence: true` now resolve
+  eligible conversational queries by default. This can add one provider request
+  per operator input, up to 512 output tokens and ten seconds before local
+  retrieval. It consumes the same run token budget. Set
+  `compaction.resolveEvidenceQueries: false` to keep the previous literal-query,
+  local-only behavior. Automatic recall itself still defaults off.
+
+- c4aaf9b: Interactive CLI sessions now honor `limits.maxIterations` and `limits.tokenBudget` from user and trusted project configuration. Previously these configured limits were ignored by TUI startup, although headless commands applied them. This also applies when rebuilding a session after a model change or reopening a conversation. To keep interactive cumulative tokens unlimited, omit `limits.tokenBudget` from the effective config and use `--token-budget` for individual headless runs. Omitted defaults remain unchanged; `limits.waitForProviderMs` remains a headless policy.
+
+  SDK closing prose requested by a token, cost or time warning now preserves the triggering limit's stop reason instead of reporting `end_turn`. The partial text is still returned, including when allowance remains, but this path skips prose answer review and must not be treated as verified completion. Cancellation and validated native structured-output settlement retain their existing behavior.
+
+- 97acc32: Resident run/start now automatically retrieve bounded original tool evidence
+  from earlier settled admissions before model requests, under both context
+  profiles. Previously these admissions exposed explicit archive tools only.
+  Set `compaction.recallEvidence: false` to retain that previous behavior. This
+  adds local archive I/O and request context; it does not add query-planning
+  inference, replay actions or grant ordinary chats/delegated agents access.
+
+  SDK hosts can attach `createResidentEvidenceRecallStep` to an admitted run.
+  It preserves historical Session/run/claim addresses and shares bounded evidence
+  selection with conversation recall. Resident tool sources also support bounded
+  token queries and exact cursor-only recovery, retaining query/filter identity
+  across reopening. Incomplete results do not establish absence.
+
+  Resident Sessions now leave signal handling to their enclosing host. Previously
+  the SDK emergency handler could exit immediately on SIGINT/SIGTERM before the
+  host wrote cleanup/runner receipts. Cancellation now drains through the resident
+  lifecycle and preserves the interrupted claim for inspected reconciliation.
+
+- 6cd24e9: Enable automatic historical evidence recall by default in recorded CLI conversations, including resumed conversations and resident turns using the conversation host. Previously, omitted `compaction.recallEvidence` disabled this preparation even when original tool text had been shortened to a retained preview.
+
+  Follow-ups may now make an additional bounded, metered model call to resolve the historical subject, then read scoped conversation evidence into the next request. This adds inference usage and possible latency; it shares the run's provider, effort, token budget and cancellation. Retrieval retains its existing four-page, 8 MiB read and 6,000-character context ceilings.
+
+  Set `compaction.recallEvidence: false` to retain the previous default, disabling both automatic archive reads and query-planning inference. Set `compaction.resolveEvidenceQueries: false` to keep automatic literal retrieval without the extra inference. Explicit archive tools remain available. SDK host defaults and stateless archive access are unchanged.
+
+- f92daf8: Resident `run` and `start` now default to `--learning-disclosure on-demand` in the resident context profile. Previously all accepted learned skill bodies were included automatically; now the model sees their descriptions and can read relevant guidance with `read_resident_skill`. To retain automatic inclusion, pass `--learning-disclosure eager`. The interactive context profile and ordinary chat retain their existing behavior. Stored learning is unchanged.
+
+  The SDK adds `createResidentStepContext`, which returns prompt contributions and a read-only skill tool bound by the host to one admitted run. Source dependencies are checked when instructions are read and before subsequent requests. Existing `createResidentStepContributions` callers retain eager disclosure.
+
+- 5d31eea: Resident learning hosts and direct skill promotions now require a `protection` plan with disjoint `verification` and `confirmation` task IDs chosen before candidate generation. Existing hosts without this field are refused before inference. Include at least one real preservation task per round, with two measured successful baseline trials and two successful candidate trials. Missing or uncertain controls block activation; losing one established success rejects the candidate even when aggregate scores improve.
+
+  Update `ResidentLearningCycleOptions`, discovery hosts, and `ResidentSkillEvaluation` callers to supply this plan and its actual paired evidence. Historical stored skills remain readable but do not gain protection evidence retroactively. Generic `reviewHarnessCandidate` callers can opt into the same checks with its third argument. CLI learning summaries display protected-task outcomes.
+
+- f1e33a1: Resident wake calls now retain all accepted inputs until the next step settles, instead of replacing the previous wake reason. `ResidentState.wakeEvidence` exposes immutable reasons and receipt times; the SDK resident prompt and both CLI resident profiles include the complete batch. CLI resident status shows pending input counts.
+
+  The new default accepts at most 16 pending inputs and 16,000 total reason characters per pursuit. Overflow rejects the new wake without discarding accepted evidence. Callers that previously sent an unlimited series of replacement wakes must process each batch before sending more, or coalesce superseded inputs before calling `wake`. Custom callbacks should read `wakeEvidence` rather than only the latest `reason`.
+
+  Standalone resident records now write schema 2 and agenda records schema 6. Older processes refuse these new formats: upgrade all processes sharing the store together. Prior formats remain readable without inventing historical inputs. Crashed steps keep their pending evidence; only successful exact-claim settlement or explicit inspected reconciliation consumes it.
+
+- b888779: Separate the SDK's overflow threshold from the size of an authenticated retained-output preview. `query`/`resumeRun` and `ReactiveAgent` accept `retainedToolPreviewChars`; unset or zero preserves the existing behavior. A shorter preview is used only after full host text and its integrity manifest are saved. Storage failure keeps the ordinary text budget. Rich blocks and independently supplied model text keep their existing handling.
+
+  Recorded CLI conversations now default to at most 4,000 characters for these retained overflow previews, previously up to 40,000. The 40,000-character spill threshold and ordinary smaller results are unchanged. Set `compaction.retainedToolPreviewChars: 0` in CLI configuration to retain the previous preview size. This applies to new tool results in ordinary turns and resumed runs, without rewriting existing history. Stateless sessions and delegated workers retain their existing defaults.
+
+- ea5367d: The CLI now requires Node.js 22.13+ and stores session metadata in
+  `NAMZU_HOME/state/sessions.sqlite`, with artifacts directly under
+  `NAMZU_HOME/sessions/<sessionId>/`. It no longer creates or reads a `projects/`
+  runtime tree. Generated memory remains isolated under `memory/<projectId>/`,
+  and resident state moves to `residents/<projectId>/<agent>/`.
+
+  This changes the default persisted CLI format. Existing project trees are left
+  untouched and are not imported automatically. Back up the original application
+  home and retain the older CLI to access its conversations, generated memory
+  and residents. Credentials, preferences and authored configuration keep their
+  locations. Update custom artifact readers to the new session paths.
+
+  The SDK adds the optional `SqliteSessionStore` driver and an exact `directory`
+  option for `DiskMemoryStore`. Existing SDK drivers, formats and defaults remain
+  unchanged; SQLite is loaded only when its driver is used.
+
+  `history` now accepts real conversation UUIDs as well as host keys, and with no
+  key reads the most recent workspace conversation as its help documents.
+
+### Minor Changes
+
+- 2a1e0e5: Preserve provider-identified public assistant message items through streaming,
+  settlement and conversation persistence. The SDK adds optional `textParts`
+  snapshots, `textPart` delta metadata and `selectAssistantText`. Completed content
+  selects explicitly final answers instead of concatenating intermediate progress
+  into the answer; ordinary unphased streams retain their existing behavior.
+
+  The Codex subscription driver maps native message phases and verifies the original
+  public parts before native replay. The CLI exposes optional item metadata on
+  delta events, separates streamed item bubbles and uses the settled answer for
+  turn completion. Consumers that manually concatenate deltas should use completed
+  content when they want the final answer; deltas still contain public progress.
+
+- ce55c21: Add experimental `createEvidenceRecallStep` and its typed host retrieval contract.
+  It ranks a bounded pool of authenticated historical passages and supplies exact
+  excerpts with source/error/preview labels in request-only context. Every request
+  revalidates ownership and source data; deadlines discard late reads without
+  accumulating overlapping retrieval or replaying actions.
+
+  Recorded CLI conversations can opt in with `compaction.recallEvidence: true`.
+  The default remains off. Automatic recall excludes the requesting invocation;
+  explicit conversation search/read still cover live evidence, more pages and
+  complete text. This adds historical context, not automatic verification of
+  current workspace state or a guarantee of exhaustive recall.
+
+- bb0281b: Add optional `EvidenceRecallBatch.continuations` with exported
+  `EvidenceRecallContinuation` hints for bounded, host-mounted read-only tools.
+  Incomplete recall now reports its status even when no new passage is selected,
+  so missing context cannot silently look like an exhaustive negative search.
+  Hint arguments and output are bounded within the existing context allowance.
+
+  CLI `search_conversation` accepts `cursor` alone to restore the original query,
+  case setting and excluded invocation. Automatic recall supplies these handles
+  when live or earlier-run traversal has more pages. The model can continue from
+  that position without replaying an action or starting the same scan again.
+  New searches still require a literal query. Scope, expiry, source-integrity
+  checks and read limits remain enforced; live handles require the same active
+  writer and never downgrade to another source. Automatic recall remains opt-in.
+
+- 2869fbe: Add an optional SQLite resident learning journal with atomic event/summary updates, scoped ancestry and recorded usage, plus hash-verified immutable JSON artifacts. `runStoredResidentLearningCycle` connects existing generation and independent evaluation callbacks to the journal without adding another model loop. The store requires Node.js 22.13 or newer when used; other SDK stores retain their existing support.
+
+  Add `namzu resident learn <experiment.learning.mjs>` for explicit trusted host modules and `namzu resident learning [cycle-id]` for read-only inspection. Modules select and bound their own providers and evaluators. Interrupted work and incomplete prices remain visible; these commands do not automatically replay experiments, activate unverified guidance or start background learning. Records live in `state/learning.sqlite` and `learning/artifacts/`; accepted skills remain in the existing resident agenda.
+
+  Expose `pathBuilder`, `runStore` and `checkpointStore` on `runAgent`, forwarding the kernel's existing host storage controls. Hosts can separate generated execution evidence from a searched workspace. Omitting these options preserves the SDK's current local layout; the CLI retains its application-home layout.
+
+- d5d2b9a: Expose optional `recordedAt` Unix milliseconds on evidence search matches, exact read pages and recall candidates. CLI conversation search/read and automatic recall preserve the stored event time, including each included occurrence of equal text. Callers can distinguish recording times without inferring them from run IDs, file times or run-start metadata.
+
+  Unknown or invalid stored timestamps stay absent; custom recall callbacks must omit unknown times and supply positive integer milliseconds within the JavaScript Date range when known. The timestamp dates recording, not fact validity; compaction copies carry their own copy time. Sequence still orders one run, and clocks across runs do not establish causal order. Existing retrieval ordering, scope, read limits and source validation remain unchanged.
+
+- b971796: Expose `classifyEvidenceSource`, `EvidenceRecordKind` and `EVIDENCE_RECORD_GUIDANCE` for hosts presenting authenticated text evidence. Automatic recall uses the same classification. The helper interprets source tags only; it does not authenticate text or establish that its claims are true.
+
+  CLI `search_conversation` matches and located `read_conversation` pages now include `recordKind` with interpretation guidance. Exact reads also preserve recorded `toolName` and `isError`, leaving missing status unknown. Tool names exceeding 256 JSON-encoded UTF-8 bytes are omitted consistently. Original text, addresses, scope checks and pagination remain unchanged.
+
+- 0a0baf2: Add bounded resident activity inspection and a reusable consumption projection in the SDK. The CLI's new `namzu resident inspect` command reports retained admissions, settlements, archived pursuits, historical verification receipts and known versus missing usage across process restarts.
+
+  Root usage and descendant-inclusive token totals remain separate. Missing or interrupted receipts are explicitly incomplete; unpriced tokens do not imply free work. Cost reports cover the root invocation, not descendant prices or a provider bill. Inspection does not impose a new lifetime spending limit or change existing execution defaults. Use `--max-revisions` or the returned `--cursor` to inspect histories beyond the default bounded range.
+
+- 4828eb0: Add opt-in learning discovery from retained, host-scored failures. Hosts can record observations and authorize evaluator revisions; the SDK selects an eligible task against the installed guidance, then uses the existing generation, verification and fresh confirmation cycle. Task claims survive process restarts and prevent concurrent or accidental duplicate experiments. Provider errors, unresolved usage and obsolete observations are excluded from selection.
+
+  The CLI accepts discovery hosts in `resident learn` and adds `resident learning --observations` for paginated inspection. Compact output includes failure reasons and verification/confirmation pass counts so inspection does not require following raw artifact hashes. Existing explicit-failure hosts remain supported. Learning storage upgrades to schema 2 on its next write; older SDK builds restricted to schema 1 cannot reopen that upgraded database. Keep a database backup if a rollback to such a build is required.
+
+- b649224: Expose optional `PrepareStepContext.captureRunEvidence(maxReadBytes?, signal?)`
+  for authenticated text from the current invocation's writer. It rejects local
+  or run cancellation and settled invocations; unsupported stores return
+  `undefined`. Automatic evidence recall forwards this capability with its own
+  deadline and revokes new captures when the recall pass ends.
+
+  With `compaction.recallEvidence: true`, recorded CLI turns now recall missing
+  observations from the current run, including after compaction. Up to two live
+  pages share the existing four-page, 8 MiB read ceiling with earlier runs;
+  explicit conversation tools still handle further pages and exact full text.
+  The default remains off. Captured observations describe the past and do not
+  establish current workspace contents or replay a tool action.
+
+- e0b30c2: The `/plugins` menu can now explicitly remember a plugin's enabled or disabled state across restarts and model switches. Session-only controls keep their existing behavior. A remembered disabled plugin remains visible without importing its executable modules or starting its MCP servers. Choices belong to the plugin's canonical directory and name, so another project's same-named plugin is unaffected. Settings are stored privately in `NAMZU_HOME/plugin-settings`; loading configuration and project trust still apply.
+- 6394010: Learning hosts can supply an optional `explore` callback to run environment experiments before generating guidance. The SDK retains bounded observations and their digest, then provides them to `generate` as `context.exploration`. Missing usage, cancellation, stale state or evidence-journal failure prevents continuing to synthesis or activation.
+
+  The CLI forwards the callback, shows its exploration phase and retains evidence in SQLite. Hosts that omit it keep their current behavior. Event consumers opting into this feature should handle the new `explore` stage and `exploration` event kind. Exploration needs separately authorized tools and independent evaluation; enabling it does not automatically start learning in ordinary conversations.
+
+- f4b3ffb: Residents can retrieve earlier settled summaries and consumed wake inputs when
+  the latest summary omits needed evidence. The SDK adds experimental
+  `DiskResidentAgenda.history`, `ResidentHistorySource` and related result types,
+  `buildResidentHistoryTools`, and optional `ResidentStepPromptOptions.history`.
+  Searches are bounded and paged, tied to one pursuit and an explicit upper
+  revision, and report unreadable evidence without treating it as proven absence.
+
+  CLI foreground and managed resident runs mount the two read-only recall tools
+  in both context profiles, including deferred loading. Ordinary conversations
+  and delegated children do not inherit the resident's history. These tools read
+  existing immutable revisions; they do not restore full tool transcripts, replay
+  actions, or change the persisted schema.
+
+- d1a6ce5: Residents can search and page original retained tool text from earlier settled invocations, even when the latest summary or compacted context omits it. The SDK adds bounded disk indexing, scoped source interfaces and `search_resident_tools` / `read_resident_tool` builders. The CLI binds them to the admitted pursuit, matching attempt receipts and invocation ownership; ordinary conversations gain no cross-session access.
+
+  Fix fresh disk-backed runs capturing their output directory before store initialization, which could leave oversized tool output as an unrecoverable preview. New spills record chunk integrity manifests, and new run metadata records its own tenant/project/Session/run scope independently of shared token accounting. The existing 40,000-character model-visible cap remains unchanged. Older unscoped runs are unavailable through this API; older truncated records without authenticated spills remain explicitly partial. Missing or modified output is never replayed or presented as an intact original.
+
+- 8095541: Allow resident skill candidates to declare source revision dependencies. Their approval hash includes those bindings, and context projection withholds a bound skill unless every dependency matches fresh host observations. Unbound candidates keep their existing hashes and behavior. SDK hosts can resolve revisions per model request; the CLI resident profile supports bounded workspace-file SHA-256 observations.
+
+  Correct TUI stop messages for unresolved usage and accounting failures, including unlimited runs, so they no longer claim the token allowance was exhausted.
+
+- bdf923d: Add `/plugins` to inspect loaded plugins and enable or disable them for an idle session. The menu reports registered tools and skills, shows plugin scope and directory, and explains how to configure loading when it is off. Changes reset on restart or model switch; configuration and plugin files are retained. Active sends, compaction and durable resumes prevent plugin changes, and session cleanup waits for a pending change to settle.
+
+  Fix discovery when project and user plugin locations resolve to the same directory under an explicit application home. Load that directory once as user scope; project-only scope still excludes it. Distinct plugin directories remain discoverable even if their authority roots match.
+
+- 0a36260: Add `createJsonClaimVerifier` for host-configured scalar JSON claims and observation-time receipts. It rejects mismatched, incomplete, historical or foreign observations, bounds verification time and bytes, and exposes pending observation drainage. Hosts supply an authorized read adapter; this does not verify arbitrary prose or establish atomic/future source state.
+
+  Resident `run` and `start` accept `--verify <manifest>` to require configured claims before recording completion. The manifest explicitly authorizes bounded host file reads, is snapshotted per invocation, and applies to every admitted pursuit. Rejected values use the existing repair budget; only the reviewed answer can complete. Existing invocation behavior is unchanged without the flag.
+
+### Patch Changes
+
+- 7bb8163: SDK evidence sources now accept `matchMode: 'token'` for complete Unicode
+  letter/number/underscore terms, with the same lowercase keys used by bounded
+  evidence ranking. The default remains literal substring search. Token queries
+  must contain one token per term; use literal mode for phrases or punctuation.
+  Continuations retain their matching mode, and token search authenticates the
+  preceding chunk when checking a word boundary within the existing I/O budget.
+
+  CLI automatic evidence recall uses this mode to keep incidental substrings
+  such as `in` inside `Packing`, or `3` inside `13000`, from consuming its candidate
+  slots. Explicit conversation search still supports literal substrings.
+  Whole-word frequency can still limit bounded discovery; this change does not
+  claim complete or globally ranked archive retrieval.
+
+- 6663561: Prose `reviewAnswer` callbacks now fail the run when they throw or return a malformed verdict. Previously a thrown error accepted the answer without review. To keep a deliberately permissive policy, catch the error in the host callback and explicitly return `{ accept: true }`; return `{ accept: false, feedback }` only when requesting a bounded correction. Rejection feedback must be a nonempty string.
+
+  `maxAnswerReviews` now rejects negative, fractional, non-finite or unsafe values. Use a nonnegative safe integer (default three corrections). Rejection counts and feedback are saved together in checkpoints, so resuming the same checkpoint preserves the remaining allowance even after history compaction. Cancellation stops waiting for a pending reviewer; external work started by the callback must still honor its signal.
+
+  The CLI inherits these SDK semantics for host-supplied reviewers. Its command gate already converts unavailable checks to bounded rejection and keeps that behavior. Forced finalization, terminal tools and structured output retain their separate settlement paths.
+
+- 6e4a820: Recover original oversized tool text in ordinary conversations after compaction or restart. `search_conversation` and `read_conversation` now use authenticated retained output for closed scoped runs while preserving assistant-message and compaction-history search. Search results can provide a UTF-8 byte position for reading near a match; returned character positions remain UTF-16. Missing or changed originals are explicitly unavailable, and partial legacy records remain previews.
+
+  The SDK adds `createDiskRunTextEvidenceSource` and its public types, a bounded text view alongside the existing tool-only evidence source, plus an optional smaller per-operation read ceiling. New spill manifests record character positions without changing the existing tool-only source interface.
+
+  Headless `run --resume`/`--continue` and persistent `run-stream --session` now receive conversation retrieval tools. Both search and read remain available with deferred tool loading. Hosts still authorize the invoking conversation; no tool is replayed to recover its result.
+
+- bde219d: Preserve underscores within identifiers in assistant replies. For example,
+  `RUN_LIMITS_READY` now displays exactly as returned instead of losing its
+  underscores to italic formatting. Standalone underscore emphasis still works;
+  stored conversation content is unchanged.
+- 61d47e1: Clean up application homes created by the CLI test suite after both passing and failing tests, with a run-owned parent and final runner-exit sweep for late TUI persistence. Explicitly supplied homes remain untouched, including when a test changes `NAMZU_HOME`. This prevents development and CI runs from accumulating temporary session state; installed CLI behavior is unchanged.
+- eb2e7ba: Preserve Codex native response items when the subscription stream sends them as completed output-item events but leaves the final response output empty. Newly recorded conversations now retain those reasoning and tool-call items for eligible tool continuations and resume. The same correction retains hosted citations and reports tool-call finish reasons correctly. Existing route and message-integrity checks remain in force; native state already discarded by older versions cannot be recovered by upgrading.
+- 738d012: Recover a retained conversation passage after restart without spending a model
+  turn on every empty index page. Each read now advances through at most eight
+  lookup pages within its existing 8 MiB allowance, checking source ownership and
+  integrity before each operation. A continuation still returns when the work or
+  byte allowance requires another call. Durable addresses, exact text, read offsets
+  and cancellation behavior are unchanged.
+- bd4bd2e: Allow automatic evidence-query resolution to use one explicitly marked compaction summary as a derived lookup reference after original turns leave visible history. The existing six-excerpt, 64-message and inference limits remain; ordinary system policy and tool text are excluded. Query-resolution basis metadata may now include `source: "compaction-summary"`. This provenance marks a derived reference, not proof of the requested fact: answers still require retained originals. Recorded CLI conversations use this through their existing recall configuration.
+- 17933cf: Conversation search now advances through fully searched, nonmatching indexed runs in the same call instead of requiring a model round trip for each irrelevant run. It keeps the shared 8 MiB read ceiling, bounded directory discovery, source ownership checks and existing result limits. Partial index pages and matching pages still return control with a continuation when needed; unavailable evidence remains explicitly incomplete.
+
+  The read tool now asks the model to copy the search result's exact byte position, and gives actionable recovery guidance when an estimated position splits a UTF-8 character. It continues to refuse invalid reads rather than silently adjusting the requested position.
+
+- f1cd16e: Conversation search and read results now show concise source and page-status summaries in the TUI. Retained previews, partial pages, unavailable search runs and recorded tool errors stay visible instead of appearing as plain complete text. Ctrl+O retains the full returned JSON and uses a single-line window heading. Tool responses sent to the model, stored evidence, access checks and retrieval limits are unchanged.
+- 77eac40: Conversation search can return matches from several completely searched runs in one call instead of stopping at the first matching run. The existing result limit, 12,000-byte match allowance, 8 MiB read ceiling and bounded directory discovery still apply. The host reserves output space before each SDK operation and adjusts its requested match count to the available room, including escaped text and source metadata. Partial index pages still yield their continuation, and missing or changed evidence remains incomplete. Callers should continue to use returned cursors rather than assume a page belongs to one run.
+- df686fc: System messages can now carry `source: { type: 'compaction-summary' }`.
+  Kernel-generated compaction summaries receive this marker. When retained,
+  their text is searchable and readable as `compaction_shed:summary`, preserving
+  exact text and existing part positions. Ordinary system text with the same
+  heading and older unmarked archives keep their previous classification.
+
+  Automatic evidence recall orders matching source records before known derived
+  summaries within its bounded candidate pool, using separate relevance statistics.
+  Summaries remain available as passages and exact read addresses; they are not
+  deleted. CLI evidence guidance explains that these are derived text, not
+  independent observations. Recall limits and opt-in settings are unchanged.
+
+- e954d02: Automatic evidence recall now reports `omittedPassages` when eligible distinct
+  records do not fit the selected passage count or context size. Bounded
+  `additionalEvidence` addresses let archive tools recover withheld text;
+  `omittedAddresses` reports addresses which also could not fit. The original
+  scope checks and character ceiling remain in force.
+
+  The context can now retain an omission notice and read address even when no
+  whole excerpt fits. `incomplete` continues to describe source traversal, rather
+  than implying that every matched record was presented. In the CLI these
+  addresses work with the existing `read_conversation` tool. This corrects hidden
+  selection loss without changing the recall opt-in or adding model calls to the
+  retrieval hook itself.
+
+- df143c8: Expose optional `excerptComplete` on retained-evidence search matches and recall candidates. Built-in sources prove whether the displayed excerpt contains a whole full-retained text part using validated UTF-8 bounds. A partial excerpt or retained preview reports false; custom sources that omit the field remain unknown.
+
+  CLI conversation search and automatic recall preserve this information and explain when reading the same unchanged part adds no text or independent evidence. The field describes one text part, not the truth of its claims or coverage of the whole conversation. Existing scope, integrity, cancellation and context limits remain enforced.
+
+- 45c8292: Fix opt-in evidence query resolution skipping follow-up questions after six or
+  more assistant progress messages. Within the existing 64-message scan, retain
+  the nearest preceding operator request and five recent updates when progress
+  would otherwise fill all six reference slots. The prompt, retrieval and scan
+  ceilings remain unchanged. A missing or compacted-away request is not invented.
+
+  Do not rewind the reference window to an older identical question when the
+  current retained input is outside visible history, such as steering carried on
+  a tool result. Use the known message object as the boundary when available;
+  otherwise consider bounded recent history instead of inventing a position.
+
+  Normalize grounded filenames and punctuation-separated identifiers into the
+  same word tokens used by evidence discovery. A valid term such as
+  `sevkiyatlar.txt` no longer causes the entire optional plan to fail; all expanded
+  tokens must remain grounded and fit the existing 16-token ceiling.
+
+  Cover this behavior through the CLI Session host, including the existing
+  `resolveEvidenceQueries: false` opt-out. The CLI adds no default model call.
+
+- 6a6921c: Report unavailable automatic historical evidence in temporary model context instead of silently dropping every sign of a failed query plan or read. The short status distinguishes planning failure, retrieval failure, timeout and an earlier read still pending; it does not imply that the requested history is absent.
+
+  Raw error bodies, malformed plans and rejected source data stay out of the note. Existing error diagnostics and direct callback rejections remain, parent cancellation stops work, and context/read bounds still apply. Explicit archive tools remain available, and a failed cached query plan does not trigger an extra model call each iteration. No status note is stored as operator conversation history.
+
+- 691342c: Automatic conversation recall now labels selected passages and visible-source
+  references with their producer kind. Prior assistant statements are identified
+  as claims rather than proof of observed file state or successful actions.
+
+  Within the existing candidate and context limits, selection keeps the best
+  lexical match first and then considers matching records from other producer
+  kinds before repeating a kind. This prevents repeated model claims from taking
+  every slot when a tool record is available. Derived summaries remain last.
+  Archive bytes, explicit search/read tools and access boundaries are unchanged;
+  these labels and ranking do not establish truth or independent corroboration.
+
+- 612879e: Recover text blocks in compacted tool results that also contain images or
+  documents. Scoped conversation search and exact reads now include those blocks
+  after compaction and restart, without mixing binary bytes or inserted separators
+  into the text. Existing plain-text part addresses keep pointing to the same
+  content. Newly written large archives retain the additional text parts; old
+  archives are not rewritten. Unindexed legacy scans report skipped block arrays
+  as incomplete instead of claiming a complete search. No configuration changes
+  are required; automatic CLI recall remains opt-in.
+- e7bc7a1: When optional conversation query planning finds competing referents, preserve
+  that interpretation for the main model instead of silently skipping recall.
+  A temporary note carries validated quotes and asks the model to clarify if
+  needed; it is labelled as a fallible interpretation, not historical evidence.
+  No subject is selected for automatic retrieval in this case. The note shares
+  the existing context allowance and cancellation, and new operator input clears
+  the cached interpretation. SDK defaults and CLI configuration keys are unchanged.
+- 3e09024: Learning candidates and learning cycles can declare `purpose: 'exploration'` for instructions intended to improve an explorer. Their purpose is covered by the content digest, and generation cannot redirect the host-admitted purpose. A skill cannot change purpose under the same name.
+
+  `projectResidentLearning` continues to select task guidance by default. Exploration policies require an explicit matching purpose and are reported as `different-purpose` when withheld. Existing skills without a purpose retain their task behavior and hashes. CLI resident steps therefore keep exploration policies out of ordinary task context. Explicit exploration projection still requires matching source revisions and does not grant tools or start inference.
+
+- d1be0be: Stabilize goal conversation UI tests by waiting for the enabled composer before
+  typing commands, including after conversation replacement. Tests continue to
+  exercise durable goal ordering and automatic continuation without increasing
+  timeouts or changing CLI behavior.
+- 43124f0: When automatic evidence query resolution is enabled, allow its existing bounded
+  planner to select grounded subject words for discovery. A named record can now
+  focus the search without generic field words filling context with other records.
+  Source spelling, quoted context and every candidate's conversation ownership
+  are validated before use.
+
+  Temporary context reports the selected focus, observed focus words and locally
+  excluded passages. An empty focused scan is explicitly not proof of archive
+  absence. Explicit conversation search/read tools remain available with their
+  existing semantics; no additional model call or retrieval budget is introduced.
+  SDK query resolution remains opt-in. CLI integration checks cover archived
+  observations after reopening a conversation.
+
+- e40044b: Correct evidence-source guidance for questions about earlier observations. The SDK coding-agent doctrine now distinguishes retained historical content from current workspace reads, preserves exact identifiers in reports and requires unavailable history to be reported honestly. Recorded CLI turns explain how to recover clipped details with their conversation search/read tools, before compaction as well as after restart. The guidance is omitted when those tools are unavailable and remains stable across a run. Search responses explicitly distinguish remaining pages from unavailable evidence so a matching announcement is not confused with the original observation. Storage, permissions, retrieval bounds and freshness checks for edits are unchanged.
+- 6446182: Fix opt-in evidence query planning failing when a model rewrites a word's
+  spelling or inflection. The internal planner selects numbered words supplied
+  by the host; retrieval receives the original spellings after quote validation.
+  The vocabulary shares the existing 12,000-character preparation allowance,
+  offers at most 256 distinct spellings, and reports omissions. Each plan still
+  selects at most 16 words. Literal retrieval remains the SDK default, and the
+  CLI's existing query-resolution opt-out remains available.
+
+  Keep present-state plans from expanding with historical terms. Invalid IDs or
+  quotes still reject optional preparation instead of weakening source grounding.
+  Update the CLI Session regression for the internal selection protocol.
+
+- 77272e3: Read retained original observations after a process exits before recording a
+  terminal run status. Disk evidence factories accept `consistency: 'snapshot'`
+  for explicitly scoped nonterminal runs; the existing default remains `closed`.
+  Snapshot reads validate ownership and unchanged source bytes on every operation
+  without acquiring an execution lease, resuming tools or changing run metadata.
+
+  The CLI now uses this mode for recorded `idle`, `pending` and `running` runs
+  outside its requesting live writer. An incomplete final JSONL fragment is
+  excluded within the existing bounded I/O allowance without editing the source.
+  Search remains incomplete for nonterminal snapshots; a full read describes only
+  the selected retained text. File or metadata changes require a fresh search,
+  and missing or altered retained originals remain unavailable.
+
+- 5996a84: Recover retained tool text while the same invocation is still running. The SDK adds optional `ToolContext.captureRunEvidence` and `RunStore.captureTextEvidence` capabilities; custom stores need not implement them. Disk events carry additive integrity links so new appends do not invalidate earlier search/read continuations. Scope changes, damaged records and modified retained outputs are refused; torn boundaries remain explicitly incomplete.
+
+  CLI conversation search and read use this capability for the requesting invocation, preserving exact output after compaction without repeating the original action. Live cursors expire when the writer is replaced; start a new search after restart. Closed-run retrieval continues to support durable run/event/part references.
+
+  Conversation search also identifies the originating tool and directs callers to read the full passage, so original observations can be distinguished from prior retrieval excerpts.
+
+- ebfb3b4: Preserve original messages removed by CLI `/compact`, including exact user details
+  absent from its summary, for conversation search/read after restart. Failed
+  retention keeps the existing conversation; messages whose serialized form exceeds
+  3 MiB are refused before replacement.
+
+  SDK consumers handling `compaction_shed.reason` or `ShedPass.reason` exhaustively
+  must add the new `manual` case. Both manual compaction helpers accept optional
+  `onShed` to await host-owned retention before returning replacement history;
+  callback failure rejects the operation. Existing callers without a callback keep
+  their projection-only behavior.
+
+- 7168bbf: Avoid returning an underfilled conversation-search response solely because an internal SDK index page ended. Search can follow up to seven internal continuations while preserving its existing requested match count, 12,000-byte match output allowance and 8 MiB read ceiling. Public cursors still resume remaining work, and each internal page revalidates scope and source integrity. A later validation failure removes that run's accumulated matches from the current response; cancellation still aborts the call. Run counts describe distinct runs visited within the response.
+- 7182f1b: Fix conversation evidence searches that permanently excluded runs after the
+  first 100 directory entries. `search_conversation` now returns a continuation
+  for later discovery batches, including empty batches containing no run IDs.
+  `read_conversation` and automatic recall keep their existing exact-text,
+  ownership, byte and page limits; no tool action is replayed.
+
+  Discovery resources are bounded to 32 scans and 128 cached name pages per
+  process and expire after ten minutes. Concurrent reads of one continuation
+  share its page. Directory changes require restarting discovery, and CLI
+  Session shutdown closes abandoned scans. Batch order is not chronological
+  or globally ranked; automatic recall remains opt-in and non-exhaustive.
+
+- c329408: Fix repeated historical observations filling every automatic evidence-recall
+  passage slot and excluding a different record such as a correction. Exact equal
+  text with the same producer, retention and error status now shares a passage
+  before bounded BM25 scoring. Copies retain their separate source addresses;
+  changed identifiers, previews and errors remain distinct.
+
+  Request context includes `otherOccurrences` for additional addresses and
+  `omittedOccurrences` when the character allowance cannot hold all addresses in
+  the retrieved pool. Distinct text takes priority over extra addresses. No archive
+  record is removed, no current-state or cross-run chronology is inferred, and
+  explicit search/read tools are unchanged. CLI automatic recall remains opt-in
+  with `compaction.recallEvidence: true`; no read or passage limits increase.
+
+- e1b8bc7: Fix live evidence continuations incorrectly reporting an exhaustive search
+  after automatic recall had encountered a preview or unavailable original.
+  The continuation now retains omissions from the same live scan, even when its
+  remaining pages contain only valid records and are fully consumed.
+
+  `unavailableRuns` remains a count for the current call. A final page can have
+  zero new unavailable runs while `incomplete` remains true because an earlier
+  record was missing. Healthy scans still finish normally; a separate historical
+  scan's omissions do not taint the live cursor. No additional reads, model calls,
+  action replay or broader access are introduced.
+
+- 10e9984: Add optional `RunEvidenceSearchOptions.excludeSuccessfulTools` to omit successful
+  results from up to 16 exact tool names during bounded discovery. The default
+  excludes nothing. Filter membership is bound to continuations; exact reads stay
+  available and errors or unknown provenance remain searchable. Search results and
+  `EvidenceRecallBatch` can report optional `excludedToolResults`, counting skipped
+  visits rather than unique facts. A positive count can produce an explanatory
+  recall context even when no passage is selected.
+
+  Preserve tool name and explicit error status in compacted text when the same
+  record contains an unambiguous, correctly ordered call/result pair. Newly written
+  large compaction archives retain that metadata; older archives without it stay
+  unknown. Text addresses, original messages and copy timestamps are unchanged.
+
+  When CLI automatic evidence recall is enabled, successful `search_conversation`
+  and `read_conversation` results no longer occupy its initial candidate slots,
+  allowing original observations behind repeated archive quotes to be considered.
+  Automatic cursors preserve this filter. Start a new literal search without that
+  cursor to inspect the quoted search/read results. This fixes candidate pollution
+  without increasing budgets or changing the default-disabled recall option.
+
+- 4801a6f: Automatic evidence recall now recognizes text already present in tool text
+  blocks and earlier preparation stages. Those passages receive source references
+  instead of occupying slots intended for missing information. Images, documents
+  and private reasoning are not treated as visible text, and separate blocks are
+  never joined to invent a matching passage. Existing scope validation, context
+  limits and opt-in behavior are unchanged.
+
+  CLI automatic discovery can fill a candidate page from several completely
+  searched runs, within the same byte, output and page limits. It no longer
+  spends one automatic page on every small matching run. Explicit literal
+  searches retain their early return; unfinished source pages still require
+  continuation. Serialized matches, including escaping, share the output cap.
+
+- b9e0f37: Add the experimental `refineEvidenceRecallTerms` SDK helper for bounded lexical
+  coverage checks. Hosts can use the returned strict query subset to search terms
+  missing from candidate excerpts without introducing another model call.
+
+  When `compaction.recallEvidence` is enabled, the CLI spends existing retrieval
+  pages on uncovered terms so frequent words are less likely to hide an earlier
+  observation. Original and focused cursors retain their own query and omission
+  state. The four-page, two-live-page and 8 MiB read limits remain in force;
+  explicit conversation searches retain literal matching. No configuration or
+  stored-data migration is required.
+
+- 2bcf017: Improve automatic resident evidence selection when a long objective/summary
+  loses its subject or frequent matches hide a rarer requested observation.
+  Selection samples both ends of bounded fields and can spend existing search
+  pages on uncovered query words. Original and corrected observations retain
+  separate provenance; ambiguous references are not silently resolved.
+
+  Disk evidence sources and the resident source factory now advertise
+  `supportsTermRefinement`. SDK callers can supply `refineTerms` with an existing
+  token-search cursor to branch a strict subset at its authenticated position.
+  Returned cursors use the subset; the original broad cursor remains valid.
+  Scope, filters, read ceilings and automatic page/context limits stay enforced.
+  Custom sources without this capability use a fresh subset search; the resident
+  factory restarts within the selected invocation when its resolved backend
+  cannot refine a cursor.
+
+- e63ca83: Add `PrepareStepResult.context` for current observations carried after history in a labelled runtime message for this request only. It is separate from `system` authority, counted in subsequent stages' context estimates, and never replaces operator intent or accumulates in conversation history.
+
+  The emitted `RuntimeContextMessageKind` union now includes `step-context`. Consumers with exhaustive switches or records over that exported union must handle the new kind as runtime-generated context, not operator input. This is the SDK's breaking surface; existing `prepareStep.system` callers retain their behavior.
+
+  The CLI moves its changing context inventory into this field. OpenAI and Anthropic request conversion no longer moves that inventory ahead of conversation history as system text. This preserves history placement without promising cache hits or reduced billed tokens.
+
+  Anthropic message caching now places its breakpoint before request-only step context, so the cached boundary ends on stable history rather than the inventory that changes next step. Requests without step context keep their existing breakpoint.
+
+- 52f2d09: Resumed conversations and earlier-prompt forks no longer show blank assistant
+  rows for tool-only messages. Retained public commentary and final-answer items
+  are restored as separate entries when they still match the saved answer. Edited
+  or compacted content takes precedence over stale parts. Tool results and provider
+  replay state remain unchanged for the next model request.
+- 2e93158: Preserve full permitted shell output before condensing similar lines. Previously,
+  condensation happened before retention, so omitted row values could be lost even
+  though conversation search reported the stored result as complete. Historical
+  search and reads can now recover those originals without repeating the command.
+
+  Compact output carries its recovery path. Authenticated retention may also write
+  an artifact for a condensed result below the normal size cap. If retention fails,
+  the ordinary bounded original is shown instead; hook-redacted text stays redacted.
+
+- 1d651d0: Keep large compacted histories searchable, including short user text attached to
+  large images and individual long text messages. The disk store writes a bounded
+  `compaction_archive` storage record and saves original messages and authenticated
+  text chunks under the run's `compaction-output/` directory. Full SDK event readers
+  restore the original `compaction_shed` event with its attachments and metadata.
+
+  Raw JSONL consumers must handle this new storage record or switch to
+  `RunDiskStore.readEvents()` / `readRunEventsIn()`. Preserve `compaction-output/`
+  with the transcript when copying a run. Upgrade SDK readers before consuming new
+  archives. Existing inline records remain readable; older oversized records are
+  not converted automatically.
+
+  CLI manual compaction now offloads messages above 3 MiB instead of refusing them.
+  Automatic compaction and scoped search/read use the same SDK mechanism. Archive
+  write failures and limits still prevent the history replacement.
+
+- 281859f: Correct recovery guidance in shortened tool output. The kernel no longer assumes that workspace `read`/`grep` tools can open internal retained-output paths. It directs recovery through the host-authorized tools and distinguishes the saved observation from a fresh read of its source. Existing permissions, exact retention and preview limits are unchanged; previously recorded previews are not rewritten.
+- c795e3f: Read an already located conversation passage directly through its authenticated
+  SDK address instead of searching index pages again. This removes an unnecessary
+  empty read page after late search matches. Source ownership and bytes are checked
+  again on every read; changed evidence is refused.
+
+  The host retains at most 128 locations for ten minutes without retaining their
+  payloads. Expiry, eviction or restart falls back to the existing bounded lookup
+  using the same run/sequence/part address. Closing a conversation now releases
+  both search and read cursors, as well as these temporary locations.
+
+- 0fa8941: Allow a host to bound a resident tool-evidence operation across history,
+  invocation resolution and archive reads with `maxReadBytes`. Configure the
+  source's `resolutionReadBytes` with a host-enforced document-read ceiling;
+  bounded calls refuse to proceed without that declaration. Their `chargedBytes`
+  includes the declared resolution allowance, and a failed source search without
+  a byte receipt conservatively consumes the remainder. Calls without the new
+  option retain their separate existing limits.
+
+  The CLI declares the existing size bounds of its two attempt receipts, making
+  its source usable by bounded host retrieval. This does not enable automatic
+  resident recall yet. Returned pages must match their resolved invocation's
+  tenant/project/Session/run identity, and cancelled reads cannot expose a late
+  backend result. Custom sources must honor the read limits they accept.
+
+- 3c60512: Add optional writer-owned `PersistedRunEvent.previousTextRecord` links for live
+  text retrieval. Bounded searches can reach earlier observations without spending
+  their record allowance on intervening nontext lifecycle events. Operational JSONL
+  records and adjacent links remain intact. Missing text links retain adjacent
+  traversal, and malformed content or incomplete history cannot be skipped as if
+  the archive were complete.
+
+  The CLI's opt-in automatic evidence recall benefits from these links within its
+  existing page and byte limits. No extra model call or tool action replay is used.
+  This is selected-text integrity checking, not a full audit of skipped operational
+  records; the `compaction.recallEvidence` default remains off.
+
+- 6c682d8: Text evidence searches accept `excludeDerivedSummaries`, defaulting to false.
+  This excludes only explicitly marked compaction summaries, binds the selection
+  into cursors, and reports `excludedSummaries` as skipped part visits. Summary
+  text remains available through unfiltered searches and exact reads.
+
+  When a partial automatic CLI evidence page contains derived summaries, the host
+  can spend its existing refinement page on source records instead. The general
+  cursor and already retrieved summaries are preserved. This helps discovery reach
+  original observations behind repeated summaries without increasing the four-page,
+  8 MiB read or context allowances. Explicit tool continuations restore the exact
+  filter; new literal searches remain unfiltered. An incomplete scan still cannot
+  establish absence.
+
+- 656e79d: Add optional cancellation signals to `ToolContext.captureRunEvidence` and
+  `RunStore.captureTextEvidence`. Existing implementations that accept fewer
+  arguments remain compatible; custom stores should observe the supplied signal
+  to stop their own I/O promptly.
+
+  Tool evidence capture now observes the tool's deadline and nested dispatch
+  cancellation, and refuses use after the tool call settles even if its parent
+  run is still working. Cancelling a local read leaves other calls available.
+  Queued cancelled captures are skipped without releasing a writer lock early.
+  An uncooperative custom store can still delay later appends until its pending
+  operation settles, although the cancelled caller stops waiting immediately.
+  CLI conversation search and exact reads also forward their operation signal
+  when capturing live evidence.
+
+- 3c6326f: Prevent checkpoint resume from repeating a tool that started but never recorded
+  its completion. Previously, resuming a partially completed batch could execute
+  such a call again, duplicating an external effect. The resumed conversation now
+  receives an explicit unknown outcome and can verify current state before further
+  work. Completed calls remain recovered and proven unstarted calls can continue.
+
+  Add optional `RunStore.readToolExecutions` and exported `ToolExecutionSnapshot` /
+  `ToolExecutionRecord` types. Disk and memory stores implement the scan; custom
+  stores without it use their strict `readEvents` contract. Missing or contradictory
+  execution evidence does not authorize replay. The disk scan has documented size
+  bounds; exceeded bounds produce unknown outcomes instead of automatic re-execution.
+
+  Explicitly answered durable questions may still re-enter their own asking tool,
+  without granting the same exception to interrupted siblings.
+
+  CLI `drain` now passes configured run limits to its resume host. Previously a
+  bounded run could fail with a token-budget root-limit mismatch because `drain`
+  silently used an unlimited limit. Keep the original token limit in configuration;
+  the existing ledger still enforces its spent allowance.
+
+- 3c6ef94: Validate returned archive pages before exposing their text or caching an address.
+  Conversation search, exact reads and automatic recall now consistently reject
+  pages with mismatched ownership, invalid retrieval bounds or inconsistent text
+  positions. Exact reads also reject a wrong sequence/part during address lookup
+  and discard results returned after cancellation. Faulty captured sources report
+  unavailable evidence instead of contributing text to the conversation. Existing
+  built-in storage integrity checks and retrieval limits are unchanged.
+- f3b377e: Project bounded file-evidence references and owned worker status into model requests. A successful write body is referenced only while its complete call input and receipt remain visible and match the conversation's observation fingerprint. Existing disk-drift checks still run before mutations. Observations without content now invalidate an earlier fingerprint instead of carrying it forward.
+
+  `FileReadTracker.recordRead` accepts an optional third argument for a successful full-body write's tool-call ID, exposed through the optional `writeCallId` method. The built-in tracker preserves this witness across identical observations and clears it on changed or unknown content. Existing custom trackers remain valid; trackers without the witness do not enable the new file reference projection.
+
+  Add `CompletionInbox.describeOwnedWork()` for a non-consuming snapshot of up to sixteen owned tasks, separating scheduler state from delivery to history. The runtime uses it to keep available results visible after operator steering; delivery does not claim that a user-facing synthesis was produced. No automatic relaunch, answer-verification inference or persisted duplicate transcript is added.
+
+- fd0d270: Automatic evidence recall now retains bounded source references for exact text already visible in conversation history. The temporary context can contain `visibleEvidence` entries binding an exact bounded `textQuote` to an `address` for a host archive-read tool, recording time when known, source and retention/error metadata. `omittedVisibleEvidence` reports references withheld by the existing character limit. Quotes repeat at most 512 UTF-16 units to make the source association explicit; full records remain available through the read address. Visible quotes and new passages share `maxPassages`, with new text taking priority.
+
+  An otherwise complete recall pass may now return source metadata even when all matching text is already visible. Consumers should not assume every recall block contains new passage text. New-text ranking is independent of visible copies, and source ownership, revalidation, read limits and cancellation remain enforced. CLI models can use each reference's `address` with `read_conversation` to recover the exact source association without searching again or replaying an action.
+
+- Updated dependencies [40651dd]
+- Updated dependencies [b156888]
+- Updated dependencies [7bb8163]
+- Updated dependencies [2d26b44]
+- Updated dependencies [6663561]
+- Updated dependencies [2a1e0e5]
+- Updated dependencies [ce55c21]
+- Updated dependencies [9463b6f]
+- Updated dependencies [de53442]
+- Updated dependencies [6e4a820]
+- Updated dependencies [28d3874]
+- Updated dependencies [985db49]
+- Updated dependencies [eb2e7ba]
+- Updated dependencies [bd4bd2e]
+- Updated dependencies [fe6e0fb]
+- Updated dependencies [bb0281b]
+- Updated dependencies [cff2b6a]
+- Updated dependencies [df686fc]
+- Updated dependencies [e954d02]
+- Updated dependencies [2869fbe]
+- Updated dependencies [b1e3bc5]
+- Updated dependencies [df143c8]
+- Updated dependencies [45c8292]
+- Updated dependencies [6e14db9]
+- Updated dependencies [6a6921c]
+- Updated dependencies [691342c]
+- Updated dependencies [d5d2b9a]
+- Updated dependencies [b971796]
+- Updated dependencies [e9a4192]
+- Updated dependencies [612879e]
+- Updated dependencies [e7bc7a1]
+- Updated dependencies [b2d5b01]
+- Updated dependencies [3e09024]
+- Updated dependencies [f49a4b8]
+- Updated dependencies [43124f0]
+- Updated dependencies [e40044b]
+- Updated dependencies [6446182]
+- Updated dependencies [0a0baf2]
+- Updated dependencies [c4aaf9b]
+- Updated dependencies [77272e3]
+- Updated dependencies [7579aa0]
+- Updated dependencies [5996a84]
+- Updated dependencies [ebfb3b4]
+- Updated dependencies [4828eb0]
+- Updated dependencies [97acc32]
+- Updated dependencies [c329408]
+- Updated dependencies [b649224]
+- Updated dependencies [10e9984]
+- Updated dependencies [4801a6f]
+- Updated dependencies [b9e0f37]
+- Updated dependencies [2bcf017]
+- Updated dependencies [e63ca83]
+- Updated dependencies [830f81e]
+- Updated dependencies [6394010]
+- Updated dependencies [f4b3ffb]
+- Updated dependencies [9a4877a]
+- Updated dependencies [f92daf8]
+- Updated dependencies [22203b0]
+- Updated dependencies [5d31eea]
+- Updated dependencies [9ea5074]
+- Updated dependencies [f1e33a1]
+- Updated dependencies [2e93158]
+- Updated dependencies [1d651d0]
+- Updated dependencies [b888779]
+- Updated dependencies [281859f]
+- Updated dependencies [d1a6ce5]
+- Updated dependencies [d81aca6]
+- Updated dependencies [61aab1f]
+- Updated dependencies [ea5367d]
+- Updated dependencies [0fa8941]
+- Updated dependencies [3c60512]
+- Updated dependencies [8095541]
+- Updated dependencies [6c682d8]
+- Updated dependencies [bdf923d]
+- Updated dependencies [656e79d]
+- Updated dependencies [3c6326f]
+- Updated dependencies [0a36260]
+- Updated dependencies [f3b377e]
+- Updated dependencies [fd0d270]
+- Updated dependencies [2869fbe]
+  - @namzu/sdk@39.0.0
+  - @namzu/openai@3.1.1
+  - @namzu/anthropic@5.1.1
+  - @namzu/zen@1.0.1
+  - @namzu/computer-use@1.4.2
+  - @namzu/ollama@2.2.2
+  - @namzu/openrouter@2.4.0
+
+## 24.0.0
+
+### Major Changes
+
+- 1efafcb: Resident `run` and `start` now default to a resident-specific context profile
+  instead of the interactive coding and plan-mode prompt. Read-only residents
+  can complete read-only objectives without being instructed to pause for an
+  interactive plan approval. Pass `--context-profile interactive` to preserve
+  the previous guidance. Ordinary chat, tool permissions, output validation and
+  claim settlement are unchanged.
+
+  The SDK exports `createResidentStepContributions` and `ResidentStepPromptOptions`
+  for stable resident guidance and captured invocation-specific continuity through
+  the existing prompt registry. Prompt-cache validation now checks rendered
+  instructions so replacing content under the same contribution or skill name
+  cannot retain stale guidance. Full-prompt cache hits still render once locally.
+
+### Minor Changes
+
+- 09c5993: Add experimental `namzu resident` commands to save, inspect, execute, pause, resume, wake, reconcile and archive project-bound pursuits. Execution reuses the configured CLI runtime, requires a finite step cap and defaults to read-only plan mode; provider/tool/token options apply to each invocation or SDK step as documented. Saved execution directories, last-step summaries and private attempt receipts survive reopening. Interrupted work retains its exact claim and requires explicit inspection before reconciliation; no service, automatic replay, external messaging or ordinary TUI default is enabled.
+
+  Add an optional durable `pauseGeneration` to resident agendas. Each successful `setPaused(true)` increments it, and resume preserves it, allowing a CLI runner to notice even a rapid pause/resume between local checks. SDK agenda writes use schema 5; schemas 1–4 remain readable with an absent generation interpreted as zero. Older writers refuse the new schema rather than drop stop authority. SDK hosts remain opt-in; existing local `ResidentHost.pause()` behavior is unchanged.
+
+- e5bd6a2: Add `ToolRegistry.fork()` and `ToolRegistryForkOptions` to snapshot tool membership and availability independently for a run. Optional `deferExcept` hides currently active schemas until discovery without changing handlers, authorization or the source registry. Definitions and configuration remain shared; this is not a deep clone. Exact short/generic deferred tool names can now be discovered, and scoped prompts only recommend `search_tools` when it is available to that scope.
+
+  Add opt-in `namzu resident run|start --tool-loading deferred` to load optional tool schemas on demand for each step. The default remains `eager`; project instructions, memory recall, continuation evidence, permissions and provider-native search are unchanged. Discovery may require another model response. The internal CLI session option applies to fresh sends, not checkpoint resume.
+
+- b7f6720: Add opt-in `ResidentHostRunOptions.keepAlive` while preserving the default idle-return behavior. A keep-alive invocation retains its original finite step budget and performs no model calls when no work is due; it requires a positive `maxIdleMs`.
+
+  Add `namzu resident start --max-steps <n>` for managed background execution, `stop` for exact-runner drainage, and `release <runner-id> --executor-stopped` for inspected crash recovery. Foreground and background CLI runners share exclusive immutable ownership. Status distinguishes live control replies from unresponsive retained state; failed cleanup does not establish drainage. No OS service or automatic replay is installed. Existing interrupted pursuit claims still require explicit reconciliation.
+
+### Patch Changes
+
+- e376b7c: Fix Windows startup rejecting private CLI state directories whose ACL includes
+  the operating system's SYSTEM account (`SY`). The current user must still have
+  access; grants to other users or groups remain refused. This fixes a local
+  state-permission failure that could appear after selecting a discovered Claude
+  session, without requiring another provider sign-in.
+
+  Claude session discovery now honors `CLAUDE_CONFIG_DIR`, including directories
+  with spaces. An explicitly selected profile cannot silently fall back to the
+  default Claude profile, the paired Windows home, or the default macOS Keychain.
+  Custom macOS Keychain entries remain unsupported.
+
+- 63328d0: Fix npm startup failures in Windows provider setup and `namzu upgrade` by running npm's JavaScript entry point with the Node runtime that runs Namzu. Arguments, including installation paths with spaces or shell characters, remain literal. Windows uses the npm bundled with that runtime; if it is absent, Namzu explains how to repair it instead of trying a custom PATH wrapper. Cancelling provider installation requests termination of its Windows process tree and reports if cleanup cannot be confirmed.
+
+  CLI 23.0.0's existing Windows updater cannot acquire this fix itself when it fails with `spawn EINVAL`. Run `npm.cmd install --global @namzu/cli@latest` once using the same Node installation; include `--prefix "<existing-prefix>"` for a custom global prefix. Restart Namzu afterward.
+
+- 3225450: Make the Windows conversation resume hint executable in PowerShell, including Windows PowerShell 5.1. The hint explicitly names PowerShell, quotes paths and arguments literally, and resumes only after a required directory change succeeds.
+- 63328d0: Fix Windows startup failing on nested private state directories. Current-user
+  access now propagates to new child directories and files instead of leaving
+  Windows to assign its default ACL. Protecting a named private directory removes
+  an existing Administrators grant, including after an earlier failed startup;
+  it does not accept that group or unrelated accounts as private.
+
+  Existing descendant files with explicit grants are not recursively migrated.
+  POSIX permissions and credential-file ACL validation are unchanged.
+
+- Updated dependencies [449988e]
+- Updated dependencies [09c5993]
+- Updated dependencies [0c9c98a]
+- Updated dependencies [1efafcb]
+- Updated dependencies [f3fa065]
+- Updated dependencies [e5bd6a2]
+- Updated dependencies [8400937]
+- Updated dependencies [44b8dcf]
+- Updated dependencies [b7f6720]
+  - @namzu/sdk@38.2.0
+
 ## 23.0.0
 
 ### Major Changes