@loompad/cli 0.1.0 → 1.1.1

package/dist/web/shell.html

@@ -0,0 +1,39 @@
+<!doctype html>
+<html lang="en" class="dark">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
+<meta name="theme-color" content="#0a0a0a">
+<link rel="manifest" href="/app/manifest.webmanifest">
+<link rel="icon" id="favicon" type="image/svg+xml" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'%3E%3Crect width='100' height='100' rx='22' fill='%230a0a0a'/%3E%3Ctext x='50' y='60' font-size='36' text-anchor='middle' fill='%23fafafa' font-family='-apple-system,Segoe UI,sans-serif' font-weight='600'%3Elo%3C/text%3E%3Crect x='32' y='70' width='36' height='4' rx='2' fill='%2367e8f9'/%3E%3C/svg%3E">
+<link rel="stylesheet" href="/app/vendor/xterm.css">
+<title>Loom</title>
+<script>
+/* Apply the saved theme before first paint so there is no flash. */
+try{var t=localStorage.getItem("loomTheme");if(t==="light"||(t==="system"&&matchMedia("(prefers-color-scheme: light)").matches))document.documentElement.classList.remove("dark")}catch(e){}
+/* The telemetry backend's own UI, for the trace deep links, injected by the
+   daemon from LOOM_TRACE_UI_URL. Empty unless one is configured — the links
+   hide themselves rather than pointing at a guessed port. */
+window.__loomTraceUrl="%%TRACE_UI_URL%%";
+window.__loomPageRev="%%BUILD_REV%%";
+</script>
+<style>%%APP_CSS%%</style>
+</head>
+<body id="loom-app">
+<!-- ADE brand marks, defined once (see brand-icons.ts). Every agent glyph on
+     the page is a <use> of one of these symbols. -->
+%%BRAND_SPRITE%%
+<div id="root"></div>
+<div id="toast" role="status" aria-live="polite" aria-atomic="true"></div>
+<div id="a11y-alert" role="alert" aria-live="assertive" class="visually-hidden"></div>
+<!-- xterm.js, served by the daemon from node_modules: the app has no build
+     step and must work offline on a tailnet, so no bundler and no CDN. Only
+     used when the daemon has a real pty; the fallback needs none of it. -->
+<script src="/app/vendor/xterm.js"></script>
+<script src="/app/vendor/addon-fit.js"></script>
+<script src="/app/vendor/addon-web-links.js"></script>
+<script>
+%%APP_JS%%
+</script>
+</body>
+</html>

package/docs/README.md

@@ -0,0 +1,21 @@
+# Loom docs
+
+| Doc | What's in it |
+|---|---|
+| [SETUP.md](SETUP.md) | Installing Loom and connecting your agents |
+| [teams-architecture.md](teams-architecture.md) | Loom Teams: the design, all 78 decisions, and what's built |
+| [teams.md](teams.md) | Loom Teams as a user: set up a team, share a repo, land goals, run a runner |
+| [adapters.md](adapters.md) | How each agent CLI is driven, and how to add one |
+| [cloud.md](cloud.md) | Loom Cloud: reaching your daemon from your phone on any network |
+| [observability.md](observability.md) | Telemetry, the Observatory, and what's recorded |
+| [loompad.md](loompad.md) | The LoomPad hardware controller |
+| [design-system.md](design-system.md) | The UI's tokens and components |
+| [integration-notes.md](integration-notes.md) | Notes from integrating t3code and agent-orchestrator ideas |
+| [proposals/](proposals/) | Design proposals |
+
+Code-level guides live beside the code:
+[src/](../src/README.md), [src/adapters/](../src/adapters/README.md),
+[src/hub/](../src/hub/README.md), [supabase/](../supabase/README.md),
+[test/](../test/README.md), [scripts/](../scripts/README.md),
+[desktop/](../desktop/README.md), [app/](../app/README.md),
+[hardware/](../hardware/README.md).

package/docs/SETUP.md

