@mono-agent/agent-app 0.13.0 → 0.15.0

package/skills/mono-agent-composer/references/config-blueprint.md

@@ -158,7 +158,7 @@ new agent.
   // NodeRepl shares state only inside one run and uses the same sandbox policy
   // as Bash.
 
-  // Human-in-the-loop bridge: blocking AskUser / TelegramAskButtons plus
+  // Human-in-the-loop bridge: structured blocking AskUser plus
   // run-scoped project-MCP progress. It auto-starts when either ask tool is
   // allowed, this block or an interaction env override is configured, or
   // interaction.progress.enabled resolves true while
@@ -183,7 +183,8 @@ new agent.
   },
 
   // Observability: the recorder writes empty events + a running summary at start,
-  // buffers key-redacted/capped events in RAM, then replaces both files at finish/fail.
+  // buffers sensitive-key-redacted, credential-scanned, capped events in RAM,
+  // then replaces both files at finish/fail.
   // A pre-terminal crash can lose buffered events. `mono-agent status` reads the
   // separate trace-source registry.
   "artifacts": {
@@ -213,7 +214,7 @@ new agent.
   },
 
   // ----- Channels: one section per channel; all independent. Most channels are
-  // ----- opt-in; operator surfaces (`tui`, `live`) default on and can opt out.
+  // ----- opt-in; the `tui` operator surface defaults on and can opt out.
   // ----- A waiting/disabled channel never blocks the others.
 
   "tui": {
@@ -224,14 +225,6 @@ new agent.
     "allowNonLoopback": false              // set MONO_AGENT_TUI_API_KEY in .env when needed
   },
 
