@mono-agent/agent-app 0.20.11 → 0.21.0

package/README.md

@@ -28,13 +28,21 @@ Turn a folder's `mono-agent.config.json` into a running agent host:
   external channel plugins from `channels.plugins[]`.
 - Build the shared runtime/responder/memory stack through app-owned configured
   composition
-  (including canonical `runtime.fallbacks` routes and legacy
-  `runtime.fallbackModels` compatibility).
+  (canonical `runtime.fallbacks` routes).
 - Preserve bounded answered/expired `AskUser` evidence in the assistant history
   copy so cold/stateless provider replay does not lose the out-of-band exchange;
   cancelled asks are not journaled.
+- Publish the harness's bounded, redacted continuity account for every admitted
+  non-isolated turn that settles as cancelled or failed before its success
+  commit. Cancellation preserves operator, shutdown, stale-session, signal,
+  timeout, generic, and unrecorded-reason provenance; failure records a trusted
+  host settlement category while bounding/redacting runtime/provider code and
+  detail as untrusted evidence. Eligible durable Pi recovery retains native context
+  without appending the account to Pi; cold reseed includes the account. The
+  on-disk history shape is unchanged by recovery;
+  `RunHistory` and `SessionHistory` remain the deeper evidence paths.
 - Expose the request-scoped read-only `RunHistory` tool for safe normalized
-  search and paged evidence from completed prior runs in the logical
+  recovery, search, and paged evidence from settled prior runs in the logical
   conversation, independent of daily rollover buckets.
 - Expose the sibling request-scoped read-only `SessionHistory` tool over the
   harness's canonical retained managed-tool lifecycle sidecar.
@@ -46,7 +54,8 @@ Turn a folder's `mono-agent.config.json` into a running agent host:
   Slack/Telegram/web/WhatsApp wake routing with exact active-run steering and a
   reserved visible normal-turn fallback,
   wake with age-bounded busy deferrals, bounded pending/store materialization,
-  stable secret-free safety errors, native same-message lifecycle surfaces,
+  stable secret-free safety errors, a memory-only redacted live output tail,
+  native same-message lifecycle surfaces,
   fail-closed live store health, a bounded monotonic registry that seals every
   retained state root even after disable or reconfiguration, bounded locked
   recovery through a fixed-name owner-private sibling directory while request
@@ -60,6 +69,15 @@ Turn a folder's `mono-agent.config.json` into a running agent host:
   routes, and `mono-agent jobs` CLI at the app boundary. This
   local contract does not resist a hostile same-UID provider; use OS privilege
   separation when that is in the threat model.
+- Opt in to Pi-native host-owned watches through `monitors.*`. Telegram, Slack,
+  and existing web conversations receive coalesced event batches as exact-origin
+  tool-capable wake turns; web uses ordinary assistant turns rather than a
+  Monitor card, and shares one per-thread serialization lane with ProcessJobs
+  wakes and queued user follow-ups.
+  Optional batch deduplication and wake intervals suppress unnecessary inference;
+  exit-only watches deliver one terminal wake. The host clamps intervals through
+  `monitors.maxWakeIntervalMs` (default/cap 300000) and exposes durable suppression
+  and delivery-disposition counters. `maxChainDepth` defaults to 4, with cap 64.
 - Drive each channel through a uniform driver contract with per-channel
   `disabled` / `waiting_for_config` / `running` / `degraded` / `failed` status.
   `degraded` means a temporarily unavailable transport owns its recovery while
@@ -73,8 +91,8 @@ Turn a folder's `mono-agent.config.json` into a running agent host:
   actions are config-opt-in, API-key-protected, and explicitly confirmed; they
   never rewrite config, environment, or Markdown job sources.
 - Register the host as a traceability source. Config edits are made directly in
-  `mono-agent.config.json`, or proposed through the OS-owner-managed macOS
-  configuration TUI; direct edits take effect on the next `mono-agent restart`.
+  `mono-agent.config.json` or `IDENTITY.md` and take effect after validation and
+  `mono-agent restart`.
 - Check managed launchd logs with bounded metadata reads every five minutes,
   reconcile installed macOS LaunchAgents at login and hourly, and make `status`
   require agreement between the cached trace and launchd's live PID.
@@ -88,16 +106,25 @@ Turn a folder's `mono-agent.config.json` into a running agent host:
 - Scaffold (`mono-agent init`) and validate (`mono-agent validate`) agent
   folders non-destructively.
 - Resolve local-first WebSearch/WebFetch settings into every runtime run and
