@loompad/cli 0.1.0 → 1.1.1

package/docs/integration-notes.md

@@ -3,27 +3,102 @@
 These are not guesses: each surface below was verified against the locally installed
 tool before the adapter was written. Re-verify when versions move.
 
-## Claude Code (verified: v2.1.83)
+## Claude Code (verified: v2.1.278, Agent SDK 0.3.283)
 
-Headless invocation per turn:
+Loom drives the user's installed `claude` through the Claude Agent SDK
+(`@anthropic-ai/claude-agent-sdk`), one warm streaming-input `query()` per chat
+session, the way t3code does (`src/providers/claude/adapter.ts`). Each turn is one
+more user message on the open stream. The SDK speaks the CLI's stream-json control
+protocol over stdio:
 
 ```
-claude -p "<prompt>" \
-  --output-format stream-json --verbose \
-  [--resume <session-id>] \
-  [--append-system-prompt "<loom briefing>"] \
-  --permission-mode acceptEdits
+claude --output-format stream-json --verbose --input-format stream-json \
+  --permission-prompt-tool stdio --setting-sources=user,project,local \
+  --permission-mode <mode> (--session-id=<uuid> | --resume=<uuid>) [--model <m>]
+  [--include-partial-messages] [--mcp-config <json>]
+stdin:  control_request {subtype: "initialize"}  → control_response
+        {type: "user", message: {content: [{type: "text", text}]}, uuid: <turn id>}  (per turn)
+        control_request {subtype: "set_model", model}                          (model switch)
+stdout: system/init (session_id) · system/status (requesting | compacting) ·
+        stream_event (message_start, content_block_delta text/thinking) ·
+        system/compact_boundary {pre_tokens, post_tokens} · assistant (content, usage) ·
+        rate_limit_event {utilization 0–1, rateLimitType, resetsAt s} ·
+        result (usage, total_cost_usd, modelUsage[*].contextWindow)
 ```
 