@@ -43,6 +43,7 @@ useful.
 | **Codex** | [Codex.app](https://openai.com/codex/), or `npm i -g @openai/codex` | `codex login` | `codex login status` |
 | **OpenCode** | `curl -fsSL https://opencode.ai/install \| bash` | `opencode auth login` | `opencode --version` |
 | **Grok Code** | [docs.x.ai](https://docs.x.ai) | `grok` (once, interactively) | `grok --version` |
+| **Antigravity CLI** | `curl -fsSL https://antigravity.google/cli/install.sh \| bash` | `agy` (once, sign in with Google) | `agy --version` |
 
 Two things worth knowing:
 
@@ -55,6 +56,15 @@ coming up empty doesn't mean it's missing.
 **Being logged in is not optional and not detectable in advance.** Loom probes
 whether a CLI *exists*, not whether it's authenticated. An unauthenticated agent
 looks installed, takes your turn, and fails. Run each one once by hand first.
+(The Antigravity CLI is the one exception Loom *can* check — `agy models` only
+answers when you're signed in — but running it once yourself is still the move.)
+
+**Antigravity comes in two shapes, and only one is on offer.** The **Antigravity
+CLI** (`agy`) above is a real headless agent: it holds the baton and runs a turn
+to completion on Gemini (or hosted Claude/GPT — `agy models` lists them), which
+is how you offload work off your orchestrator's token budget. The Antigravity
+**IDE** is a different thing — a GUI Loom could only watch — and the bridge that
+drove it has been **withdrawn** in favour of the CLI.
 
 Then ask Loom what it can see:
 

package/docs/adapters.md

@@ -8,7 +8,7 @@ decision:
 | Can hold the baton (write lock) | ✅ | ❌ never |
 | Must implement | `send`, live events, `injectMemory`, `interrupt`, `diff` | events (best-effort), `injectMemory` |
 | For | agents with a real API / headless mode | GUI agents without a stable control surface |
-| Examples | Claude Code, OpenCode | Antigravity |
+| Examples | Claude Code, OpenCode, Codex, Grok Code, Antigravity CLI | Kiro |
 
 This split is deliberate (see [ARCHITECTURE.md](../ARCHITECTURE.md)): the baton
 authorizes *edits to the user's working tree*, so it can only be held by an agent Loom
@@ -16,9 +16,15 @@ can reliably start, stream, interrupt, and account for. If your target tool only
 a debug port and pixels, build a bridge; if it exposes an API, build an adapter. A
 bridge can graduate later.
 
+Kiro is the only bridge Loom ships. Antigravity was one too — a CDP bridge that drove
+the IDE's chat panel over DevTools and could only watch — and that is the graduation
+path working: it was withdrawn once `antigravity-cli` could drive the same tool headless
+as a real adapter. The registration survives so projects that still name `antigravity`
+open, but nothing offers it (`src/adapters/index.ts`, `WITHDRAWN_KINDS`).
+
 ## The contract
 
-Everything lives in `threadloom/sdk`:
+Everything lives in `@loompad/cli/sdk`:
 
 ```ts
 import {
@@ -27,7 +33,7 @@ import {
   registerAgentKind,
   type SendInput,   // { text, briefing? }
   type AdapterEvent // { kind, payload }
-} from "threadloom/sdk";
+} from "@loompad/cli/sdk";
 ```
 
 ### Events you can emit
@@ -49,7 +55,7 @@ becomes context for everyone else.
 ### A complete adapter
 
 ```ts
-import { AdapterBase, registerAgentKind, type SendInput } from "threadloom/sdk";
+import { AdapterBase, registerAgentKind, type SendInput } from "@loompad/cli/sdk";
 
 export class MyAgentAdapter extends AdapterBase {
   // available(): is the underlying tool installed/reachable?
@@ -99,13 +105,15 @@ Users then declare it in `.loom/config.json`:
 ```
 
 `cfg.options` arrives in your constructor if you define one — see
-`src/adapters/claude-code.ts` and `src/adapters/opencode.ts` for real examples,
-including session persistence via project state.
+`src/adapters/opencode.ts` for a real example, including session persistence via
+project state and native continuity (a turn with `input.continuity` runs on its
+binding's session and reports `turn_started` / `native_turn_accepted`). Codex and Claude Code are built differently — as warm provider
+sessions on the contract in `src/providers/` (see `providers/agent.ts`).
 
 ### A bridge
 
 ```ts
-import { BridgeBase, registerAgentKind } from "threadloom/sdk";
+import { BridgeBase, registerAgentKind } from "@loompad/cli/sdk";
 
 export class MyGuiBridge extends BridgeBase {
   async available() { return true; }
@@ -117,7 +125,12 @@ export class MyGuiBridge extends BridgeBase {
   // driving the GUI agent points it at that file.
 }
 
-registerAgentKind("my-gui", (cfg, dir) => new MyGuiBridge(cfg.id, "my-gui", dir));
+// The third argument is the tier, and it defaults to "adapter". Omit it and your
+// bridge is registered as an adapter: the roster answers "adapter or bridge?" from
+// this map — it has to, for kinds that are switched off and have no instance to ask
+// — so a disabled bridge would advertise itself as an adapter and the composer,
+// which filters its chips on that field, would offer it the baton.
+registerAgentKind("my-gui", (cfg, dir) => new MyGuiBridge(cfg.id, "my-gui", dir), "bridge");
 ```
 
 ## Ground rules

package/docs/brain-continuity.md

@@ -0,0 +1,186 @@
+# Native Brain continuity
+
+The deterministic implementation is **opt-in**. This guide describes what works
+now; it does not claim every milestone in the [approved plan](proposals/brain-continuity-implementation.md)
+is finished. Release gates and results are in [BRAIN-TODO](refactoring/BRAIN-TODO.md)
+and [BRAIN-NOTES](refactoring/BRAIN-NOTES.md).
+
+## Enable and switch
+
+Enable **Native context continuity** in Settings → Preferences, or set
+`brain.continuity: true` in `.loom/config.json`. Finish/reconcile active turns and clear queued prompts before
+changing modes. The default remains the legacy workflow.
+
+Select Codex, Claude Code or OpenCode in an ordinary chat. The next request captures its
+target/model. Requests sent during another foreground turn queue until it finishes;
+later picker changes do not retarget them. Explicit handoff/Stop interrupts, waits
+for process close, and refuses unproven quiescence. Preparing turns can also be stopped.
+
+| Capability | Current support |
+| --- | --- |
+| Codex | Any installed version; `codex app-server`, explicit `thread/resume`; context in ordinary turn input (stdin, no argv limit). Acceptance is the `turn/start` response or `turn/started`. |
+| Claude Code | Any installed version, driven through the Claude Agent SDK; explicit resume by session; context in the ordinary user message (stdin). Acceptance is the `requesting` status or the first output. |
+| Lost native session | A resume that finds no session fails before any turn starts. The adapter reports `NativeSessionMissing`; the receipt fails and the binding moves to a new epoch, so the next packet reconstructs into a fresh session. |
+| Harness health | Each native CLI is probed with `--version` every 20 s and before dispatch. An unreachable CLI refuses the turn before the request is recorded. Status reports `available` and `cliVersion`; transitions are logged. Protocol drift appears as missing acceptance evidence, never as success. |
+| Per-chat model | Supported. Changing the model keeps the same native session (Codex and Claude accept a model on resume; OpenCode switches the session's model in place); other configuration changes select a new binding. |
+| OpenCode | Driven over `opencode serve`'s HTTP API (verified on 1.18.31); explicit resume by session; context in the ordinary prompt. Acceptance is the prompt's admission; the turn is over, and quiescent, when `/api/session/active` no longer lists the session. A session the server no longer has fails before anything is sent, and the next packet rebuilds in a new one. An agent pointed at a running server (`baseUrl`) is probed by that server's health. |
+| Bridges | Native continuity unsupported; legacy workflow available. |
+| Parallel subagents/orchestra | Unsupported in this sequential mode. |
+| Embeddings/inference/cheap helpers | Not loaded or launched by this mode; helpers disabled. |
+| Attachments | Existing `[image]`/`[file]` upload protocol rejected; ordinary workspace references usable. |
+| Native compaction | Every harness reports it: Claude as `status: compacting` then `compact_boundary`, Codex as a `contextCompaction` item, OpenCode as `session.next.compaction.started`/`.ended`. The binding is marked compacted, and the next packet rebuilds reviewed state and recent history into the same resumed session. The UI shows compaction while it runs, and the context in use against the model's window. No private transcript modifications. |
+
+Checked fixtures are not live account validation on every listed version or
+cross-platform packaging certification.
+
+## Context and storage
+
+One ordinary foreground request contains an origin-labelled historical block and
+the current request once. What the block carries depends on the target session:
+
+- **Resumed session (delta).** The native session already holds everything earlier
+  packets gave it and its own turns. It receives only what it lacks: user messages
+  sent to another agent meanwhile, other agents' work since its last turn, and
+  reviewed items if they changed. Returning after a short detour costs roughly the
+  size of that detour, not the conversation.
+- **New or compacted session (reconstruction).** Current reviewed items, the most
+  recent user messages exactly, one-line headlines for older user messages (full
+  text in a local evidence file) and recent observations, all within the target.
+
+A request becomes conversation history only once it may have reached a harness.
+Queued, overflowed or refused requests are not shown to other turns. Discussion is not automatically accepted
+as a decision; agent claims are not automatically verified work. Corrections carry
+revision/supersession and source references. Small user points never depend on top-K.
+
+Canonical originals remain in `.loom/log.db` on EventLog's existing connection.
+Brain adds versioned requests, native bindings, items/revisions/dispositions, packets,
+receipts and FTS5 projections with lexical fallback. There is no second canonical
+database or vector service. Writes retain the synchronous owner semantics; worker
+isolation is a measured follow-up, without `Atomics.wait` or memory-only acknowledgements.
+
+Source references include project, event ID, SHA-256 and validated UTF-8 spans.
+Packets, rendered text/hashes and receipts are separate immutable/transitioned records.
+Native IDs are scoped to chat, agent instance, workspace, compatibility fingerprint
+and epoch. Ambiguous legacy instance IDs are neither adopted nor overwritten.
+
+App packet assembly prevents cross-chat injection. A native coding harness with
+project filesystem access can still inspect other local files; application scoping
+is not a sandbox isolating private chats from a trusted local agent.
+
+## Budgets and checkpoints
+
+The default target is **6,000 estimated turn-input tokens**, including the current
+request and app-added context, estimated from UTF-8 bytes / 3,
+rounded up. This is a heuristic, not a provider tokenizer or verified native capacity.
+Native history, tools, output and provider caching affect usage outside
+that estimate. The wire field retains its v1 name `estimatedAddedTokens`. Resuming a native session does not imply free or unlimited context.
+
+Priority is: reviewed items and the current request, then user messages (exact
+newest-first up to about 75% of the target, then headlines), then observations.
+Nothing is dropped silently: each source is recorded as exact, summarized
+(reviewed checkpoint), referenced (headline plus evidence file) or omitted.
+Omitted observations are reconsidered by the next delta. Overflow now occurs only
+when reviewed items plus the current request exceed the target. It saves the
+request/packet without starting a coding turn. The review dialog
+lets you increase the target or create a reviewed checkpoint from selected originals,
+then resume the saved request. Increasing the target can consume more quota and
+still exceed native capacity. Exact restrictions and unresolved questions belong in
+the checkpoint; the app does not certify your summary's fidelity.
+
+Original checkpoint evidence is accessible as content-addressed local JSON under
+`.loom/brain/artifacts/`. It is flushed and atomically finalized before reference.
+Submission checks integrity and rejects unsafe paths. Unreferenced crash artifacts
+are retained for now; automatic GC/deletion/retention remains a release gate.
+
+Checkpoints can be created or changed only while no agent turn is running, so a
+running agent cannot forge user-reviewed context through the local API.
+
+Protocol limits: 4 MB serialized contract input, nesting depth 32, 1 million
+characters per text field, 1 MB rendered context, 10,000 protected messages/items,
+1,000 item sources, 32 MB native JSONL records/retrieval artifacts, 100 MB offline JSONL imports, and
+an explicitly chosen added-context target of 128–100,000 estimated tokens.
+Exceeding limits produces an error/overflow instead of silent truncation.
+
+## Delivery and recovery
+
+`prepared` means stored; `submitting` means durable intent to call the harness.
+`accepted` requires correlated native turn/output evidence, not spawn or initialization.
+Execution is separately `running`, `complete`, `failed`, `interrupted` or `unknown`.
+A provider error may arrive before process exit; it does not release the runtime
+writer barrier early. Accepted does not mean understood or retained.
+
+After restart/lost acknowledgement, uncertain runs keep their workspace lease.
+Inspect native processes and changed files, then explicitly reconcile with evidence.
+Reconciliation clears the lease and increments the binding epoch; it does not replay
+the action. Reconciliation is atomic with binding invalidation and cannot be repeated
+on a resolved receipt. Retry is a new deliberate request. Failed stops block successors.
+
+Native POSIX launches own a process group. Parent exit starts inherited-child cleanup;
+completion waits for containment and output drain. Unknown termination retains the
+writer lease. Escaped/detached children are not fully contained; inspect them during
+manual recovery. Windows native harnesses launch inside kill-on-close Job Objects;
+the launch handshake completes containment before any harness or tool can start.
+Shutdown verifies zero job members, and failed inspection retains the writer lease.
+The daemon probes assignment on the current host (including enclosing jobs) before
+enabling native continuity. OpenCode supports both the legacy `/api/session` API
+and npm 1.19.0's `/session/:id/prompt_async` admission and `/session/status` idle proof.
+App-owned diff/commit work also finishes before the next native turn starts.
+
+The Brain pane lists the latest 100 attempt summaries and loads individual full
+packets on demand. Project-authenticated routes under
+`/api/projects/:id/brain/continuity` are:
+
+| Method/path | Purpose |
+| --- | --- |
+| `GET /?requestId=...` | Bounded attempt summaries, counts, estimates and outcomes. |
+| `GET /packets/:packetId` | One packet and exact rendered text/hash. |
+| `GET /source/:eventId?chat=...` | Scoped original text/source hash. |
+| `GET /items?chat=...`, `POST /items` | Reviewed `ContextItemV1` records. |
+| `POST /checkpoint` | `{chat,itemId,eventIds,reviewed:true}`; atomic full-source dispositions. |
+| `POST /requests/:requestId/resume` | `{targetAddedTokens}`; rebuild an unsubmitted overflow/preflight request. Submitted requests cannot be replayed here. |
+| `POST /search/rebuild` | `{}`; rebuild FTS transactionally from canonical events. |
+| `POST /reconcile` | `{receiptId,evidence,quiescent:true}`; explicit uncertain-run reconciliation. |
+
+`POST /api/projects/:id/messages` accepts `requestId`. Same ID/content/target does
+not append/execute twice; different content is a conflict. Captured queued text,
+target and model are immutable, including whitespace. Native queue action edits are
+unsupported until durable supersession is implemented; remove the unsent entry and
+submit a new request. Removal stops dispatch, but retains original evidence.
+Autonomous routes, orchestra and subagents reject before starting in native mode.
+
+## Migration and ownership
+
+Activation backs up SQLite with `VACUUM INTO` before schema migration. Request/event
+transactions publish only after commit. A second live Brain owner or unowned event
+writer is refused. Dead-owner takeover is conservative; live/reused PIDs do not
+authorize takeover. Use a local filesystem; network-filesystem recovery is not certified.
+
+Legacy JSONL remains readable with `LOOM_STORE=jsonl` but cannot provide transactional
+continuity. Stop the daemon, then run:
+
+```sh
+loom brain:migrate /path/to/project
+```
+
+The importer backs up JSONL/SQLite, preserves IDs/Main history and records a manifest.
+Repeated imports are idempotent. Malformed records/conflicting IDs abort the import;
+distinct histories are never merged/renumbered silently. Original files remain.
+An unmatched SQLite/JSONL pair fails visibly. New SQLite events are not automatically
+copied back to JSONL for an older reader; rollback requires explicit backup/export
+reconciliation.
+
+## Verification and follow-ups
+
+Protocol fakes (a Claude CLI speaking the SDK control protocol, a Codex app-server
+speaking JSON-RPC; `test/native-fakes.ts`) test switching, chat isolation, corrections, explicit resume after restart,
+captured queue targets/models, idempotency, protected overflow and uncertain delivery.
+Storage tests exercise migration conflicts/rollback, SQLite contention, commit-before-
+publication and unknown schema rejection. Ordinary tests make no paid model calls.
+
+Remaining gates include isolated account-supported
+cheap helpers, OpenCode parity, retention/GC, full platform packaging and long-history
+quality/performance comparisons. Electron optimization remains future work.
+See [architecture](../ARCHITECTURE.md) and the linked notes/TODO for measured evidence.
+
+Cleanup evidence and the complete E01–E64 status audit are in
+[BRAIN-AUDIT](refactoring/BRAIN-AUDIT.md).

package/docs/cloud.md

@@ -0,0 +1,108 @@
+# Loom Cloud setup (Supabase)
+
+One Supabase project powers three optional features:
+
+| Feature | Uses | Without it |
+|---|---|---|
+| **Loom Cloud relay**: phone ↔ computer from any network | Realtime (broadcast) | The phone works on the same Wi-Fi or tailnet only |
+| **Sign in with Google** in the phone app | Auth | "Continue without an account" still works fully |
+| **Anonymous usage stats** (country only) | one Postgres table | Nothing is sent |
+
+The free tier covers all three. Loom runs no server of its own, but out of the
+box the relay and the Team Hub use Loom's hosted Supabase project (see
+`src/core/hosted.ts`). Everything below points them at a project of your own.
+
+## 1. Create the project
+
+1. Go to https://supabase.com/dashboard and create a **New project**.
+2. Open **Project Settings → API** and copy two values:
+   - the **Project URL**: `https://<ref>.supabase.co`
+   - the **anon public** key.
+
+   The anon key is designed to be public. It ships inside the app, and everything
+   it can reach is locked down by the policies below.
+
+## 2. Realtime (the relay)
+
+The relay uses **broadcast** channels named `loom-relay:<random id>`. Nothing is
+stored, and every message is end-to-end encrypted with a key that exists only in
+your pairing QR.
+
+- **Realtime → Settings**: keep **public channels allowed**. This is the default.
+  If "private channels only" is on, the relay can't join.
+
+Turn it on for your computer:
+
+```bash
+loom cloud enable --url https://<ref>.supabase.co --key <anon key>
+loom pair       # the QR now carries the relay credentials in its #fragment
+```
+
+Or set `LOOM_SUPABASE_URL` / `LOOM_SUPABASE_ANON_KEY` in the daemon's environment
+and use **Settings → Loom Cloud** in the desktop app.
+
+- `loom cloud rotate` mints a new key. Phones that paired through the cloud must
+  pair again.
+- `loom cloud disable` leaves the channel.
+
+## 3. Sign in with Google
+
+1. **Google Cloud Console → APIs & Services → Credentials → Create credentials →
+   OAuth client ID**:
+   - Application type: **Web application**
+   - Authorized redirect URI: `https://<ref>.supabase.co/auth/v1/callback`
+2. **Supabase → Authentication → Sign In / Providers → Google**:
+   - enable it;
+   - paste the **Client ID** and **Client secret**.
+3. **Supabase → Authentication → URL Configuration → Redirect URLs**: add
+   - `loom://auth-callback` (installed app)
+   - `exp://**`, for development in Expo Go only.
+4. In the phone app, copy `app/.env.example` to `app/.env` and fill in:
+
+   ```
+   EXPO_PUBLIC_SUPABASE_URL=https://<ref>.supabase.co
+   EXPO_PUBLIC_SUPABASE_ANON_KEY=<anon key>
+   ```
+
+   For EAS builds, set the same two names as EAS environment variables.
+
+An account is optional. Loom's local features never need one.
+
+## 4. Anonymous usage stats
+
+Run [`supabase/migrations/0001_app_opens.sql`](../supabase/migrations/0001_app_opens.sql)
+in **SQL Editor**, or use `supabase db push` if you use the CLI.
+
+**What is collected, per app open (at most once a day):**
+- **country**: from the phone's region setting. No IP address, no location.
+- **platform**
+- **app version**
+
+**What is not collected:** no user id, no device id, no email, no prompts, no code.
+
+- Anyone can insert. Nobody but the service role can read.
+- The phone app has an **Anonymous usage stats** switch to turn it off.
+
+Read the counts in the SQL editor, which runs as the service role:
+
+```sql
+select country, count(*) from app_opens group by 1 order by 2 desc;
+```
+
+## Security model, in one paragraph
+
+- **Supabase relays but cannot read.** Every relay message is
+  XChaCha20-Poly1305-sealed with a 32-byte key minted on your computer. That key
+  travels only in the pairing link's URL fragment, which is never sent to a server.
+- **Requests are authorized exactly as on the LAN.** Your computer runs each
+  relayed request against itself, with the phone's own paired token. Revoking a
+  phone (`loom clients --revoke`) stops its requests the same way over the cloud.
+  Every phone paired to one computer shares one relay key, though, so a revoked
+  phone that kept the key can still *read* the others' traffic until you run
+  `loom cloud rotate` (which re-pairs everyone).
+- **A captured request can't be replayed.** Each one carries its send time
+  inside the seal; your computer refuses anything stamped more than ten minutes
+  off and never runs the same request id twice.
+- **The local admin bootstrap is refused over the relay.**
+- Someone who learns your channel id still can't read or forge anything without
+  the key.

package/docs/crews.md

@@ -0,0 +1,62 @@
+
+
+## Desktop and phone controls
+
+Crew is available beside Orchestra on desktop and in the phone project tabs.
+Pick Ship, Fan-out or Race in Play and limits before starting the next goal.
+Each active seat shows its own work, goal spend and native context epoch. The
+board keeps Planned -> Building -> Review -> Testing -> Ready to integrate -> Done;
+Race waits for Choose this result before integrating a winner.
+
+Pause finishes active turns and then prevents new turns. Resume keeps a plan
+waiting for approval. Budget and team holds explain why work stopped. A native
+recovery warning requires inspecting/reconciling the action first; Resume is
+not offered while the receipt is uncertain. Refresh context starts a new
+native epoch only when it is safe to do so.
+
+Team requests and runner crews contains encrypted requests for owner approval
+and remote runner progress. Start composer goal on my runner queues the goal
+text from the composer; the runner's plan still needs the owner's approval.
+Completed runner goals provide Review PR; humans merge them.
+
+Crew cards also appear in the ordinary Board with their crew, stage and seat.
+These are scheduler-owned cards; open Crew to control them. Fleet includes
+active crews, and a crew notification opens the corresponding Crew view.
+
+CLI examples:
+
+```powershell
+loom crew pause --crew ship
+loom crew resume --crew ship
+loom crew pick --crew ship --to builder-2
+loom crew budget --crew ship --amount 15
+loom crew overlap --crew ship --card c12 --decision narrow --touches 'src/api/**'
+loom crew refresh --crew ship --to reviewer
+loom crew deliver --crew ship
+```
+
+Physical native-phone acceptance, hosted migration acceptance and trusted
+installer signing are separate checks. The local browser checks and native
+Windows orchestration evidence do not substitute for them.
+The hosted hub needs migration `0010_crew_coordination.sql` for requests and
+control jobs at full capacity. Review/apply it separately with admin access;
+Loom does not apply it. The self-hosted hub supports these paths directly.
+
+
+A reviewed role/runner permission ceiling is checked against the actual harness
+before work starts. OpenCode's `ask` mode is currently unverified/unsupported,
+so a team role requiring it must use Codex/Claude (or a separately reviewed,
+supported role setting). Loom refuses the seat instead of silently using auto.
+Tightening permissions during a goal settles and recreates the warm adapter
+before its next turn; native compatibility changes receive a fresh binding.
+
+The `hub-sql` CI job runs all migrations and authorization checks in a disposable
+PostgreSQL cluster and fails if tools are missing. It never connects to hosted
+Supabase. Migration 0010 and the other SQL checks passed there (26 checks).
+
+
+If an owner-approved request stays queued because a budget or startup check
+blocked admission, Check delivery retries that known unstarted item after the
+block is resolved. A running, delivered or failed request is never executed
+again by this button. An interrupted delivery needs inspection and a new
+explicit request; restarting the daemon does not silently replay it.

package/docs/design-system.md

@@ -11,7 +11,7 @@ Canonical token sources:
 
 | Surface | Token file |
 | --- | --- |
-| Web app (daemon-served) + Electron shell | `src/daemon/app-page.ts` (`:root` light / `.dark`) |
+| Web app (daemon-served) + Electron shell | `src/web/styles/base.css` (`:root` light / `.dark`) |
 | Phone app (Expo RN) | `app/src/theme.ts` |
 
 ## Color tokens — web / desktop (from Orca desktop)
@@ -164,7 +164,7 @@ xterm.js, served from `node_modules` at `/app/vendor/*` — no bundler, no CDN.
 **`pipe` — the fallback** (no node-pty). `node-pty` is a native module, so it
 is an *optionalDependency* and ships prebuilds only for macOS/Windows; Loom
 runs headless on Linux boxes that may have no toolchain, and `npm i -g
-threadloom` must never break. A long-lived shell on plain pipes:
+@loompad/cli` must never break. A long-lived shell on plain pipes:
 
 - `cd` and exported variables still persist; tabs are isolated.
 - No tty, so the daemon reports each command's exit code and cwd out of band:
@@ -202,6 +202,35 @@ pills.
 Mobile (<900px) keeps the single-column thread: chips row, glass sheets, and
 the docked composer.
 
+## The thread (1.1 layer)
+
+The last block of the stylesheet ("Loom 1.1 design layer") is the finish on
+top of the tokens above; it uses the same tokens and wins by order.
+
+- **One reading column** — `--measure: 760px` with a `--gutter` either side.
+  Prose is Geist at 14.5px / 1.72; mono is for code, paths and ids only.
+- **A reply is a byline, not a bubble.** `.who` = 22px mark tile (`.av`),
+  name, model pill, time (on hover). The body indents 30px under the name.
+  An agent continuing its own turn (`.msg.agent.cont`) drops the byline.
+- **Your message** is the only bubble: `--secondary`, 18px radius with a
+  6px tail corner, right-aligned.
+- **Tool use** folds: consecutive `.tool` rows become one `details.acts`
+  whose summary counts them ("Ran 3 commands, read 2 files").
+- **Every turn ends on `.turnend`** — agent · duration · model · cost.
+- **Live** — `#feedlive` holds a `.livebox` per working agent: a bar
+  (spinning ring + shimmer label + timer) until text arrives, then the reply
+  itself with a cyan `.caret`. Never logged; the finished message replaces it.
+- **Cards** — `.plancard` (orchestrator plan), `.nicard` (needs you, warn
+  tint), `.apcard` (approval), `.errcard` (error, raw payload folded),
+  `.odone` (orchestra complete, ok tint). One radius (14px), one shadow.
+- **Motion** — custom `--ease-out`; nothing over 250ms on UI; no animation on
+  keyboard-driven actions; `prefers-reduced-motion` turns it all off.
+- **Confirmations** are `askConfirm()` (an in-app `.cfmodal`), not
+  `window.confirm`.
+- **Regex escapes in the page are written doubled** (`\\s`), because the
+  page is one template literal and a single backslash is eaten — a test
+  enforces it.
+
 ## Window chrome (Electron)
 
 Matches Orca: `titleBarStyle: hiddenInset` (macOS) with traffic lights at