brane 0.0.2 → 0.3.0

package/protocols/bebrief.md

@@ -0,0 +1,41 @@
+# /bebrief [tone]
+
+The agent says just the right thing, every time, so the conversation itself can be handed to a human audience that balks at walls of text.
+
+## Why
+
+Some readers stop at the first screenful. A conversation worth showing them is short exchanges: a question, an answer that fits, the next question. Reasoning and caveats live in the record, where `nid:seq` reaches them; the narration's job is the conclusion, the operator's — asking on the audience's behalf — to draw out the rest. A question is a move in a strategy of inquiry (Roberts), an answer a proposal to common ground (Clark), worth making only for what it changes in the reader (Sperber & Wilson).
+
+Like /twin, `/bebrief` holds for the session. There is no line budget, only a direction of error: too long taxes every line and cannot be taken back; too short costs one word, "more?". In doubt, the agent cuts.
+
+Never cut: a failure or a risk, and first; a blocking question; a correction of something already said; `meta.summary`.
+
+## Tone
+
+The argument names the voice, chosen for the audience: register, vocabulary, and, within reason, length (`/bebrief wizard`). The set is open; reference points: `student` reports to a supervisor (done, found, asking next); `wizard` is terse and certain, names the mechanism; `dad` is warm and plain-spoken, never at the operator's expense; `eli5` uses no jargon and one concrete image per idea. None given: plain and technical. An unusual one (`/bebrief pirate`) is worn lightly — enough per message to say which voice it is, never a costume that hides the answer: stripped of the tone, what remains must still be the thing asked. Brief pirate reports that don’t waste the captain’s time.
+
+The argument may name the reader instead of a voice — `/bebrief for a new contributor` — and that is usually the better argument, since the voice follows from it. If neither the argument nor the conversation says who the reader is, the agent looks before asking: /memory may hold who this operator shares with and how. Failing that, it is the first thing to align on: altitude, what counts as new and what counts as surprising are all relative to that reader's common ground.
+
+## Just the right thing
+
+- **The thing asked, at the altitude asked.** "Is it fixed?" gets yes and where; "how does it work?" gets the mechanism, not the code. The question is not restated; it is in the transcript.
+- **Only what is new.** Never a recap, never the same caveat twice.
+- **Words follow surprise, not effort.** The expected outcome gets a line however long it took; the unexpected one gets the words.
+- **A sentence someone could repeat.** Not a pointer, not a wall: the sentence carries the meaning, the `nid:seq` rides at its end. Confidence in a word — "measured", "likely", "not checked" — and when uncertain, the agent grounds first: /memory is cheap and silent, and a search before answering is what turns "likely" into "measured" without a line of hedging or a question the record could answer. A cut never upgrades a confidence word: recalled is not measured.
+- **The same shape, every time.** No preamble, no sign-off, no closing offer. Held as late in the session as early.
+
+## Leading questions
+
+The operator will often ask Socratically, knowing some of the answer, for the reader's sake. The agent answers as if the reader asked, answering and reasoning in one breath, never "as you know" or "exactly right", and never running ahead: the questions are the operator's path for the reader. A wrong premise is contradicted first; the transcript is worth reading only while the answerer is honest. The operator may also be rehearsing a path the archive already holds, even redoing a Socratic narrative tried with another agent. The agent uses everything /memory tells it and none of it aloud: no "as we discussed", no "didn't we cover this" — the déjà vu is the agent's alone, and voicing it ruins the narrative the operator is trying to elicit. The archive is cited for facts, never for "we have been here".
+
+## The stack
+
+A conversation is a stack. A question pushes a subtopic; when it concludes, the next question usually comes from the frame beneath, not from somewhere new. The agent keeps the stack in mind and makes pushes and pops legible: a subtopic that is settled is closed in a word and the enclosing topic resumed where it was left — "That settles the token. Back to the cert: …" — without re-explaining the frame below, which the reader has just read. It answers within the current frame; a point that belongs further down waits for the pop. A numbered fork is a push, and the digit pops it. Only the operator pushes, except for what Never cut requires; the agent may name what is still open in the frame it returns to, not open it. A live predecessor's new events, to a /twin, are context for the current frame, not questions in it.
+
+## While working
+
+`/bebrief` changes Vocalize and nothing else in /LIVE_loop; Listen, Interpret and Execute run as they always did. Alignment is one line of plan, and a question only if it blocks. While executing, a progress line is sent whenever there is something worth saying, and not before: news that rises to a threshold the reader would notice — "tests green; building the bundle, two minutes" — never a plan or a recap. Several things to say are coalesced into one message whenever possible, riding in the same turn as the work. Exports carry no tool calls, so these lines are the transcript's trace of the work, and an excerpt that doesn't want them leaves them out. The report that returns the agent to Listen is the answer: outcome first, surprise gets the words, no recap of the steps. With every tool call hidden, the narrations alone should still read as a complete conversation. The terminal is off the record: permission prompts and the like are cleared there, with the operator's help, and never mentioned in the narrative unless the terminal is itself the topic the operator has set. When another protocol is invoked in the session — /review, /digest, /summarize — it decides *what* must arrive and `/bebrief` decides *how*: tersely, or in a file per Mechanics.
+
+## Mechanics
+
+One question at a time, the one that blocks. When the work forks, the agent puts the two or three branches it would actually take as a numbered list, recommended first, so the reply can be a digit — never exhaustive, and an answer off the list always allowed. It decides everything else, and announces a decision only where the operator might have chosen differently. A deliverable that is long by nature — a draft, a findings list, a diff — goes in a file or a `nid:seq`, and the message says what it holds in a sentence. But a complete list the operator asks for, which both know the agent has, is given whole: no forced pagination, no withholding — the bias is toward synthesis and alignment, never against the answer. Formatting is for tables and those lists. "why", "more", "?" license one full answer, same tone; then the agent snaps back. 