-  report a separate bounded readiness section for loopback SearXNG plus the
-  optional `agent-browser` renderer; the app never owns either companion's
-  lifecycle.
+  report the four-request default WebSearch budget plus separate bounded
+  readiness for explicit Ollama or loopback
+  SearXNG plus the optional `agent-browser` renderer; the app never owns any
+  companion's lifecycle. Opt-in `tools.web.coordination: "host"` injects the same private
+  admission and cooldown store into parent and subagent runs;
+  `mono-agent web-control status|reset` inspects or clears idle operational state.
+- Bind oversized tool-block persistence to the harness's authoritative run id,
+  writing owner-private raw payloads under `artifacts.dir/tool-output/<runId>/`.
+  The sink is not injected into out-of-harness child callbacks. The hourly
+  artifact sweep bounds run directories with the existing `artifacts.retention`
+  policy while conservatively retaining active, uncertain, or recently modified runs.
 - Operate the machine-wide `@mono-agent/web` assistant-ui console through
-  `mono-agent web`, including persisted curated host themes and hostname
-  identity; on macOS pair its worker with one helper-only, stopped-writer log
-  controller while the worker remains wake-only; publish a bounded, refreshable
-  skill registry through each running operator endpoint so the web composer can
-  discover valid `$skill-name` references; use `mono-agent tui` for bounded
-  recorded-run replay.
+  `mono-agent web`, including persisted curated host themes and a console label
+  that defaults to the hostname and can be restored with `--name -`; on macOS
+  pair its worker with one helper-only,
+  stopped-writer log controller while the worker remains wake-only; publish a
+  bounded, refreshable skill registry through each running operator endpoint so
+  the web composer can discover valid `$skill-name` references; use
+  `mono-agent tui` for bounded recorded-run replay.
 - Discover and expose one exact running agent through the ACP core-session
   profile with `mono-agent bridge acp`, including durable session resume, while
   preserving agent-owned configuration, workspace, sandbox, tools, MCP servers,
@@ -105,6 +132,14 @@ Turn a folder's `mono-agent.config.json` into a running agent host:
 
 ## Install / Usage
 
+Process-job chains keep the default depth budget of 4 and allow a configured
+ceiling of 64. Request diagnostics remain visible when the budget is exhausted.
+Background Exec/Bash accepts `wake_on_completion: false` for helpers that only
+need terminal card updates. Exact sentinel-only wakes suppress delivery; a
+receipt timeout before the destination confirms steering or durable follow-up
+admission settles as unknown and never automatically replays. A confirmed web
+follow-up receipt does not wait for that turn's later model outcome.
+
 ```bash
 # Install the scoped CLI host directly:
 npm install --global @mono-agent/agent-app
@@ -122,6 +157,10 @@ same CLI.
 
 ### Guided initialization and readiness
 
+Linux lifecycle commands use systemd user services with journald logs and
+`dev (unmanaged)` runtime provenance. See [Linux background services](../../docs/observability/linux-services.md)
+for linger, external HTTPS, migration, and the initial operator-command scope.
+
 On an interactive terminal, bare `mono-agent init` (no flags) runs a colourful,
 step-by-step wizard — powered by `@clack/prompts` — that asks for the public
 agent name plus exact Role text for `IDENTITY.md` → `## Role` and composes the capability selection before writing anything. An existing `IDENTITY.md` is preserved and the review says the entered Role will not be written. Escape
@@ -151,9 +190,12 @@ primary/fallback pickers combine every bundled model
 for the guided Pi providers (Anthropic, GitHub Copilot, OpenAI Codex, and
 OpenCode-Go), Codex's live account catalog, the Claude SDK catalog, and local
 discovery. The live Codex provider default leads when available; offline setup
-falls back to curated `codex:gpt-5.6-terra` without guessing effort metadata, so
-only **Provider default** is offered until live `model/list` succeeds. GPT-5.6 Sol is selectable as
-`codex:gpt-5.6-sol` or `pi:openai-codex:gpt-5.6-sol`.
+falls back to curated `openai-codex:gpt-5.6-terra` without guessing effort metadata, so
+only **Provider default** is offered until live `model/list` succeeds. GPT-6
+Astra is selectable as `openai-codex:gpt-6-astra` for Codex subscriptions;
+`openai:gpt-6-astra` is also runtime-compatible for OpenAI API keys through the
+existing hand-authored provider path, without adding direct OpenAI to guided
+setup. GPT-5.6 Sol remains selectable as `openai-codex:gpt-5.6-sol`.
 OpenCode-Go Pi refs can save `OPENCODE_API_KEY` into
 the Pi auth store or remain environment-provided, and any number of fallback
 models are selected from the same discovered choices one at a time. Each route
@@ -184,21 +226,39 @@ action fails the check.
 Escape or Ctrl-C interrupts preflight; recovery can resume verified routes when
 the non-secret plan fingerprint still matches, restart all checks, edit choices,
 or cancel. Authentication repair clears every prior route proof because it can