-- `--output-format stream-json` — newline-delimited JSON events on stdout:
-  - `{"type":"system","subtype":"init","session_id":...}` → capture session id
-  - `{"type":"assistant","message":{"content":[{"type":"text"|"tool_use",...}]}}`
-  - `{"type":"result","subtype":"success","total_cost_usd":...}` → run complete
-- `--resume <session-id>` — continue the same conversation across turns.
-- `--append-system-prompt` — **this is how Loom injects the handoff briefing** without
-  touching user files.
-- `--permission-mode` — `acceptEdits` default for baton holders (configurable).
-- Interrupt = SIGINT to the child process (escalate SIGKILL).
+- `pathToClaudeCodeExecutable` points the SDK at the user's `claude`, so the
+  signed-in version runs. `spawnClaudeCodeProcess` lets Loom spawn it in its own
+  process group (quiescence for Brain), and capture stderr.
+- `systemPrompt: {type: "preset", preset: "claude_code"}` and
+  `settingSources: ["user", "project", "local"]` reproduce an interactive
+  `claude`; the SDK loads neither by default. A warm session's system prompt is
+  fixed when it starts, so a handoff briefing rides in front of the turn's text.
+- The session id is chosen up front (`--session-id`, a UUID) and is the resume
+  cursor; `initializationResult()` proves the session opened before any prompt.
+- Permissions: "ask" is `permissionMode: default` with `canUseTool` answered
+  in-process by Loom's approval broker (no MCP shim); "auto" is `acceptEdits`;
+  "bypass" is `bypassPermissions` with `allowDangerouslySkipPermissions`.
+- Interrupt closes the session (query and process group), as t3code does:
+  `interrupt()` can acknowledge while background tasks keep the CLI alive. Loom
+  reports `interrupted`; the next turn resumes the same session.
+- A resumed session that no longer exists: the CLI prints `No conversation found`
+  and exits before reading the prompt; `initializationResult()` rejects with it
+  (verified live, 2.1.x). Loom starts a new session, or with Brain continuity
+  reports `NativeSessionMissing` so Brain rebuilds into a new epoch.
+- Context in use is the main thread's last response usage (input + cache read +
+  cache creation + output); the window comes from the result's `modelUsage`.
+- The SDK package pulls a platform binary as an optional dependency (~228 MB);
+  Loom never runs it because `pathToClaudeCodeExecutable` is always set.
+
+## Codex (verified: codex-cli 0.153.4)
+
+Loom keeps one warm `codex app-server` per chat session
+(`src/providers/codex/adapter.ts`): newline-delimited JSON-RPC (`{id, method,
+params}`, no `jsonrpc` field), the protocol t3code uses. The thread stays open, so
+each turn is one `turn/start` on the same connection.
+
+```
+initialize {clientInfo, capabilities: {experimentalApi: true}} → initialized
+thread/start {cwd, sandbox, approvalPolicy, model?, config?}
+  | thread/resume {threadId, excludeTurns: true, …same}
+turn/start {threadId, input: [{type: "text", text, text_elements: []}], model?, effort?,
+  clientUserMessageId?}
+… item/agentMessage/delta · item/reasoning/textDelta · item/reasoning/summaryTextDelta ·
+  item/commandExecution/outputDelta · turn/plan/updated · turn/diff/updated · model/rerouted
+… item/started · item/completed (agentMessage, reasoning, commandExecution, fileChange,
+  mcpToolCall, webSearch, contextCompaction) · thread/tokenUsage/updated
+  {total, last, modelContextWindow} · account/rateLimits/updated · error {willRetry}
+turn/completed {turn: {id, status: completed | interrupted | failed, error}}
+turn/interrupt {threadId, turnId}
+```
+
+- Sandbox and approvals per Loom mode: bypass → `danger-full-access` + `never`;
+  auto → `workspace-write` + `never`; ask → `read-only` + `untrusted`, and each
+  `item/commandExecution/requestApproval` / `item/fileChange/requestApproval` is
+  answered by Loom's approval broker. Requests Loom can't put to a person
+  (elicitations, extra permissions) are declined rather than left waiting.
+- Project MCP servers go in `thread/start` config as `mcp_servers.<key>`.
+- Context in use is `last.totalTokens`; `inputTokens` already includes cached
+  tokens and `outputTokens` includes reasoning, so neither is added twice.
+- A missing thread on resume is an error response; Loom starts a new thread, or
+  with Brain continuity reports `NativeSessionMissing`.
+- The account's own default model comes from `~/.codex/config.toml`. A model the
+  account can't use fails the turn with Codex's 400; `model/list` says which
+  models the account offers.
+
+### Warm sessions and Brain continuity
+
+A session per (chat, agent) stays up between turns and is reaped after 30 minutes
+idle (its binding keeps the resume cursor). A turn — Brain continuity turns included
+— settles at turn level: the provider reported it complete and no command it started
+(`commandExecution` / Bash item) is still running.
+
+Plan mode: Codex `turn/start.collaborationMode {mode: "plan" | "default", settings:
+{model, reasoning_effort, developer_instructions}}`; Claude `setPermissionMode("plan")`,
+and the plan arrives as the `ExitPlanMode` tool's input (Claude first writes it to
+`~/.claude/plans/`). Questions: Codex `item/tool/requestUserInput` → `{answers: {id:
+{answers: [..]}}}`; Claude `AskUserQuestion` through `canUseTool` → `updatedInput:
+{questions, answers: {<question text>: <label>}}`.
 
 ## OpenCode (verified: v1.17.20)
 
@@ -66,11 +141,44 @@ Dogfood findings (verified live on 1.17.20):
   spawning agents — running `loom` from inside a Claude Code terminal otherwise poisons
   nested agent auth.
 
-## Antigravity (bridge, best-effort)
+## Antigravity — the CDP bridge, and what replaced it (verified: `agy` 1.1.6)
+
+**The bridge is withdrawn.** It is kept here because the spike is worth the record, not
+because it is on offer.
+
+The original integration drove the Antigravity IDE. Launched with a debug port, the app
+exposes a Chromium DevTools endpoint:
 
-Launched with a debug port it exposes a Chromium DevTools endpoint:
 - `GET http://127.0.0.1:{port}/json/version` — presence check
 - `GET http://127.0.0.1:{port}/json` — target list (read-only visibility)
 