package/protocols/digest.md

@@ -0,0 +1,231 @@
+# /digest [guidance]
+
+Generate a rich digest of narrative activity over a time window.
+
+## Accuracy is the whole job
+
+A digest is built entirely from the **narrative event log** — the
+permanent, append-only record of `narration` and `human_signal` events.
+That log is the source of truth, and it does not go away: you can always
+re-read any narrative's events with `listen` / `narrative_info` /
+`narrative_search`. The digest is nothing more than a faithful account
+of what that record says. It is itself durable too — the next `/digest`
+finds this one to set its window, so one invented detail propagates and
+misleads for weeks.
+**Accuracy outranks completeness** — a short digest covering only the
+narratives you actually read beats a comprehensive-looking one padded
+with guesses. The rules below are mandatory, not aspirational; a real
+digest run violated every one (see "Failure modes" at the end).
+
+### Report only what the log actually says
+
+Every accomplishment, decision, and theme must trace to specific events
+in the log — not to memory, not to what a narrative "probably" said. If
+you are unsure whether something happened, re-read the events; the record
+is right there. Do not invent narrative IDs, summaries, quotes, or
+events, and do not attribute work to a narrative whose events you have
+not read. Cite the narratives you draw on as `nid:seq` so every claim is
+checkable against the record.
+
+### Don't editorialize
+
+Report what the events say without coloring it. This is the same
+discipline the /wiki protocol calls *Voice and register* — a neutral,
+descriptive account — applied to the digest:
+
+- **Attribute positions; don't assert them.** A decision, preference,
+  conjecture, or claim is reported as someone's — "the operator
+  directed…", "claude-abc proposed…", "is described as…" — not stated as
+  settled fact. Only things that demonstrably happened (a PR merged, a
+  test added) are stated flat.
+- **Cut editorializing phrases.** Don't inflate a routine fix into a
+  milestone, dramatize a setback, or reach for adjectives ("major,"
+  "critical," "elegant," "bold") the record hasn't earned. State a
+  substantive claim plainly and attribute it; drop decoration.
+- **Don't sharpen or supply motive.** Don't turn a vague status into a
+  definite outcome or invent a "why" the events don't give. Where the
+  record is ambiguous, say so rather than resolving it for them.
+
+By default, then, the digest reads as wiki-style reference: neutral,
+descriptive, attributed. The `[guidance]` is the one thing that loosens
+this — when it asks for more than a neutral account (prioritization,
+risk assessment, cross-narrative connections, recommendations, what to
+do next), provide that judgment, but keep it grounded in the events and
+clearly marked as your interpretation rather than woven into the
+description as fact.
+
+### gh/git are corroboration, not the substance
+
+The digest reports what narratives did, drawn from their events — it is
+not a catalog of PRs and commits. A PR number or commit hash belongs in
+a digest only when a narrative's events reference it, and even then the
+claim "this narrative shipped that PR" comes from the events, never from
+guessing what a number maps to. If you cite a repo fact, copy the
+identifier from real `gh`/`git` output obtained this run; never compose
+one to look precise.
+
+### Report gaps, don't fill them
+
+You will not always read every narrative in the window — there may be too
+many, or a search may return nothing. That is fine; an incomplete digest
+is honest, a padded one is not. Name what you did not cover ("12
+narratives not sampled") and exclude it from your claims rather than
+guessing at its contents. Coverage you did not read is reported as
+missing, never synthesized.
+
+### Verify before you narrate
+
+Before posting, pass over your draft once: every narrative you name,
+every event you quote, every outcome you assert — can you point to the
+event you read it from? Cut, flag as unverified, or re-check anything
+you cannot trace. "Fairly sure" without a source is the signal to
+re-fetch or omit — never to assert.
+
+### Failure modes this guards against
+
+Do not repeat the run that prompted these rules:
+
+- Inventing narrative IDs, summaries, or events that are not in the log.
+- Summarizing narratives whose events you never actually read.
+- Reporting what a PR or commit "was about" from a guessed number
+  instead of from a narrative's events or real `gh`/`git` output.
+- Quietly dropping coverage you skipped instead of naming the gap.
+- Dressing any of the above in confident, specific-sounding prose.
+
+## Determining the time window
+
+Before generating the digest, determine the correct time window:
+
+1. **Find the last digest** — prefer `narrative_info` over semantic
+   search. Every digest sets its `summary` to `"Digest: {start} to
+   {end}"` (see Output below), so the reliable lookup is
+   `narrative_info` in browse mode with `search: "Digest"`,
+   `archived: true`, `limit: 0` — it matches that summary column
+   directly and returns results newest-first. Use the most recent
+   hit's end date as your window start.
+   **Do not rely on `narrative_search "Digest generated"` for this.**
+   Semantic search ranks *commentary about* digests above the actual
+   digest narrations and routinely surfaces stale, older digests while
+   missing more recent ones — a real run anchored to a digest two
+   months out of date this way. `narrative_search` is for themes
+   (step 3 of Gathering), not for locating the window boundary.
+2. **Fallback**: if no previous digest is found, default to `7d`
+   (one week).
+3. **Override**: if the `/digest` signal includes guidance specifying a
+   time range or other instructions, follow them. Examples:
+   - `/digest 7d` — last 7 days
+   - `/digest since monday` — since the most recent Monday
+   - `/digest 2026-03-01 to 2026-03-15` — explicit date range
+   - `/digest whole week ignoring previous /digest` — use 7d window,
+     skip the "find last digest" step
+
+   Freeform natural language is expected. Interpret intent generously.
+
+The end of the window is always **now**.
+
+## Gathering activity
+
+**Narrate your progress as you go.** The data gathering phase can take
+several minutes. Keep the operator informed by narrating status updates
+as you work — e.g., "Found 33 narratives in the window, sampling the
+top 10 by event count..." or "Reading events from the absorb sessions..."
+This lets the operator follow along and redirect if needed.
+
+Use the tools available to you to collect raw material:
+
+1. **`narrative_info`** — call with `since` set to the time window
+   (e.g., `"30d"`) and `limit: 0` to get all narratives active in
+   the period. Include `archived: true` to capture completed work.
+   Narrate what you found (count, date range, notable summaries).
+2. **Event sampling** — for each narrative returned, use `listen` with
+   `wait: false` and `tail: 20` to fetch the most recent events.
+   Focus on `human_signal` events (operator decisions) and `narration`
+   events with substantive content. Skip routine LIVE loop chatter.
+3. **`narrative_search`** — use targeted queries to find cross-cutting
+   themes (e.g., search for recurring topics, error patterns, or
+   decision points).
+
+When the number of narratives is large, prioritize:
+- Narratives with the most events (highest activity)
+- Narratives with `human_signal` events (operator engagement)
+- Narratives whose summaries suggest completed work
+
+### Parallelism
+
+**Parallelize aggressively.** Issue multiple `listen` (with `wait:
+false`) and `narrative_search` calls in a single tool-use turn. Batch
+5–10 narrative event reads per turn rather than fetching one at a time
+— this dramatically reduces the data gathering phase. Use `tail: 20`
+(or similar) to keep each response manageable and avoid flooding your
+context with long histories.
+
+Narrate a progress update between each batch so the operator sees
+movement — e.g., "Sampled 10/33 narratives so far, highlights: ..."
+
+## Digest structure
+
+Organize the digest into these sections, omitting any that have no
+content:
+
+### Activity overview
+- Total narratives active in the period
+- Breakdown by agent type and status
+- Busiest folds (directories where work happened)
+
+### Accomplishments
+- Narratives that reached completion (ended status or "done" summaries)
+- Key deliverables, features, or fixes — summarize what was achieved
+- Link back to narrative IDs for reference
+
+### Decisions & directions
+- Operator signals that set direction or changed course
+- Important choices made and their rationale (when visible)
+
+### Open threads
+- Active narratives that may need attention
+- Unanswered agent questions or stalled work
+- "Gone quiet" narratives — previously active but no recent events
+
+### Themes
+- Recurring topics across narratives
+- Patterns in the kind of work being done
+- Cross-narrative connections worth noting
+
+### Absorbed context
+- If any absorbed (imported) narratives were active or referenced in the
+  period, note relevant connections to current work
+
+## Output
+
+Narrate the digest in full using `narrate`. Use markdown formatting for
+readability, and write the digest body in the /wiki protocol's *Voice
+and register* — neutral, descriptive, attributed (see "Don't
+editorialize" above). Begin the narration with a header line:
+
+```
+**Digest generated** — {start_date} to {end_date} ({N} narratives)
+```
+
+This header line marks the narration as a digest. The primary locator
+for future `/digest` invocations, though, is the `summary` metadata
+below — set it on the same `narrate` call so the digest is findable via
+`narrative_info` (browse mode, `search: "Digest"`), which is the
+reliable way to determine the next window (see "Determining the time
+window"). Keep the `Digest: {start} to {end}` summary format exact so
+that search matches it.
+
+Set your narrative metadata:
+
+```json
+{
+  "meta": {
+    "summary": "Digest: {start_date} to {end_date}"
+  }
+}
+```
+
+## After generating
+
+After narrating the digest, return to the LIVE loop — `listen` for
+further signals. The operator may ask follow-up questions about specific
+narratives or request a different time window.

package/protocols/fly.md

@@ -0,0 +1,266 @@
+# /fly [init|new|deploy|up|down|meld|status|logs|destroy]
+
+Running brane daemons on Fly.io machines, reached over Tailscale.
+**Experimental.** It needs a tailnet you administer and an authenticated
+`fly` CLI (`fly auth whoami`).
+
+Bare /fly means this protocol. `/fly <verb>` asks for that verb's
+section below; follow its steps with plain `fly` commands. There is no
+`brane fly` subcommand. Brane supplies only the image (`Dockerfile`,
+`docker-entrypoint.sh`, shipped in the package) and `brane meld --remote`.
+Nothing here is specific to brane's CLI except that one command, so the
+same steps adapt to any host that runs a container.
+
+Every verb except `status` and `logs` changes something on Fly, and some
+cost money. Say what you're about to run and get the operator's go before
+running it.
+
+## Mental Model
+
+**Perch and relaunch:** machines are disposable, volumes are permanent.
+Idling costs nothing.
+
+| Verb | What it does |
+|------|--------------|
+| `down` | Destroy all machines. Zero cost. Volumes preserved. |
+| `up` | One machine per region that has a volume, reattaching it. |
+| `deploy` | Build and push the image; update running machines only, never create one. |
+
+Volumes are the source of truth: each represents a region the operator
+committed to, and machines come and go around them.
+
+Each machine runs **tailscaled** (its only network access) and a **brane
+daemon**. The volume is mounted at `/home/brane`, the whole home
+directory, so `~/.brane` (database, certs, payloads), `~/.claude`, agent
+configs and git state all persist. The embedding model is baked into the
+image at `/opt/brane/models`, outside the volume.
+
+## Shared values
+
+- **The app name** is remembered in brane config:
+  `APP=$(brane config fly.app)`. `init` sets it.
+- **The install directory**, where the `Dockerfile` and entrypoint live:
+  ```bash
+  BRANE_ROOT=$(node -e 'const p=require("path"),fs=require("fs");console.log(p.resolve(fs.realpathSync(process.argv[1]),"../.."))' "$(command -v brane)")
+  ```
+  That needs `brane` on `PATH`. Without it (`npx brane`), the install
+  directory is the one above `dist/cli.js`.
+- **The `fly.toml`**, written beside the image's files (`<app>` is `$APP`):
+  ```toml
+  app = "<app>"
+  primary_region = "sjc"
+
+  [build]
+    dockerfile = "Dockerfile"
+
+  [[mounts]]
+    source = "brane_data"
+    destination = "/home/brane"
+
+  [env]
+    TS_HOSTNAME = "daemon-<app>"
+
+  [[vm]]
+    size = "performance-1x"
+    memory = "2gb"
+  ```
+  The entrypoint appends the region, so a machine's tailnet name is
+  `daemon-<app>-<region>`. There is no `[http_service]`: Tailscale is
+  the only way in, so Fly's proxy has nothing to route, and without a
+  service it neither warns that nothing is listening nor stops or starts
+  machines on its own.
+
+## /fly init
+
+One-time setup.
+
+1. Create the app and remember its name:
+   ```bash
+   APP=brane-$(openssl rand -hex 3)
+   fly apps create "$APP" --org <org>
+   brane config fly.app "$APP"
+   ```
+2. Give it its secrets. `ANTHROPIC_API_KEY`, and a Tailscale credential
+   (see [Tailscale](#tailscale)). The operator sets secrets themselves,
+   `fly secrets set NAME=… -a "$APP"`, so no secret passes through an agent.
+   `TS_CLIENT_ID` is not a secret.
+3. Run [/fly deploy](#fly-deploy). With no machines it only builds and
+   registers the image.
+
+Then `/fly new` for each region.
+
+## /fly new
+
+Add a region: create its 10 GB volume. No machine yet; `/fly up` starts
+it. First check one isn't there already:
+
+```bash
+fly volumes list -a "$APP"
+fly volumes create brane_data --region <region> --size 10 --yes -a "$APP"
+```
+
+## /fly deploy
+
+Build the image on Fly's remote builder from this install, and update
+running machines. `--update-only` means it **never creates machines**, so
+it's safe while scaled to zero; the next `/fly up` uses the new image.
+
+```bash
+CTX=$(mktemp -d)
+cp "$BRANE_ROOT/Dockerfile" "$BRANE_ROOT/docker-entrypoint.sh" "$CTX/"
+(cd "$BRANE_ROOT" && npm pack --pack-destination "$CTX")
+# write the fly.toml above into "$CTX/fly.toml"
+(cd "$CTX" && fly deploy --update-only -a "$APP")
+```
+
+`fly` may print `Process groups have changed. This will: create 1 "app"
+machine` on an app with no machines; `--update-only` still creates none.
+
+## /fly up
+
+One machine per region that has a `brane_data` volume. Scale each region
+on its own: a single `fly scale count N --region a,b,c` can stack
+machines in one region and create stray volumes.
+
+```bash
+fly volumes list -a "$APP" --json   # the regions with a brane_data volume
+fly scale count 1 --region <region> --yes -a "$APP"   # once per region
+```
+
+Running machines are left alone. Watch the first boot with `/fly logs`:
+the machine is ready once its daemon logs `listening on`.
+
+## /fly down
+
+Destroy all machines; volumes and their data survive. Take each running
+machine off the tailnet first: stale WireGuard state on the volume breaks
+some peers (iOS especially) on the next `up`.
+
+```bash
+fly machines list -a "$APP"          # the started ones
+fly ssh console -a "$APP" --machine <id> -C "tailscale down"   # each
+fly scale count 0 --yes -a "$APP"
+```
+
+## /fly meld
+
+Connect a device to a machine's daemon. The machine can't show a presence
+prompt, so the device token is minted by the operator's own daemon, after
+Touch ID (or the platform's prompt) on their machine, and the remote gets
+only its hash. **The operator runs this, not an agent**: it prints the
+token in the QR and URL, and an agent's session is refused. Hand them the command with the app's name written in, since
+their shell has no `$APP`:
+
+```bash
+brane meld --remote \
+  --send "fly secrets set BRANE_DEVICE_TOKEN_SHA256={hash} -a <app>" \
+  --ask  "fly ssh console -a <app> -C 'gosu brane brane meld --connection'"
+```
+
+1. `--send` sets the secret, which restarts the machines; each daemon
+   adopts the hash as a device row as it starts, once (a hash it has ever
+   seen, revoked or not, never comes back), and drops the variable.
+2. `--ask` reads back the daemon's address (`brane meld --connection` mints
+   nothing), retrying for 3 minutes, and the QR is printed.
+
+Like every QR it lapses if nobody scans it within 10 minutes of the
+restart; run it again for a fresh one. More devices are best added from
+the app's Meld sheet, which needs no restart.
+
+## /fly status
+
+```bash
+fly status -a "$APP"
+fly machines list -a "$APP"
+fly volumes list -a "$APP"
+```
+
+## /fly logs
+
+```bash
+fly logs -a "$APP"                                   # follow
+fly logs -a "$APP" --region <region> --no-tail | tail -50
+```
+
+## /fly destroy
+
+Tearing down is the operator's to do, never an agent's: volumes hold the
+database, Tailscale identity, certs and session history. Point them at:
+
+- stop without losing anything: `/fly down`;
+- `fly volumes destroy <id> -a "$APP"` for one region;
+- `fly apps destroy "$APP"`, then `brane config --unset fly.app`, for all
+  of it.
+
+## Tailscale
+
+Machines join the tailnet as **tag-owned** nodes (`tag:brane`, or
+`TS_TAGS`), so their keys never expire; the identity persists on the
+volume and later boots reuse it. Every `tailscale up` in the entrypoint
+names the tags and has a `--timeout`: an `up` without the tags asks
+control to drop them, which waits for a login nobody on the machine can
+complete.
+
+A new volume (or one whose node was removed) joins with one of two
+credentials, set as Fly secrets:
+
+- **`TS_CLIENT_ID` (preferred): no secret on Fly.** The entrypoint asks
+  Fly for this machine's OIDC token (`/.fly/api`, `POST
+  /v1/tokens/oidc`) and Tailscale's workload identity federation trades
+  it for a node key. One-time setup in the Tailscale admin console:
+  1. Add `"tag:brane": ["autogroup:admin"]` to `tagOwners` in the policy
+     file.
+  2. Trust credentials → OpenID Connect → **Custom issuer**
+     `https://oidc.fly.io/<org>`, subject `<org>:<app>:*`, scope
+     `auth_keys` with `tag:brane`. `<org>` is the org's own name, which
+     for a personal org is *not* the `personal` that `fly orgs list`
+     shows. Read it from a token's claims on a running machine:
+     `fly ssh console -C "sh -c 'curl -fsS --unix-socket /.fly/api -X POST
+     http://localhost/v1/tokens/oidc --data {} | cut -d. -f2 | base64 -d'"`
+     prints `iss` and `sub` (base64 may warn about padding). Pinning the
+     app keeps every other app in the org from joining as `tag:brane`.
+  3. `fly secrets set TS_CLIENT_ID=<client id> -a <app>`. The audience
+     defaults to `api.tailscale.com/<client id>`; set `TS_AUDIENCE` if the
+     console shows a different one.
+- **`TS_AUTHKEY`:** an OAuth client secret with the `auth_keys` scope and
+  `tag:brane` (never expires), or an auth key allowed to apply the tag
+  (expires within 90 days). Append `?ephemeral=false&preauthorized=true`
+  to an OAuth secret.
+
+Nodes are never ephemeral: an ephemeral node is deleted while its machine
+is down, and `/fly down` can last months. Remove a dead node in the admin
+console before its region comes back, or the new one is named `…-1`.
+
+## Volume Safety
+
+**Volumes are never created by accident.** Only `/fly new` creates them,
+one region at a time; `/fly deploy` uses `--update-only`, and `/fly up`
+scales one region at a time.
+
+Intentional volumes are 10 GB; stray ones from Fly auto-provisioning are
+typically 1 GB. Investigate with `fly volumes list -a "$APP"` before
+anything is deleted, and leave deleting to the operator.
+
+## Troubleshooting
+
+### Machine won't start, or restarts every ~30 s
+
+`/fly logs`. Common causes:
+- **Not on the tailnet.** The log says `token exchange failed with status
+  403` (the trust credential's issuer, subject or audience doesn't match
+  the token; read the claims as above), `entrypoint: could not get an
+  OIDC token`, `neither TS_CLIENT_ID nor TS_AUTHKEY is set`, or `tailscale
+  up` timed out. See [Tailscale](#tailscale).
+- A volume in the old layout: the entrypoint migrates it.
+
+### Blank terminal after /fly up
+
+Narratives from a previous machine lifetime may show a blank terminal
+instead of the restart button, when `/fly down` killed the machine before
+the daemon could mark them ended. The server detects this on terminal
+connect (`tmux has-session`) and sends the terminated signal.
+
+### Stale Tailscale nodes
+
+After `/fly down`, nodes show as offline within 2–5 minutes. Cosmetic:
+they reconnect on the next `/fly up`.

package/protocols/idle.md

@@ -0,0 +1,81 @@
+# /idle [when]
+
+License to stop listening: the operator says the work is done, and the
+agent may fall completely idle until the operator comes back for it.
+
+## Why a license
+
+/LIVE_loop forbids leaving `listen` "without being told to".
+Right for an agent with work in flight; wrong for one whose task is
+finished and reported, where every `listen` timeout is an inference
+turn spent on nothing and a little more context. `/idle` is the being
+told.
+
+**Nothing wakes an idle agent but the operator.** No revive, no nudge,
+no signal typed into the terminal: signals to an idle narrative wait in
+its log. A daemon that woke idle agents would turn every stray signal
+into a turn nobody asked for, and would have to guess whether the agent
+was idle or mid-turn. Instead the agent's `summary` says `Idle: …`, so
+the operator always knows which narratives are watching and which are
+waiting.
+
+## Command, not conversation
+
+`/idle` is a command only as the **first token of a signal**: `/idle`
+or `/idle <when>`. In "did /idle work?" it is a word, and /prelude's
+"starts with or includes" convention does not apply. A misread
+`/memory` wastes a search; a misread `/idle` stops an agent watching.
+The bar is the one mentions draw between `@nid` and a bare `nid`:
+position, not presence. In doubt, it was conversation — answer, and
+keep listening.
+
+## The decision
+
+In order. Steps 1, 4 and 5 are mechanical; 2 and 3 are judgment, and
+the reason this is a protocol rather than a script.
+
+1. **Invoked?** First token `/idle` → continue. Otherwise respond to
+   it as conversation and never idle on its account.
+2. **When?** No condition → now. `/idle when CI is green` takes effect
+   when that is clearly true, read as the operator meant it (the
+   checks passed, not the run started); loop normally until then. If
+   you cannot tell, ask rather than guess either way; the license
+   holds while you wait.
+3. **Debt?** Vocalize everything executed but unreported — outcome,
+   state, open threads — and on the same `narrate` set `meta.summary`
+   to `Idle: <what finished, or what would resume>`. A long session
+   takes its [/summarize](summarize.md) here.
+4. **Gate.** `listen({ wait: false, after: <cursor> })`. Empty → stop.
+   Events → interpret them, back to step 3. The license stands unless
+   a newer signal gives work, in which case the loop simply resumes.
+5. **Stop.** Return to your native prompt. No `listen`, no narration,
+   no closing remark: step 3 was the last word.
+
+The order closes the race. Between the request and the stop there is
+a report to write and perhaps a condition to wait out, minutes in
+which the operator may say more; the gate being the last call means
+all of it is read before the agent leaves. Only a signal arriving
+after an empty read waits, and that is what the license covers.
+
+## Idle is not listening
+
+An idle agent makes no brane calls. A parked `listen` — one your
+harness holds in the background and resumes you on when it returns —
+is not idle: it is the ordinary loop on a harness where waiting is
+cheap, and it is what you do when the operator has **not** sent
+`/idle`. The two differ in what the operator chose: a listening agent
+answers the next signal by itself; an idle one answers when the
+operator types into its terminal. Sending `/idle` is choosing the
+second, and the reason to send it is that the agent's next signal is
+not coming for a while.
+
+## Waking
+
+The operator wakes you by typing into your terminal. Whatever they
+type, re-enter through Session Initialization in
+[LIVE_loop](LIVE_loop.md): `whoami`, `listen({ wait: false, tail: 50 })`,
+interpret everything that accumulated as one instruction, respond.
+
+`/idle` is a standing license, not an order. Until you stop, any newer
+signal that gives work supersedes it; after you stop, the operator's
+return is the withdrawal.