-replace credential bytes. Guided commit atomically creates the config and rechecks its exact snapshot after validation. On macOS it then creates or refreshes the canonical per-config launchd service and waits up to 60 seconds for a fresh trace whose durable `metadata.lifecycle.startupCompleted` proof is true. The worker publishes that proof only after channels, memory rituals, and final memory-health work complete; later trace refreshes change the diagnostic `metadata.reason` without revoking readiness. The controller also re-proves the live launchd PID, exact snapshot, current channel/memory health, and reachable TUI before it opens `mono-agent tui --configure` against that background responder. A readiness timeout or trace/TUI-probe error preserves the committed files and skips chat, then unloads the worker plus scheduled maintenance and removes their definitions only when stopped state is proven. If cleanup cannot be proven, the command says that a process may still be running and prints exact `start`, `status`, and `logs --follow` recovery commands plus log paths. Workers from an older release that have no durable lifecycle marker must restart once before configuration can attach. Off macOS, conversational configuration is unavailable: the wizard preserves the files and gives manual edit/validate, foreground-start, and ordinary-TUI guidance without claiming readiness. Any flag or non-TTY invocation remains scaffold-only and never starts a process.
+replace credential bytes. Guided commit atomically creates the config and
+rechecks its exact snapshot after validation. On macOS it then creates or
+refreshes the canonical per-config launchd service and waits up to 60 seconds
+for a fresh trace whose durable `metadata.lifecycle.startupCompleted` proof is
+true. The worker publishes that proof only after channels, memory rituals, and
+final memory-health work complete; later trace refreshes change the diagnostic
+`metadata.reason` without revoking readiness. Once ready, init prints the manual
+continuation: edit `mono-agent.config.json` or `IDENTITY.md`, run
+`mono-agent validate`, restart, and open the ordinary TUI. A readiness timeout
+preserves the committed files, then unloads the worker plus scheduled
+maintenance and removes their definitions only when stopped state is proven. If
+cleanup cannot be proven, the command says that a process may still be running
+and prints exact `start`, `status`, and `logs --follow` recovery commands plus
+log paths. On Linux the next steps use the systemd background service and
+ordinary TUI; platforms without a background backend use foreground start. Any
+flag or non-TTY invocation remains scaffold-only and never starts a process.
 
 ### Managed skills and documentation companion
 
-Every scaffold selects versioned `mono-agent-configure` and `mono-agent-memory`
-skills from `./skills` with index disclosure. `ReadSkill` remains separate from
-action-tool policy. `mono-agent install-skill --project --check|--update` reports
-version/hash drift and refreshes only unchanged managed copies with backups; a
-canonical owner-only non-symlink parent chain, per-project owner lock, and
-compare-and-swap activation prevent outside or concurrent
-operator edits from being overwritten, and a partial activation restores only
-files that still equal the managed bytes it wrote.
-The persistent SELF-CONFIG workflow guidance is managed-skill version `1.2.0`.
-Existing unchanged copies are reported as stale and are never rewritten on TUI
-startup; run `mono-agent install-skill --project --update` explicitly to refresh them.
+Every scaffold selects the versioned `mono-agent-memory` skill from `./skills`
+with index disclosure. `ReadSkill` remains separate from action-tool policy.
+`mono-agent install-skill --project --check|--update` reports version/hash drift
+and refreshes only unchanged managed copies with backups; a canonical owner-only
+non-symlink parent chain, per-project owner lock, and compare-and-swap activation
+prevent outside or concurrent operator edits from being overwritten, and a
+partial activation restores only files that still equal the managed bytes it
+wrote. Bundle version `2.0.0` retires `mono-agent-configure`: runtime loading
+ignores that exact selected name and validation reports it as non-fatal waiting,
+while any other missing selected skill remains an error. Project check reports
+four retirement states. Project update removes a retired manifest entry and
+deletes its file only when the entry proves ownership and its bytes still match;
+modified and colliding copies fail closed, and retirement participates in the
+same lock, backup, and rollback transaction as the memory update.
 
 Harness-mode `mono-agent install-skill` also pairs the exact matching
 `@mono-agent/docs-mcp` version with available selected Codex and Claude Code
@@ -209,43 +269,6 @@ transactional; an unrelated entry named `mono-agent-docs` is never overwritten,
 including with `--force`. Project `--check` / `--update` mode does not touch
 harness MCP configuration.
 