-No stable send/interrupt/memory surface → **Bridge tier** (never holds the baton),
-receives projections via `.loom/memory/antigravity.md`.
+There was no stable send/interrupt/memory surface behind it, so it could only watch, which
+put it in the **Bridge tier** — never the baton, projections delivered as a file the human
+driving the GUI reads (`.loom/memory/antigravity.md`).
+
+Google then shipped a headless CLI, and it graduated: `antigravity-cli` is a real adapter
+that holds the baton and runs a turn to completion with no GUI in the loop
+(`src/adapters/antigravity-cli.ts`). One process per turn:
+
+```
+agy -p "<text>" --dangerously-skip-permissions --add-dir <dir> \
+    --model <model> --print-timeout <dur>
+agy -p "<text>" --conversation <id> …            (follow-up turns)
+```
+
+- `-p/--print` runs one prompt non-interactively and prints **only** the final assistant
+  message (markdown) to stdout, then exits 0. There is no JSON event stream — so the
+  adapter reports the final message plus the files it touched, parsed from the
+  `[name](file://…)` links `agy` emits.
+- No tokens and no cost come back, so turns report a model and a duration and nothing
+  else. A price table would only produce a fabricated number rendered as fact.
+- Conversations are keyed by working directory in
+  `~/.gemini/antigravity-cli/cache/last_conversations.json`. The adapter reads the id back
+  after a fresh turn and resumes it explicitly with `--conversation` from then on, so
+  continuity survives another tool rewriting that mapping.
+- `agy` leaves a language server holding the stdout pipe after it exits, so anything
+  reading it must key off process exit rather than EOF.
+
+The bridge's registration still exists — deleting it would stop any project that still
+names `kind: "antigravity"` from opening at all — but it is in `WITHDRAWN_KINDS` and no
+surface offers it (`src/adapters/index.ts`). The one remaining bridge is **Kiro**.

package/docs/loompad.md