-  "live": {
-    "enabled": true,                       // default-on read-only SSE relay (run-event operator surface)
-    "host": "127.0.0.1",
-    "port": 0,
-    "basePath": "/live",
-    "allowNonLoopback": false              // set MONO_AGENT_LIVE_API_KEY in .env when needed
-  },
-
   "webhook": {
     // For bearer auth, put MONO_AGENT_WEBHOOK_API_KEY=<strong-random-secret> in
     // the owner-only .env file; JSON strings are literal and do not interpolate env: values.
@@ -409,14 +402,14 @@ mono-agent config       # resolved config field-by-field, each value tagged env/
 mono-agent validate [--preset <id>] [--consumer <path>]     # per-section report; --preset also checks the preset's capabilities
 mono-agent start        # traceability + every configured channel
 mono-agent restart      # apply config edits (config is JSON-first; restart to re-apply)
-mono-agent restart --clear-sessions  # restart AND purge persisted pi sessions (fresh start; durable memory kept)  [--force is a deprecated alias]
+mono-agent restart --clear-sessions  # restart AND purge persisted pi sessions (fresh start; durable memory kept)
 ```
 
 A `.env` file in the folder is loaded automatically (exported shell variables win); use `--env-file <path>` for an alternate file. `validate --consumer <path>` loads the consumer folder's `.env` by default and resolves relative `--config` / `--env-file` paths there. `start` prints the traceability source (Phoenix when an `observability.exporters` Phoenix entry is configured, otherwise the local JSONL artifacts) and one status line per channel: `running` with its endpoint facts, `waiting_for_config` with the exact missing setting, `disabled`, or `failed` with the reason. Config is JSON-first: edit `mono-agent.config.json` directly (agents can edit it) and run `mono-agent restart` to apply — there is no live browser re-apply.
 
 For BuJo capture and the effective `bujo` tier that runs scheduled consolidation, configure `memory.llm`. Use `provider: "ollama"` with a local Ollama chat model string and optional `endpoint`, or `provider: "agent-host"` with `model` as a normal SDK runtime model reference such as `pi:openai-codex:gpt-5.5` and `executionMode: "sdk"`. `endpoint` is Ollama-only, and CLI-backed refs such as `codex:gpt-5.5` are rejected for memory LLMs until runtimes can enforce no external actions. The same values can be supplied via `MONO_AGENT_MEMORY_LLM_PROVIDER`, `MONO_AGENT_MEMORY_LLM_MODEL`, `MONO_AGENT_MEMORY_LLM_EXECUTION_MODE`, and `MONO_AGENT_MEMORY_LLM_ENDPOINT`. Routine BuJo consolidation runs via the in-app scheduler; the standalone `memory-bujo` maintenance CLI was removed (use `mono-agent memory <subcommand>` from the agent folder). `agent-host` LLM capture is an in-app composition path that injects the `LlmComplete` implementation into the BuJo store.
 
-For operator views, run `mono-agent tui` or `mono-agent web` from any directory once the agent is started. Both discover running agents via the trace-source registry. The TUI and assistant-ui web console chat over the default-on `tui` stream endpoint (`"tui": {"enabled": false}` opts out); on macOS, `mono-agent tui --configure` opens a persistent, visibly marked proposal-only SELF-CONFIG conversation against the managed background agent and must not be combined with `--local`. Approval, rejection, and no-change turns continue that session; only quitting exits it. `mono-agent web` is an always-on service namespace, binds `0.0.0.0:5050` by default, and has no app login; use `--loopback` to narrow it. The `mono-agent sessions` Session Recorder command was removed; use `mono-agent tui` (recorded-run replay) or `mono-agent web` (live console). Its `@mono-agent/session-web` package still ships and reads artifacts plus live updates from the default-on `live` relay (`"live": {"enabled": false}` opts out), but has no CLI launcher. The low-level `mono-agent-tui` bin also supports `--responder <file>` (embedded, an ESM module default-exporting an `AgentResponderLike` or exporting `createResponder(env, cwd, configJson)`) and `--url <baseUrl>` (direct connect).
+For operator views, run `mono-agent tui` or `mono-agent web` from any directory once the agent is started. Both discover running agents via the trace-source registry. The TUI and assistant-ui web console chat over the default-on `tui` stream endpoint (`"tui": {"enabled": false}` opts out); on macOS, `mono-agent tui --configure` opens a persistent, visibly marked proposal-only SELF-CONFIG conversation against the managed background agent and must not be combined with `--local`. Approval, rejection, and no-change turns continue that session; only quitting exits it. `mono-agent web` is an always-on service namespace, binds `0.0.0.0:5050` by default, and has no app login; use `--loopback` to narrow it. The former read-only recorder command, package, and relay were removed; use `mono-agent tui` (recorded-run replay) or `mono-agent web` (live console). The low-level `mono-agent-tui` bin also supports `--responder <file>` (embedded, an ESM module default-exporting an `AgentResponderLike` or exporting `createResponder(env, cwd, configJson)`) and `--url <baseUrl>` (direct connect).
 
 ## Programmatic Escape Hatch
 

package/skills/mono-agent-composer/references/discovery-questions.md

@@ -252,7 +252,7 @@ Do you need a browsable trace viewer or just local artifacts?
 2. JSONL artifacts only (bounded terminal snapshots; no external viewer)
 ```
 
-Fills: `artifacts.dir`, `traceability.registryDir` / `sourceId` / `sourceLabel`, and — when Phoenix is wanted — an `observability.exporters` (phoenix) OTLP entry. The local recorder starts with empty events plus a `running` summary, applies key-based redaction and caps event strings at 4,096 bytes by default, buffers events in RAM, and replaces the artifacts at finish/fail; a pre-terminal crash can lose buffered events. Phoenix adds a best-effort terminal batch, not a crash-safe stream. Artifacts record runtime/tool/message events and summaries, not private chain-of-thought. For a terminal operator console, mention `mono-agent tui` (run from anywhere once the agent is started; live chat with thinking/tool insight, run replay, config view). Config is JSON-first — edit `mono-agent.config.json` directly and run `mono-agent restart` to apply changes.
+Fills: `artifacts.dir`, `traceability.registryDir` / `sourceId` / `sourceLabel`, and — when Phoenix is wanted — an `observability.exporters` (phoenix) OTLP entry. The local recorder starts with empty events plus a `running` summary, applies sensitive-key redaction, scans retained free text for high-confidence credential shapes, and caps event strings at 4,096 bytes by default. It buffers events in RAM and replaces the artifacts at finish/fail; a pre-terminal crash can lose buffered events. Phoenix adds a best-effort terminal batch, not a crash-safe stream. Artifacts record runtime/tool/message events and summaries, not private chain-of-thought. For a terminal operator console, mention `mono-agent tui` (run from anywhere once the agent is started; live chat with thinking/tool insight, run replay, config view). Config is JSON-first — edit `mono-agent.config.json` directly and run `mono-agent restart` to apply changes.
 
 ## 9. Acceptance Smoke Test
 

package/skills/mono-agent-composer/references/feature-coverage.md

@@ -18,7 +18,8 @@ Every framework capability and how a composed agent reaches it. This table is th
 | Pi-native transport, retry, and durable provider-session tuning | config | `providers.piNative.{transport,piMaxRetries,maxRetryDelayMs,piSessionsRoot}` | `runtime.pi-native-tuning` |
 | Tool-output bloat guard, cost tracking | auto | built into every run | — |
 | Context handling / auto-compaction | config + provider | `runtime.compaction.*` (matching `MONO_AGENT_COMPACTION_*`) controls adaptive Pi compaction. Omitted budgets derive from the active model window; reactive recovery re-prompts exactly once only after a verified reduction, and persistent `context_limit` advances to a configured fallback | `runtime.context-compaction` |
-| Structured output (JSON schema), live input steering | code | harness `runtimeOptions` | — |
+| Structured output (JSON schema) | code | harness `runtimeOptions.outputSchema` | — |
+| Live input steering | auto + code | built into ordinary Slack, Telegram, and web-console turns; custom hosts use `runtimeOptions.liveInput` | — |
 | Tool approval gates (risk tiers, timeouts, always-allow) | code | `createMonoRuntime({ onToolApprovalRequest, ... })` — needs a host UI | — |
 | Fully custom runtime | code | `startMonoAgentApp({ runtime })` | — |
 
@@ -29,7 +30,7 @@ Every framework capability and how a composed agent reaches it. This table is th
 | Public name plus identity and optional soul documents; wizard Role has one explicit destination and created/preserved outcome | config + cli | `agent.name`, `context.identityPath`, `context.soulPath`; guided Role is `IDENTITY.md` → `## Role`, and an existing identity is never overwritten | `agent.public-name`, `context.identity`, `context.soul` |
 | Selected skills from a skills root | config | `context.skillsRoot`, `context.selectedSkills` | `skills.selected-activation` |
 | Generated project configuration skills with progressive disclosure | config + cli | init selects `mono-agent-configure` + `mono-agent-memory` under `./skills` with `context.skillDisclosure: "index"`; drift: `mono-agent install-skill --project --check\|--update` | `app.managed-project-skills` |
-| Version-matched semantic documentation companion for the global composer skill | cli + tool | `mono-agent install-skill` pairs `mono-agent-docs` with every available Codex/Claude target by default; `--no-docs-mcp` opts out; tool `search_mono_agent_docs` searches full offline excerpts from `@mono-agent/docs-mcp` | — |
+| Version-matched semantic documentation companion for the global composer skill | cli + tool | `mono-agent install-skill` pairs `mono-agent-docs` with every available Codex/Claude target by default; `--no-docs-mcp` opts out; `mono_agent_docs` uses `action: "search"` for ranked 2–3k excerpts and `action: "read"` for anchored windows up to 10k, internal-link targets, and exact continuation actions | — |
 | Per-skill byte cap | config | `context.skillMaxBytes` | `skills.byte-capping` |
 | Conversation history (owner-only durable store) | auto | 64 messages per exact conversation id independent of `runtime.maxTurns`; aggregate defaults 256 MiB / 10,000 conversations / 365 inactive days; staged atomic publication and post-commit pruning; custom store via code | — |
 | Lite memory (FTS keyword recall + rapid-log capture; no external deps) | config | `memory.mode: "lite"`, `path`, `maxBytes`, `writeMode` | `memory.lite` |
@@ -38,7 +39,7 @@ Every framework capability and how a composed agent reaches it. This table is th
 | BuJo memory (journal + LLM capture/reconcile ADD/UPDATE/SUPERSEDE/NOOP + entity graph + auto-scheduled consolidation; needs embeddings + an app-level `memory.llm`) | config | `memory.mode: "bujo"`, `path`; selected Ollama/LM Studio/OpenAI embeddings are independent from explicit `memory.llm` with `provider: "ollama"` (`model`, optional `endpoint`) or `provider: "agent-host"` (`model` is an SDK runtime model ref, optional `executionMode: "sdk"`) — see `docs/memory/index.md` | `memory.bujo` |
 | Supermemory external backend (server-side extraction/consolidation; async ingestion; explicitly installed plugin) | config | `memory.backend: "supermemory"`, `memory.writeMode`, `memory.supermemory.{baseUrl,apiKey,apiKeyEnv,container,timeoutMs,exposeMcpServer}`; install the exact matching `@mono-agent/memory-supermemory` version | `memory.backend-supermemory` |
 | BuJo consolidation auto-scheduler (projection-only `index.md` refresh + empty `future-log.md` stub + duplicate-group reporting; in-app, no external cron needed) | config | `memory.consolidation.{enabled,cron}` (five-field UTC, default `0 */2 * * *`, no hashed `H`); env `MONO_AGENT_MEMORY_CONSOLIDATION_CRON`, `MONO_AGENT_MEMORY_CONSOLIDATION_ENABLED` | `memory.bujo-consolidation` |
-| Memory maintenance CLI | cli | `mono-agent memory <subcommand>` from the agent folder (stats/today/show/search/top/audit/inspect/rebuild/rollback/…). The standalone `memory-bujo <subcommand> <root>` CLI was removed — its bin now prints a redirect and exits non-zero; routine BuJo consolidation runs via the in-app scheduler | — |
+| Memory maintenance CLI | cli | `mono-agent memory <subcommand>` from the agent folder (stats/today/show/search/top/audit/inspect/rebuild/rollback/…). The standalone `memory-bujo <subcommand> <root>` CLI and bin were removed; routine BuJo consolidation runs via the in-app scheduler | — |
 | Config-aware memory preview CLI (stats/today/show/search/top plus metadata-only audit; remains available when the live recall tool is disabled; local search warns and falls back to FTS-only when embeddings are down) | cli | `mono-agent memory stats\|today\|show <date>\|search <query>\|top\|audit [--limit <n>] [--json]` | — |
 | Memory liveness check (managed tier/provider/model/dimension identity; provider-native typed discovery plus real finite-vector/dimension probe for Ollama or LM Studio; declared auth env; BuJo LLM config + consolidation cadence; no cross-provider fallback) | cli | `mono-agent validate` | — |
 | Memory write modes and per-turn BuJo capture | config | `memory.writeMode`: `disabled`, `append-host-summary`, or `capture`; capture requires `memory.mode: "bujo"` | `memory.write-mode`, `memory.per-turn-capture` |
@@ -54,7 +55,7 @@ Every framework capability and how a composed agent reaches it. This table is th
 | MCP servers (stdio/sse/http) from a JSON file | config | `tools.mcpConfigPath` | `tool-policy.mcp-servers` |
 | Durable origin-bound continuations for trusted stdio/loopback-HTTP MCP services | config + auto | `tools.continuationServers` + `continuations.*`; interactive claims pin a bounded immutable origin snapshot before commit, exact rollover buckets are preserved, v3 state is restart-safe, and unavailable/legacy snapshots use a fixed zero-model fallback | `agent-app.durable-continuations` |
 | Adapter-derived send tools for enabled Slack/Telegram adapters | config | auto-available under allow-all once the channel is enabled; a **specific** `tools.allowedTools` must include `SlackSendMessage` / `TelegramSendMessage`; valid `slack.*` / `telegram.*` config and existing adapter allowlists provide credentials and destination bounds; confirmed message posts are idempotently recorded in destination history | `agent-app.adapter-send-tools` |
-| Interaction bridge for adapter-send history, blocking asks, and MCP progress | config + auto | `interaction.bridge.{host,port}`, `interaction.askUser.timeoutMs`, `interaction.progress.enabled`; env `MONO_AGENT_INTERACTION_BRIDGE_HOST`, `MONO_AGENT_INTERACTION_BRIDGE_PORT`, `MONO_AGENT_ASK_USER_TIMEOUT_MS`, `MONO_AGENT_PROGRESS_ENABLED`. It auto-starts for configured Slack/Telegram send tools, when `AskUser` or `TelegramAskButtons` is allowed, when an `interaction` block or interaction env override is configured, or when `interaction.progress.enabled` resolves true and `tools.mcpRequestContextServers` names at least one opted project stdio MCP server. | `interaction.bridge` |
+| Interaction bridge for adapter-send history, structured blocking asks, and MCP progress | config + auto | `interaction.bridge.{host,port}`, `interaction.askUser.timeoutMs`, `interaction.progress.enabled`; env `MONO_AGENT_INTERACTION_BRIDGE_HOST`, `MONO_AGENT_INTERACTION_BRIDGE_PORT`, `MONO_AGENT_ASK_USER_TIMEOUT_MS`, `MONO_AGENT_PROGRESS_ENABLED`. It auto-starts for configured Slack/Telegram send tools, when `AskUser` is allowed, when an `interaction` block or interaction env override is configured, or when `interaction.progress.enabled` resolves true and `tools.mcpRequestContextServers` names at least one opted project stdio MCP server. AskUser presents all questions together on web and sequential native controls on Slack/Telegram. | `interaction.bridge` |
 | Sandbox on/off + srt engine (Pi-owned tools; direct Codex has its own sandbox, Claude/direct OpenCode reject native mono policy) | config | `sandbox.mode` | `sandbox.mode` |
 | Network policy (none/localhost/allowlist/all) | config | `sandbox.network.{mode,allowlist}` | `sandbox.network-policy` |
 | Filesystem scopes (readable/writable roots, deny-write globs) | config | `sandbox.readableRoots`, `sandbox.writableRoots`, `sandbox.denyWrite` | `sandbox.filesystem-scopes` |
@@ -68,7 +69,7 @@ Every framework capability and how a composed agent reaches it. This table is th
 | Webhook (sync/async HTTP invoke + status polling + optional bearer) | config | `webhook` section; `apiKey` protects invoke/status and is required with non-loopback opt-in; endpoint overrides at `webhook.endpoints[].{model,effort,maxRunMs}`; endpoint `maxRunMs` wins over the `webhook.maxRunMs` fallback and `0` disables that endpoint watchdog | `webhook.http-invoke`, `webhook.run-watchdog` |
 | OpenAI-compatible API (/v1/models, /v1/chat/completions, SSE, bearer) | config | `openaiApi` section; sampling fields remain request metadata, while non-default values are ignored with a `runtime_warning` and runtime config stays authoritative | `openai-api.chat-completions` |
 | Telegram long polling and chat allowlist | config | `telegram` section | `telegram.long-polling` |
-| Telegram runtime/command/reaction/button/file interactivity | config + code | built-in per-chat `/model` and `/effort` use configured primary/fallback models (no Telegram config key); `telegram.commands[]`, `telegram.reactions`, `telegram.quietHours`; `TelegramAskButtons` / `TelegramSendFile` through `tools.allowedTools` | `telegram.interactive` |
+| Telegram runtime/command/reaction/button/file interactivity | config + code | built-in per-chat `/model` and `/effort` use configured primary/fallback models (no Telegram config key); `telegram.commands[]`, `telegram.reactions`, `telegram.quietHours`; `AskUser`, non-blocking `TelegramSendMessage.reply_options`, and `TelegramSendFile` | `telegram.interactive` |
 | Telegram inbound audio transcription | config | `telegram.transcription.{endpoint,model,language,timeoutMs}`; opt-in OpenAI-compatible transcription endpoint for voice notes, audio files, and round-video attachments | `telegram.transcription` |
 | Slack (Socket Mode, channel allowlist, mention handling, native runtime controls) | config + code | `slack` section; built-in Block Kit controls use configured primary/fallback choices through DM-wide/thread-local `@agent /model` and `@agent /effort`, plus channel-wide workspace commands `/<bot>-model` and `/<bot>-effort` derived from `auth.test.user` (Slack app registration + `commands` scope; no mono-agent config key) | `slack.socket-mode` |
 | Slack global/message shortcuts | config | `slack.shortcuts[]: {callbackId, prompt, channelId?, ackText?, threadReply?}`; JSON-only | `slack.shortcuts` |
@@ -78,7 +79,6 @@ Every framework capability and how a composed agent reaches it. This table is th
 | A2A provider (Agent Card, JSON-RPC + REST, streaming, bearer, configurable request-body limit, opt-in durable dispatch identity) | config | `channels.plugins[].package: "@mono-agent/a2a-adapter"` plus plugin `config.provider` (including `maxRequestBytes` and `idempotency.{namespace,stateDir,retentionMs,maxRecords}`), `config.agent`, `config.skill`; `config.enabled` is canonical | `a2a.provider` |
 | A2A consumer settings (remote agent URLs, timeouts) and calls | config + code | same A2A plugin entry's `config.consumer`; calls via `sendA2AMessage({ idempotencyKey })` or `createA2AConsumerResponder({ idempotencyKeyForRequest })` | `a2a.consumer` |
 | TUI stream endpoint (operator console transport) | config | `tui.{enabled,host,port,basePath,allowNonLoopback,apiKey}`; default on, loopback | `tui.stream-endpoint` |
-| Live event relay (read-only run-event SSE for web) | config | `live.{enabled,host,port,basePath,allowNonLoopback,apiKey}`; default on, loopback | `live.event-relay` |
 | Cron jobs (five-field expressions, timezones, stable job-id-seeded `H`; agent-app pins overlap to skip) | config + code | `cron.jobs[]`, including per-job `model` / `effort`; single-job `MONO_AGENT_CRON_*`, or one markdown file per job in `cron.dir` / `MONO_AGENT_CRON_DIR` (default `cron/`); queue/replace controls are programmatic-only `startCronAdapter` options | `cron.scheduled-prompts` |
 | Cron per-run watchdog | config + code | `cron.jobs[].maxRunMs` or `maxRunMs` frontmatter; programmatic adapter fallback via `startCronAdapter({ maxRunMs })` | `cron.run-watchdog` |
 | Per-request runtime model and effort overrides | config + code | `cron.jobs[].{model,effort}`; `webhook.endpoints[].{model,effort}` plus request body `{model,effort}` (request wins); Telegram `/model` and `/effort`; Slack Block Kit selectors through thread-local `@agent /model` / `@agent /effort` and channel-wide `/<bot>-model` / `/<bot>-effort`, all over configured primary/fallback models | `runtime.per-trigger-model` |
@@ -90,13 +90,12 @@ Every framework capability and how a composed agent reaches it. This table is th
 
 | Capability | Coverage | Where | Registry config ids |
 | --- | --- | --- | --- |
-| JSONL run artifacts (events + summaries; strings capped; non-numeric values under sensitive-looking object keys are redacted; numeric values under matched keys are retained; free text is not content-scanned) | config | `artifacts.dir`, `artifacts.retention`, `artifacts.memoryRetention` | `observability.jsonl-artifacts` |
+| JSONL run artifacts (events + summaries; strings capped; non-numeric values under sensitive-looking object keys are redacted; numeric values under matched keys are retained; retained free text is scanned for a closed set of high-confidence credential shapes) | config | `artifacts.dir`, `artifacts.retention`, `artifacts.memoryRetention` | `observability.jsonl-artifacts` |
 | Trace-source registry (heartbeat manifests `mono-agent status` reads) | config | `traceability.{registryDir,sourceId,sourceLabel,heartbeatMs,staleAfterMs,globalDiscovery}` | `observability.trace-registry` |
 | Phoenix trace viewer (best-effort terminal-batched OTLP exporter; independent local JSONL has bounded terminal snapshots and can lose RAM-buffered events on crash) | config | `observability.exporters` (phoenix entry) | `observability.phoenix-exporter` |
 | Operator console (live chat with thinking/tool/telemetry insight, run replay, config view) | cli | `mono-agent tui [--agent <label>]`; agents serve the `tui` stream endpoint by default (`tui.enabled`, loopback) | — |
 | Always-on multi-agent web console (persistent conversations and same-thread quotes, fixed compact/expanded rail, offline-agent filtering that always preserves pinned/selected agents, alive-page/PWA response notifications, attachments, model/effort selection, reasoning/tools, hidden telemetry-backed cumulative context usage, cancellation) | cli | `mono-agent web start\|stop\|restart\|status\|logs\|run`; bare `mono-agent web` is read-only status/help; default `0.0.0.0:5050`, `--loopback` narrows to `127.0.0.1`; notifications require explicit per-origin browser permission plus a secure context and do not use Web Push; package `@mono-agent/web`; no app authentication, so LAN/Tailnet reachability is the access boundary | — |
 | Managed proposal-only SELF-CONFIG conversation | cli + tool | macOS `mono-agent tui --configure` attaches to the authoritative background agent; persistent marker and capability map; stable configuration conversation with a fresh proposal capability after each checkpoint; host-gated `ProposeAgentConfiguration`; approval restarts and waits for readiness, failed start rolls files/agent back; only quitting exits. `--local` is ordinary chat only; off macOS configuration is manual | — |
-| Session Recorder web PWA (read-only run browser) | cli | Command removed — use `mono-agent tui` (recorded-run replay) or `mono-agent web` (live console); the `@mono-agent/session-web` package still ships without a CLI launcher, and `MONO_AGENT_WEB_AUTH_TOKEN` is no longer read by any code (its only reader, the removed `sessions` command, is gone) | — |
 | Setup presets (saved answer-sets: generate config + `.env.example` + checklist) | cli | `mono-agent presets list\|show <id>`, `mono-agent init --preset <id> --yes` (the `recipes` command and `--recipe` alias were removed) | — |
 | Interactive setup wizard (preset/custom; exact `IDENTITY.md` → `## Role` prompt/outcome; walks model→channels→memory→tools→sandbox→observability; Journal/BuJo explicitly choose Ollama or LM Studio service root/model/dimension/optional auth env using typed discovery and a real probe; macOS starts the background agent before persistent SELF-CONFIG) | cli | `mono-agent init` (no flags, on a TTY; `setup` alias); manual embedding entry still requires readiness probe; flags/non-TTY stay scaffold-only; unsupported platforms use manual configuration/foreground start/ordinary TUI | — |
 | Tools reporting + no-tools guardrail (allow-all → `All tools allowed`; explicit empty `allowedTools: []` → `waiting`; unknown-tool "did you mean"; send-tool/channel cross-checks) | cli | part of `mono-agent validate`/`doctor`; the wizard's tools step | — |

package/skills/mono-agent-composer/references/package-map.md

@@ -51,7 +51,7 @@ Use this path when the agent needs identity, selected skills, history, and optio
 | Memory substrate (schema, migrations, FTS+vector db, RRF) | `@mono-agent/memory/store` | SQLite storage, BM25 FTS, optional vector index, hybrid recall; re-exports `MemoryStore`/`MemoryBlock`/`MemoryWriteResult` from `@mono-agent/agent-contracts` |
 | Memory engine (all tiers: lite/journal/bujo) | `@mono-agent/memory/bujo` | `BujoMemoryStore` — tier-aware: FTS recall (lite), hybrid recall + static salience (journal), LLM capture/reconcile + entity graph + projection-only scheduled consolidation (bujo) |
 | Embedding providers | `@mono-agent/memory/search` | Exclusive Ollama/LM Studio/OpenAI embedding providers used by the store subpath for vector recall; `agent-app` owns guided typed discovery and the real readiness probe |
-| Composer documentation search | `@mono-agent/docs-mcp` (optional plugin) | Exact-version offline hybrid semantic/BM25 search over canonical docs and composer references through `search_mono_agent_docs`; paired by `mono-agent install-skill`, outside the composed agent's own `mcp.json` |
+| Composer documentation search + guided reading | `@mono-agent/docs-mcp` (optional plugin) | Exact-version offline hybrid semantic/BM25 `mono_agent_docs` search plus anchored reads, cross-link resolution, and continuation windows over canonical docs and composer references; paired by `mono-agent install-skill`, outside the composed agent's own `mcp.json` |
 | External Supermemory backend | `@mono-agent/memory-supermemory` (optional plugin) | Explicitly installed lockstep package selected by `memory.backend: "supermemory"`; proxies the shared `MemoryStore` / `MemoryRecall` contracts to local or hosted Supermemory for server-side extraction, consolidation, and hybrid recall |
 | Recall tool surface | `@mono-agent/agent-app` (bundled) | Auto-provisions read-only `MemoryRecall` for every configured tier and direct configured responder; automatic/tool recall share the same store and per-turn query cache |
 
@@ -105,7 +105,7 @@ Communication adapters are edge packages. They accept an `AgentResponder` and ow
 | Slack | `@mono-agent/slack-adapter` | Allowed channel or DM gets the final reply |
 | WhatsApp | `@mono-agent/whatsapp-adapter` (external channel plugin) | Allowed sender/group trigger produces a reply |
 | OpenAI-compatible API | `@mono-agent/openai-api-adapter` | `curl /v1/models` and `/v1/chat/completions` |
-| Operator endpoints | `@mono-agent/operator-adapter` | `mono-agent tui` and `mono-agent web` connect for chat; the read-only `live` relay feeds operator tooling such as the `@mono-agent/session-web` PWA |
+| Operator endpoint | `@mono-agent/operator-adapter` | `mono-agent tui` and `mono-agent web` connect for chat |
 | A2A provider/consumer | `@mono-agent/a2a-adapter` (external channel plugin) | Send text to the Agent Card URL |
 | Webhook | `@mono-agent/webhook-adapter` | `curl` the configured invocation path (with `Authorization: Bearer ...` when `apiKey` is set) |
 | Cron | `@mono-agent/cron-adapter` | One scheduled or manually triggered invocation |
@@ -116,13 +116,12 @@ Adapters must not import the harness, runtime adapter, memory package (`@mono-ag
 
 Use:
 
-- `@mono-agent/tui` for the pi-tui operator console (`mono-agent tui`): live chat with structured stream-event insight, recorded-run replay, and config view. Remote event frames have a strict 256 KiB UTF-8 NDJSON cap: assistant-thought/tool-call payload fields are reduced and remeasured, while another oversized variant or a reducible event whose minimal form still does not fit becomes a bounded `oversized_event` marker. Other frame kinds are unaffected, and replay contains only key-redacted, capped events that reached terminal JSONL persistence.
+- `@mono-agent/tui` for the pi-tui operator console (`mono-agent tui`): live chat with structured stream-event insight, recorded-run replay, and config view. Remote event frames have a strict 256 KiB UTF-8 NDJSON cap: assistant-thought/tool-call payload fields are reduced and remeasured, while another oversized variant or a reducible event whose minimal form still does not fit becomes a bounded `oversized_event` marker. Other frame kinds are unaffected, and replay contains only sensitive-key-redacted, credential-scanned, capped events that reached terminal JSONL persistence.
 - `@mono-agent/web` for the assistant-ui always-on browser console (`mono-agent web`): persistent multi-agent conversations and same-thread quotes, fixed compact/expanded agent navigation with offline filtering, explicit alive-page/PWA response notifications, device-local file picking, streamed reasoning/tools, internal telemetry-backed cumulative context usage, cancellation, LAN-default HTTP on port 5050, and conflict-safe optional Tailscale Serve HTTPS. It has no app login; network reachability is the access boundary.
-- `@mono-agent/session-web` for the read-only Session Recorder PWA. Its `sessions` launcher command was removed (use `mono-agent tui` for recorded-run replay or `mono-agent web` for the live console); the package still ships without a CLI command and full retirement is pending. Local artifact paging and live relay aggregation stay on its port 4599 surface.
-- `@mono-agent/operator-adapter` for the loopback NDJSON stream endpoint the TUI and web chat console connect to (`tui` config section, on by default) and the read-only live SSE endpoint operator tooling observes (`live` config section, on by default).
+- `@mono-agent/operator-adapter` for the loopback NDJSON stream endpoint the TUI and web chat console connect to (`tui` config section, on by default).
 - `@mono-agent/observability` for JSONL event artifacts, summaries, trace-source registration, and the `@mono-agent/observability/otel` Phoenix OTLP exporter configured via `observability.exporters`.
 
-Traceability is local-first. A running host registers a source manifest; `mono-agent status` reads the trace-source registry to report live sources, and artifacts are keyed by `(sourceId, runId)` so duplicate run ids do not collide. Phoenix is the recommended trace viewer when an `observability.exporters` (phoenix) entry is configured; its terminal-batched export is best-effort. Independently, the local recorder writes empty events plus a `running` summary at start and a key-redacted, capped snapshot at finish/fail. Events stay in RAM between those boundaries, so a crash can lose them. Without Phoenix, those bounded terminal JSONL snapshots are the only local run record.
+Traceability is local-first. A running host registers a source manifest; `mono-agent status` reads the trace-source registry to report live sources, and artifacts are keyed by `(sourceId, runId)` so duplicate run ids do not collide. Phoenix is the recommended trace viewer when an `observability.exporters` (phoenix) entry is configured; its terminal-batched export is best-effort. Independently, the local recorder writes empty events plus a `running` summary at start and a sensitive-key-redacted, credential-scanned, capped snapshot at finish/fail. Events stay in RAM between those boundaries, so a crash can lose them. Without Phoenix, those bounded terminal JSONL snapshots are the only local run record.
 
 ## Multi-Agent Join
 

package/skills/mono-agent-composer/references/playbooks.md

@@ -190,7 +190,7 @@ const orchestrator = await createConfiguredAgentResponder({
 
 ## 10. Phoenix-observed agent with the TUI
 **For:** an agent builder evaluating runs in a tracing dashboard.
-**Goal:** run locally with the TUI, attempt a best-effort terminal-batched Phoenix export, and retain a key-redacted, capped local JSONL snapshot after terminal persistence. A pre-terminal crash can omit the Phoenix batch and lose RAM-buffered JSONL events.
+**Goal:** run locally with the TUI, attempt a best-effort terminal-batched Phoenix export, and retain a sensitive-key-redacted, credential-scanned, capped local JSONL snapshot after terminal persistence. A pre-terminal crash can omit the Phoenix batch and lose RAM-buffered JSONL events.
 **Features:** `observability.phoenix-exporter`, `observability.jsonl-artifacts`, `observability.trace-registry`, `tui.chat`.
 
 ```json
@@ -202,7 +202,7 @@ const orchestrator = await createConfiguredAgentResponder({
 }
 ```
 **Steps:** start Phoenix (6006) → `init` → add artifacts/traceability/exporter → `validate` (POSTs an empty protobuf) → `start` (prints the Phoenix endpoint) → `mono-agent tui`.
-**Smoke:** complete a TUI prompt; confirm a JSONL artifact AND a Phoenix trace with merged tool spans under the project. Artifact/export strings are capped; non-numeric values under sensitive-looking object keys are redacted; numeric values under matched keys are retained; free text is not content-scanned or scrubbed.
+**Smoke:** complete a TUI prompt; confirm a JSONL artifact AND a Phoenix trace with merged tool spans under the project. Strings are capped. For local artifacts, non-numeric values under sensitive-looking object keys are redacted; numeric values under matched keys are retained; retained free text is scanned for a closed set of high-confidence credential shapes. Phoenix applies that scan only when `contentPatternRedaction` is true.
 
 ## 11. Backfill historical runs to Phoenix
 **For:** an ops engineer onboarding observability after the fact.
@@ -275,7 +275,7 @@ per-route form for a new agent.
 **Goal:** one Telegram agent uses `AskUser`, long-running MCP tool progress, a self-hosted Bot API server, and `TelegramSendFile`.
 **Features:** `telegram.long-polling`, `agent-app.adapter-send-tools`, `interaction.ask-user`, `interaction.progress`, `tool-policy.mcp-servers`.
 
-**Bridge startup:** the loopback interaction bridge auto-starts when `AskUser` or `TelegramAskButtons` is allowed, when the `interaction` block or an interaction env override is configured, or when `interaction.progress.enabled` resolves true and `tools.mcpRequestContextServers` names at least one opted project MCP server.
+**Bridge startup:** the interaction bridge defaults to loopback and auto-starts when `AskUser` is allowed, when the `interaction` block or an interaction env override is configured, or when `interaction.progress.enabled` resolves true and `tools.mcpRequestContextServers` names at least one opted project MCP server. Keep `interaction.bridge.host` on loopback because non-loopback values are not rejected. AskUser takes one to five structured questions with two or three described choices each; Telegram presents them sequentially with native buttons, Other/custom reply, and Done for multi-select.
 
 ```json
 {

package/skills/mono-agent-composer/references/validation.md

@@ -43,6 +43,26 @@ mono-agent start
 
 Every channel the user asked for must report `running` with its endpoint facts; anything `failed` is a blocker, not a footnote.
 
+On macOS, managed start also installs a no-`KeepAlive` recovery helper that runs
+at login and every five minutes. It safely reconciles an inactive worker, a
+changed keyed snapshot, or a different available controller CLI closure without
+executing mutable source bytes. The existing worker stays live during runtime
+installation; failed recovery preserves the helper and both definitions for the
+next scheduled retry. `mono-agent stop` removes that authority, so an explicitly
+stopped agent is not resurrected.
+
+Confirm the authoritative process boundary with:
+
+```bash
+mono-agent status --json
+```
+
+Treat `ok: true` as proof only because the status command now requires the trace
+PID to be alive and equal launchd's current PID. When launchd has no matching
+live process, cached `running` channels are rendered `stopped`, live endpoint
+facts are omitted, `pid` is `null`, and the command exits 1. Do not interpret an
+old trace manifest by itself as a running consumer.
+
 ## Documentation Validation
 
 To confirm a skills folder is indexable (replace `<skillsRoot>` with the
@@ -104,7 +124,7 @@ pnpm run test:demo
 | A2A | Send text to the Agent Card URL with `sendA2AMessage()`. |
 | Webhook | `curl` the invocation path and inspect the response body/status. |
 | Cron | Run a one-off scheduled invocation or wait for one tick. |
-| Observability | Confirm a run writes a JSONL artifact with strings capped: non-numeric values under sensitive-looking object keys are redacted; numeric values under matched keys are retained; free text is not content-scanned. If an `observability.exporters` Phoenix entry is set, confirm the trace appears in Phoenix. |
+| Observability | Confirm a run writes a JSONL artifact with strings capped: non-numeric values under sensitive-looking object keys are redacted; numeric values under matched keys are retained; retained free text is scanned for a closed set of high-confidence credential shapes. If an `observability.exporters` Phoenix entry is set, confirm the trace appears in Phoenix. |
 | Memory recall tool | With any memory tier configured (`memory.recallTool.enabled` defaults on), ask the agent to recall an old note and confirm `MemoryRecall` appears separately from action-tool allowlists and returns it. |
 | Semantic memory search | With `memory.embeddings` set, first prove the configured provider only: Ollama model advertises `embedding` through `/api/show` and answers `/api/embed`, or LM Studio model has exact `type: "embedding"` in `/api/v1/models` and answers `/v1/embeddings`. Verify the finite vector dimension matches config, then ask a paraphrased question about an old note and confirm `MemoryRecall` returns it. Never accept a cross-provider fallback as proof. |