-### Conversational self-configuration
-
-In the separate, visibly marked **SELF-CONFIG** session only, the background app injects proposal-only
-`ProposeAgentConfiguration`. The opening message shows a user-led map of identity/knowledge,
-runtime/models, skills/tools/MCP/plugins, memory, channels/APIs/A2A, automation,
-security, observability/operations, and acceptance criteria, then builds the chosen
-workflow conversationally. It says never to enter secrets and to expect a separate
-host approval before anything changes. Approval, rejection, a proposal-free turn,
-`done`, and `no changes` all keep SELF-CONFIG active; only `/quit`, `/exit`, or
-double `ctrl+c` exits the session, and quitting leaves the background agent running.
-The host accepts only a fail-closed low-risk
-allowlist: public name; effort, turn/session UX; selected project skills and
-disclosure; memory size or MemoryRecall enablement; semantic tool-policy
-tightening; and the separately validated Role body. Every path, memory-tier or
-capture-cost change, runtime/provider route, channel/proactive/plugin, MCP,
-exporter, embeddings/LLM endpoint, sandbox/network field, secret, and unknown
-future field is handed to the explicit guided flow. It canonicalizes
-config/Identity/state paths without following symlink parents, stages and
-fsyncs replacements, then performs the final source comparison and rename as
-one non-yielding commit step under an owner-only transaction lock. Separate TUI
-confirmation, failure-atomic config/Role rollback compensation, rollback
-evidence, a successful managed restart, and a fresh ready trace source remain mandatory. Configuration turns replace
-the ordinary tool/MCP policy with `ReadSkill`, `MemoryRecall`, and the proposal
-tool only. Pure direct-Codex chains use its native read-only plan posture;
-mixed chains keep the finite proposal surface so a route that cannot represent
-it cannot widen authority. Direct OpenCode cannot receive the host-owned MCP
-proposal capability: a direct-OpenCode primary is routed through a configured
-proposal-capable fallback, while a direct-OpenCode fallback makes self-configuration
-unavailable with explicit remediation. The approval card shows
-every full, untruncated JSON patch value and pages through the exact Role body
-while keeping Reject/Approve reachable, and rejects
-terminal-control or bidi-control review text before displaying it. The configuration
-conversation id stays stable across incremental checkpoints and verified restarts;
-each settled turn receives a fresh opaque proposal capability plus a safe host-outcome
-summary. Fast follow-up text remains in the editor until settlement and is never sent
-as ordinary chat or to a stale endpoint. Remote/proactive channels never receive this tool.
-
 ### Managed background runtime
 
 Before the first macOS background launch, the CLI copies the exact package and
@@ -285,8 +308,8 @@ login or reboot. A loaded v1 proof is treated as one-time drift and republished
 by the recovery controller.
 A managed worker freezes the proven config, Identity, optional Soul, and MCP authority
 file into private read-only copies before app/channel loading, while trace metadata continues to
-name the canonical config. Readiness requires one live launchd-owned trace PID,
-the exact durable snapshot, and, for configuration, a reachable TUI endpoint.
+name the canonical config. Readiness requires one live launchd-owned trace PID and
+the exact durable snapshot.
 Stop succeeds only after both launchd unload and worker death are proven.
 
 ### Validation, recovery, and managed logs
@@ -298,10 +321,11 @@ names its full closure id plus sanitized install metadata; other executions repo
 `dev (unmanaged)`. With `--consumer`, this remains the validator CLI's provenance,
 not an attestation of a separately running daemon.
 
-Its **Web search & fetch** section reports the resolved SearXNG backend and
+Its **Web search & fetch** section reports the resolved search backend and
 static/browser extraction mode. With liveness enabled it performs one bounded
-JSON query against a configured loopback SearXNG endpoint and checks that an
-enabled browser renderer reports `agent-browser` 0.33.1 or newer. Start
+JSON query against the selected SearXNG or Ollama endpoint and checks that an
+enabled browser renderer reports `agent-browser` 0.33.1 or newer. Hosted Ollama
+authentication is sent only to the exact official origin. Start
 preflight (`liveness: false`) skips both probes without changing structural
 validation.
 
@@ -434,26 +458,42 @@ verified turn. Missing Codex setup points to the official instructions at
 <https://developers.openai.com/codex/cli/>; the app never auto-installs it. The
 wizard offers browser callback and headless device-code login. Detected credentials
 skip redundant authentication but remain unverified until the exact route call
-successfully runs. Guided Pi setup covers Anthropic, GitHub Copilot, OpenAI Codex,
-and OpenCode-Go; other hand-authored Pi and local-provider configs remain compatible
+successfully runs. Passive status treats refreshable OAuth expiry as present but
+unverified and fails closed on unusable material or unsafe stores. The optional
+provider-auth check operator runs one explicit target-only, bounded request per
+displayed provider, records only fixed sanitized outcomes, and never probes from
+a status read. Ordinary run evidence is generation-fenced before provider
+execution: a target-store mutation invalidates already-running summaries and
+their failover attempts, including when the surrounding persistence finishes
+after logical cancellation or reports a post-install cleanup failure. Guided Pi
+setup covers Anthropic, GitHub Copilot, OpenAI Codex, and OpenCode-Go; other
+hand-authored Pi and local-provider configs remain compatible
 without being advertised as guided cloud integrations. Supported OAuth methods and
 the OpenCode-Go key flow come from the bundled upstream catalog;
 stale auth locks are repaired only when the recorded process is securely proven
 gone. The
