@openrig/cli 0.6.4 → 0.6.6

package/daemon/docs/reference/bundle-formats.md

@@ -0,0 +1,207 @@
+# Bundle formats (v1)
+
+The shared data formats for sharing rig bundles: the configurations a bundle offers, the before-install view of what it
+will do, run records and the public status file, and registry entries. The schemas are in [`schemas/`](schemas/), with
+fixtures that pass and fail them in [`schemas/fixtures/`](schemas/fixtures/). Tools outside this repository read them
+at a pinned commit.
+
+**A v1 format only grows:** new optional properties may appear, and consumers ignore properties they don't know. Any
+other change is a v2. The schemas are open to new properties, with three closed on purpose: the package digest (an exact
+value), a run record's subject (a harness check can never carry a team's identity), and the public status file, where
+nothing outside the schema may appear, so a private field can't leak in. A new property in a closed part is a v2. The
+status schema also rejects labels that contradict their evidence: a tested label needs records and a package, tested
+with help needs its count, tested can't carry a count above zero, and an unreadable listing carries only Status
+unavailable.
+
+## Three identities, kept apart
+
+| What | Name | Defined by |
+|---|---|---|
+| What someone chose | configuration ID | the mapping of every seat to a runtime |
+| What was packaged | package digest | the built archive's files |
+| What actually ran | execution binding | a run record (resolved resources, settings, environment, unknowns) |
+
+None stands in for another. A package digest doesn't describe what ran, and a configuration ID doesn't describe what was
+packaged.
+
+### Source identity
+
+A bundle on GitHub is named by `repository` (`https://github.com/<owner>/<repo>`, no credentials), `folder` (the
+repo-relative path of the folder holding `rig.yaml`, or `.` for the repository root) and `resolvedCommit` (40 lowercase
+hex).
+- `requestedRef` (the branch, tag or commit someone gave, or `HEAD` for a link without `/tree/…`) and `canonicalUrl`
+  (`…/tree/<resolvedCommit>/<folder>`, with each folder segment percent-encoded and no folder part for the root)
+  explain it, and aren't part of it.
+- A built bundle records its source in its manifest's provenance, which is outside the package digest.
+
+### Configuration ID
+
+Every member's `pod.member=runtime`, sorted by `pod.member` in UTF-16 code-unit order, joined with `,`. There's no
+whitespace, and runtimes are spelled as in `rig.yaml`. For example:
+
+```text
+build.impl=claude-code,build.lead=claude-code,check.qa=codex,check.review=codex
+```
+
+Preset names such as `recommended` or `all-claude` are aliases shown beside the ID, never part of it.
+
+### Package digest
+
+`{ algorithm: "sha256", value, coverage: "openrig.package-digest/v1" }`:
+- `value` is SHA-256 over UTF-8 lines `<quoted path>\t<sha256>\n`, one for each entry of the built archive's
+  `integrity.files`, sorted by path in UTF-16 code-unit order;
+- `<quoted path>` is the path as a JSON string, exactly as JavaScript's `JSON.stringify(path)` writes it, so a tab or
+  newline in a file name can't make two different file lists hash the same. In words: wrapped in `"`; `"` and `\`
+  escaped with a backslash; U+0008, U+0009, U+000A, U+000C and U+000D written `\b`, `\t`, `\n`, `\f` and `\r`; any
+  other character below U+0020, and any lone surrogate, written `\uXXXX` in lowercase hex; everything else as itself;
+- it's the same when the same folder is rebuilt by the same OpenRig, while the archive's own hash changes with every
+  build (`createdAt`).
+
+**Coverage, shown wherever the digest is:** the bytes of every packaged file. It doesn't cover:
+- `bundle.yaml`, so no manifest field, provenance or `createdAt`;
+- the names the integrity walk skips (`.DS_Store`, `Thumbs.db`, `.gitkeep`);
+- file modes;
+- anything resolved on the installing machine at launch, for example an `openrig-home:` plugin, catalog skills, or a
+  model or effort nothing declares.
+
+**A build result** carries `source` (`null` unless the bundle was built from a GitHub link), `configurationId`,
+`packageDigest`, `archiveHash` and `assembler`. `rig bundle inspect` reports the same fields for an archive, and any the
+archive doesn't state are `null`. `assembler` is `{ openrigVersion }`: the format also allows a `commit`, which this
+OpenRig doesn't write. `configurationId()` and `packageDigest()` are exported from `@openrig/daemon/bundle-identity`.
+Shared test vectors are in `schemas/fixtures/identity-vectors.json`.
+
+## The formats
+
+| Format | Schema | Lives | Written by |
+|---|---|---|---|
+| Declared configurations | `bundle-configurations.v1` | `configurations.yaml` beside `rig.yaml` | the bundle's author |
+| Before-install view | `bundle-behaviour.v1` (`openrig.bundle-behaviour/v1`) | the registry, one file per configuration and assembler version; never inside the archive | the daemon's inspect: `rig bundle inspect`, under `behaviour` with `--json` |
+| Run record | `run-record.v1` | beside its receipt, private | Fleet, Dev QA, and maintainers for community reports |
+| Public status | `bundle-status.v1` | `openrig-world` status, generated | the status generator only |
+| Registry entry | `registry-entry.v1` | `openrig-world/registry/<slug>.yaml` | maintainers, through review |
+
+### Declared configurations
+
+`seats` gives a `pod.member` the runtimes it may use, and the profile each runtime uses. A member it doesn't list keeps
+the runtime `rig.yaml` gives it. `presets` names full mappings, and `recommended` names one of them, which must be
+`rig.yaml` as written. `rig bundle create`, `rig bundle configurations` and `rig bundle check` refuse a file that breaks
+these rules.
+
+`--preset` and `--seat` choose a configuration (see the [rig bundle reference](rig-bundle.md)). Any mix of each seat's
+declared runtimes can be built, not only the presets; a runtime a seat doesn't declare is refused, and nothing is built.
+Without either flag, create builds `rig.yaml` as written. The built archive's manifest records
+`configuration: { id, preset }` outside the package digest; `preset` is there only when `--preset` or `--seat` chose a
+mapping that matches a declared preset.
+
+### Before-install view
+
+It's derived from the archive's files alone. Nothing is launched, probed or fetched. It's a view, never a gate, and
+carries no tested status.
+- **`identity`:** source, configuration ID, package digest, the archive's assembler, the generator that made the view,
+  stated compatibility, stated provenance (not verified), and integrity (self-consistency, not authorship). A source,
+  configuration ID, package digest or assembler the archive doesn't state is `null`; unstated compatibility and
+  provenance are empty objects. None of it is filled from the inspecting OpenRig.
+- **`team`, `posture`, `toldFiles`, `alsoRuns`, `writes`, `outsideAddresses`, `needs` and `unknownBeforeLaunch`**, in
+  that order. Facts cite the archive file they come from (`sourceRefs`), except `team` entries and the bundle-wide
+  unknowns. `toldFiles` and `alsoRuns` also say how each resolves: `archive`, `host_at_launch` or `unresolved`.
+  - Posture separates what the archive declares from the product's default. Its effect on the host is `unknown`,
+    because host settings decide it.
+    Optional `posture[].permissionPrompts` is `off` for declared `full_bypass` (including rig- or member-level
+    `builtin:yolo`) on any runtime; for Claude/Codex, `on` for a declared flag-surface floor policy or `default` when
+    no policy is declared (prompts on unless the installing machine's settings turn them off); for Codex, `on` for
+    declared `auto`. Omit it for Claude under auto (naming auto mode in `selection`), config-surface policies
+    (`builtin:locked`, `builtin:standard`, `builtin:open` or an archived `surface: config` policy), host-resolved
+    Codex profiles, `permission_policy: none`, a policy the archive can't resolve, and every runtime other than Claude
+    and Codex (Pi, terminal) except declared full bypass. `selection` names the declared policy.
+    An absent field means not stated, never `on`. For `off`, Claude
+    bypasses permissions, Codex runs with full access and never asks, and Pi gets full resource trust (`--approve`,
+    not a permission mode). These are archive facts; `nativeEffect` remains `unknown`.
+    Optional `posture[].firstRunWarnings.claudeBypass: "harness_asks_once"` names the first-run bypass warning for a
+    declared full-bypass Claude seat, conditional on whether the harness has remembered acceptance.
+    `posture[].nonInterruptive: "available"` says a full-bypass Claude/Codex seat can use
+    [non-interruptive launch flags](non-interruptive-mode.md). It does not select the option, read host acceptance
+    state or prove a prompt-free launch. Both fields are omitted where inapplicable or unresolved; older v1 views
+    remain valid without them. Pi has no additional warning-suppression flag. `nativeEffect` stays `unknown`.
+  - An empty list means none are known. Something unknown goes in `unknownBeforeLaunch`.
+  - Per-seat facts carry `seat` (`pod.member`) and human output labels them with that identity. It's required on
+    `team` and `posture`. Elsewhere it's optional: bundle-wide facts (services, library and project writes, setup and
+    version needs) omit it, and older generators may not have stated it.
+- **`not_generated`:** a combination without a generated view, or an archive the generator can't describe: schema 1, no
+  readable pod-aware rig spec, a member missing its pod, id or agent reference, a runtime that depends on an AgentSpec
+  the archive can't read, or an error while reading. It carries a reason and the local command that shows it, and no
+  sections.
+
+### Declared setup preconditions
+
+The author's `bundle.yaml`, beside `rig.yaml`, may declare setup that the user must do before installing:
+
+```yaml
+preconditions:
+  - name: Run inside an OpenRig source clone with dependencies installed and packages built.
+    commands:
+      - git clone https://github.com/mvschwarz/openrig.git
+      - cd openrig
+      - npm ci
+      - npm run build
+  - name: Sign in to the selected coding runtimes before starting the team.
+```
+
+Local-folder creation and GitHub-link imports carry these declarations into the archive manifest. A generated
+before-install view lists each as `needs[]` with `kind: precondition`, the author's `name`, optional ordered `commands`,
+`status: not_checked`, and a `sourceRefs` entry naming `bundle.yaml` and `preconditions[index]`. Inspect, plan and apply
+previews show the same declaration. A legacy schema-1 archive retains it in the manifest, but its view remains
+`not_generated`. Missing preconditions mean none were declared, not that no setup is needed.
+
+Each command is one plain command line, without shell operators (`;`, `&&`, pipes, command substitution, backticks or
+redirection). Run them in order in **one shell**, then run the install command in that same shell: it inherits the
+working directory left by the setup commands. There is no separate `workdir` field. Commands are untrusted author data;
+a site building a copyable block must validate every line and bound the number of entries, omitting all setup lines
+if any fails its plain-command rule. OpenRig displays these declarations; it does not execute them, verify that setup
+was done, or add a prerequisite gate. The archive hash covers the manifest; `packageDigest` excludes `bundle.yaml`
+and therefore does not cover these declarations.
+
+At creation, malformed preconditions produce a warning and the whole block is omitted; other author-field validation
+is unchanged. Shell operators in otherwise valid command lines produce a warning, but the declarations are retained
+as data. An already-built archive with malformed preconditions reports them as unknown before launch.
+
+### Run records and status
+
+**A run record's subject** is either a team (source, configuration ID, package digest, assembler) or a harness check (a
+runtime). A harness check never upgrades a team label.
+
+**A run record's `environment.platform` and `arch`** are Node's `process.platform` (`linux`, `darwin` or `win32`) and
+`process.arch` (`x64` or `arm64`): the values a status platform key can carry, so every valid record can be labelled.
+
+**Records are private.** Only `outcome.publicNote` (a short public cause) reaches the status file.
+
+**Relations:** `supersedes`, `withdraws` and `resolves`. Reusing earlier evidence for a changed package is a reviewer's
+decision, recorded in the registry entry's `evidenceReuse`.
+
+**The status file** is generated from records by rule `openrig.status-rule/v1`:
+- **Labels:** `known_problem`, `tested`, `tested_with_help`, `partly_tested`, `not_tested` and `status_unavailable`.
+  They're shown as Known problem, Tested by OpenRig, Tested with help (N), Partly tested, Not tested by OpenRig
+  and Status unavailable.
+- **A label belongs to one configuration ID.** No configuration is ever shown another configuration's label.
+- **Empty `platforms`** means Not tested by OpenRig. So does a custom configuration, one the listing doesn't offer.
+- **Status unavailable is only for a listed configuration** whose records can't be read, or that's missing from the
+  status file; never Not tested by OpenRig. A listing whose records can't be read is `status_unavailable` as a whole.
+- **Platform keys** are `<os>-<arch>` (`linux`, `darwin` or `win32`; `x64` or `arm64`).
+- **`tested` means no help was needed:** it can't carry an assistance count above zero.
+- **An assist** is one action a person or the test runner took to get past a problem during the run, such as restarting a seat or re-running a command; following the bundle's own documented steps doesn't count.
+- **The file holds no private paths, host names, row IDs, account names or receipt text,** and regenerating it gives
+  identical bytes.
+- **`bodyDigest`** is SHA-256, lowercase hex, over the RFC 8785 (JCS) canonical JSON, as UTF-8, of an object holding
+  every other top-level field. The site import recomputes it and rejects a hand-edited file. `harnessChecks` has its own
+  `state`, so an unreadable harness-check record reads Status unavailable too.
+
+### Registry entries
+
+Each entry records:
+- the source at its reviewed commit;
+- each offered configuration with its package digest, assembler and behaviour-view file;
+- optional `evidenceReuse`;
+- the review date, and `listed` or `withdrawn` (with `withdrawnOn`).
+
+v1 has no author field: a listing shows the owner of `source.repository`.
+
+A listing shows "Reviewed for listing on `<date>` at commit `<short>`. Review is not a security audit."