@@ -0,0 +1,105 @@
+# LoomPad
+
+LoomPad is the physical companion for Loom: a printable ESP32-S3 desk pad that
+selects an agent, sets effort, captures hold-to-talk audio, and sends work to
+the Loom stack. The current repository ships the v0.1 enclosure, keycaps, CAD
+sources, and the daemon-side connectivity surface. Firmware and the voice
+backend are not yet included, so the flashing and voice sections below define
+the intended integration contract rather than a ready-to-run build.
+
+See [`hardware/orchestrator-pad/README.md`](../hardware/orchestrator-pad/README.md)
+for CAD regeneration and [`hardware/orchestrator-pad/SPEC.md`](../hardware/orchestrator-pad/SPEC.md)
+for the dimensional source of truth.
+
+## Parts
+
+| Qty. | Part | Notes |
+| ---: | --- | --- |
+| 1 | ESP32-S3 DevKitC-1 | Use a board without factory headers, or trim the headers flush; the tray has no clearance below the PCB. |
+| 14 | MX-style switches | 13 1u switches plus one switch under the 2u voice bar. |
+| 1 | EC11 rotary encoder | M7 threaded bush; the printed knob fits its D-shaft. |
+| 1 | INMP441 I2S microphone | Mount behind the front three-hole mic grille. |
+| 4 | M3 heat-set inserts | Fit the tray's corner bosses. |
+| 4 | M3×8 button-head screws | M3×10 screws bottom out before clamping the plate. |
+| 4 | Rubber feet, about Ø8 mm | Fit the tray's recessed feet pockets. |
+| Optional | WS2812 LEDs | Intended for the three preset/status keys. |
+
+Print `tray.stl`, `plate.stl`, `caps-all.stl`, and `knob.stl` from
+`hardware/orchestrator-pad/exports/`. Use a 0.4 mm nozzle and 0.2 mm layers in
+PLA or PETG. Print the tray and plate flat without supports, the knob upright,
+and the caps face-down or with tree supports.
+
+The v0.1 electrical build is hand-wired. The matrix row/column GPIO assignment
+and I2S pin mapping are firmware-owned and are not defined in this repository;
+do not infer them from the mechanical 4×4 layout.
+
+## 4×4 keymap
+
+The grid is viewed from the user, with row 0 at the back of the pad. The voice
+bar spans columns 1 and 2 but is one 2u key/switch position for matrix purposes.
+
+| Row \ Column | 0 | 1 | 2 | 3 |
+| --- | --- | --- | --- | --- |
+| 0 | Effort encoder | Preset/status: dot | Preset/status: ring | Preset/status: target |
+| 1 | Codex (`X`) | Claude (`C`) | Antigravity (`A`) | OpenCode (`O`) |
+| 2 | Kiro (`K`) | Run (`⚡`) | Approve (`✓`) | Reject (`✕`) |
+| 3 | Prompt/terminal | Voice hold (`🎤`, 2u) | Voice hold (`🎤`, 2u) | Send/dispatch (`➤`) |
+
+Agent keys lock the target agent. The encoder maps its detents to effort:
+`low`, `medium`, `high`, `xhigh`, `max`, and `ultracode`. Run, approve, reject,
+prompt, and send are command actions; their exact daemon mapping belongs in the
+firmware once implemented.
+
+## Flashing with `arduino-cli`
+
+There is currently no `firmware/` sketch in this repository, so these commands
+are the expected flow after a LoomPad sketch is added or checked out locally.
+They intentionally do not name a serial port or dependencies that the missing
+sketch has not declared.
+
+```bash
+# Install the ESP32 board support once.
+arduino-cli core update-index
+arduino-cli core install esp32:esp32
+
+# Identify the DevKitC-1's serial port.
+arduino-cli board list
+
+# From the directory containing the future LoomPad sketch.
+arduino-cli compile --fqbn esp32:esp32:esp32s3 firmware/loompad
+arduino-cli upload --fqbn esp32:esp32:esp32s3 --port /dev/cu.usbmodemXXXX firmware/loompad
+
+# Inspect boot and Wi-Fi logs.
+arduino-cli monitor --port /dev/cu.usbmodemXXXX --config baudrate=115200
+```
+
+Replace `/dev/cu.usbmodemXXXX` with the port from `arduino-cli board list`
+(`COM…` on Windows or `/dev/ttyACM…` on Linux). If upload cannot enter the
+bootloader, hold the board's **BOOT** button while starting upload, then release
+it when the tool connects.
+
+## Voice loop
+
+The intended hold-to-talk flow is:
+
+1. Press an agent key to lock the recipient, and turn the encoder to choose
+   effort.
+2. Hold the voice bar. Firmware samples the INMP441 and buffers/streams audio.
+3. On release, firmware sends the selected agent, action, effort, and audio to
+   the voice service. The planned envelope is `{ "agent", "action", "effort",
+   "audio" }`.
+4. The voice service performs speech-to-text, asks Loom to route the text to
+   the locked agent, and waits for that agent's reply.
+5. The service synthesizes the reply and returns audio for playback on the pad.
+
+Loom exposes a best-effort proxy for the service at `/api/loompad/health` and
+`/api/loompad/connect`. It reads `LOOMPAD_BACKEND_URL`, defaulting to
+`http://127.0.0.1:8080`; the desktop UI uses it to report whether the backend
+is reachable. The expected backend is responsible for STT → agent dispatch →
+TTS. Its implementation, audio codec, authentication, Wi-Fi provisioning, and
+speaker/amplifier wiring are not yet shipped here.
+
+For local operation, run Loom and the voice backend on the same trusted machine
+or tailnet, keep pairing credentials out of firmware source, and require a
+deliberate press-and-hold before recording. The microphone should be visibly
+indicated as active by firmware or LEDs before audio leaves the device.

package/docs/observability.md