-wizard keeps **Allow all tools** as its default. Pi/Claude flows disclose
-shell/file/web/channel effects and reconfirm an unsandboxed choice. Direct Codex
-fixes policy to effective allow-all (an omitted or wildcard-containing
-allowlist with no denied tools), uses its native network-off workspace sandbox,
-denies unattended escalations, and fails unexpected server requests promptly.
-Mixed chains are unrestricted only under explicit `runtime.routeSafety:
-"per-route-native"`, which isolates provider runtimes and applies a documented
-route-local contract. The default `uniform` mode keeps one common monotonic
-contract and rejects/skips routes that cannot represent it. Pi keeps mono-agent
-tool policy and optional SRT; Claude uses representable provider-native controls;
-direct Codex/OpenCode use provider-native safety plus effective allow-all. No route
-silently drops a required capability. Pi `pi:opencode-go:*` remains a Pi route.
-Direct OpenCode has the same omitted-or-wildcard/empty-deny requirement; restrictive static policies fail
-validation/runtime and an incompatible dynamic override is warned and ignored.
+wizard keeps **Allow all tools** as its default, disclosing shell/file/web/channel
+effects and reconfirming an unsandboxed choice. Every route is Pi-native, so one
+common monotonic contract covers the whole chain and rejects or skips a route
+that cannot represent it. Pi keeps mono-agent tool policy and optional SRT. No
+route silently drops a required capability.
+
+Every app-owned TUI/operator endpoint owns an in-memory provider-auth service
+for the web console's Agent settings, with no additional configuration. Its
+routes are keyless when the endpoint has no normal API key and otherwise require
+that bearer. It reports only providers used by effective configured routes and
+keeps credential detection distinct from a successful live request. GitHub
+Copilot and OpenAI Codex use Pi's native device-code flow; Anthropic uses the
+existing manual-code redirect callback; API-key providers use masked
+provider-owned prompts. Returned credentials pass through the same owner-private,
+cross-process-locked, sibling-preserving, no-clobber Pi-store transaction as
+the CLI API-key flow. A valid repeated login replaces the current session only
+after validation. Late provider work is discarded before promotion; a mutation
+already in atomic promotion or cleanup drains before another writer starts. If
+that drain exceeds two seconds, the fresh session fails closed with
+`replacement_timeout`. Sessions, submitted values, URLs, and codes are never
+written to agent history. The service covers `providers.piAuthPath` only, not
+Codex CLI credentials.
 
 ### Run history
 
@@ -461,7 +501,7 @@ validation/runtime and an incompatible dynamic override is warned and ignored.
 allow-all on MCP-capable routes; a restrictive `tools.allowedTools` must name
 `RunHistory` explicitly (`run_history` remains a deprecated policy alias), and
 `disallowedTools` can remove it. Direct OpenCode and other MCP-incompatible
-routes suppress it. The agent-facing shorthand is `{}` to list recent runs,
+routes suppress it. The agent-facing shorthand is `{}` to list recent settled runs,
 `{ "query": "topic terms" }` to search safe trigger and summary metadata,
 `{ "runId": "..." }` for a compact overview, and
 `{ "runId": "...", "cursor": "..." }` for the next timeline page. The
@@ -469,7 +509,11 @@ routes suppress it. The agent-facing shorthand is `{}` to list recent runs,
 compatible. List/search defaults to 5 results (maximum 10); timeline pages hold
 at most 10 entries and about 16 KiB. Each result includes tool-authored
 `navigation.guidance` and exact `navigation.nextActions[].arguments` for
-continuing exploration.
+continuing exploration. For an unhinted request to pick up, continue, or
+recover incomplete work, start with `{}`, select a `failed`, `cancelled`, or
+`interrupted` candidate, and inspect its `runId`. That overview marks output as
+incomplete evidence and returns a conditional exact `navigation.relatedTools`
+handoff to follow only when `SessionHistory` is available.
 List and search read retained summaries once; search never reads event JSONL
 and matches all normalized terms only against sanitized trigger/user input,
 run id, dates, status/failure kind, source/detail, model, and effort. Daily
@@ -519,6 +563,14 @@ successful-turn commit. A lifecycle record may therefore exist without a
 canonical message-history entry. Stable conversation/run/tool-call keys and
 writer-assigned per-run start/end sequences make retries idempotent; process
 recovery closes dangling starts as `interrupted` without rerunning a tool.
+Each client event waits at most 250 ms for foreground confirmation. If an
+accepted write is still queued or syncing, the event records immutable
+`persistence: "deferred"` metadata without an error code while the worker keeps
+the real request alive. The harness drains those accepted writes before bounded
+run finalization. `persisted` means the row committed before publication;
+`failed` is reserved for a definitive writer rejection. A deferred run artifact
+is not final storage evidence: after the run, `SessionHistory` is authoritative
+for committed rows. All three event states keep `untrusted: true`.
 Arguments/results are securely pre-bounded, redacted, and byte-bounded, with truncation metadata and
 opaque artifact ids. Filesystem-shaped spans in object keys and string values use an opaque host-root token plus
 at most two non-sensitive trailing components, so commands and results remain
@@ -528,6 +580,33 @@ root, or private run path. Only regular files beneath the configured run-specifi
 outside or symlinked paths are dropped. Isolated/proactive
 runs persist but search excludes them unless explicitly requested.
 