package/daemon/docs/reference/chain-file-convention.md

@@ -50,13 +50,19 @@ Established chain names on the topology tree:
 - `LEARNED.md` — what a POSITION has learned; never shared or shipped as-is.
   A seat's LEARNED is identified by its PATH: the same seat name in two rigs
   is two different files.
-- `CULTURE.md` — norms layered into members at startup.
+- `CRAFT.md` — how work is done at that altitude (shipped at instance, rig and
+  seat), with `ORCHESTRATION-CRAFT.md` at rig level for orchestration practice.
+- `CULTURE.md` — team norms. Note that startup delivers the rig spec's own
+  `culture_file` (a path beside `rig.yaml`), not a `CULTURE.md` under
+  `topology.root`.
 
 ### The project tree
 
 Rooted at the workspace keys (`workspace.root`, `workspace.slices_root`).
 Chain names there: `SPEC.md` (intent in frontmatter composes up the chain;
-specification is a leaf property), `PROOF.md`, `PROGRESS.md`.
+specification is a leaf property), `PROOF.md`, `PROGRESS.md`. The walkers also
+read `NOTES.md` (or `MISSION_NOTES.md`), and fall back to `README.md` for a node
+without a `SPEC.md`.
 
 **Project-tree context cannot ship.** It describes what *you* are building —
 mission intent, slice specifications, proof contracts. No vendor can author it