@@ -0,0 +1,220 @@
+# Observability — Loom over OpenTelemetry
+
+Loom ships its agent activity as **all three OpenTelemetry signals — traces,
+metrics and logs**. Every turn, tool call, baton handoff, route step and memory
+fold your agents produce becomes a span; the same events are folded into
+counters and histograms; and every agent message, tool call, edit, decision and
+error is also emitted as a log record correlated to the span it happened inside.
+You get the whole fleet in one place: latency, cost, token usage, error rates,
+the critical path across agents — and, from a slow span, the log lines saying
+what the agent was actually doing while it was slow.
+
+**Backend-agnostic by construction.** Loom speaks OTLP/HTTP and nothing else, so
+it works against anything with a `/v1/{traces,metrics,logs}` endpoint: the
+OpenTelemetry Collector, Grafana/Tempo, Jaeger, SigNoz, Honeycomb, Datadog's
+OTLP intake. Loom has no vendor SDK and no vendor-specific code path — point
+`OTEL_EXPORTER_OTLP_ENDPOINT` at your collector and it works.
+
+## How it works
+
+Loom's daemon is already a stream of `LoomEvent`s. The observability layer
+(`src/observability/`) folds the notable ones into each signal and exports them
+over **OTLP/HTTP (JSON)** — no OpenTelemetry SDK dependency, just `fetch`.
+Egress is best-effort: if no collector is reachable the POST fails silently and
+never touches the agent loop.
+
+| Signal | Endpoint | Module |
+|---|---|---|
+| Traces | `/v1/traces` | `src/observability/otlp.ts` |
+| Metrics | `/v1/metrics` | `src/observability/metrics.ts` |
+| Logs | `/v1/logs` | `src/observability/logs.ts` |
+
+All three carry the same `service.name`, `service.namespace = loom` resource
+block — a backend keys a service off `service.name`, and a mismatch is what
+makes a trace and its own logs look like two different apps.
+
+Event → span mapping (using the OpenTelemetry [GenAI semantic
+conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) where they
+apply):
+
+| LoomEvent | Span | Key attributes |
+|---|---|---|
+| `run_complete` | `gen_ai.agent.turn` | `gen_ai.agent.id`, `gen_ai.request.model`, `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, `gen_ai.usage.cost_usd`, duration |
+| `tool_call` | `gen_ai.tool.call` | `gen_ai.tool.name` |
+| `handoff` | `loom.baton.handoff` | `loom.handoff.from`, `loom.handoff.to` |
+| `route_*` | `loom.route.<phase>` | `loom.route.id` |
+| `memory_add/update/forget` | `loom.memory.<op>` | `loom.memory.kind`, `loom.memory.scope` |
+| `error` | `loom.error` (ERROR status) | message |
+
+Every span carries `service.name = loom`, plus `loom.project` and `loom.chat`
+so you can slice by project and conversation. One trace per turn: it is minted
+at the turn boundary rather than off a `turn_started` status only some adapters
+emit, so the span tree is right for the whole roster.
+
+### Metrics emitted
+
+Six, all delta temporality — the daemon restarts whenever you edit a config or
+upgrade the CLI, which is the case cumulative handles worst.
+
+| Metric | Unit | What it counts |
+|---|---|---|
+| `gen_ai.client.token.usage` | `{token}` | Tokens an agent turn consumed, split by `gen_ai.token.type` (`input`/`output`) |
+| `gen_ai.client.operation.duration` | `s` | Turn duration (histogram, as the convention specifies) |
+| `loom.turns` | `{turn}` | Turns that reached completion, by outcome |
+| `loom.cost.usd` | `USD` | Money an adapter *reported* spending on a turn |
+| `loom.agents.active` | `{agent}` | Agents currently executing a turn |
+| `loom.handoffs` | `{handoff}` | Baton handoffs between agents |
+
+These same six names are the default set the Observatory's metric explorer
+queries when a caller names none (`LOOM_METRIC_NAMES` in
+`src/observability/insights.ts` — a constant in the code, not a knob).
+
+`gen_ai.client.token.usage` deviates from the convention on purpose: it is a
+monotonic sum rather than a histogram, because Loom reports exactly one
+input/output pair per turn and the question anyone asks is "how many tokens did
+this agent burn today", which a sum answers exactly.
+
+**Nothing emits a zero to keep a chart's line alive.** A flat zero and "nothing
+happened" look identical on a graph and only one of them is true. The same rule
+governs cost: an adapter that reports tokens but no dollar figure (codex does
+exactly this) produces token datapoints and *no* cost datapoint, rather than a
+cost of 0 — zeros are indistinguishable from real cheap turns once summed, and
+the total then reads as authoritative.
+
+### Logs emitted
+
+Every agent message, tool call, file edit, decision, route step, budget pause
+and error becomes one OTLP log record. When the event happened inside a turn it
+carries that turn's `traceId`/`spanId`, so the trace view gets a working
+"related logs" tab. Severity is mapped without inflation: an agent speaking is
+INFO, a failed turn is ERROR, something a human must look at but that isn't a
+failure (blocked on input, over budget, a suggested handoff) is WARN, adapter
+lifecycle chatter is DEBUG. Nothing is FATAL.
+
+## Point it at your collector
+
+Nothing to configure for a local collector — Loom exports to
+`http://localhost:4318` out of the box. To target another one, set environment
+variables before starting the daemon:
+
+```bash
+# a collector on another host
+export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4318"
+
+# a hosted backend that wants an ingestion key — any header name it asks for
+export OTEL_EXPORTER_OTLP_HEADERS="signoz-access-token=<key>"
+# or, for a different vendor:
+export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=<key>"
+
+# optional: rename the service
+export LOOM_SERVICE_NAME="loom"
+```
+
+The ingestion key rides in through the standard `OTEL_EXPORTER_OTLP_HEADERS`
+(`k=v,k2=v2`) rather than a per-vendor variable, so a new destination is a
+config change and never a code change.
+
+## Turn it off
+
+Consent is not per-signal — any of these kills all three:
+
+```bash
+export DO_NOT_TRACK=1               # or
+export LOOM_TELEMETRY_DISABLED=1    # or
+export LOOM_OTEL=0
+```
+
+## Every environment variable
+
+Resolved in `resolveTelemetryConfig` (`src/observability/otlp.ts`) unless noted.
+
+| Variable | Default | What it does |
+|---|---|---|
+| `LOOM_OTEL_ENDPOINT` | `http://localhost:4318` | Collector base URL. `OTEL_EXPORTER_OTLP_ENDPOINT` is the fallback. |
+| `OTEL_EXPORTER_OTLP_HEADERS` | — | Standard `k=v,k2=v2` headers, for whatever ingestion key your backend wants. |
+| `LOOM_SERVICE_NAME` | `loom` | `service.name` on all three signals. `OTEL_SERVICE_NAME` is the fallback. Also what the read-back queries filter on, so emit and read-back can't disagree. |
+| `DO_NOT_TRACK` | — | Any truthy value disables **all** telemetry. |
+| `LOOM_TELEMETRY_DISABLED` | — | Same, Loom-specific. |
+| `LOOM_OTEL` | — | `0` disables all telemetry. |
+| `LOOM_OTEL_METRICS` | on | `0` turns off the metrics exporter only; traces and logs keep going. |
+| `LOOM_OTEL_LOGS` | on | `0` turns off the logs exporter only. Volume control — Loom ships every agent message as a log record, which is the point, and also a lot of bytes. |
+
+### Reading telemetry back
+
+The Observatory reads spans, metrics and logs back out of the backend's store to
+render Span Replay, the trace waterfall, burn rate and the Logs view. That
+requires a ClickHouse-backed store; the physical table names default to the
+layout an OTLP collector writes and are overridable for a backend that lays them
+out differently.
+
+| Variable | Default | What it does |
+|---|---|---|
+| `LOOM_CLICKHOUSE_URL` | `http://localhost:8123` | Where to query the telemetry store. |
+| `LOOM_SPAN_TABLE` | `signoz_traces.distributed_signoz_index_v3` | The span index. |
+| `LOOM_LOG_TABLE` | *(collector default)* | The log table. |
+| `LOOM_METRIC_SAMPLES_TABLE` / `LOOM_METRIC_SERIES_TABLE` | *(collector defaults)* | The metric tables. |
+| `LOOM_TRACE_UI_URL` | — | Your backend's own UI, for the trace deep links. Unset means the links hide themselves rather than pointing at a guessed port. |
+
+Read-back is optional. With no store reachable, the panels that can fall back to
+the local event log do (Span Replay, triage, burn rate); the Logs view says so
+instead, because a log record's severity and trace correlation only exist once
+it has been shipped, and reconstructing something log-shaped from the event log
+would be inventing the correlation that is the whole point.
+
+These steer the LLM-backed read-back features, and exist so those paths can be
+made deterministic:
+
+| Variable | Default | What it does |
+|---|---|---|
+| `LOOM_TRIAGE_NO_LLM` | — | `1` makes triage skip the model entirely and return the deterministic heuristic. `src/observability/triage.ts` |
+| `LOOM_DECISION_MODEL` | `claude-haiku-4-5-20251001` | The model used to extract decisions from a turn's output. `src/observability/decisions.ts` |
+| `LOOM_DECISIONS_NO_CLI` | — | `1` stops decision extraction from shelling out to a signed-in CLI when there's no `ANTHROPIC_API_KEY`; it falls through to the regex extractor. `src/observability/decisions.ts` |
+
+The classification and evidence behind triage are deterministic either way; only
+the prose is model-written.
+
+## Self-heal
+
+Loom accepts alerts back from your monitoring at `POST /api/webhooks/alerts`, in
+the Alertmanager-shaped payload SigNoz, Prometheus and Grafana all send. A
+firing alert takes the named agent out of rotation — it is refused the baton
+until the alert resolves — and a resolved one puts it back.
+
+This is the part a dashboard cannot show you: it knows the alert fired, only
+Loom knows the fleet reacted. The Observatory's Self-heal view is built from
+Loom's own event log rather than the backend's API, so it still answers when the
+backend is down — which is exactly the moment you want to know which agents are
+still paused.
+
+| Variable | Default | What it does |
+|---|---|---|
+| `LOOM_WEBHOOK_SECRET` | — | Shared secret the webhook requires, when set. |
+| `LOOM_HEAL_DISABLED` | — | `1` accepts alerts but never acts on them. |
+| `LOOM_HEAL_MAX_RETRIES` | — | How many times a recovered agent is retried. |
+| `LOOM_HEAL_RECHECK_MS` | — | How long before a quarantined agent is re-examined. |
+
+## Verify it's flowing
+
+Run a turn, then look for the `loom` service in your backend, or query the
+store directly:
+
+```sql
+SELECT name, count()
+FROM signoz_traces.distributed_signoz_index_v3
+WHERE serviceName = 'loom' AND timestamp > now() - INTERVAL 15 MINUTE
+GROUP BY name;
+```
+
+## Test it
+
+The exporter and the event→span mapping are covered end to end:
+
+```bash
+npm test -- observability          # unit: config, mapper, OTLP payload shape
+npm test -- observability-export   # integration: a stand-in OTLP collector
+                                   # receives real spans from daemon turns
+```
+
+The integration test stands up a real HTTP server, points the daemon at it, runs
+real turns and asserts on the OTLP payloads that arrive — so "it exports" is a
+measured claim rather than a mocked one.