+Configured harness runs install the run-bound tool-output sink. When a tool
+lifecycle record persists too, `SessionHistory` exposes only its opaque id and
+current availability, never the host path or contents. The immediate truncation
+summary still names a successfully saved path. These files contain raw,
+untrusted data. The hourly artifact sweep removes eligible run directories by
+the existing `artifacts.retention` age/count policy, with dry-run parity; it
+protects directories projected from running or uncertain summaries and can
+clean an aged orphan without a tool-history row. Recently modified directories
+are held through the next hourly interval, even under count pressure, and are
+revalidated before removal. Tool-history retention itself
+still owns only its database records and tombstones. After file pruning,
+`SessionHistory` recomputes the opaque reference as unavailable.
+
+For tool evidence from a failed, cancelled, or interrupted `RunHistory` candidate, use
+`{ "action": "search", "runIds": ["..."], "includeIsolated": true }` without
+a `states` filter. If it returns no records, do not broaden into another run or
+conversation. Each search result distinguishes the invocation `recordId` from
+the terminal `resultRecordId`; follow its trusted navigation to inspect the
+result first when present and the invocation when its arguments are needed.
+The exact navigation retains `includeIsolated: true`, uses `chunkBytes: 8192`,
+and gives the next exact `get` arguments for every cursor. A bounded search
+preview is not the full record and cannot replace record-level inspection when
+recovering interrupted work. This is read-only evidence recovery: it does not
+resume provider state, replay tools, rerun work, or guarantee continuation from
+the interrupted point. Continue as fresh work in the current run with currently
+available tools and fresh verification.
+
 `{ "action": "search" }` returns at most 10 bounded previews with text,
 tool/state/run/time filters and a query-bound opaque cursor.
 `{ "action": "get", "recordId": "..." }` (or `toolCallId`) returns bounded
@@ -542,6 +621,7 @@ projection capped at 64 KiB including its truncation marker; warm provider resum
 continues natively and receives no replay. A zero-byte fresh sidecar is absent
 for automatic projection; another corrupt/unsafe projection emits a structured
 warning and continues the turn, while explicit SessionHistory reads fail closed.
+Neither history tool resumes provider state or replays/reruns retained work.
 Lazy writer acquisition keeps one at-most-10-second restart-handoff attempt.
 After failure, writes from every already-created turn reuse that rejection and
 new turns fail immediately during an initial 30-second backoff. Each failed
@@ -577,13 +657,53 @@ terminal record in place. A newer tool-history schema hard-fails downgrade until
 persisted conversation state is purged; an older compatible version is reported
 as upgrade-pending for the next writer.
 
+### Memory evidence routing and chronological browsing
+
+The configured host keeps four evidence sources distinct: the active
+conversation for what was just said, `MemoryRecall` for a targeted durable fact
+or decision, `MemoryJournal` for a broad retrospective over explicit local
+calendar dates, and `RunHistory`/`SessionHistory` for exact execution evidence.
+Unhinted interrupted-work recovery still begins with `RunHistory {}`.
+
+`MemoryJournal` is request-scoped and read-only. It is offered only for a local
+Lite, Journal, or BuJo store when `memory.recallTool.enabled` is on and normal
+tool policy allows it. Supermemory has search but no chronological capability.
+A first call requires `fromDate`, `throughDate`, and an IANA `timeZone`; the
+inclusive range is capped at 31 calendar days. Pages default to 10 and cap at
+25 entries, 8 KiB projected data, and 2 KiB per entry text. The frozen snapshot
+caps at 1,000 entries/2 MiB and continues only with its request-private authenticated,
+run-bound cursor at the exact issued offset.
+It returns curated daily-source provenance and lifecycle state, excludes raw
+audit observations and dropped records, and labels content untrusted. A clean
+empty range, unsupported composition, and backend failure remain distinct.
+
+### Durable memory writes
+
+`Remember` gives the agent an explicit way to persist one stated fact, closing
+the loop left by read-only `MemoryRecall`. It is request-scoped, deterministic,
+and append-only, and it writes through the shared memory retrieval service so no
+second store is opened.
+
+Availability is deliberately narrow: a configured memory block with
+`memory.rememberTool.enabled` left on, a store that affirms `supportsRemember()`
+(read-only stores and external backends never do), and tool policy that allows
+`Remember` — unlike `MemoryRecall`, this tool is allowlist-gated so writes can be
+withheld without disabling recall.
+
+Before anything is stored the host normalizes the text to exactly what will be
+written and checks that against configured credential values, known token shapes,
+credential assignments, and terminal/bidi controls. A match is rejected rather
+than redacted, so a mangled value is never persisted behind a success result.
+
 ### Web conversation titles
 
 `SetConversationTitle` requires no config key. For an ordinary interactive web
 turn whose title is still automatic, the app supplies a request-scoped MCP tool
 that accepts one normalized title of at most 80 characters. Its model-facing
-guidance asks for a concise semantic title after the topic becomes clear and a
-new title only when the conversation materially changes direction. The web
+guidance asks it to name the conversation as a whole and to keep refining that
+name whenever a better whole-thread name emerges, never to use the title as a
+status line for the step in progress. The tool result stays a proposal: the
+console applies it out of band and may decline it. The web
 console applies successful tool results quietly while retaining the tool call in
 the collapsed Activity disclosure.
 