@@ -70,8 +76,11 @@ defaults.)
 
 Before this convention the topology tree lived at `~/.openrig/shared-docs/rigs/`
 (design decision 2026-08-14: an arbitrary folder on one machine, not a product
-path). That location **stays readable** as a per-level fallback so existing
-rigs migrate instead of breaking — but every read that resolves there emits a
+path). That location **stays readable** as a per-level fallback for
+`rig context trace`, at the rig and seat levels, so existing rigs migrate instead
+of breaking. The refocus trace, `seat:` profile atoms and handover priming read
+only `topology.root`, so until migration they report those files as missing. Every
+read that resolves to the legacy location emits a
 named advisory (`legacy-topology-read: …`) stating the legacy source, the
 canonical destination under `topology.root`, and the config key. A silent
 legacy read is a defect. The legacy literal lives in exactly one helper per
@@ -93,9 +102,9 @@ reproduces the drift it was meant to catch. Run it; do not recall it.
 
 ## Shipped defaults and the curation path
 
-Included rigs (product-team first) ship sensible-default chain files at the
-applicable instance, rig, pod, and seat altitudes, installed under
-`topology.root` at rig-up.
+Included rigs ship sensible-default chain files under a `topology/` folder,
+installed under `topology.root` at rig-up. Today only `factory` ships one,
+with instance, rig and seat defaults; the installer also supports pod defaults.
 A shipped default is a **starting point** the occupying team appends to — it
 is never overwritten by a later rig-up (existing files win).
 