package/docs/play-store.md

@@ -0,0 +1,123 @@
+# Loom on Google Play
+
+What the Play Console asks for, and Loom's answers. The app is `tech.loompad.app`.
+
+## Build the bundle
+
+```bash
+LOOM_KEYSTORE_PROPS=/path/to/keystore.properties app/scripts/build-aab.sh
+```
+
+It writes `app/dist/loom-<version>-<versionCode>.aab`, signed with your **upload key**.
+Google re-signs it with the app signing key it keeps (Play App Signing — accept it when
+you create the app). Before each new upload, raise `expo.android.versionCode` in
+`app/app.json` (Play refuses a code it has seen). Raise `expo.version` when users should
+see a new version number.
+
+Keep the keystore and its `keystore.properties` backed up somewhere safe and out of git.
+If the upload key is lost, Play support can reset it, which takes a few days.
+
+The APK on GitHub Releases is signed with a different key (the `ANDROID_KEYSTORE_*`
+secrets). Android won't install the Play build over that APK, so anyone moving from the
+APK to the Play build uninstalls the APK first. To avoid that, choose "use my own key"
+under Play App Signing and upload that same keystore as the app signing key.
+
+### Push notifications in the Play build
+
+Expo Go gets push for free. A store build needs two things that only you can set up:
+
+1. **Firebase:** create a project at console.firebase.google.com, add an Android app with
+   package `tech.loompad.app`, and download `google-services.json` into `app/`. It's
+   gitignored, and `app.config.js` picks it up.
+2. **Expo:** run `npx eas-cli login`, then `npx eas-cli init` in `app/`. It prints a
+   project id. Build with `EAS_PROJECT_ID=<that id>` set. Then upload the Firebase
+   service-account key in expo.dev → the project → Credentials → Android → FCM V1.
+
+Without them, the app works and its account sheet says this build can't get push.
+
+## Store listing
+
+- **App name:** Loom
+- **Short description (80):** Watch, steer and approve your coding agents from your phone.
+- **Full description:**
+
+  > Loom is the remote for Loom, the free and open-source workspace where your coding
+  > agents (Claude Code, Codex, OpenCode, Grok, Antigravity and plain models) work side by
+  > side and share one memory of your project.
+  >
+  > Loom runs on your computer. This app pairs with it by QR code and lets you:
+  > • follow every agent live and send them messages, pictures or voice
+  > • answer their questions and Allow or Deny tool calls
+  > • run Orchestra goals and races, and crews of agents with roles
+  > • review diffs, rewind to a checkpoint, commit and push
+  > • see what each agent cost, in dollars and tokens
+  > • get notified when an agent asks something, finishes, or a goal is done
+  >
+  > You'll need Loom on a Mac, Linux or Windows computer: see
+  > loompad.tech. Nothing goes through Loom's servers. The phone
+  > talks to your computer over your network, your tailnet, or an encrypted relay.
+
+- **Category:** Tools (or Productivity) · **Tags:** developer tools
+- **Contact email:** required, use one you read.
+- **Website:** https://loompad.tech
+- **Privacy policy:** https://loompad.tech/privacy (the landing site,
+  nickthelegend/loompad-landing)
+- **Graphics:** a 512×512 icon (`app/assets/icon.png` scaled down), a 1024×500 feature
+  graphic, and at least 2 phone screenshots (Board, a chat, the Orchestra tab, the
+  account sheet).
+
+## App content (the questionnaires)
+
+- **Privacy policy:** the URL above.
+- **Ads:** no ads.
+- **App access:** "All or some functionality is restricted." Reviewers can't pair without
+  a computer running Loom, so give them instructions: "Loom is the companion app for a
+  desktop tool. Install Loom on a computer (loompad.tech), run
+  `loom up` then `loom pair`, and scan the QR code." Better still, link a short screen
+  recording of pairing and use.
+- **Content rating:** answer the IARC questionnaire as a utility/productivity app. No
+  violence, sexual content, gambling or drugs. It does show text written by AI models.
+  It doesn't let users message other people.
+- **Target audience:** 18+ (a developer tool); not designed for children.
+- **News app:** no. **COVID / government:** no. **Financial features:** none.
+- **Data safety** (for the Play build, which has no sign-in or analytics):
+  - Data collected: **none** (nothing is sent to the developer).
+  - Data shared: **none**. What goes to Firebase/Expo for push, and to the speech
+    recognizer, is processed for you by a service provider. Google's guidance doesn't
+    count that as sharing.
+  - Data is encrypted in transit: **yes** (HTTPS / the relay); over a plain LAN or tailnet
+    address the transport is your own network's.
+  - Users can request deletion: **yes**, by unpairing or uninstalling. The data lives on
+    their own computer.
+  - If a later build turns on Google sign-in or usage stats, update this form: name,
+    email and user id for the account, and approximate location (region) for analytics.
+- **Permissions:** camera (QR pairing, attaching a photo), microphone (dictation),
+  notifications. Nothing in the background. Storage and media-library permissions are
+  blocked in `app.json`.
+
+## Testing tracks, and the 12-tester rule
+
+Personal developer accounts created after November 2023 can't publish to production
+straight away. You need a **closed test with at least 12 testers who stay opted in for 14
+days in a row**; then "Apply for production" unlocks. It can't be skipped. (Organisation
+accounts are exempt.)
+
+1. **Internal testing** (up to 100 testers, no review, live in minutes): create a release,
+   upload the `.aab`, add your own Google accounts as testers, and install from the opt-in
+   link. Use this to check the build on real phones.
+2. **Closed testing:** create a track, upload the same `.aab` (or promote it), add testers
+   by email list or a Google Group, and share the opt-in link. You need **12+ people who
+   accept and keep it installed for 14 days**. Friends, a Discord or the repo's community
+   all work; a Google Group makes adding people easy.
+3. After 14 days, **Apply for production** in the dashboard. You'll answer questions about
+   the test and the app. Review usually takes a few days.
+4. **Production:** promote the release, choose countries, roll out (a staged rollout
+   such as 20% first is a good habit).
+
+## Updates
+
+- Each Play update needs a higher `versionCode`. Build, upload to a track, and promote.
+- Users get updates through Play. The app's account sheet also shows whether the
+  *computer's* Loom is behind the newest GitHub release. The computer pushes an "update
+  available" notification once per release (the "Loom updates" switch).
+- The account sheet's **Rate Loom** opens the Play listing (Android only).