@@ -597,10 +717,19 @@ title remains the fallback.
 
 ### Channel interactions and conversation history
 
+The configured agent preserves the harness's positive `importContext`
+capability through root-ownership, monitor, process-job, posted-reply, reply-file,
+and MCP-App decorators. The default durable store exposes it only when complete
+batch retention and provider-state retirement or absence are provable. Slack's
+posted-reply wrapper overlays destination history only on the leased Send view;
+the canonical import itself stays scope-free.
+
 For missing context, the agent should use active conversation history first,
-`MemoryRecall` for intentionally captured durable facts, `RunHistory` for exact
-prior-run evidence, and `SessionHistory` for retained managed-tool calls and
-results. Answered or expired blocking `AskUser` exchanges
+`MemoryRecall` for a targeted intentionally captured durable fact,
+`MemoryJournal` for a broad explicit-period curated retrospective, `RunHistory`
+for exact settled prior-run evidence (including failed/cancelled/interrupted
+work), and `SessionHistory` for retained managed-tool calls and results.
+Answered or expired blocking `AskUser` exchanges
 are written into the assistant history copy before the final response;
 cancelled asks are not journaled. The copy is explicitly labelled as untrusted
 historical data and bounded by newest whole interactions. If the newest valid
@@ -730,8 +859,8 @@ staging, current-run, or authorized in-flight content. Retried identities are
 deduplicated. A manifest
 that cannot accept its delivery-conversation binding becomes one bounded failed
 part while answer text and other valid parts survive. Terminal failure,
-cancellation, or missing run metadata removes uncommitted state. The sealed
-local self-configuration override excludes this publisher.
+cancellation, or missing run metadata removes uncommitted state. An authenticated
+authoritative request-tool override can exclude this publisher.
 
 Audit storage performs one root inventory for a process/root lifecycle, then
 maintains exact owner byte counts under a global append gate. Reclamation uses