package/daemon/docs/reference/developing.md

@@ -1,8 +1,18 @@
 # Developing OpenRig — gates and lanes
 
 This is the contributor-facing statement of which checks BLOCK a change and which are
-advisory. There is no external CI at this tip: the root `package.json` script chain IS
-the gate, and the release checklists invoke it.
+advisory. Every pull request to `main` runs `.github/workflows/tests.yml` on a clean GitHub
+runner: build and packaging, typecheck, the repository scripts (`npm run test:repo`), each
+workspace's test suite (daemon, cli, tui and ui) on macOS without ambient credentials or
+external network, and an installed-package scenario (`scripts/run-pr-scenarios.sh`). The root
+`package.json` scripts below run the same build, typecheck, repository and test checks locally,
+with one difference: `npm test` does not include the UI suite, which CI runs as
+`package-tests (ui)`. Run `npm run test:ui` for it.
+
+**In a fresh clone or worktree, run `npm ci`, then `npm run build`,** as CI's build-and-package and
+package-test jobs do (typecheck and repo-checks build only the daemon, through their scripts; see
+`CONTRIBUTING.md` and [worktree builds](worktree-builds.md)).
+Locally, `npm test` builds only the daemon, and `test:workspaces` and `test:ui` build nothing.
 
 ## Blocking gates (must pass before a candidate moves)
 
@@ -10,23 +20,28 @@ the gate, and the release checklists invoke it.
 |---|---|---|
 | Typecheck | `npm run lint` | daemon + **ui** + cli + tui tsconfigs — UI typecheck STAYS blocking |
 | Build | `npm run build` | all workspaces — the UI dist ships in the package, so its build STAYS blocking |
-| Repo scripts | `npm run test:repo` | script self-tests, docs guard, skill mirror check |
+| Repo scripts | `npm run test:repo` | daemon build, script self-tests, docs guard, skill mirror check, context-pack generation check |
 | Unit tests | `npm run test:workspaces` | `packages/daemon` + `packages/cli` + `packages/tui` |
+| UI unit tests | `npm run test:ui` | `packages/ui` vitest. NOT part of `npm test`, but every pull request runs it as `package-tests (ui)` (the `package-tests` matrix in `.github/workflows/tests.yml`) |
+| Installed-package scenario | CI only: `scripts/run-pr-scenarios.sh` | the installed package, a daemon restart and a seeded durability failure. The script refuses to run outside GitHub Actions unless given `--remote` with `DOCKER_HOST=ssh://…` |
+| Package file lists | CI only | records each package's published file list (`npm pack --dry-run`) |
 
-`npm test` runs `test:repo` and `test:workspaces` — the blocking set is readable in the
-script itself.
+`npm test` runs `test:repo` and `test:workspaces`; `npm run test:ui` is the separate UI
+suite. Both sets are readable in the root `package.json` scripts.
 
 ## Advisory lane
 
 | Lane | Command | Meaning |
 |---|---|---|
-| UI unit tests | `npm run test:ui` | runs `packages/ui` vitest at will; NOT part of `npm test` |
+| Portability report | `node scripts/portability-report.mjs` | lists added lines with machine-specific values; findings never fail it (`.github/workflows/portability-report.yml`) |
 
 ## The norm (web-UI freeze at 0.5.0)
 