@@ -764,8 +893,16 @@ ten-minute idle timeout. See
 [Reply files and MCP Apps](https://mono-agent-docs.vercel.app/tools/rich-replies/)
 for native channel behavior, fallbacks, browser security, and limits.
 
+Successful cron answers suppressed by the shared notification classifier project
+`NOTHING_TO_REPORT` as operator summary and detail text. Classification uses the
+full stored answer before either byte limit, including a sentinel on the final
+line of long narration. Agent SQLite and retained activity keep the original
+text; failures and non-suppressed output retain their existing truncation rules.
+
 ## Architecture
 
+Configured continuous sessions persist the requested primary model with their durable epoch. Per-model runtime factories are cached for the harness lifetime, and history retirement resolves the owning runtime. A model switch cold-seeds one new epoch; repeated overrides stay warm. Existing fallback and proactive-isolation policies continue to apply. See [session boundaries](../../docs/runtime/sessions-concurrency.md).
+
 ### Data flow
 
 `@mono-agent/agent-app` is the composition root. A running host follows this
@@ -803,7 +940,7 @@ path:
 | Channel integration | `channels.ts`, `channel-drivers/` | Built-in drivers plus config-loaded plugin resolution. |
 | Interaction and send tools | `interaction-bridge.ts`, `adapter-send-tools*.ts` | Structured `AskUser` state, channel sinks, progress, adapter-send tools, and bounded interaction-history projection. |
 | Operator CLI | `cli*.ts`, `jobs-command.ts`, `init.ts`, `doctor.ts`, `doctor-observability.ts`, `background*.ts`, `launchd*.ts`, `managed-web-logs.ts`, `web-*.ts` | Setup, focused validation sections, paired managed service/log lifecycle, process-job operation, and diagnostics. |
-| Host services | `run-history.ts`, `session-history.ts`, `conversation-title.ts`, `request-scoped-mcp.ts`, `process-jobs*.ts`, `continuation*.ts`, `memory-*.ts` | Shared request-scoped guards, bounded prior-run/tool-lifecycle evidence, automatic web conversation titles, local process-job ownership/wake/recovery, durable continuations, and memory operations. |
+| Host services | `run-history.ts`, `session-history.ts`, `conversation-title.ts`, `request-scoped-mcp.ts`, `process-jobs*.ts`, `continuation*.ts`, `memory-*.ts` | Shared request-scoped guards, bounded prior-run/tool-lifecycle evidence, bounded local memory chronology, automatic web conversation titles, local process-job ownership/wake/recovery, durable continuations, and memory operations. |
 
 ## Public API
 
@@ -817,6 +954,7 @@ path:
 | Scaffold or validate an agent folder | `initMonoAgentFolder`, `validateMonoAgentFolder` |
 | Add bounded prior-run inspection | `createRunHistoryRuntimeExtension`, `isRunHistoryToolAllowed` |
 | Add bounded retained-tool inspection | `createSessionHistoryRuntimeExtension`, `isSessionHistoryToolAllowed` |
+| Add bounded local memory chronology | `createMemoryJournalRuntimeExtension`, `isMemoryJournalToolAllowed`, `resolveMemoryJournalRange` |
 | Operate the CLI programmatically, including process jobs and the managed web lifecycle | `runCli`, `runJobsCommand`, `parseCliArgs`, `renderHelp` |
 
 The web maintenance controller and publication helpers remain private CLI
@@ -894,8 +1032,20 @@ IssueContinuationCapabilityInput
 MANAGED_SRT_LOCK_SHA256
 MANAGED_SRT_PACKAGE
 MANAGED_SRT_VERSION
+MEMORY_JOURNAL_DEFAULT_PAGE_SIZE
+MEMORY_JOURNAL_ENTRY_TEXT_MAX_BYTES
+MEMORY_JOURNAL_MAX_PAGE_SIZE
+MEMORY_JOURNAL_MAX_RANGE_DAYS
+MEMORY_JOURNAL_MAX_SNAPSHOTS
+MEMORY_JOURNAL_MCP_SERVER_NAME
+MEMORY_JOURNAL_PAGE_MAX_BYTES
+MEMORY_JOURNAL_TOOL_NAME
 ManagedSrtSetupOptions
 ManagedSrtSetupResult
+MemoryJournalBinding
+MemoryJournalCapableStore
+MemoryJournalErrorCode
+MemoryJournalRuntimeExtensionOptions
 MemoryRitualSchedule
 MonoAgentApp
 MonoAgentAppConfigInput
@@ -907,6 +1057,7 @@ PreflightResult
 RUN_HISTORY_MCP_SERVER_NAME
 RUN_HISTORY_TOOL_NAME
 ResolvedExporter
+ResolvedMemoryJournalRange
 RunContinuationCommandOptions
 RunHistoryBinding
 RunHistoryRuntimeExtension
@@ -952,6 +1103,8 @@ createConfiguredAgentResponder
 createConfiguredAgentRuntime
 createConfiguredMemory
 createCronChannelDriver
+createMemoryJournalRuntimeExtension
+createMemoryJournalServer
 createOpenAIApiChannelDriver
 createRunHistoryRuntimeExtension
 createRunHistoryServer
@@ -970,6 +1123,9 @@ isAppCoreConfigError
 isColorEnabled
 isContinuationMode
 isContinuationState
+isMemoryJournalCapableStore
+isMemoryJournalToolAllowed
+isMemoryJournalToolPolicyName
 isRunHistoryToolAllowed
 isSessionHistoryToolAllowed
 keyValue
@@ -990,6 +1146,7 @@ resolveAppTraceSourceId
 resolveAppTraceSourceLabel
 resolveAppTraceStaleAfterMs
 resolveChannelDrivers
+resolveMemoryJournalRange
 rule
 runCli
 runContinuationCommand
@@ -1023,6 +1180,11 @@ compose communication adapters; adapters never depend on it.
   `@mono-agent/agent-harness` and `@mono-agent/runtime-adapter`).
 - Multi-agent orchestration (owned by `@mono-agent/agent-orchestrator`).
 
+Opt in to metadata-only prompt-cache request fingerprints with
+`providers.piNative.promptCacheDiagnostics` (default `false`) or
+`MONO_AGENT_PI_PROMPT_CACHE_DIAGNOSTICS`. The offline reader is documented in
+[Prompt-cache measurement](https://mono-agent-docs.vercel.app/runtime/prompt-cache-measurement/).
+
 ## Related Documentation
 
 - [Quickstart](https://mono-agent-docs.vercel.app/getting-started/quickstart/)

package/dist/adapter-send-tools.d.ts

@@ -53,7 +53,7 @@ export interface TelegramSendToolSettings {
 export interface AskUserToolSettings {
     readonly bridgeUrl: string;
     readonly bridgeToken: string;
-    readonly timeoutMs: number;
+    readonly timeoutMs: number | null;
     readonly producerConversationId?: string;
     readonly interactionConversationId?: string;
     readonly runId?: string;
@@ -89,6 +89,7 @@ export interface AdapterSendToolsDeliveryHistoryCapabilityIssuer {
 export interface AdapterSendToolsRuntimeExtension {
     readonly runtimeOptions: {
         readonly mcpServers: Record<string, unknown>;
+        readonly mcpCallNoTotalTimeoutTools?: readonly string[];
     };
     readonly cleanup: () => Promise<void>;
     readonly settleCleanup?: () => Promise<void>;
@@ -151,7 +152,7 @@ export interface AdapterSendToolsChildContext {
 export interface AdapterSendToolsInteractionEnv {
     readonly bridgeUrl: string;
     readonly bridgeToken: string;
-    readonly timeoutMs: number;
+    readonly timeoutMs: number | null;
 }
 export declare function adapterSendToolsMcpEnv(configPath: string, allowedTools: readonly string[], context?: AdapterSendToolsChildContext, interaction?: AdapterSendToolsInteractionEnv): Record<string, string>;
 export interface AdapterSendToolsChildConfig {