-Daemon API changes no longer require UI sync or UI verification; the contract mirrors
-under `packages/ui/src/hooks/` are no longer proactively maintained; a new `test:ui`
-failure signals a moved API contract, not a broken gate.
+Daemon API changes no longer require browser or interaction verification of the UI, and
+the contract mirrors under `packages/ui/src/hooks/` are no longer proactively maintained. A
+new `test:ui` failure usually signals a moved API contract. Because pull-request CI runs the
+UI suite as `package-tests (ui)`, the change that moves the contract has to update the affected
+UI test or mirror to pass that check.
 
 Browser/interaction testing of the web UI is not a contributor gate. (The packaged
 starter-rig agent skills that exercise the UI are product content for user rigs, not

package/daemon/docs/reference/edge-types.md

@@ -1,8 +1,7 @@
 # Edge Types Reference
 
-Version: 0.2.0
-Last validated against code: 2026-04-11
-Source of truth: `packages/daemon/src/domain/rigspec-schema.ts`, `packages/daemon/src/domain/rigspec-instantiator.ts`
+Last validated against code: 2026-10-05, at main `fcaf1f8e`
+Source of truth: `packages/daemon/src/domain/rigspec-schema.ts`, `packages/daemon/src/domain/rigspec-instantiator.ts`, `packages/daemon/src/domain/queue-owner.ts`
 
 ---
 
@@ -17,17 +16,18 @@ See `docs/reference/rig-spec.md` for the YAML syntax.
 
 ## Edge Kinds
 
-Five edge kinds are accepted by the validator:
+Five edge kinds are accepted by the pod-aware validator (the legacy flat-node format accepts only `delegates_to`,
+`spawned_by` and `can_observe`):
 
 | Kind | Accepted | Has Runtime Behavior | Description |
 |------|----------|---------------------|-------------|
-| `delegates_to` | yes | **yes — affects launch order** | Source delegates work to target |
-| `spawned_by` | yes | **yes — affects launch order** | Target was spawned by source |
+| `delegates_to` | yes | **yes — launch order and queue escalation** | Source delegates work to target |
+| `spawned_by` | yes | **yes — affects launch order** | Source was spawned by target |
 | `can_observe` | yes | no | Source can observe target's output |
 | `collaborates_with` | yes | no | Peer collaboration |
 | `escalates_to` | yes | no | Source escalates to target |
 
-## What Edges Actually Do Today (OpenRig 0.1.x)
+## What Edges Actually Do Today
 
 ### Launch ordering
 
@@ -36,10 +36,16 @@ Only `delegates_to` and `spawned_by` affect runtime behavior. They constrain the
 - **`delegates_to`**: source launches BEFORE target. The delegator must be up before the delegate.
 - **`spawned_by`**: target (parent) launches BEFORE source (child). The parent must be up before the child it spawned.
 
-This ordering is enforced in both `PodRigInstantiator` (initial launch) and `RestoreOrchestrator` (restore from snapshot). The code uses topological sort over the dependency graph — if there's a cycle, instantiation fails.
+This ordering is enforced in both `PodRigInstantiator` (initial launch) and `RestoreOrchestrator` (restore from snapshot). The code uses topological sort over the dependency graph — if there's a cycle, instantiation fails with `cycle_error` before the rig is created. A `delegates_to` or `spawned_by` edge from a member to itself counts as a cycle. Restore uses the same sort but has no cycle check of its own.
 
 All other edge kinds (`can_observe`, `collaborates_with`, `escalates_to`) do NOT constrain launch order.
 
+### Queue escalation
+
+`delegates_to` also names a seat's orchestrator for the queue: the source of the `delegates_to` edge into a seat. The
+wake ladder escalates an unacknowledged row to that orchestrator, and stuck-row findings and recovery go to it. A seat
+with no incoming `delegates_to` edge has no default orchestrator. `spawned_by` plays no part here.
+
 ### Graph visualization
 
 All edges are rendered in the UI topology graph. They create visual connections between nodes, helping the operator understand the team structure. Pod-local edges appear within the pod group; cross-pod edges connect across groups.
@@ -50,13 +56,15 @@ All edges appear in `rig whoami --json` output under `edges.outgoing` and `edges
 
 ### Attach hint heuristic
 
-The post-command handoff (the "Attach:" line after `rig up` and `rig restore`) uses edges to prefer the orchestrator as the default attach target. The heuristic looks for the first node with `delegates_to` outgoing edges.
+The post-command handoff (the "Attach:" line after `rig up` and `rig restore`) doesn't use edges. It names the first
+node, in creation order, whose session is running, or else the first node with a session name.
 
 ## What Edges Do NOT Do Today
 
 Edges do NOT currently:
 
-- **Route messages** — `rig send` can target any session, regardless of edges
+- **Route messages** — `rig send` can target any session, regardless of edges (queue escalation, above, is the one
+  daemon path that follows `delegates_to`)
 - **Enforce delegation** — an agent can communicate with any peer, not just its edge targets
 - **Control permissions** — there's no edge-based access control
 - **Affect transport** — `rig capture`, `rig broadcast`, etc. work based on session identity, not edge topology