mirror of
https://github.com/mvschwarz/openrig.git
synced 2026-11-10 03:31:40 -10:00
Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 v-openrig-build
|
ce2a3bd8eb | ||
|
v-openrig-build
|
b81d97c2da | ||
|
v-openrig-build
|
038019a4e7 |
No files matched your search
@@ -23,17 +23,12 @@ not by restarting the daemon you live in.
|
||||
|
||||
| You want to know | Read | How much to trust it |
|
||||
|---|---|---|
|
||||
| What OpenRig can already do, before you decide something is missing | `rig context get onboarding-width/public-what-you-can-do.md`; in this checkout, `packages/daemon/context-packs-src/onboarding-width/public-what-you-can-do.md` (the installed copy can differ) | The capability map; check it before proposing a new command or calling a gap a defect |
|
||||
| Whether a `rig` command already exists | `rig --help`: the full command list, before you decide a command is missing | The running binary; read the whole list, not only the command you expected |
|
||||
| Whether a problem is already known | The "Known problems to compare against" section of [`docs/reference/help.md`](../../../docs/reference/help.md) | Lists known issues by symptom; check an issue's current status before relying on it |
|
||||
| Whether a feature is already planned | [`ROADMAP.md`](../../../ROADMAP.md) | Check it before proposing a feature |
|
||||
| How the packages fit, the request path, where to add a command, route, migration, adapter, skill, context pack or scenario | [`ARCHITECTURE.md`](../../../ARCHITECTURE.md) | Checked against the commit it names; counts come with the command to refresh them |
|
||||
| Whether your change touches a high-risk area, what depends on it, what broke there before | [`docs/as-built/arteries.md`](../../../docs/as-built/arteries.md) | Incomplete by design: absence from it doesn't make a change safe |
|
||||
| What to run before you push, and what each layer can and can't prove | [`docs/as-built/test-layers.md`](../../../docs/as-built/test-layers.md) | Checked against the commit it names |
|
||||
| The exact behaviour of a `rig` command | `rig <command> --help` on the running binary, then `packages/cli/src/commands/` | The binary and the code win over any document |
|
||||
| A subsystem in depth | [`docs/as-built/`](../../../docs/as-built/README.md) | Each module names the commit it was last checked against in `last-verified-against-source`; compare that marker with `git log` before relying on it |
|
||||
| A subsystem in depth | [`docs/as-built/`](../../../docs/as-built/README.md) | Most modules predate 0.6; check each one's `last-verified-against-source` marker against `git log` before relying on it |
|
||||
| Rig spec, agent spec and other user-facing reference | [`docs/reference/`](../../../docs/reference/) | Ships to every user; if you find drift, fix it there |
|
||||
| Which shipped skill covers a task | [`skills/_canonical/core/openrig-skills/SKILL.md`](../../../skills/_canonical/core/openrig-skills/SKILL.md) | The index of the skills that ship with OpenRig |
|
||||
| How to open a good pull request, and what review looks like | [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) | Current |
|
||||
|
||||
If none of these answers your question, search the code before inventing an answer. A missing map is worth an issue.
|
||||
@@ -61,10 +56,6 @@ stub-agent scenarios, which run the real CLI, daemon, tmux and SQLite with scrip
|
||||
OpenRig is a coordination layer for a trusted environment: it should help agents and people keep work flowing.
|
||||
|
||||
- A change that removes friction, or makes state more truthful, is usually welcome.
|
||||
- OpenRig runs on agents working in context with tools. Before adding code for a behaviour, ask whether an agent with
|
||||
the right instructions and today's commands could do it. A skill or a page of guidance is often the better change.
|
||||
- Where to look: the capability map above, and the `agent-operated-workflows` skill, which ships in the
|
||||
`openrig-core` plugin (`packages/daemon/assets/plugins/openrig-core/skills/agent-operated-workflows/SKILL.md`).
|
||||
- A change that adds a refusal, a prompt or a required step needs the concrete case in CONTRIBUTING.md: who is
|
||||
harmed, how, and what it costs everyone else.
|
||||
- One concern per pull request. Keep the diff reviewable in one sitting.
|
||||
|
||||
@@ -23,17 +23,12 @@ not by restarting the daemon you live in.
|
||||
|
||||
| You want to know | Read | How much to trust it |
|
||||
|---|---|---|
|
||||
| What OpenRig can already do, before you decide something is missing | `rig context get onboarding-width/public-what-you-can-do.md`; in this checkout, `packages/daemon/context-packs-src/onboarding-width/public-what-you-can-do.md` (the installed copy can differ) | The capability map; check it before proposing a new command or calling a gap a defect |
|
||||
| Whether a `rig` command already exists | `rig --help`: the full command list, before you decide a command is missing | The running binary; read the whole list, not only the command you expected |
|
||||
| Whether a problem is already known | The "Known problems to compare against" section of [`docs/reference/help.md`](../../../docs/reference/help.md) | Lists known issues by symptom; check an issue's current status before relying on it |
|
||||
| Whether a feature is already planned | [`ROADMAP.md`](../../../ROADMAP.md) | Check it before proposing a feature |
|
||||
| How the packages fit, the request path, where to add a command, route, migration, adapter, skill, context pack or scenario | [`ARCHITECTURE.md`](../../../ARCHITECTURE.md) | Checked against the commit it names; counts come with the command to refresh them |
|
||||
| Whether your change touches a high-risk area, what depends on it, what broke there before | [`docs/as-built/arteries.md`](../../../docs/as-built/arteries.md) | Incomplete by design: absence from it doesn't make a change safe |
|
||||
| What to run before you push, and what each layer can and can't prove | [`docs/as-built/test-layers.md`](../../../docs/as-built/test-layers.md) | Checked against the commit it names |
|
||||
| The exact behaviour of a `rig` command | `rig <command> --help` on the running binary, then `packages/cli/src/commands/` | The binary and the code win over any document |
|
||||
| A subsystem in depth | [`docs/as-built/`](../../../docs/as-built/README.md) | Each module names the commit it was last checked against in `last-verified-against-source`; compare that marker with `git log` before relying on it |
|
||||
| A subsystem in depth | [`docs/as-built/`](../../../docs/as-built/README.md) | Most modules predate 0.6; check each one's `last-verified-against-source` marker against `git log` before relying on it |
|
||||
| Rig spec, agent spec and other user-facing reference | [`docs/reference/`](../../../docs/reference/) | Ships to every user; if you find drift, fix it there |
|
||||
| Which shipped skill covers a task | [`skills/_canonical/core/openrig-skills/SKILL.md`](../../../skills/_canonical/core/openrig-skills/SKILL.md) | The index of the skills that ship with OpenRig |
|
||||
| How to open a good pull request, and what review looks like | [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) | Current |
|
||||
|
||||
If none of these answers your question, search the code before inventing an answer. A missing map is worth an issue.
|
||||
@@ -61,10 +56,6 @@ stub-agent scenarios, which run the real CLI, daemon, tmux and SQLite with scrip
|
||||
OpenRig is a coordination layer for a trusted environment: it should help agents and people keep work flowing.
|
||||
|
||||
- A change that removes friction, or makes state more truthful, is usually welcome.
|
||||
- OpenRig runs on agents working in context with tools. Before adding code for a behaviour, ask whether an agent with
|
||||
the right instructions and today's commands could do it. A skill or a page of guidance is often the better change.
|
||||
- Where to look: the capability map above, and the `agent-operated-workflows` skill, which ships in the
|
||||
`openrig-core` plugin (`packages/daemon/assets/plugins/openrig-core/skills/agent-operated-workflows/SKILL.md`).
|
||||
- A change that adds a refusal, a prompt or a required step needs the concrete case in CONTRIBUTING.md: who is
|
||||
harmed, how, and what it costs everyone else.
|
||||
- One concern per pull request. Keep the diff reviewable in one sitting.
|
||||
|
||||
@@ -1 +0,0 @@
|
||||
github: mvschwarz
|
||||
+1
-4
@@ -4,12 +4,9 @@
|
||||
troubleshooting. An index linking to agent-friendly documentation is at
|
||||
https://openrig.dev/llms.txt.
|
||||
- **Agents helping a user:** read [docs/reference/help.md](../docs/reference/help.md), or run `rig context get help`.
|
||||
The same guide is at https://www.openrig.dev/help/agents.
|
||||
- **Email:** hello@openrig.dev, which needs no GitHub account.
|
||||
- **Questions:** [Discussions › Q&A](https://github.com/mvschwarz/openrig/discussions/categories/q-a).
|
||||
- **Bugs:** [open an issue](https://github.com/mvschwarz/openrig/issues/new/choose) with the bug
|
||||
template. Include `rig --version`, your OS, Node and tmux versions, the harnesses involved, and
|
||||
relevant redacted command output.
|
||||
template. Include `rig --version`, your OS and Node versions, and relevant redacted command output.
|
||||
Reports are public: remove credentials, private prompts and personal information.
|
||||
- **Ideas and setups:** [Ideas](https://github.com/mvschwarz/openrig/discussions/categories/ideas)
|
||||
and [Show and tell](https://github.com/mvschwarz/openrig/discussions/categories/show-and-tell).
|
||||
|
||||
@@ -3,12 +3,9 @@ name: Tests
|
||||
# Builds, type-checks and runs every test suite on a clean GitHub runner, and records the file
|
||||
# list each published package would contain. Each suite is its own job so one failure does not
|
||||
# hide the others. No provider credentials or operator configuration are supplied.
|
||||
# Package suites and the Linux seat-environment check deny external networking;
|
||||
# scenario runtime has no external route.
|
||||
# Package suites deny external networking; scenario runtime has no external route.
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
branches: [main]
|
||||
workflow_dispatch:
|
||||
@@ -17,7 +14,7 @@ permissions:
|
||||
contents: read
|
||||
|
||||
concurrency:
|
||||
group: tests-${{ github.event_name }}-${{ github.ref }}
|
||||
group: tests-${{ github.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
jobs:
|
||||
@@ -77,42 +74,7 @@ jobs:
|
||||
- run: npm ci
|
||||
- run: npm run test:repo
|
||||
|
||||
linux-seat-environment:
|
||||
if: ${{ github.event_name != 'push' }}
|
||||
# This integration test reads /proc/<pid>/environ and is skipped on macOS.
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 20
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
persist-credentials: false
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 22
|
||||
cache: npm
|
||||
- name: Install the real terminal and staging tools
|
||||
run: |
|
||||
sudo apt-get update
|
||||
sudo apt-get install --yes tmux rsync
|
||||
- run: npm ci
|
||||
- run: npm run build
|
||||
- name: Check seat environments without ambient credentials or external network
|
||||
run: |
|
||||
set -euo pipefail
|
||||
suite_root=$(mktemp -d "$RUNNER_TEMP/opr-seat-env.XXXXXX")
|
||||
mkdir -p "$suite_root/home"
|
||||
# Only loopback exists in this namespace. Drop back to the runner user
|
||||
# before the CLI, private daemon and private tmux server are started.
|
||||
sudo unshare --net -- /bin/bash -s -- "$(id -un)" "$suite_root" "$PATH" <<'SUITE'
|
||||
set -euo pipefail
|
||||
ip link set lo up
|
||||
exec runuser -u "$1" -- env -i HOME="$2/home" PATH="$3" TMPDIR="$2" TMUX_TMPDIR="$2" \
|
||||
CI=true TERM=xterm-256color \
|
||||
npm run test -w packages/daemon -- test/seat-env-parent-session.integration.test.ts --maxWorkers=1 --reporter=verbose
|
||||
SUITE
|
||||
|
||||
package-tests:
|
||||
if: ${{ github.event_name != 'push' }}
|
||||
# macOS, the platform OpenRig runs on: several daemon and cli tests read macOS ps columns,
|
||||
# file-inode behaviour and release tags.
|
||||
runs-on: macos-latest
|
||||
|
||||
+39
-45
@@ -3,14 +3,14 @@
|
||||
> **This map is not the territory.** It is a zoomed-out guide for finding your way around the
|
||||
> code. It is incomplete by design and it may be stale. Where it disagrees with the code, the code
|
||||
> is right; please fix the page. Every path, symbol, count and command below was checked against
|
||||
> commit `c750304f` (0.6.6 development). Each count shows the command that produced it, so you
|
||||
> commit `1347d825` (`v0.6.3-33-g1347d825c`). Each count shows the command that produced it, so you
|
||||
> can re-run it.
|
||||
|
||||
## What OpenRig is
|
||||
|
||||
OpenRig runs a team of coding agents on your machine as one system. A local daemon keeps the team's
|
||||
state in SQLite and runs each agent as an ordinary Claude Code or Codex session (or a plain
|
||||
terminal, a Pi or Oh My Pi (OMP) runner, or a scripted test stub) inside tmux. People and agents drive it through the
|
||||
terminal, a Pi runner, or a scripted test stub) inside tmux. People and agents drive it through the
|
||||
`rig` CLI, a terminal UI (TUI) and an MCP server, all of which talk to the daemon over local HTTP.
|
||||
The agents themselves are unmodified. What OpenRig adds is the coordination around them: launching
|
||||
and restoring agents, delivering messages, keeping durable work in a queue, and giving each agent
|
||||
@@ -34,9 +34,9 @@ build goes to `ui/dist`; the TUI build goes to `tui/dist`. So `docs/reference/`
|
||||
user; `docs/as-built/` and this file do not.
|
||||
|
||||
**Sharing code between packages.** The CLI and TUI import daemon code only through the subpaths in
|
||||
the `exports` field of `packages/daemon/package.json` (21 at this commit), for example
|
||||
the `exports` field of `packages/daemon/package.json` (18 at this commit), for example
|
||||
`@openrig/daemon/attention`, which points at `packages/daemon/src/attention-surface.ts`. The CLI
|
||||
uses 19 of them and the TUI uses 2. In development they resolve through the npm workspace. At
|
||||
uses 16 of them and the TUI uses 2. In development they resolve through the npm workspace. At
|
||||
package time `scripts/rewrite-daemon-imports.mjs` rewrites them to the shipped `daemon/dist` copy
|
||||
and fails the build on a specifier with no `exports` entry. To share new daemon code, add a
|
||||
`*-surface.ts` file and an `exports` entry.
|
||||
@@ -55,7 +55,7 @@ and fails the build on a specifier with no `exports` entry. To share new daemon
|
||||
packages/daemon/src/domain/ services, repositories, orchestrators, event bus
|
||||
/ | \
|
||||
SQLite (db/) tmux (adapters/tmux.ts) runtime adapters (adapters/*-adapter.ts)
|
||||
claude-code, codex, pi, omp, terminal, stub
|
||||
claude-code, codex, pi, terminal, stub
|
||||
```
|
||||
|
||||
**Inside the daemon** (`packages/daemon/src/`):
|
||||
@@ -65,8 +65,7 @@ and fails the build on a specifier with no `exports` entry. To share new daemon
|
||||
database (`db/connection.ts`: WAL mode, foreign keys on), runs `migrate(db, ALL_MIGRATIONS)`,
|
||||
constructs every service and adapter, and passes them to `createAppWithWebSocket(deps)` in
|
||||
`server.ts`.
|
||||
- **`server.ts`.** In `createApp(deps)`, an early `app.use("*", ...)` middleware (after the
|
||||
request-phase observer and the JSON body-parse tracker) puts each
|
||||
- **`server.ts`.** In `createApp(deps)`, the first `app.use("*", ...)` middleware puts each
|
||||
service on the request context (`c.set("<name>" as never, deps.<name>)`), serves `/healthz`, and
|
||||
mounts each router with `app.route("/api/<area>", ...)`. Unknown `/api/*` paths get a JSON 404;
|
||||
other GET requests serve the web UI's built files.
|
||||
@@ -79,8 +78,8 @@ and fails the build on a specifier with no `exports` entry. To share new daemon
|
||||
`seat-delivery-guard.ts`) and events (`event-bus.ts`). Larger areas have their own
|
||||
subdirectories, such as `gateway/`, `provider/`, `policies/`, `scope/`, `context-packs/` and
|
||||
`mission-control/`.
|
||||
- **`adapters/`.** The outside world. `tmux.ts` wraps tmux. The six `RuntimeAdapter`
|
||||
implementations (OMP's extends Pi's) launch each runtime and project skills and files into it. `cmux.ts` and
|
||||
- **`adapters/`.** The outside world. `tmux.ts` wraps tmux. The five `RuntimeAdapter`
|
||||
implementations launch each runtime and project skills and files into it. `cmux.ts` and
|
||||
`compose-services-adapter.ts` cover other integrations.
|
||||
- **`db/`.** `connection.ts`, `migrate.ts`, `all-migrations.ts` and `migrations/`.
|
||||
- **`middleware/auth-bearer-token.ts`.** The bearer-token check for operator write routes, plus
|
||||
@@ -113,19 +112,19 @@ that is already running keeps running the code it started with.
|
||||
|
||||
## Key counts
|
||||
|
||||
At commit `c750304f`. Run these from the repository root to refresh them.
|
||||
At commit `1347d825`. Run these from the repository root to refresh them.
|
||||
|
||||
| What | Count | Command |
|
||||
|---|---|---|
|
||||
| Database migrations | 94 files (latest: `095_rig_non_interruptive.ts`; there is no 093) | `git ls-files packages/daemon/src/db/migrations \| wc -l` |
|
||||
| Database migrations | 89 (latest: `089_classification_identity_provenance.ts`) | `git ls-files packages/daemon/src/db/migrations \| wc -l` |
|
||||
| Files in `routes/` | 67 | `git ls-files packages/daemon/src/routes \| wc -l` |
|
||||
| ... of which create a Hono router | 65 | `git grep -l 'new Hono' -- packages/daemon/src/routes \| wc -l` |
|
||||
| `app.route(...)` mounts in `server.ts` | 69 | `grep -c 'app.route(' packages/daemon/src/server.ts` |
|
||||
| Top-level `rig` commands | 87 | `grep -c 'program.addCommand(' packages/cli/src/index.ts` |
|
||||
| Runtime adapters | 6 (`claude-code`, `codex`, `pi`, `omp`, `terminal`, `stub`); the command counts 5 because `OmpRuntimeAdapter` extends `PiRuntimeAdapter` | `git grep -l 'implements RuntimeAdapter' packages/daemon/src \| wc -l` |
|
||||
| Top-level `rig` commands | 85 | `grep -c 'program.addCommand(' packages/cli/src/index.ts` |
|
||||
| Runtime adapters | 5 (`claude-code`, `codex`, `pi`, `terminal`, `stub`) | `git grep -l 'implements RuntimeAdapter' packages/daemon/src \| wc -l` |
|
||||
| MCP tools | 18 | `grep -c 'server.tool(' packages/cli/src/mcp-server.ts` |
|
||||
| Daemon `exports` subpaths | 21 | `node -p 'Object.keys(require("./packages/daemon/package.json").exports).length'` |
|
||||
| Library scenarios | 15 | `grep -l '^scenario:' packages/test-system/scenarios/*.yaml \| wc -l` |
|
||||
| Daemon `exports` subpaths | 18 | `node -p 'Object.keys(require("./packages/daemon/package.json").exports).length'` |
|
||||
| Library scenarios | 11 | `grep -l '^scenario:' packages/test-system/scenarios/*.yaml \| wc -l` |
|
||||
|
||||
## Where to add things
|
||||
|
||||
@@ -169,7 +168,7 @@ the authority.
|
||||
1. Create `packages/daemon/src/db/migrations/<NNN>_<name>.ts` exporting a `Migration`
|
||||
(`{ name: "<NNN>_<name>.sql", sql: "..." }`; the type is in `packages/daemon/src/db/migrate.ts`).
|
||||
`089_classification_identity_provenance.ts` is a one-line example.
|
||||
2. Take the next number after the highest on `main` (095 at this commit). Parallel pull requests
|
||||
2. Take the next number after the highest on `main` (089 at this commit). Parallel pull requests
|
||||
often pick the same number, so check again and renumber if `main` moved before you merge.
|
||||
3. Import it in `packages/daemon/src/db/all-migrations.ts` and append it to `ALL_MIGRATIONS`.
|
||||
Startup runs exactly that list (`startup-migrations-mirror.test.ts` pins this).
|
||||
@@ -211,16 +210,17 @@ Skills ship from three copies in this repository (the "edges"), listed in
|
||||
Each skill in the layout file lists which edges carry it. At this commit, 33 skills are in `spec`
|
||||
and `canonical`, 17 only in `plugin`, and 2 in all three.
|
||||
|
||||
- Each skill has one editable home: its `spec` copy when it has a `spec` edge, otherwise its
|
||||
`plugin` copy. Its other edges are generated from that home.
|
||||
- `npm run mirror-skills:check` (part of `npm test`) hashes every file in each edge and compares the
|
||||
hashes with `scripts/skill-edge-digests.generated.json`. It also fails on a `SKILL.md` the layout
|
||||
does not list, on a generated copy that differs from its home, and on a home holding text the
|
||||
public copies would drop.
|
||||
- The full apply, `npm run mirror-skills`, regenerates every generated copy from its home and
|
||||
refreshes the digests. It reads nothing outside the repository and never writes to a home.
|
||||
- **To fix a skill:** edit its home, run `npm run mirror-skills`, then run
|
||||
`npm run mirror-skills:check`.
|
||||
does not list.
|
||||
- The full apply, `npm run mirror-skills`, regenerates all three edges from the maintainers' skill
|
||||
source, which lives outside this repository. It needs `OPENRIG_SKILL_CANON_ROOT` and three
|
||||
authority-file environment variables, so an outside contributor cannot run it.
|
||||
- **To fix a skill:** edit the file in every edge that carries it (same bytes), run
|
||||
`node scripts/regen-edge-digests.mjs` to refresh the hashes from disk, then run
|
||||
`npm run mirror-skills:check`. Say in the pull request that you edited mirrored skill files: the
|
||||
next full apply regenerates these copies from the maintainers' source, so the change has to land
|
||||
there too.
|
||||
- **To add a skill:** open an issue first. Its layout entry is generated from files that are not
|
||||
in this repository.
|
||||
- Every shipped skill also becomes a context pack at package time (next recipe).
|
||||
@@ -267,13 +267,11 @@ and no model cost.
|
||||
inside tmux, including an agent's pane. It supplies no fault controller, so a
|
||||
`seed_regression` step fails there; the seeded pair runs in the container path.
|
||||
6. **CI.** The `installed-scenario` job runs `scripts/run-pr-scenarios.sh` in disposable,
|
||||
network-less containers built from the packed package. It runs four cases: `fixture` and `library`
|
||||
(`queue-baton-survives-restart.yaml`), each with a healthy run and a seeded lost-baton run, plus
|
||||
`transcript` and `capture`, healthy runs only. Adding a seeded case means changing three files:
|
||||
the `--case` list in `scripts/run-pr-scenarios.sh`, `CASES` in
|
||||
network-less containers built from the packed package. It runs two cases, both built around
|
||||
queue durability (`library` is `queue-baton-survives-restart.yaml`). Adding a case today means
|
||||
changing three files: the `--case` list in `scripts/run-pr-scenarios.sh`, `CASES` in
|
||||
`packages/test-system/ci/result.mjs`, and the fault controller in
|
||||
`packages/test-system/ci/run.mjs`; a healthy-only case goes in `PASSING_CASES` in the first two
|
||||
and needs no fault controller. [docs/as-built/test-layers.md](docs/as-built/test-layers.md)
|
||||
`packages/test-system/ci/run.mjs`. [docs/as-built/test-layers.md](docs/as-built/test-layers.md)
|
||||
covers both run modes, running a case on your own Docker host, and what a stub can and cannot
|
||||
prove.
|
||||
|
||||
@@ -290,10 +288,9 @@ packages.
|
||||
package, and the daemon copies its Markdown files to `$OPENRIG_HOME/reference/` when it
|
||||
starts. Files in `docs/as-built/` carry a `last-verified-against-source` commit in their
|
||||
frontmatter.
|
||||
- **Internal-leak guard** (`scripts/internal-leak-scanner.mjs`). Its term lists come from an
|
||||
optional local file that `OPENRIG_LEAK_GUARD_RULES` names (`scripts/leak-guard-rules.mjs`);
|
||||
without one the term checks are skipped and every other check runs, and the release-time
|
||||
substance gate requires it. It runs in `generate-context-packs.mjs` (static pack sources, on every
|
||||
- **Internal-leak guard** (`scripts/internal-leak-scanner.mjs`, with rules in
|
||||
`scripts/internal-tokens.generated.json`). It refuses maintainer-internal names and paths in
|
||||
content that ships. It runs in `generate-context-packs.mjs` (static pack sources, on every
|
||||
`npm test`), in the full skill mirror apply (each public skill), in `scripts/build-package.sh`
|
||||
(the daemon `specs/` tree before it is copied into the package), and in the release-time
|
||||
substance gate (`scripts/check-substance-gate.mjs`, `npm run gate:substance`) over the packed
|
||||
@@ -303,12 +300,8 @@ packages.
|
||||
machine-specific values: credentials, home and temporary paths, network addresses, email
|
||||
addresses. It never fails the job; you read it and decide.
|
||||
- **Generated files.** Do not hand-edit `scripts/*.generated.json` or anything under
|
||||
`packages/daemon/context-packs/`. The skill-edge digests are refreshed by
|
||||
`npm run mirror-skills` (see "A shipped skill").
|
||||
The internal-token rules support optional `allowed_context_lines` for reviewed generic
|
||||
examples: the complete line must match exactly, including indentation and case. Unlike
|
||||
`allowed_context_substrings`, this does not exempt a line with added or substituted text;
|
||||
internal-path checks and the substance gate's human-review dispositions still apply.
|
||||
`packages/daemon/context-packs/`. The skill-edge digests are the one generated file a contributor
|
||||
refreshes, with `node scripts/regen-edge-digests.mjs` (see "A shipped skill").
|
||||
- **Hosted CI** (`.github/workflows/tests.yml`): `build-and-package`, `typecheck`, `repo-checks`,
|
||||
`package-tests` (macOS; daemon, CLI, TUI and UI suites with no credentials and no external
|
||||
network) and `installed-scenario`.
|
||||
@@ -317,14 +310,15 @@ packages.
|
||||
|
||||
- [CONTRIBUTING.md](CONTRIBUTING.md): setup, what a pull request needs, what to expect from review.
|
||||
- [docs/reference/developing.md](docs/reference/developing.md): which checks block and which are
|
||||
advisory, and what `.github/workflows/tests.yml` runs.
|
||||
advisory. It predates the hosted Tests workflow; `.github/workflows/tests.yml` is current.
|
||||
- [docs/reference/worktree-builds.md](docs/reference/worktree-builds.md): building in a git
|
||||
worktree, with its own `npm ci` rather than a symlinked `node_modules`.
|
||||
worktree, with its own `npm install` rather than a symlinked `node_modules`.
|
||||
- [docs/reference/](docs/reference/): user and operator reference; it ships with the package.
|
||||
- [docs/as-built/](docs/as-built/README.md): module-by-module descriptions of the system. **These
|
||||
are being re-verified for 0.6.6.** Each page's `last-verified-against-source` names the commit it was
|
||||
checked against; until a page is re-verified, treat its counts as historical. Use them for
|
||||
orientation, then check the code.
|
||||
are being re-verified.** Most modules were last verified against `7eaf524c` (2026-05-16, around
|
||||
v0.3.1); the two pages this change adds, `arteries.md` and `test-layers.md`, are verified against
|
||||
`1347d825`. The older modules' counts are historical: `architecture/daemon-core.md`
|
||||
describes 40 migrations, and there are 89 today. Use them for orientation, then check the code.
|
||||
- [docs/as-built/test-layers.md](docs/as-built/test-layers.md): what each test layer covers and
|
||||
what it cannot catch.
|
||||
- [docs/as-built/arteries.md](docs/as-built/arteries.md): the areas where a small change has a
|
||||
|
||||
-3748
File diff suppressed because it is too large.
Load diff
+15
-26
@@ -8,12 +8,12 @@ change in with the least friction on both sides.
|
||||
## Before you start
|
||||
|
||||
- **Bugs:** open an issue with the bug template. Include your OpenRig version (`rig --version`),
|
||||
OS, Node and tmux versions, which harnesses are involved (or none), and the relevant command and output.
|
||||
OS, Node version, which harnesses are involved (or none), and the relevant command and output.
|
||||
Reports are public: remove credentials, private prompts, personal details and private paths
|
||||
before posting. Share a small reproduction rather than a full transcript or instance dump.
|
||||
- **Features and behaviour changes:** open an issue or a Discussion in *Ideas* first. Search issues
|
||||
and Discussions, and check ROADMAP.md, before proposing a feature. A short "what I am trying to do
|
||||
and what stops me" saves both of us a rewrite. Small, obvious fixes do not need an issue.
|
||||
- **Features and behaviour changes:** open an issue or a Discussion in *Ideas* first. A short
|
||||
"what I am trying to do and what stops me" saves both of us a rewrite. Small, obvious fixes do
|
||||
not need an issue.
|
||||
- **Questions:** use [Discussions › Q&A](https://github.com/mvschwarz/openrig/discussions/categories/q-a),
|
||||
not an issue.
|
||||
|
||||
@@ -40,11 +40,7 @@ repository, and we're happy to link to it.
|
||||
|
||||
## Setting up
|
||||
|
||||
Node `^22 || ^24`, a working `tmux` and `rsync` are required. macOS includes `rsync`; many Linux
|
||||
installs don't (`sudo apt-get install rsync` on Debian or Ubuntu). `npm test` and `npm run mirror-skills`
|
||||
use it. Use the npm that comes with your Node, which is npm 10 or newer (`npm --version` shows which you
|
||||
have). A separately packaged npm 9, such as Debian or Ubuntu's `npm` package, fails a fresh `npm ci` with
|
||||
`ENOENT` on `chmod` of `node_modules/@openrig/tui/dist/main.js`. Then:
|
||||
Node `^22 || ^24` and a working `tmux` are required. Then:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/mvschwarz/openrig.git
|
||||
@@ -60,19 +56,13 @@ runs too. Use `npm install <package>` only when you're adding or changing a depe
|
||||
the lockfile change with it.
|
||||
|
||||
`npm test` builds the daemon and runs repository checks before the package suites. Read the
|
||||
specific failure. Each shipped skill has one editable home in this repository (see
|
||||
["A shipped skill" in ARCHITECTURE.md](ARCHITECTURE.md#a-shipped-skill)). Edit its home, run
|
||||
`npm run mirror-skills` to regenerate its other copies and refresh the digests, then run
|
||||
`npm run mirror-skills:check` and commit the result. The apply reads nothing outside the repository.
|
||||
The repository checks include a docs guard: a
|
||||
tracked file under `docs/` must be in `docs/as-built/`, `docs/reference/` or `docs/releases/`
|
||||
(`docs/DESIGN.md` is the one exception). They check that shipped first-run text names only teams, skills and
|
||||
commands that exist, and they validate the context-pack sources;
|
||||
`npm run generate-context-packs` rebuilds the generated packs locally, which aren't committed.
|
||||
The UI unit-test suite is separate from `npm test`: run `npm run test:ui`. CI runs it on every pull
|
||||
request as `package-tests (ui)`, so a change has to pass it.
|
||||
[docs/as-built/test-layers.md](docs/as-built/test-layers.md) lists every test layer, what CI runs,
|
||||
and what each layer can and cannot prove.
|
||||
specific failure. A shipped skill may exist in more than one copy (see ARCHITECTURE.md): edit every copy, then run
|
||||
`node scripts/regen-edge-digests.mjs` (the full `npm run mirror-skills` apply needs maintainer-only
|
||||
inputs; see "A shipped skill" in [ARCHITECTURE.md](ARCHITECTURE.md#a-shipped-skill)).
|
||||
`npm run generate-context-packs` updates generated packs. Review the generated diff; neither
|
||||
fixes every documentation failure. The UI unit-test suite is advisory and separate:
|
||||
`npm run test:ui`. [docs/as-built/test-layers.md](docs/as-built/test-layers.md) lists every test
|
||||
layer, what CI runs, and what each layer can and cannot prove.
|
||||
|
||||
For hands-on development, read the [check requirements](docs/reference/developing.md),
|
||||
[worktree setup](docs/reference/worktree-builds.md), and
|
||||
@@ -94,7 +84,7 @@ your working copy.
|
||||
- Do not bump versions.
|
||||
- Match the surrounding style. `npm run lint` typechecks; it does not format code.
|
||||
- Write commit messages in the form the log already uses: `fix(cli): …`, `feat(daemon): …`,
|
||||
`docs(reference): …`, `test: …`.
|
||||
`docs(reference): …`, `harness: …`.
|
||||
|
||||
## The pull request
|
||||
|
||||
@@ -128,8 +118,7 @@ clarifying question or run the reproduction; a maintainer makes the merge decisi
|
||||
when they work in this checkout (`.claude/skills/` and `.agents/skills/`). It points at the maps
|
||||
above and at what to run before you push.
|
||||
- Repository reference: `docs/reference/`; user documentation: [openrig.dev/docs](https://openrig.dev/docs).
|
||||
- Skills: `packages/daemon/specs/agents/shared/skills/`, plugin skills under
|
||||
`packages/daemon/assets/plugins/`, and `skills/_canonical/`; static context-pack sources:
|
||||
`packages/daemon/context-packs-src/`.
|
||||
- Skills: `packages/daemon/specs/agents/shared/skills/` and plugin skills under
|
||||
`packages/daemon/assets/plugins/`; static context-pack sources: `packages/daemon/context-packs-src/`.
|
||||
Generated packs live in `packages/daemon/context-packs/` and are not hand-edited or committed.
|
||||
- Releases: [GitHub Releases](https://github.com/mvschwarz/openrig/releases) and npm `@openrig/cli`.
|
||||
@@ -8,76 +8,19 @@ OpenRig is open-source software for building and running your own network of age
|
||||
|
||||
It's the open-source system behind my AI civilization experiments.
|
||||
|
||||
**Guide:** [Getting started](docs/reference/quickstart.md) · **Stuck?** [Help](docs/reference/help.md) · **Questions:** [Q&A](https://github.com/mvschwarz/openrig/discussions/92) · **Updates and demos:** [@_feralmachine on X](https://x.com/_feralmachine)
|
||||
**Guide:** [Getting started](docs/reference/getting-started.md) · **Stuck?** [Help](docs/reference/help.md) · **Questions:** [Q&A](https://github.com/mvschwarz/openrig/discussions/92) · **Updates and demos:** [@_feralmachine on X](https://x.com/_feralmachine)
|
||||
|
||||
## See it running
|
||||
|
||||
|
||||
|
||||
**Start here:** [the guided first-use path](docs/reference/quickstart.md): install, talk to the kernel operator, then choose a team for your first useful change.
|
||||
**Start here:** [the guided first-use path](docs/reference/getting-started.md): install, launch a two-agent team in your repository, and get one reviewed change.
|
||||
|
||||
Not setting this up today? Get the next walkthrough and occasional OpenRig updates → https://openrig.dev/follow
|
||||
|
||||
## Install and first run
|
||||
|
||||
**Let your coding agent set it up.** First check that `node --version` shows 22 or 24: the command below needs
|
||||
Node.js and the `npx` that comes with it. Then, in your project folder, add OpenRig's `rigs` skill to the agent you
|
||||
use:
|
||||
|
||||
```sh
|
||||
# Claude Code
|
||||
npx skills add https://github.com/mvschwarz/openrig/tree/v0.7.4/skills/rigs --skill rigs --agent claude-code
|
||||
# Codex
|
||||
npx skills add https://github.com/mvschwarz/openrig/tree/v0.7.4/skills/rigs --skill rigs --agent codex
|
||||
```
|
||||
|
||||
Then type `/rigs` in Claude Code, or `$rigs` in Codex, and say what you want built. The skill has your agent tell
|
||||
you what it will run and change before it does, install OpenRig, open the OpenRig view and pass your goal to
|
||||
OpenRig's operator.
|
||||
|
||||
You need Node.js 22 or 24 (22 on Apple silicon), tmux, macOS or Linux (WSL2 on Windows), and Claude Code or Codex
|
||||
signed in. One provider is enough to start.
|
||||
|
||||
Already have OpenRig? Use the tag that matches `rig --version`, or upgrade first.
|
||||
|
||||
Prefer to type the commands yourself? [Install it yourself ↓](#install-it-yourself)
|
||||
|
||||
Requires Node.js 22 or 24 and tmux, on macOS or Linux, and one working Claude Code or Codex account: one is enough, since the kernel operator adapts the shipped `starter` team to whichever you have. On Linux, the distribution's own Node.js can be older (Ubuntu 24.04's is 18); install a supported version with [nvm](https://github.com/nvm-sh/nvm) (`nvm install 22`) or NodeSource. On a Mac with Apple silicon, use Node.js 22 ([compatibility history](docs/releases/v0.5.15.md#known-compatibility-limitation)). On a Mac where you aren't an administrator, or where Homebrew belongs to another account (its `brew install` is refused), install Node.js in your own home folder with [nvm](https://github.com/nvm-sh/nvm): run `touch ~/.zshrc` (a new Mac account has none, and nvm's installer only adds itself to a profile file that already exists), then nvm's install command, for nvm v0.40.8 `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash` ([nvm's page](https://github.com/nvm-sh/nvm#install--update-script) has the newest), open a new terminal, and run `nvm install 22`. nvm itself needs no administrator password, and `npm install -g` then installs into your nvm folder. If nvm's installer says you need Apple's command line tools, run `xcode-select --install`, then its install command again. On Windows, use WSL2, the Windows route OpenRig supports; native Windows isn't supported. OpenRig's automated tests don't run on WSL2 yet; see [one user's working setup](docs/reference/getting-started.md#wsl2-a-reported-working-setup).
|
||||
|
||||
> **What OpenRig changes on your machine**
|
||||
> - **Install:** `@openrig/cli` goes in globally with npm.
|
||||
> - **Setup:** `rig setup` adds an OpenRig block to `~/.tmux.conf`. It can install tmux (with Homebrew on macOS), and
|
||||
> Herdr unless you pass `--no-herdr`. Plain `rig setup`, which is what the one-command install runs, checks both
|
||||
> Claude Code and Codex and may install a missing one; `rig setup --providers claude` (or `codex`) limits it to
|
||||
> yours.
|
||||
> - **Starting OpenRig, for the coding agent you use** (paths are the usual defaults):
|
||||
> - Codex: hooks and trust in `~/.codex/config.toml`.
|
||||
> - Claude Code: workspace trust in `~/.claude.json`, and activity hooks in the project's
|
||||
> `.claude/settings.local.json`, plus a status line unless you already have your own.
|
||||
> - Discovery skills go in `~/.claude/skills` and `~/.agents/skills`.
|
||||
> - **Starting a team in your project:** adds managed guidance to `AGENTS.md` or `CLAUDE.md`, plus the team's skills
|
||||
> and plugins.
|
||||
> - **Permissions:** by default, OpenRig's own kernel gets broader permissions than a project team gets by default.
|
||||
> On Codex that's full access with no approval prompts (`-s danger-full-access -a never`). On Claude Code, its file
|
||||
> tools, web fetches and operational commands, including reads under your home folder, run without asking. A
|
||||
> permission policy, per-agent choice or Codex profile changes that. What your team can do depends on the team you
|
||||
> choose and your settings; `workshop`, for example, ships with broad access.
|
||||
> - **Backups:** OpenRig doesn't guarantee it can preserve or roll back these files, so back them up first.
|
||||
>
|
||||
> [Everything OpenRig writes, and why →](https://github.com/mvschwarz/openrig#what-openrig-changes-on-your-machine)
|
||||
|
||||
### Install it yourself
|
||||
|
||||
This runs OpenRig's install script from the `v0.7.4` release. It checks Node.js and npm, installs the latest published `@openrig/cli` with `npm install -g`, runs the Node.js and SQLite check, then runs `rig setup --dry-run` and `rig setup`. The first line prints that plan and changes nothing:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.7.4/scripts/install.sh | sh -s -- --dry-run
|
||||
curl -fsSL https://raw.githubusercontent.com/mvschwarz/openrig/v0.7.4/scripts/install.sh | sh
|
||||
```
|
||||
|
||||
If a provider isn't signed in yet, the last step reports `FAILED [4/4]`, and `rig setup` lists the sign-in under "Some steps need attention". If the only remaining failures are provider sign-ins, the install steps finished; sign in to each selected provider as below and continue.
|
||||
|
||||
**Or step by step:**
|
||||
Requires Node.js 22 or 24 and tmux, on macOS or Linux. On a Mac with Apple silicon, use Node.js 22 ([compatibility history](docs/releases/v0.5.15.md#known-compatibility-limitation)). Native Windows is not supported yet, and WSL2 has not been tested. Launching a rig writes provider hooks and workspace trust settings. Before running the commands below, read [what OpenRig changes on your machine](#what-openrig-changes-on-your-machine) and back up the relevant files.
|
||||
|
||||
```bash
|
||||
npm install -g @openrig/cli
|
||||
@@ -86,103 +29,46 @@ rig setup --dry-run
|
||||
|
||||
To install with Bun instead, run `bun add -g @openrig/cli`. OpenRig still runs on Node.js, so install Node.js 22 as well. Bun may block this package's postinstall script, in which case the Node.js and SQLite check described under [what OpenRig changes on your machine](#what-openrig-changes-on-your-machine) does not run at install time.
|
||||
|
||||
npm 11 and later can skip that postinstall script and print `npm warn install-scripts` naming `@openrig/cli`. That's expected: the CLI still works, and only the Node.js and SQLite check was skipped. To run it yourself, use `node "$(npm root -g)/@openrig/cli/scripts/check-abi.mjs"`; `rig doctor` checks the Node.js version only.
|
||||
Choose the working account you already have: **Claude Code, Codex, or both**. Reuse an explicit choice; no second subscription is required. `rig setup --dry-run` previews the broader setup, but applying `rig setup` checks both harnesses and cmux. It is optional for the [selected-provider path](docs/reference/getting-started.md#choose-your-providers).
|
||||
|
||||
Choose the working account you already have: **Claude Code, Codex, or both**. Reuse an explicit choice; no second subscription is required. `rig setup --dry-run` previews the broader setup; applying `rig setup` checks both harnesses and installs a missing one, plus Herdr unless declined with `--no-herdr`. Pass the choice with `--providers claude` or `--providers codex` so the other reads not selected instead of failed. The one-command install above doesn't know the choice, so it installs and checks both; for one provider, go step by step and run `rig setup --providers <choice>`. On macOS, the installing agent offers Ghostty once. Setup leaves an existing cmux installation alone. It is optional for the [selected-provider path](docs/reference/getting-started.md#choose-your-providers).
|
||||
|
||||
A team seat with no permission policy, per-seat choice or (for Codex) named profile launches with OpenRig's [team default](docs/reference/rig-spec.md#team-launch-defaults): Claude runs ordinary `rig` commands, project reads and common tests without prompting, while lifecycle commands such as `rig up` and `rig down` still ask; Codex also gets the OpenRig workspace and its pod's state directory as writable directories. Before launching, your agent recommends keeping that default, and offers to remember selected OpenRig commands in your native settings only if you want that, at personal project scope unless you explicitly choose user-wide sessions. It is not global YOLO or permission to invent work. On Yes, the agent [adds and verifies native rules](docs/reference/getting-started.md#have-your-agent-configure-permissions); No or no answer keeps the team default and leaves settings unchanged. An existing explicit choice is reused. Say “Undo the OpenRig command allowances added by this setup” to remove only its additions.
|
||||
|
||||
If permission prompts are slowing you down, consider the
|
||||
[workshop bundle](https://openrig.dev/rigs/workshop). It ships with broad access
|
||||
and [non-interruptive mode](docs/reference/non-interruptive-mode.md): its agents
|
||||
bypass permission prompts and supported harness warning dialogs. The listing
|
||||
and before-install view explain that access before you choose it.
|
||||
Before launching, your agent asks once: **“Allow your agents to run OpenRig commands without repeated permission prompts?” Yes — recommended / No — keep prompts.** This covers every `rig` command, including starting/stopping agents and configuration, at personal project scope unless you explicitly choose user-wide sessions. It is not global YOLO or permission to invent work. On Yes, the agent [adds and verifies native rules](docs/reference/getting-started.md#have-your-agent-configure-permissions); No or no answer leaves settings unchanged. An existing explicit choice is reused. Say “Undo the OpenRig command allowances added by this setup” to remove only its additions.
|
||||
|
||||
Check `tmux -V` and only your selected CLI/login: `claude --version` plus
|
||||
`claude auth status`, or `codex --version` plus `codex login status`. If needed,
|
||||
sign in once with `claude auth login` or `codex login`; do not install or log in
|
||||
to an unused provider.
|
||||
|
||||
### Your agent opens OpenRig for you
|
||||
|
||||
After installing, your agent opens the OpenRig TUI and the operator for you. To get back to them later, ask your
|
||||
agent for OpenRig or your agents in any words. After checking the selected login, it starts the daemon if it's stopped
|
||||
and opens the view:
|
||||
|
||||
```sh
|
||||
rig daemon start
|
||||
rig terminal open saved:kernel --window
|
||||
```
|
||||
|
||||
`--window` opens a new terminal tab or window itself, or a space in your current
|
||||
Herdr session. Below 120 measured columns,
|
||||
the **operator** fills the first page; from 120, the dashboard and operator share
|
||||
it equally. The advisor has a separate tab or tmux window.
|
||||
An installing agent can run it from its shell on the daemon's
|
||||
desktop; the person copies nothing. It uses Herdr when installed, otherwise
|
||||
the same layout in plain tmux, and preserves existing conversations. `rig tui`
|
||||
is the team dashboard. Installation is finished when you are talking to the
|
||||
operator; if you choose to talk later, that handoff remains pending.
|
||||
|
||||
If setup stops, read the named step: missing tools and selected-provider logins
|
||||
need their specific setup action. A harness permission rule, sandbox or automatic
|
||||
permission decision can also block the installing agent's command. The agent
|
||||
should name the command and reported reason, then help you resolve that specific
|
||||
step within your chosen permissions. A permission refusal is not an OpenRig
|
||||
installation result.
|
||||
|
||||
The desktop may need an Automation approval; SSH/headless sessions may have no
|
||||
display. Herdr can show first-run panels, and an 80×24 window can cramp the view.
|
||||
Follow [the OpenRig view checks and next steps](docs/reference/getting-started.md#what-can-interrupt-installation-and-the-openrig-view).
|
||||
Herdr is visible only inside a terminal you can see. Changing the shared TUI to
|
||||
`:terminals` does not open that terminal. The agent checks the visible window when
|
||||
it has desktop access and says what it could not verify otherwise. Over headless
|
||||
SSH, it asks you to open a new terminal window or tab and gives the exact connection
|
||||
and attachment command for the current view. If you choose a manual attachment
|
||||
after a failure,
|
||||
ask the installing agent for the exact command using your current operator
|
||||
session; run that in a new terminal window.
|
||||
|
||||
The kernel's operator helps you pick a first team. It asks what you want to build,
|
||||
recommends one of three, and fits it to the providers you have.
|
||||
|
||||
| Team | Talk to | Agents and purpose |
|
||||
| Team | Starter | Models |
|
||||
| --- | --- | --- |
|
||||
| `starter` | `dev-build@starter` | A Claude Code builder and Codex reviewer for one bounded change |
|
||||
| `workshop` | `orch-lead@workshop` | A lead, builder, QA and reviewer for ongoing work in one repository; a rig bundle the operator installs from its pinned listing |
|
||||
| `factory` | `orch-lead@factory` | Seven: a lead, advisor, build, QA, design and two independent reviewers for sustained product work |
|
||||
| Two Codex agents | `first-project` | Both `gpt-6-astra` (unchanged) |
|
||||
| Two Claude agents | `first-project-claude` | Configured native Claude default |
|
||||
| Claude owner + Codex checker | `first-project-mixed` | Claude default + `gpt-6-astra` |
|
||||
|
||||
As shipped, `starter` uses both Claude Code and Codex. With only one of them, ask
|
||||
the kernel operator to adapt it: it writes a copy of the team for your providers
|
||||
under the same name. [The naming guide](docs/reference/topology-naming.md) explains
|
||||
how their pods and roles grow and how to name your own team. `first-project` is
|
||||
starter's old name and still starts it,
|
||||
unless you already have a rig named `first-project` or `starter`: then it refuses
|
||||
and names the `rig up <name> --existing` command that brings that rig back.
|
||||
Show the selected runtime, configured model and command before launch; confirm the
|
||||
account supports the model instead of silently falling back. The kernel starts
|
||||
automatically and selects from available authenticated providers independently of
|
||||
these teams. A missing unused provider is not a setup requirement.
|
||||
|
||||
To launch the starter yourself instead (the manual path, without the operator):
|
||||
All three use the same owner/checker roles and task. Show the selected runtime,
|
||||
configured model and command before launch; confirm the account supports the
|
||||
model instead of silently falling back. The kernel starts automatically and
|
||||
selects from available authenticated providers independently of these two project
|
||||
agents. A missing unused provider is not a setup requirement.
|
||||
|
||||
```bash
|
||||
cd /path/to/your/repository
|
||||
rig specs preview starter --kind rig
|
||||
rig up starter --cwd . --plan
|
||||
rig up starter --cwd .
|
||||
starter=first-project # or first-project-claude or first-project-mixed
|
||||
rig specs preview "$starter" --kind rig
|
||||
rig up "$starter" --cwd . --plan
|
||||
rig up "$starter" --cwd .
|
||||
rig tui --shared
|
||||
```
|
||||
|
||||
To see your agents, use `rig terminal open saved:kernel --window`. If that window cannot open, `rig tui --shared` is the named dashboard-only fallback; it does not show the operator conversation. The installing agent should resolve or explain the window failure, not finish by suggesting a command for you to type. Closing a viewing terminal does not mean you should relaunch the team.
|
||||
The kernel provides separate operational support and the shared dashboard. To detach without stopping the dashboard, press Ctrl-b then d; `rig tui --shared` returns to that view. Plain `rig tui` opens an independent view. Closing a viewing terminal does not mean you should relaunch the team.
|
||||
|
||||
Check project-seat readiness with `rig ps --nodes --rig starter` and resolve any authentication, trust or permission prompt before assigning work. If a seat stopped at such a prompt before its startup context arrived, `rig ps` shows the `rig seat continue <seat>` command that delivers it once the prompt is answered. Then give the builder one bounded outcome from your repository:
|
||||
Check project-seat readiness with `rig ps --nodes --rig "$starter"` and resolve any authentication, trust or permission prompt before assigning work. Then give the owner one bounded outcome from your repository:
|
||||
|
||||
```bash
|
||||
rig send dev-build@starter 'Implement <one useful change>. Track the task in the queue and return its ID. Keep it local, verify the behavior, ask dev-review in this rig to check the exact candidate, and record the result and how I can try it.'
|
||||
rig queue list --destination dev-build@starter --limit 1000
|
||||
rig send "dev-owner@$starter" 'Implement <one useful change>. Track the task in the queue and return its ID. Keep it local, verify the behavior, ask dev-check in this rig to check the exact candidate, and record the result and how I can try it.'
|
||||
rig queue list --destination "dev-owner@$starter" --limit 1000
|
||||
```
|
||||
|
||||
Sending a message does not itself create a queue item; the builder records the task. Read the final artifact and the review of its exact candidate, then return to the same builder for the next change. [The guided first-use path](docs/reference/getting-started.md) covers readiness, a useful task, a reviewed result, Herdr/cmux terminals and recovery.
|
||||
Sending a message does not itself create a queue item; the owner records the task. Read the final artifact and the review of its exact candidate, then return to the same owner for the next change. [The guided first-use path](docs/reference/getting-started.md) covers readiness, a useful task, a reviewed result, Herdr/cmux terminals and recovery.
|
||||
|
||||
Not setting this up today? Get the next walkthrough and occasional OpenRig updates → https://openrig.dev/follow
|
||||
|
||||
@@ -191,7 +77,6 @@ Not setting this up today? Get the next walkthrough and occasional OpenRig updat
|
||||
- **Questions:** [Discussions › Q&A](https://github.com/mvschwarz/openrig/discussions/categories/q-a)
|
||||
- **Bugs and feature requests:** [open an issue](https://github.com/mvschwarz/openrig/issues/new/choose)
|
||||
- **Contributing:** [CONTRIBUTING.md](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md) · [Security policy](SECURITY.md) · [Getting help](.github/SUPPORT.md)
|
||||
- **Working on OpenRig with a coding agent?** Start with the `developing-openrig` skill in `.agents/skills/` (Claude Code: `.claude/skills/`) and [CONTRIBUTING.md](CONTRIBUTING.md).
|
||||
- **Videos:** [youtube.com/@openrig](https://www.youtube.com/@openrig)
|
||||
- **Releases:** [GitHub Releases](https://github.com/mvschwarz/openrig/releases) and npm `@openrig/cli`
|
||||
|
||||
@@ -206,12 +91,11 @@ using a published package, since repository guidance can be ahead of npm.
|
||||
|
||||
| When | What changes and why |
|
||||
| --- | --- |
|
||||
| **npm installation** | Installs the CLI (`rig` and `openrig-tui`), bundled components and dependencies under your npm prefix (with Bun, under Bun's global directory). OpenRig's postinstall checks the Node.js version and that the SQLite module loads; Bun may block this script. It does not run daemon or provider setup. |
|
||||
| **`rig setup`** | Attempts missing tools and writes an OpenRig block in `~/.tmux.conf` for mouse support and scrollback. Installs herdr by default on macOS and Linux unless declined with `--no-herdr`; an unavailable herdr install is a warning. On macOS the installing agent offers Ghostty, and `--ghostty` attempts it after acceptance. Existing cmux settings are left unchanged. `--full` adds workstation tools. `--dry-run` shows setup's plan without applying it. |
|
||||
| **Daemon startup** | Creates/updates instance state under `OPENRIG_HOME` (normally `~/.openrig`), including its database and managed plugin resources. Seeds the `openrig-skills` discovery skill, the `refocusing` skill and the person-facing `rigs` skill in `~/.claude/skills` and `~/.agents/skills`, subject to existing version ownership. When a Codex seat is already recorded and `runtime.codex.hooks_enabled` is enabled (the default), ensures its hook configuration and trust records as described below. With no recorded Codex seat, enabled hooks wait for its first launch; disabled hooks still remove a stale OpenRig-managed hook block, if present. |
|
||||
| **Rig/seat launch and attachment** | Creates tmux sessions, supplies seat identity and daemon connection environment, and projects selected guidance, skills, plugins and runtime resources into the workspace. Managed startup pre-trusts the workspace. Claude context collection can also be provisioned for attached sessions and refreshed during monitoring. In a Git repository, newly created files under `.codex/plugins/shared:openrig-core/` (or the unqualified `.codex/plugins/openrig-core/`) are added to the repository's Git `info/exclude` inside an `# BEGIN OpenRig generated files` block; new `AGENTS.md`, `CLAUDE.md` and `CLAUDE.local.md` files stay visible with a warning. |
|
||||
| **Bundle install** (`rig bundle install`, or `rig up` with a `.rigbundle` or GitHub link) | Writes the bundle's files into the install target: `--target`, or the current directory for `rig up` and for a GitHub link. `rig bundle install` with a local archive needs `--target`. Routes its declared skills, plugins and context packs into your libraries. A GitHub link's archive is kept under `OPENRIG_HOME/bundle-imports/`, and installs are recorded in `OPENRIG_HOME/bundle-audit.jsonl`. A bundle that carries a project creates it under `workspace.projects_root` and records it, with the rig's association, in the workspace catalog. |
|
||||
| **Explicit permission configuration** | The built-in bootstrap does **not** add `rig` command allow rules to your settings files; a team seat with no permission policy, per-seat choice or (for Codex) named profile gets the per-launch [team default](docs/reference/rig-spec.md#team-launch-defaults) instead. Agent-guided setup recommends keeping it and requires your actual answer before the agent [adds remembered rules at your chosen scope](docs/reference/getting-started.md#have-your-agent-configure-permissions). No/no answer keeps the team default and preserves settings; existing choices and stricter rules remain relevant. Broader access is separate. |
|
||||
| **npm installation** | Installs the CLI, bundled components and dependencies under your npm prefix (with Bun, under Bun's global directory). OpenRig's postinstall checks the Node.js version and that the SQLite module loads; Bun may block this script. It does not run daemon or provider setup. |
|
||||
| **`rig setup`** | Attempts missing tools and writes an OpenRig block in `~/.tmux.conf` for mouse support and scrollback. On macOS it can install cmux and enable its automation socket control in `~/.config/cmux/settings.json`; cmux defaults `automation.socketControlMode` to `cmuxOnly`, which only accepts processes started inside cmux and so blocks OpenRig's control, so setup switches it to `automation`. `--full` adds workstation tools. `--dry-run` shows setup's plan without applying it. |
|
||||
| **Daemon startup** | Creates/updates instance state under `OPENRIG_HOME` (normally `~/.openrig`), including its database and managed plugin resources. Seeds the `openrig-skills` discovery skill in `~/.claude/skills` and `~/.agents/skills`, subject to existing version ownership. With `runtime.codex.hooks_enabled` enabled (the default), writes Codex hook configuration and trust records as described below—even before a rig launches. |
|
||||
| **Rig/seat launch and attachment** | Creates tmux sessions, supplies seat identity and daemon connection environment, and projects selected guidance, skills, plugins and runtime resources into the workspace. Managed startup pre-trusts the workspace. Claude context collection can also be provisioned for attached sessions and refreshed during monitoring. |
|
||||
| **Explicit permission configuration** | The built-in bootstrap does **not** add `rig` command allow rules. Agent-guided setup recommends Yes and requires your actual answer before the agent [adds rules at your chosen scope](docs/reference/getting-started.md#have-your-agent-configure-permissions). No/no answer preserves settings; existing choices and stricter rules remain relevant. Broader access is separate. |
|
||||
|
||||
The provider files are separate from instance state. Here `~` means the daemon
|
||||
user's home; changing `OPENRIG_HOME` alone does not isolate provider configuration.
|
||||
@@ -219,30 +103,20 @@ user's home; changing `OPENRIG_HOME` alone does not isolate provider configurati
|
||||
- **Claude Code:** startup writes workspace trust and onboarding completion.
|
||||
With an explicit permission mode, it uses the launch-selected `HOME/.claude.json`,
|
||||
or `<CLAUDE_CONFIG_DIR>/.claude.json` when that variable is set. Classic startup
|
||||
writes `HOME/.claude.json`, and also `<CLAUDE_CONFIG_DIR>/.claude.json` when the
|
||||
daemon has that variable set. In the workspace, `.claude/settings.local.json` receives
|
||||
retains the daemon's `~/.claude.json` path. In the workspace, `.claude/settings.local.json` receives
|
||||
the context collector's `statusLine` command and selected activity hooks;
|
||||
a user's own status-line command is preserved, so it can prevent collector
|
||||
installation. Selected settings resources can still replace overlapping keys.
|
||||
The collector script lives under `.openrig/`, and the activity-hook relay under
|
||||
the instance's `state/claude-activity-hooks/`. Selected settings/MCP resources can also
|
||||
change that settings file and `.mcp.json`. The shared settings resource enables
|
||||
Exa/Context7 MCP entries and leaves existing `permissions.defaultMode` and permission
|
||||
rules unchanged. Managed launch flags select the session mode. Selected MCP resources
|
||||
configure those external services. Built-in bootstrap
|
||||
helper scripts live under `.openrig/`. Selected settings/MCP resources can also
|
||||
change that settings file and `.mcp.json`. The shared settings resource sets
|
||||
`permissions.defaultMode` to `acceptEdits` and enables Exa/Context7 MCP entries;
|
||||
selected MCP resources configure those external services. Built-in bootstrap
|
||||
no longer writes a command allowlist to `~/.claude/settings.json` or removes
|
||||
older allowances. `CLAUDE_CONFIG_DIR` does not relocate the project-local writes.
|
||||
To keep your own status line alongside the collector, see
|
||||
[Custom Claude status line](docs/reference/claude-status-line.md).
|
||||
- **Codex:** writes the daemon's `CODEX_HOME/config.toml` (normally
|
||||
`~/.codex/config.toml`). With hooks enabled, daemon startup ensures the OpenRig
|
||||
activity relay commands and their trust hashes when a Codex seat is already
|
||||
recorded; otherwise the first Codex launch does so. With hooks disabled, startup
|
||||
can remove a stale OpenRig-managed hook block even without a Codex seat. Seat startup adds
|
||||
`~/.codex/config.toml`). Startup enables hooks, adds the OpenRig activity relay
|
||||
commands and pre-writes trust hashes for those commands. Seat startup adds
|
||||
`trust_level = "trusted"` for the workspace; selected config resources can
|
||||
add MCP settings. Managed launches pass `-c check_for_update_on_startup=false`,
|
||||
which writes no config; a recognized update notice that still appears can be
|
||||
skipped, recording the skipped version in Codex's cache; this is not an update install.
|
||||
add MCP settings. Recognized update notices can be skipped during launch,
|
||||
recording the skipped version in Codex's cache; this is not an update install.
|
||||
|
||||
Activity relays send event type/subtype, seat/runtime identity, timestamps and
|
||||
native session identity to the configured OpenRig daemon's `/api/activity/hooks`
|
||||
@@ -257,38 +131,14 @@ Managed launches supply `HOME`, `CODEX_HOME` and `OPENRIG_*` identity/connection
|
||||
variables. Claude uses `--permission-mode acceptEdits` and defaults to the classic
|
||||
renderer for terminal scrollback. Codex uses `-s workspace-write` unless a named
|
||||
profile governs its sandbox; the default does not force an approval-policy flag.
|
||||
On that plain launch OpenRig first asks Codex for its own configuration and adds
|
||||
`-c sandbox_workspace_write.network_access=true` only when Codex answers that no
|
||||
configuration layer sets network access and no managed requirement could restrict
|
||||
it, so the seat can reach the local daemon. If Codex can't be asked or doesn't
|
||||
answer in time, the launch is left unchanged.
|
||||
Fresh Codex launches also add writable access to the workspace's `.git` and the
|
||||
pod's shared queue-state directory with `--add-dir`; the shared root comes from
|
||||
`OPENRIG_SHARED_DOCS_ROOT` or `~/.openrig/shared-docs`.
|
||||
A team seat with no permission policy, per-seat choice or (for Codex) named
|
||||
profile also gets the per-launch team default: Claude gets `--settings` allowing
|
||||
ordinary `rig` commands, project reads and common tests, with a session-only
|
||||
PreToolUse hook that asks before lifecycle commands, and Codex also gets the
|
||||
OpenRig workspace root as a writable directory. Neither writes a permission file.
|
||||
Seats of the rig named `kernel` launch with an operational default instead,
|
||||
unless a permission policy, a per-seat choice or (for Codex) a named profile
|
||||
applies: Claude in `acceptEdits` with a per-launch allow list for its file tools,
|
||||
web fetches and operational commands (including reads under your home folder),
|
||||
and Codex with `-s danger-full-access -a never`. Neither writes a permission file.
|
||||
YOLO is **off by default**. An explicitly selected full-bypass policy selects
|
||||
Claude's `--dangerously-skip-permissions` or Codex's
|
||||
`-s danger-full-access -a never`. The legacy environment-only `OPENRIG_YOLO=1`
|
||||
path, with no policy attached, selects Claude's bypass flag, Pi's `--approve` and
|
||||
Codex's `-s danger-full-access` without `-a never`; a resolved policy overrides
|
||||
that environment setting. The `builtin:auto` policy launches Claude with
|
||||
`--permission-mode auto`; Codex and Pi seats launch as they do without a policy (a
|
||||
named Codex profile still governs its sandbox, and Pi keeps its configured
|
||||
resource trust).
|
||||
`--non-interruptive` on `rig up` or `rig bundle install` additionally passes
|
||||
per-launch flags to full-bypass seats so Claude's bypass warning and Codex's
|
||||
full-access and GPT-5.1 migration notices don't stop startup; it writes nothing to
|
||||
their settings files and is saved on the rig. See
|
||||
[non-interruptive mode](docs/reference/non-interruptive-mode.md).
|
||||
path still selects only Codex's sandbox; a resolved policy overrides that
|
||||
environment setting.
|
||||
|
||||
Permission mode controls native execution permissions; work posture is separate
|
||||
project guidance. Use `rig policy permissions list|show|current|apply` for rig
|
||||
@@ -304,12 +154,9 @@ separates the desired selection from the last launch arguments; neither proves
|
||||
native enforcement. See the [permission guide](docs/reference/getting-started.md#per-seat-permission-mode).
|
||||
|
||||
Managed hook blocks target OpenRig's entries and retain unrelated hooks, but
|
||||
trust entries and selected resource keys can be replaced. Claude's collector,
|
||||
activity-hook and JSON resource writers leave unreadable or malformed settings
|
||||
untouched; this is not a product-wide preservation guarantee. Codex's workspace
|
||||
trust writer can treat an unreadable `config.toml` as empty and write a new trust
|
||||
configuration. Read-modify-write operations can also race other writers; there
|
||||
is no complete preservation or rollback guarantee. Back up relevant
|
||||
trust entries, selected resource keys and Claude's existing status-line command
|
||||
can be replaced. Some writers recover unreadable settings as empty objects;
|
||||
this is not a complete preservation or rollback guarantee. Back up relevant
|
||||
files before first use. Daemon/bootstrap writes are automatic and do not each
|
||||
have an interactive preview; `rig setup --dry-run` does not preview every later
|
||||
startup effect.
|
||||
@@ -330,22 +177,29 @@ OpenRig is a multi-agent harness — it manages the system that coding agents fo
|
||||
|
||||
Every agent runs in a tmux session you can attach to, inspect, and work with directly.
|
||||
|
||||
## Teams
|
||||
## Starter Rigs
|
||||
|
||||
Three teams grow with you, and the kernel operator helps you pick one:
|
||||
|
||||
- **`starter`**: a builder and a reviewer for one bounded change.
|
||||
- **`workshop`**: a lead, a builder, QA and a reviewer for ongoing work in one repository. It's a rig bundle, installed from its pinned listing.
|
||||
- **`factory`**: seven agents (a lead, an advisor, build, QA, design and two independent reviewers) for sustained product work. You bring ideas to the advisor, and the lead runs the team.
|
||||
Use `first-project`, `first-project-claude`, or `first-project-mixed` for the
|
||||
same focused first-use path on your selected providers. `product-team` is an optional
|
||||
larger product-development example:
|
||||
|
||||
```bash
|
||||
rig specs preview factory --kind rig
|
||||
rig up factory
|
||||
rig specs preview product-team --kind rig
|
||||
rig up product-team
|
||||
```
|
||||
|
||||
Specialist teams: `code-review` (two independent reviews), `research` (an analyst and a synthesizer) and `pm` (a product lead, a researcher and a builder for prototypes).
|
||||
Use it when you want a larger product squad: two orchestrators, implementation, QA, design, and two independent reviewers.
|
||||
|
||||
Also built in: `secrets-manager`, a HashiCorp Vault instance run by a specialist agent.
|
||||
For a smaller starter, use `conveyor`:
|
||||
|
||||
```bash
|
||||
rig specs preview conveyor --kind rig
|
||||
rig up conveyor
|
||||
```
|
||||
|
||||
`conveyor` is a four-seat starter mixing Claude Code and Codex. It shows a handoff path through intake, planning, build, and review; `first-project` remains the smaller two-seat starting point.
|
||||
|
||||
Also ships: `implementation-pair`, `adversarial-review`, `research-team`, and `secrets-manager` (HashiCorp Vault managed by a specialist agent).
|
||||
|
||||
Browse the library:
|
||||
|
||||
@@ -355,7 +209,7 @@ rig specs ls
|
||||
|
||||
## How It Works
|
||||
|
||||
OpenRig is a local daemon + CLI + terminal UI + MCP server, built on tmux. OpenRig itself is under active development; only the older React web UI is in maintenance mode, with best-effort support.
|
||||
OpenRig is a local daemon + CLI + terminal UI + MCP server, built on tmux. The older React web UI remains in maintenance mode with best-effort support.
|
||||
|
||||
```
|
||||
CLI / TUI / MCP
|
||||
@@ -383,23 +237,21 @@ The TUI shows the team's coordination state; herdr and cmux show the actual agen
|
||||
With herdr installed and connected, open the starter's terminals together:
|
||||
|
||||
```bash
|
||||
rig terminal open starter --provider herdr
|
||||
rig terminal open first-project --provider herdr
|
||||
```
|
||||
|
||||
For cmux, use `--provider cmux`. In the TUI, a rig's detail view has an `Open terminals ▸ rig <name>` link that opens a terminal view of the running seats of that rig (in a new window or tab, or the current Herdr session), laid out with herdr when installed, otherwise plain tmux; with herdr that is up to 16 seats per tab, in a workspace named after the rig. A seat it can't attach is reported as absent or degraded. The underlying sessions remain accessible through tmux. See the [terminal workspace guide](docs/reference/getting-started.md#share-the-dashboard-and-return-to-it) for setup and returning to an existing view.
|
||||
For cmux, use `--provider cmux`. In the TUI, a rig's detail view has a `term ▸ rig <name>` link that opens every running seat of that rig in the default terminal provider; with herdr that is up to 16 seats per tab, in a workspace named after the rig. The underlying sessions remain accessible through tmux. See the [terminal workspace guide](docs/reference/getting-started.md#share-the-dashboard-and-return-to-it) for setup and returning to an existing view.
|
||||
|
||||
## Key Concepts
|
||||
|
||||
The first words you meet, in plain language: [What these words mean](docs/reference/quickstart.md#what-these-words-mean).
|
||||
|
||||
- **RigSpec**: Declarative multi-agent harness definition in YAML. Pods, members, edges, continuity policies, culture file.
|
||||
- **AgentSpec**: Reusable agent blueprint with skills, guidance, hooks, profiles, and startup contracts.
|
||||
- **Seat**: A stable role and address in a rig, such as `dev-build@starter`. The conversation occupying it can change while its identity and authored context remain.
|
||||
- **Seat**: A stable role and address in a rig, such as `dev-owner@first-project`. The conversation occupying it can change while its identity and authored context remain.
|
||||
- **Pod**: A group of related seats with shared guidance and context. Each agent still has its own context window.
|
||||
- **Discovery**: `rig discover` fingerprints existing tmux sessions. `rig adopt` brings them under management.
|
||||
- **Snapshot/Restore**: `rig down --snapshot` captures full state. `rig up <name>` restores from latest snapshot. Restore reports per-node outcomes: resumed, fresh-primed, awaiting-decision (the original conversation can't resume; choose `--fresh`), attention_required, or failed.
|
||||
- **RigBundle**: Portable archive with vendored AgentSpecs and SHA-256 integrity. Share topologies across machines. `rig up`, `rig bundle create`, `inspect` and `install` also take a GitHub folder link, `rig bundle check` checks a folder before you share it, and `rig bundle inspect` shows what a bundle will do before you install it. See [publishing a rig bundle](docs/reference/publishing-a-rig-bundle.md).
|
||||
- **Culture**: A rig's `CULTURE.md` (its `culture_file`) sets coordination norms for the group, on top of OpenRig's default culture, which every seat receives.
|
||||
- **Snapshot/Restore**: `rig down --snapshot` captures full state. `rig up <name>` restores from latest snapshot. Restore reports per-node outcomes (resumed, fresh, or failed).
|
||||
- **RigBundle**: Portable archive with vendored AgentSpecs and SHA-256 integrity. Share topologies across machines.
|
||||
- **Culture**: CULTURE.md sets coordination norms for the group. Research rigs get exploratory culture. Implementation rigs get conservative, trust-but-verify culture.
|
||||
|
||||
## Agent-Managed Software
|
||||
|
||||
@@ -415,7 +267,7 @@ Requires Docker for service-backed rigs.
|
||||
|
||||
## Upgrading an existing instance
|
||||
|
||||
For an existing installation, follow the [upgrade procedure](skills/_canonical/core/openrig-upgrade/SKILL.md) and the [0.5.14 release notes](docs/releases/v0.5.14.md); notes for later releases are in [CHANGELOG.md](CHANGELOG.md). Preserve live seats during the upgrade; `rig down` is not an upgrade step. Upgrading to 0.6.0 also requires Node.js 22 or 24: see [Moving off Node 20](#moving-off-node-20) and the [0.6.0 release notes](docs/releases/v0.6.0.md).
|
||||
For an existing installation, follow the [upgrade procedure](skills/_canonical/core/openrig-upgrade/SKILL.md) and the [0.5.14 release notes](docs/releases/v0.5.14.md). Preserve live seats during the upgrade; `rig down` is not an upgrade step. Upgrading to 0.6.0 also requires Node.js 22 or 24: see [Moving off Node 20](#moving-off-node-20) and the [0.6.0 release notes](docs/releases/v0.6.0.md).
|
||||
|
||||
### Moving off Node 20
|
||||
|
||||
@@ -487,9 +339,7 @@ seat, plugin, and release lifecycle actions remain agent-owned.
|
||||
longer supported. Node 26 and other versions are untested. On a Mac with Apple
|
||||
silicon, use Node.js 22: see the [compatibility history](docs/releases/v0.5.15.md#known-compatibility-limitation).
|
||||
- tmux
|
||||
- macOS or Linux. On Windows, use WSL2, the Windows route OpenRig supports; native
|
||||
Windows isn't supported. OpenRig's automated tests don't run on WSL2 yet; one user's
|
||||
working setup is in the [getting-started guide](docs/reference/getting-started.md#wsl2-a-reported-working-setup)
|
||||
- macOS or Linux. Native Windows is not supported yet, and WSL2 has not been tested
|
||||
|
||||
Optional:
|
||||
- herdr or cmux for terminal workspaces showing the agents together
|
||||
@@ -497,9 +347,9 @@ Optional:
|
||||
|
||||
## Setup and Troubleshooting
|
||||
|
||||
- `rig setup` attempts core machine preparation: it installs a missing Claude Code or Codex and writes tmux defaults. It installs Herdr by default on macOS and Linux; use `--no-herdr` if you decline it. On macOS it also installs a missing tmux with an existing Homebrew; elsewhere install tmux yourself (setup only checks it). On a Mac, the installing agent offers Ghostty once; accepting uses `rig setup --ghostty`, and declining leaves Terminal.app available. Existing cmux settings are preserved. It reports what it tried and what actually succeeded. If something fails, it gives the local agent enough context to finish the job.
|
||||
- `rig setup --full` attempts a broader operator workstation setup (jq, gh, via Homebrew, so macOS only) on top of core.
|
||||
- `rig doctor` inspects current system health and helps diagnose problems after setup. Use it when something stops working or after machine changes. It shares setup's local provider login checks. These do not prove provider acceptance or a working agent; also inspect `rig ps --nodes --rig <rig>`.
|
||||
- `rig setup` attempts core machine preparation: tmux, cmux, Claude Code, Codex, and tmux defaults. It reports what it tried and what actually succeeded. If something fails, it gives the local agent enough context to finish the job.
|
||||
- `rig setup --full` attempts a broader operator workstation setup (jq, gh) on top of core.
|
||||
- `rig doctor` inspects current system health and helps diagnose problems after setup. Use it when something stops working or after machine changes.
|
||||
|
||||
Both commands support `--json` for agent-driven workflows.
|
||||
|
||||
@@ -507,7 +357,7 @@ Before setup or managed launch, review [what OpenRig changes on your machine](#w
|
||||
|
||||
Already-running adopted sessions may need restart before they pick up newly written runtime config.
|
||||
|
||||
**For agents:** First ask which available provider(s) the user wants, reusing an explicit choice, and pass it to setup (`rig setup --providers claude`, `codex` or `both`). Recommend the working account they already have and follow the selected-provider guide above. Offer core setup (`rig setup`) or the fuller workstation path (`rig setup --full`) only when they want those additional tools. Inspect the result with `--json` and use `rig doctor` to finish any remaining machine-specific issues. Starting OpenRig and opening its view are the last steps of installing, not extras, so do them without stopping to ask whether to go on: start the daemon if it is stopped, open the OpenRig TUI and operator for them (say so, then run `rig terminal open saved:kernel --window --json`; no commands for the person to copy), and hand the person's goal and project folder to the kernel operator ([installing-agent handoff](docs/reference/getting-started.md#installing-agent-handoff)). Installation is finished when the person is talking to the operator; don't implement the project yourself. When OpenRig itself misbehaves, read [docs/reference/help.md](docs/reference/help.md) (installed agents can run `rig context get help`; the same text is at [openrig.dev/help/agents](https://www.openrig.dev/help/agents)): it covers the next step, known problems, and how to reach the team if you're still stuck.
|
||||
**For agents:** First ask which available provider(s) the user wants, reusing an explicit choice. Recommend the working account they already have and follow the selected-provider guide above. Offer core setup (`rig setup`) or the fuller workstation path (`rig setup --full`) only when they want those additional tools. Inspect the result with `--json` and use `rig doctor` to finish any remaining machine-specific issues. When OpenRig itself misbehaves, read [docs/reference/help.md](docs/reference/help.md) (installed agents can run `rig context get help`; the same text is at [openrig.dev/help/agents](https://www.openrig.dev/help/agents)): it covers the next step, known problems, and how to reach the team if you're still stuck.
|
||||
|
||||
## Comparison with Claude Managed Agents
|
||||
|
||||
|
||||
+11
-13
@@ -3,19 +3,9 @@
|
||||
These are things we'd welcome help with. Most came from the community, and most are small enough for one pull request.
|
||||
This isn't a schedule or a promise: we release often, and an item ships when a good change for it lands.
|
||||
|
||||
To see what's being worked on, by release and theme, open the [OpenRig roadmap board](https://github.com/users/mvschwarz/projects/1).
|
||||
Issues labelled `good first issue` are also listed on the [contribute page](https://github.com/mvschwarz/openrig/contribute).
|
||||
|
||||
## Released in 0.7.4
|
||||
|
||||
[0.7.4 is published](https://github.com/mvschwarz/openrig/releases/tag/v0.7.4): a first, experimental step toward every
|
||||
assistant you use working on one team. See its release notes for what shipped, the experimental and security notes for
|
||||
hosted members, upgrade instructions, contributor credits and the remaining testing gaps.
|
||||
|
||||
## How to help
|
||||
|
||||
1. Pick an item and comment on its issue to say you're working on it and coordinate with others. A maintainer can assign
|
||||
you to make that work visible. If it has no issue yet, open one first.
|
||||
1. Pick an item and comment on its issue to say you're working on it. If it has no issue yet, open one first.
|
||||
2. Read `CONTRIBUTING.md`, and ask your agent to use the `developing-openrig` skill. It's a map of how OpenRig is
|
||||
built, tested and changed.
|
||||
3. Open a pull request that says what a user gets and how you verified it.
|
||||
@@ -31,20 +21,28 @@ tie. Feel free to coordinate on the issue first.
|
||||
|
||||
## Agents and runtimes
|
||||
|
||||
- **Codex seats that can reach the local daemon by default** (#275), with an easy opt-out.
|
||||
- **Custom Codex providers such as Bedrock** (#194): accept providers that authenticate with an environment key, and
|
||||
forward their token.
|
||||
- **Operator recovery for Pi and Oh My Pi seats** (#41).
|
||||
- **More harnesses:** we're working out one way for any coding-agent CLI to plug into OpenRig. More on this soon
|
||||
(design discussion: #43).
|
||||
- **New agent types:** OpenCode (#87, #227, #517), the Cursor CLI (#352), the Grok CLI (#522) and Devin (#44) are
|
||||
planned on a shared adapter.
|
||||
Design discussion: #43. Adapter pull requests are welcome once that adapter lands.
|
||||
|
||||
## Slack
|
||||
|
||||
- **A DM or private channel for single-user setups** (#313).
|
||||
- **A channel map** (#192): one channel per seat, keyed by channel ID.
|
||||
|
||||
## Reliability and everyday use
|
||||
|
||||
- **A configurable readiness window for fresh launches** (#182), so seats under load don't time out at a fixed 30
|
||||
seconds.
|
||||
- **Draft-aware delivery** (#48): automated sends wait while someone is typing in a seat, or a seat can be set to
|
||||
inbox-only.
|
||||
- **A host-aware resource budget for seats** (#80).
|
||||
- **Predictable `rig up` over a stopped rig with the same name.**
|
||||
- **A "merged" stage in the project view** for teams that integrate on a branch other than main (#402).
|
||||
- **Codex seats that leave a repository's tracked `AGENTS.md` alone** (related: #64).
|
||||
- **Install and run on Node 26.**
|
||||
|
||||
|
||||
+1
-5
@@ -9,11 +9,7 @@ Include the affected version even when reporting a problem in an older installat
|
||||
## What OpenRig touches
|
||||
|
||||
OpenRig runs a local daemon, drives coding agents in tmux sessions on your machine, and writes
|
||||
configuration for those harnesses, including workspace trust records and executable hooks: for
|
||||
example `~/.claude.json`, skills under `~/.claude`, `$CODEX_HOME/config.toml` (default `~/.codex`),
|
||||
and, in the project, `.claude/settings.local.json`, `.mcp.json` and managed blocks in `CLAUDE.md`,
|
||||
`CLAUDE.local.md` or `AGENTS.md`. `rig setup` also edits `~/.tmux.conf` and, on macOS, cmux's
|
||||
settings. OpenRig's own state lives under `$OPENRIG_HOME` (default `~/.openrig`). The README
|
||||
configuration for those harnesses (for example under `~/.claude` and `~/.codex`). The README
|
||||
section [What OpenRig changes on your machine](README.md#what-openrig-changes-on-your-machine)
|
||||
describes these effects and the trust/permission choices. Unexpected access, disclosure or
|
||||
permission changes are useful reports; include what you expected and what you observed.
|
||||
|
||||
+1
-1
@@ -18,7 +18,7 @@
|
||||
],
|
||||
"excludeFiles": [],
|
||||
"rules": [
|
||||
"Install with npm install -g @openrig/cli. OpenRig requires Node.js 22 or 24, tmux, and Claude Code or Codex signed in. The starter team uses both, and the kernel operator adapts it when you have only one.",
|
||||
"Install with npm install -g @openrig/cli. OpenRig requires Node.js 22 or 24 and tmux; the first-project starter also requires an authenticated Codex CLI.",
|
||||
"Preview before launching: rig specs preview <spec>, then rig up <spec> --cwd . --plan, then rig up <spec> --cwd .",
|
||||
"Check seat readiness with rig ps --nodes --rig <rig>, not only daemon health from rig status.",
|
||||
"Inside a rig, an agent runs rig whoami --json first and treats its output as its identity.",
|
||||
|
||||
@@ -24,7 +24,7 @@ RUN set -eux; \
|
||||
rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# --- layer 2: pinned node (an in-range engines version — see scripts/check-engines) ---
|
||||
ARG NODE_VERSION=22.23.4
|
||||
ARG NODE_VERSION=22.22.1
|
||||
ARG TARGETARCH
|
||||
RUN set -eux; \
|
||||
case "${TARGETARCH}" in \
|
||||
@@ -33,14 +33,10 @@ RUN set -eux; \
|
||||
"") echo "TARGETARCH is empty — the legacy (non-BuildKit) builder does not populate it. Pass --build-arg TARGETARCH explicitly (build-testbed-image.sh does) or enable BuildKit. REFUSING to default to amd64, which would install wrong-arch Node." >&2; exit 1 ;; \
|
||||
*) echo "unsupported TARGETARCH=${TARGETARCH}" >&2; exit 1 ;; \
|
||||
esac; \
|
||||
NODE_TARBALL="node-v${NODE_VERSION}-linux-${NODE_ARCH}.tar.xz"; \
|
||||
curl -fsSLo "/tmp/${NODE_TARBALL}" \
|
||||
"https://nodejs.org/dist/v${NODE_VERSION}/${NODE_TARBALL}"; \
|
||||
curl -fsSLo /tmp/SHASUMS256.txt \
|
||||
"https://nodejs.org/dist/v${NODE_VERSION}/SHASUMS256.txt"; \
|
||||
(cd /tmp && awk -v tarball="${NODE_TARBALL}" '$2 == tarball' SHASUMS256.txt | sha256sum -c -); \
|
||||
tar -xJf "/tmp/${NODE_TARBALL}" -C /usr/local --strip-components=1 --no-same-owner; \
|
||||
rm -f "/tmp/${NODE_TARBALL}" /tmp/SHASUMS256.txt; \
|
||||
curl -fsSLo /tmp/node.tar.xz \
|
||||
"https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-${NODE_ARCH}.tar.xz"; \
|
||||
tar -xJf /tmp/node.tar.xz -C /usr/local --strip-components=1 --no-same-owner; \
|
||||
rm -f /tmp/node.tar.xz; \
|
||||
node --version; npm --version
|
||||
|
||||
# --- layer 3: the OpenRig package from the LOCAL pack tarball, never the npm registry ---
|
||||
|
||||
@@ -4,10 +4,6 @@ This document captures the current OpenRig visual system so the product can be
|
||||
recreated, extended, or translated into other media without reverse-engineering
|
||||
the UI from code.
|
||||
|
||||
It describes the web UI in `packages/ui`, which is in maintenance mode (see
|
||||
`docs/reference/developing.md`). The terminal UI has its own theme layer in
|
||||
`packages/tui/src/theme.ts`.
|
||||
|
||||
## Essence
|
||||
|
||||
OpenRig is a local control plane for multi-agent work. The interface should feel
|
||||
@@ -86,12 +82,6 @@ terminal emulator.
|
||||
The canonical tokens live in `packages/ui/src/globals.css` and are surfaced to
|
||||
Tailwind in `packages/ui/tailwind.config.ts`.
|
||||
|
||||
The values below are the light set (`:root`). A `.dark` block in the same file
|
||||
redeclares the same names for Vellum Dark. The theme selector offers Vellum
|
||||
Light, Vellum Dark and System (`packages/ui/src/lib/theme.ts`). With no stored
|
||||
choice the UI follows the operating system's color scheme (`system`); the choice
|
||||
is stored under the `openrig.theme` local-storage key.
|
||||
|
||||
Paper:
|
||||
|
||||
- `--background: 47 20% 97%` - base paper, `#faf9f5`
|
||||
@@ -240,8 +230,6 @@ Runtime marks:
|
||||
|
||||
- Claude: pixel-style Claude mark, label `Claude`
|
||||
- Codex: Codex CLI terminal-circle mark, label `Codex`
|
||||
- Pi: blue rounded-square π mark, label `Pi`
|
||||
- Oh My Pi: violet rounded-square π mark, label `Oh My Pi` (short label `OMP`)
|
||||
- Terminal: compact terminal glyph, label `TTY` or `Terminal`
|
||||
- Unknown: neutral fallback
|
||||
|
||||
|
||||
@@ -10,14 +10,14 @@ applies-when: |
|
||||
its own source-verification stamp.
|
||||
siblings: [codemap.md, arteries.md, test-layers.md, cli-reference.md, frontmatter-schema.md]
|
||||
prerequisite-reads: []
|
||||
last-verified-against-source: e8f0ab340db773392ec8be75b072d1c0f3068a50
|
||||
last-updated: 2026-10-08
|
||||
last-verified-against-source: a350c59b5a5fb37ee4a21b1026b595068b603df1
|
||||
last-updated: 2026-10-05
|
||||
---
|
||||
|
||||
# OpenRig as-built docs
|
||||
|
||||
These pages describe the code and point to its owning files. This index was checked against
|
||||
main commit `e8f0ab340db773392ec8be75b072d1c0f3068a50`. A linked module's
|
||||
main commit `a350c59b5a5fb37ee4a21b1026b595068b603df1`. A linked module's
|
||||
`last-verified-against-source` is its own verification boundary; updating this index does not
|
||||
revalidate that module or identify a running daemon or published package.
|
||||
|
||||
@@ -93,7 +93,7 @@ At the named commit there are **26 Markdown files**: **14** under `architecture/
|
||||
these counts from the repository root:
|
||||
|
||||
```bash
|
||||
source_commit=e8f0ab340db773392ec8be75b072d1c0f3068a50
|
||||
source_commit=a350c59b5a5fb37ee4a21b1026b595068b603df1
|
||||
git ls-tree -r --name-only "$source_commit" -- docs/as-built | grep -E '\.md$' | wc -l
|
||||
git ls-tree -r --name-only "$source_commit" -- docs/as-built/architecture | grep -E '\.md$' | wc -l
|
||||
git ls-tree -r --name-only "$source_commit" -- docs/as-built/ui | grep -E '\.md$' | wc -l
|
||||
|
||||
@@ -9,14 +9,14 @@ applies-when: |
|
||||
overview or the current as-built module index linked here.
|
||||
siblings: [README.md, codemap.md, arteries.md, test-layers.md, ui.md]
|
||||
prerequisite-reads: []
|
||||
last-verified-against-source: e8f0ab340db773392ec8be75b072d1c0f3068a50
|
||||
last-updated: 2026-10-08
|
||||
last-verified-against-source: a350c59b5a5fb37ee4a21b1026b595068b603df1
|
||||
last-updated: 2026-10-05
|
||||
---
|
||||
|
||||
# Architecture module navigation
|
||||
|
||||
This compatibility page points to the modular documentation. Its links were checked against main
|
||||
`e8f0ab340db773392ec8be75b072d1c0f3068a50`; the linked pages retain their own source stamps.
|
||||
`a350c59b5a5fb37ee4a21b1026b595068b603df1`; the linked pages retain their own source stamps.
|
||||
|
||||
- [Repository architecture](../../ARCHITECTURE.md): package boundaries, request flow, derived
|
||||
source counts and contributor recipes.
|
||||
|
||||
@@ -12,114 +12,70 @@ applies-when: |
|
||||
layer).
|
||||
siblings: [daemon-core.md, agent-spec-and-startup.md, lifecycle-snapshot-restore.md]
|
||||
prerequisite-reads: [../README.md, daemon-core.md]
|
||||
last-verified-against-source: e8f0ab340db773392ec8be75b072d1c0f3068a50
|
||||
last-updated: 2026-10-08
|
||||
last-verified-against-source: b6d37bfadcc189be8fd61e35abfc09676437bf48
|
||||
last-updated: 2026-10-03
|
||||
---
|
||||
|
||||
# Adapters and Runtimes
|
||||
|
||||
How OpenRig drives the agent harnesses. Pod-aware launches go through a
|
||||
How OpenRig drives the agent harnesses. Harness launches go through a
|
||||
`RuntimeAdapter`: five adapter classes implement one contract of five required
|
||||
methods. Legacy (non-pod-aware) restore resumes through separate resume
|
||||
adapters (`ClaudeResumeAdapter`, `CodexResumeAdapter`, `PiResumeAdapter` and
|
||||
`OmpResumeAdapter` in `packages/daemon/src/adapters/*-resume.ts`), which are not
|
||||
`RuntimeAdapter`s. A separate resume-honesty layer answers the question "did
|
||||
this harness *actually* resume, or did it silently fresh-launch?" truthfully
|
||||
rather than optimistically.
|
||||
methods. A separate resume-honesty layer answers the question "did this harness
|
||||
*actually* resume, or did it silently fresh-launch?" truthfully rather than
|
||||
optimistically.
|
||||
|
||||
> Verified against source at main `e8f0ab340db773392ec8be75b072d1c0f3068a50`. Each count below sits beside the
|
||||
> Verified against source at main `b6d37bfadcc189be8fd61e35abfc09676437bf48`. Each count below sits beside the
|
||||
> command that produces it; run the command from the repository root to refresh
|
||||
> it.
|
||||
|
||||
## 1. The five-method RuntimeAdapter contract
|
||||
|
||||
`RuntimeAdapter` is `packages/daemon/src/domain/runtime-adapter.ts:143`
|
||||
`RuntimeAdapter` is `packages/daemon/src/domain/runtime-adapter.ts:134`
|
||||
(`interface RuntimeAdapter`). Every adapter declares a `readonly runtime`
|
||||
string (`runtime-adapter.ts:146`) and implements five required methods
|
||||
(`runtime-adapter.ts:152–176`; **5** =
|
||||
string (`runtime-adapter.ts:137`) and implements five required methods
|
||||
(`runtime-adapter.ts:143–166`; **5** =
|
||||
`sed -n '/^export interface RuntimeAdapter/,/^}/p' packages/daemon/src/domain/runtime-adapter.ts | grep -c -E '^ [a-zA-Z]+\('`):
|
||||
|
||||
| Method | Signature (`runtime-adapter.ts`) | Responsibility |
|
||||
|---|---|---|
|
||||
| `listInstalled` | `(binding)` `:153` | List currently installed/projected resources for a node. |
|
||||
| `project` | `(plan, binding)` `:156` | Project resources from a `ProjectionPlan` to the runtime's target locations. |
|
||||
| `deliverStartup` | `(files, binding, sendInteractiveText?)` `:160` | Deliver resolved startup files to the runtime. The startup orchestrator passes the optional third argument for Claude Code only, so Claude's `send_text` files go through the checked send described in `agent-spec-and-startup.md`. |
|
||||
| `launchHarness` | `(binding, opts)` `:170` | Launch the harness inside the bound tmux session; return a resume token. |
|
||||
| `checkReady` | `(binding)` `:176` | Probe whether the harness is responsive and ready. |
|
||||
| `listInstalled` | `(binding)` `:144` | List currently installed/projected resources for a node. |
|
||||
| `project` | `(plan, binding)` `:147` | Project resources from a `ProjectionPlan` to the runtime's target locations. |
|
||||
| `deliverStartup` | `(files, binding)` `:150` | Deliver resolved startup files to the runtime. |
|
||||
| `launchHarness` | `(binding, opts)` `:160` | Launch the harness inside the bound tmux session; return a resume token. |
|
||||
| `checkReady` | `(binding)` `:166` | Probe whether the harness is responsive and ready. |
|
||||
|
||||
The interface also has two optional members: `claudeManagedLaunch` (`:145`)
|
||||
and `skillTargetPath?()` (`:150`), implemented by `PiRuntimeAdapter`
|
||||
(`pi-runtime-adapter.ts:118`) and overridden by `OmpRuntimeAdapter`
|
||||
(`omp-runtime-adapter.ts:12`).
|
||||
The interface also has two optional members: `claudeManagedLaunch` (`:136`)
|
||||
and `skillTargetPath?()` (`:141`, implemented by `OmpRuntimeAdapter`,
|
||||
`omp-runtime-adapter.ts:12`).
|
||||
|
||||
Startup *action* execution (`slash_command` / `send_text`) is explicitly **not**
|
||||
part of this contract — the contract docstring (`runtime-adapter.ts:137–142`)
|
||||
part of this contract — the contract docstring (`runtime-adapter.ts:128–133`)
|
||||
states actions belong to the `StartupOrchestrator` *after* `checkReady()`. The
|
||||
orchestrator delivery split is in `agent-spec-and-startup.md`.
|
||||
|
||||
### `launchHarness` opts and the fork seam
|
||||
|
||||
`launchHarness` opts is `{ name: string; resumeToken?: string; forkSource?:
|
||||
ForkSource }` (`runtime-adapter.ts:172`).
|
||||
ForkSource }` (`runtime-adapter.ts:162`).
|
||||
|
||||
Per the contract docstring (`runtime-adapter.ts:162–169`) `resumeToken` and
|
||||
Per the contract docstring (`runtime-adapter.ts:152–159`) `resumeToken` and
|
||||
`forkSource` are mutually exclusive — if both are provided the adapter **must
|
||||
refuse** with a clear error, not guess; `forkSource` triggers a fork and the
|
||||
captured token is the NEW post-fork token, never the parent. `ForkSource` is
|
||||
`runtime-adapter.ts:132` (`kind: "native_id" | "artifact_path" | "name" |
|
||||
"last"`, `:133`; v1 MVP accepts `native_id` only — other shapes rejected at
|
||||
schema validation, docstring `:122–131`, and by the Claude, Codex and Pi
|
||||
adapters themselves).
|
||||
`runtime-adapter.ts:123` (`kind: "native_id" | "artifact_path" | "name" |
|
||||
"last"`, `:124`; v1 MVP accepts `native_id` only — other shapes rejected at
|
||||
schema validation, docstring `:113–122`).
|
||||
|
||||
### `HarnessLaunchResult` is a discriminated union with an honest failure arm
|
||||
|
||||
`HarnessLaunchResult` is a **discriminated union** (`runtime-adapter.ts:97–102`):
|
||||
`HarnessLaunchResult` is a **discriminated union** (`runtime-adapter.ts:88–93`):
|
||||
`| { ok: true; resumeToken?; resumeType?; appliedLaunch? }`
|
||||
`| { ok: false; error: string; recovery?: HarnessLaunchRecovery; evidence? }`.
|
||||
The failure arm carries a typed `recovery` hint
|
||||
(`HarnessLaunchRecovery = "retry_fresh" | "attention_required"`, `:95`) and
|
||||
(`HarnessLaunchRecovery = "retry_fresh" | "attention_required"`, `:86`) and
|
||||
optional `evidence` (last-N pane lines, flowed through to
|
||||
`RestoreNodeResult.attentionEvidence` for `attention_required` outcomes,
|
||||
`:99–102`). This is the honest-failure shape, not a smoothed optional `error`.
|
||||
|
||||
Readiness has its own attention codes (`runtime-adapter.ts:74–87`):
|
||||
`trust_gate`, `hook_trust_gate`, `update_gate`, `login_required`, `mcp_gate`,
|
||||
`bypass_consent_gate`, `codex_auth_refusal` and `codex_client_incompatible`.
|
||||
When `checkReady` reports one, the readiness wait returns at once and startup
|
||||
ends `attention_required`.
|
||||
|
||||
### Evidence for a failed Claude resume
|
||||
|
||||
Previously, a failed Claude launch recorded its error without the probe code or
|
||||
the captured input's identity, and a refused strict full-restore attention clear
|
||||
had no corresponding refusal event. Probe-backed Claude launch failures now
|
||||
carry an optional `probe` in `HarnessLaunchResult` and `node.startup_failed`.
|
||||
Strict full-restore refusals emit `seat.attention_clear_refused`; a
|
||||
`pane_not_usable` refusal includes that probe and the restore attempt ID.
|
||||
A missing strict reconciler emits `strict_reconciler_unavailable` without
|
||||
inventing an attempt ID or probe evidence, and still refuses the clear.
|
||||
|
||||
`native-resume-probe-evidence.ts` records the status, code, a closed-set login
|
||||
refusal and row kind when matched, and the exact capture's line count, byte
|
||||
count and SHA-256. Its new fields contain no captured pane text or free-form
|
||||
probe detail. Existing attention evidence and recovery decisions keep their
|
||||
previous behavior. MCP approval detection still takes precedence over the
|
||||
login-refusal check.
|
||||
|
||||
Pane dimensions are optional, observed after the capture. Their read has a
|
||||
250 ms deadline so a hung `listPanes` cannot indefinitely delay the failure
|
||||
result or its event. On timeout, error, ambiguous pane identity or invalid
|
||||
dimensions, the unavailable dimensions are `null`; late results are ignored.
|
||||
The deadline bounds this diagnostic wait, not the underlying tmux command.
|
||||
|
||||
`native-resume-probe-evidence.test.ts` covers unavailable and late geometry;
|
||||
`startup-orchestrator.test.ts` and `restore-orchestrator.test.ts` exercise the
|
||||
real adapter/orchestrator and SQLite event paths with available, failing and
|
||||
never-settling geometry reads. `seat-attention-reconciler.test.ts` checks that
|
||||
a missing strict reconciler records its refusal without changing restore
|
||||
history or sending input. These use synthetic terminal captures, not a
|
||||
live Claude session. The stub scenario runtime cannot draw Claude's native
|
||||
login-refusal UI, and its scenario runner does not bind the restore action.
|
||||
`:90–93`). This is the honest-failure shape, not a smoothed optional `error`.
|
||||
|
||||
## 2. The runtime adapters
|
||||
|
||||
@@ -131,217 +87,59 @@ login-refusal UI, and its scenario runner does not bind the restore action.
|
||||
Hono, `git grep -l 'from "hono' -- packages/daemon/src/adapters | wc -l`).
|
||||
`OmpRuntimeAdapter` (Oh My Pi) extends `PiRuntimeAdapter`, so the daemon wires
|
||||
**6** runtime keys — `claude-code`, `codex`, `pi`, `omp`, `stub`, `terminal`
|
||||
(`startup.ts:989`, and the same map at `:1259`;
|
||||
(`startup.ts:945`;
|
||||
`grep 'adapters: {' packages/daemon/src/startup.ts | grep -o -E '"[a-z-]+": ' | wc -l`).
|
||||
|
||||
### Launch posture
|
||||
### ClaudeCodeAdapter (`claude-code-adapter.ts:53`)
|
||||
|
||||
A seat's launch posture is `floor`, `auto` or `full_bypass`. It comes from the
|
||||
member's or rig's `permission_policy`: `builtinLaunchPosture()`
|
||||
(`packages/daemon/src/domain/permission-policy/policy-ref.ts:165`) maps
|
||||
`builtin:yolo` to `full_bypass`, `builtin:auto` to `auto`, and every other
|
||||
built-in (`locked`, `standard`, `open`) to `floor`.
|
||||
`resolvePermissionPolicyAttachment()` (`:172`) resolves the attachment, and
|
||||
`rigspec-instantiator.ts` binds the result: the member attachment
|
||||
(`resolveMemberPolicyAttachment`, `:1922`), then the persisted node or rig
|
||||
attachment (`:2007`), then the floor, set on the binding as `launchPosture`
|
||||
(`:2159`). `NativePermissionStore.apply()`
|
||||
(`native-permission-store.ts:238`) then overlays a seat's explicit
|
||||
`rig seat set-permissions` choice, or the kernel operational or team default
|
||||
described below. `bundle-behaviour.ts` is the read-only
|
||||
preview of the same mapping for an unopened bundle (see
|
||||
`packaging-bootstrap-bundles.md`).
|
||||
|
||||
`packages/daemon/src/adapters/yolo-mode.ts` turns the posture into flags:
|
||||
|
||||
- **Claude Code** (`claudePostureFlag`): an explicit `permissionMode` becomes
|
||||
`--permission-mode <mode>` (`:43`); `auto` becomes
|
||||
`--permission-mode auto` (`:47`); `full_bypass` becomes
|
||||
`--dangerously-skip-permissions`; otherwise the floor is
|
||||
`--permission-mode acceptEdits` (`:50`). For a seat with no resolved
|
||||
posture, the instance-wide YOLO setting `OPENRIG_YOLO=1` (`:27`; off by
|
||||
default) selects the bypass; a resolved posture always wins (`:26`).
|
||||
- **Codex** (`codexPostureArg`, `:62`): `full_bypass` becomes
|
||||
`-s danger-full-access -a never` (`:67`); for a seat with no resolved
|
||||
posture, `OPENRIG_YOLO=1` becomes `-s danger-full-access`; otherwise the
|
||||
seat's `-p <profile>` or `-s workspace-write`. Codex with `auto` gets the
|
||||
same: its selected profile, or the `-s workspace-write` floor without one.
|
||||
|
||||
**Non-interruptive mode** (`nonInterruptiveArgs()` in
|
||||
`packages/daemon/src/adapters/non-interruptive.ts:12`) adds per-launch
|
||||
arguments only for a `full_bypass` seat whose rig has it on
|
||||
(`rigs.non_interruptive`): Claude Code gets
|
||||
`--settings '{"skipDangerousModePermissionPrompt":true}'` (unless an explicit
|
||||
non-bypass `permissionMode` is set), and Codex gets
|
||||
`-c notice.hide_full_access_warning=true -c notice.hide_gpt5_1_migration_prompt=true`.
|
||||
It never changes permissions or native settings files. `rig up
|
||||
--non-interruptive` and `--no-non-interruptive` save the choice; otherwise the
|
||||
rig spec's `non_interruptive`, then the setting `launch.non_interruptive`,
|
||||
supplies the default (`packages/daemon/src/domain/bootstrap-orchestrator.ts:739`).
|
||||
|
||||
**Kernel operational default.** `NativePermissionStore.launchOverride()`
|
||||
(`native-permission-store.ts:47`) gives a Claude Code or Codex seat in the
|
||||
persisted rig named `kernel` operational launch arguments when the seat has no
|
||||
explicit permission choice, its member and rig declare no permission policy,
|
||||
and (for Codex) it has no `-p` profile (`launchDefault`, `:28`). Fresh start,
|
||||
continue, restore and handover all take this decision per launch.
|
||||
`operationalLaunchArgs()` (`packages/daemon/src/adapters/kernel-authority.ts:56`)
|
||||
then replaces the non-interruptive arguments for that seat:
|
||||
|
||||
- Claude Code keeps the floor, `--permission-mode acceptEdits`, and gets
|
||||
`--settings` whose `permissions.allow` is `KERNEL_CLAUDE_ALLOW`
|
||||
(`:9`): `Skill`, `Read`, `Edit`, `Write`, `Glob`, `Grep`, `WebFetch`, `Bash(<command>:*)`
|
||||
for 39 operational commands (`rig`, `tmux`, `node`, `npm`, `git`, `ssh`, `python3` and
|
||||
others), `Bash(command -v:*)` (`:16`), two read-only provider login checks (`Bash(claude auth status:*)`,
|
||||
`Bash(codex login status:*)`, `:18`), and `Read(~/**)` (`:19`), plus the `PreToolUse`
|
||||
hook described under the team default. It is not
|
||||
the bypass flag, and the user's own ask and deny rules still apply.
|
||||
- Codex gets the `full_bypass` posture, `-s danger-full-access -a never`, plus
|
||||
the two notice flags above.
|
||||
|
||||
It writes no settings file. If the rig lookup fails, the seat keeps its floor.
|
||||
`rig seat status` reports the source as "kernel operational default"
|
||||
(`kernel_default`, `native-permission-store.ts:182`).
|
||||
|
||||
**Team default.** Under the same conditions, a Claude Code or Codex seat in any
|
||||
other rig gets `teamPermissionDefault` instead (`native-permission-store.ts:38`,
|
||||
`:56`), on the same launch paths. A Claude Code seat at the floor with no native
|
||||
permission mode keeps `--permission-mode acceptEdits` and gets
|
||||
`--settings` (`kernel-authority.ts:64–66`):
|
||||
`TEAM_CLAUDE_ALLOW` (`:33`) is `Skill`, `Read(./**)`, `Glob`, `Grep`,
|
||||
`Bash(rig:*)`, eight read-only shell commands and 17 test-runner commands, and
|
||||
`TEAM_CLAUDE_ASK` (`:40`) asks before 29 `rig` commands: the 23 that start, stop or
|
||||
remove teams or agents (such as `up`, `down`, `seat stop`, `seat restart` and `bundle install`),
|
||||
and six kept for a person: `import` (its `--instantiate` mode launches nodes), `seat
|
||||
set-permissions` and `policy apply` under both spellings (an explicit permission choice),
|
||||
`setup` (kept for its `--policy` path, which records one; a prefix rule can't tell that path
|
||||
from ordinary setup, so ordinary setup prompts too), and `compact` (it replaces a peer's
|
||||
working context). Other `rig` commands fall under the `Bash(rig:*)` allowance. The list was
|
||||
42 before: 15 commands were removed and 2 added (`seat restart` and `policy permissions
|
||||
apply`), 13 fewer prompts. The settings carry the allow list and a
|
||||
`PreToolUse` Bash hook, `packages/daemon/assets/claude-team-permissions.cjs`, that applies
|
||||
both lists (`kernel-authority.ts:43–53`): it asks before a lifecycle command unless the
|
||||
command only asks for `--help` or `-h`, allows a simple literal command that matches an
|
||||
allow rule, and otherwise leaves the decision to Claude (`claude-team-permissions.cjs:234`,
|
||||
`:240`). Without the hook file, the settings carry both lists as plain `allow` and `ask`
|
||||
rules (`kernel-authority.ts:46`). A Codex seat launching at
|
||||
`-s workspace-write` gets `--add-dir` for the workspace root (`workspace.root`)
|
||||
and its pod's state directory, each created first and skipped with a warning if
|
||||
it is the home directory or an ancestor of it
|
||||
(`packages/daemon/src/domain/codex-team-workspace.ts:18`), on fresh, fork and
|
||||
resume launches (`codex-runtime-adapter.ts:378`, `codex-resume.ts:103`).
|
||||
|
||||
### ClaudeCodeAdapter (`claude-code-adapter.ts:55`)
|
||||
|
||||
- `readonly runtime = "claude-code"` (`:56`).
|
||||
- `readonly runtime = "claude-code"` (`:54`).
|
||||
- **Projects** to `.claude/` targets: guidance managed blocks →
|
||||
`<cwd>/CLAUDE.md` by default (`:194`, `:501`; default at
|
||||
`domain/managed-blocks.ts:17`, and the rig may select `CLAUDE.local.md`
|
||||
instead with `managed_blocks: { claude-code: <file> }`,
|
||||
`managed-blocks.ts:15`); `skill_install` and skill resources → the seat's
|
||||
skill root, `binding.seatSkillsRoot`, which is the `skills/` folder of the
|
||||
seat's generated plugin in its own storage
|
||||
(`domain/startup-orchestrator.ts:353–369`), or
|
||||
`<cwd>/.claude/skills/<name>/` for a seat without one (`:215–216`,
|
||||
`:849`); subagents → `.claude/agents`, plugins →
|
||||
`.claude/plugins/<id>` (only plugins that apply to Claude), runtime
|
||||
resources → `.claude/extensions/<id>` (`:584–586`); settings fragments
|
||||
merged into `.claude/settings.local.json` (`:594`) and MCP fragments into
|
||||
`<cwd>/.mcp.json` (`:597`).
|
||||
- **Launches**: fresh = `claude <posture> --session-id <generatedId> --name
|
||||
<name>` (`:329`); resume = `claude <posture> --resume <token> --name <name>`
|
||||
(`:328`); fork = `claude <posture> --resume <parentId> --fork-session
|
||||
--session-id <generatedId> --name <seat>`, which needs Claude Code 2.0.73 or
|
||||
later. `<posture>` is the flag above plus any non-interruptive,
|
||||
kernel operational or team default argument. Each command may carry a `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1`
|
||||
env prefix (`yolo-mode.ts:101–103`; on by default, off with
|
||||
`OPENRIG_CLAUDE_DISABLE_ALTERNATE_SCREEN=0`), a `--model <model>` argument
|
||||
(`:275`) and `--effort <effort>` (`:277`). A fresh launch and a fork both
|
||||
return the generated `--session-id` as their `claude_id` token, so a forked
|
||||
seat's process names its own conversation and strict proof can verify it.
|
||||
Neither reads Claude's session files back.
|
||||
- **Managed launch.** When the binding selects a native permission mode, the
|
||||
command comes from `ClaudeManagedLaunch.prepare()`
|
||||
(`domain/claude-managed-launch.ts:97`), which resolves `claude` on the
|
||||
managed `PATH`, validates the mode against `claude --help` (5-second limit),
|
||||
and launches through `/usr/bin/env -i` with only the seat's environment
|
||||
(`PATH`, `HOME`, an optional `CLAUDE_CONFIG_DIR`, the OpenRig seat identity
|
||||
and forwarded keys).
|
||||
- **Managed bootstrap.** Before delivery the adapter marks the seat's working
|
||||
directory as trusted and onboarding as completed in Claude's state file,
|
||||
writing only when a flag is missing (`provisionManagedBootstrap`, `:697`).
|
||||
It writes no permission settings. The Codex adapter does the same for
|
||||
project trust in its `config.toml` (`codex-runtime-adapter.ts:736`).
|
||||
- **Readiness** (`checkReady`, `:356`): verifies tmux session alive (`:361`),
|
||||
captures the pane command and 40 pane lines, and assesses them with
|
||||
`assessNativeResumeProbe` (§3) through `assessManagedProbe` (called `:368`,
|
||||
defined `:386`); ready only when probe `status === "resumed"`. The
|
||||
resume-launch verification loop `verifyResumeLaunch` (`:420`) retries up to
|
||||
**16 attempts** (`:422`), failing loudly with `recovery: "retry_fresh"` on
|
||||
`no_conversation_found` (`:429–434`) and with `recovery:
|
||||
`<cwd>/CLAUDE.md` by default (`:187`, `:483`; default at
|
||||
`managed-blocks.ts:16`, and the rig may select `CLAUDE.local.md` instead,
|
||||
`managed-blocks.ts:14`); `skill_install` →
|
||||
`<cwd>/.claude/skills/<name>/` (`:193`, `:564`); subagents → `.claude/agents`,
|
||||
plugins → `.claude/plugins/<id>`, runtime resources →
|
||||
`.claude/extensions/<id>` (`:566–568`); settings fragments merged into
|
||||
`.claude/settings.local.json` (`:576`) and MCP fragments into `<cwd>/.mcp.json`
|
||||
(`:579`).
|
||||
- **Launches** (`:311–312`): fresh = `claude <permissionMode> --session-id
|
||||
<generatedId> --name <name>`; resume = `claude <permissionMode> --resume
|
||||
<token> --name <name>`; fork = `claude <permissionMode> --resume <parentId>
|
||||
--fork-session --name <seat>` (`:283`). Each command may carry a
|
||||
`CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1` env prefix (`yolo-mode.ts:98`) and a
|
||||
`--model <model>` argument (`:263`) and `--effort <effort>` (`:265`).
|
||||
When `binding.permissionMode` is set, the command is built by `claudeManagedLaunch` instead (`:243–249`, `:309`).
|
||||
- **Readiness** (`checkReady`, `:338`): verifies tmux session alive (`:343`),
|
||||
captures 40 pane lines + pane command (`:348–349`), and assesses them with
|
||||
`assessNativeResumeProbe` (§3) through `assessManagedProbe` (`:368`); ready
|
||||
only when probe `status === "resumed"` (`:352`). The resume-launch
|
||||
verification loop `verifyResumeLaunch` (`:402`) retries up to **16 attempts**
|
||||
(`:404`), failing loudly with `recovery: "retry_fresh"` on
|
||||
`no_conversation_found` (`:411–416`) and with `recovery:
|
||||
"attention_required"` plus pane evidence on an `attention_required` probe
|
||||
(`:444–450`) — the adapter never relaunches on its own.
|
||||
- **Fresh in-place handover readiness.** `assessFreshInPlaceProbe` qualifies an
|
||||
otherwise ready history probe only for the matching fresh launch, binding and
|
||||
launch generation. The current pane must show a prompt, and `assessManagedProbe`
|
||||
must confirm the new launch's exact session token in the same foreground process
|
||||
across two observations, with the pane and launch still current. It reuses the
|
||||
existing managed identity proof, including its process fingerprint. A process
|
||||
label alone, old scrollback, an unavailable screen, an unreadable process list
|
||||
or an unidentified Claude process cannot admit the handover. Those cases stay
|
||||
`awaiting_runtime`; a positive identity conflict and visible approval or login
|
||||
gates keep their specific results. The handover waits within its existing
|
||||
readiness budget before sending the context packet.
|
||||
(`:426–432`) — the adapter never relaunches on its own.
|
||||
|
||||
The fresh path requires the last `❯` prompt to sit inside Claude's complete
|
||||
input frame: its top rule directly above the prompt and a bottom rule below.
|
||||
A shell's echoed launch command cannot borrow an earlier header or input
|
||||
frame, even when the matching Claude process is already running. A header
|
||||
and prompt alone, or a partially drawn frame, remain pending. This may delay
|
||||
readiness until the full frame is visible; other launch paths keep their
|
||||
existing screen predicates.
|
||||
### CodexRuntimeAdapter (`codex-runtime-adapter.ts:61`)
|
||||
|
||||
Previously, unavailable observations and ambiguous headerless prompts could
|
||||
retain the old ready result. `claude-fresh-in-place-scope.test.ts` now checks
|
||||
missing observations, unknown or changing process identity, retained UI above
|
||||
direct and script launch commands, partial frames, recovery and normal prompt
|
||||
controls. `claude-handover-readiness.test.ts` exercises the real handover
|
||||
service with migrated SQLite, modeled pane/process observations and one synthetic
|
||||
clock. Readiness and the later packet-submission receipt remain separate checks;
|
||||
these tests do not run a live Claude account.
|
||||
|
||||
### CodexRuntimeAdapter (`codex-runtime-adapter.ts:65`)
|
||||
|
||||
- `readonly runtime = "codex"` (`:66`).
|
||||
- `readonly runtime = "codex"` (`:62`).
|
||||
- **Projects** to `.agents/` targets: `guidance_merge` → `<cwd>/AGENTS.md`
|
||||
(`:309`, `:576`); `skill_install` and skill resources → the seat's skill
|
||||
root, `binding.seatSkillsRoot`, which is the `skills/` folder beside the
|
||||
seat's catalog in its own storage
|
||||
(`domain/startup-orchestrator.ts:360–369`), or
|
||||
`<cwd>/.agents/skills/<name>/` for a seat without one (`:563–564`,
|
||||
`:1060`); plugins go to `.codex/plugins/<id>` (`:1063`).
|
||||
- **Launches/resumes**: fresh = `codex[ --no-daemon]<posture>[<network>] -C
|
||||
<cwd> …` (`:442`), then capture a fresh thread id (`:460`); resume is built
|
||||
by `buildCodexResumeCore` (`:441`) as `codex<daemon><posture> resume
|
||||
[<queueStateDirArg>] <token>` (`native-resume-probe.ts:81`); fork =
|
||||
`codex<posture> fork<queueStateDirArg> <parentId>` (`:411`). `--no-daemon`
|
||||
(`:389`) comes first, and only when `codex --help` lists it
|
||||
(`domain/codex-daemon-support.ts`; an unreadable answer refuses the launch).
|
||||
`-m <model>` (`:356`) and `-c 'model_reasoning_effort="<effort>"'`
|
||||
(`:358`) are added when selected. With a thread id it returns `{ ok: true,
|
||||
resumeToken: threadId, resumeType: "codex_id" }` (`:428`, `:457`, `:463`); a
|
||||
fresh launch whose thread id is not captured returns `{ ok: true }` with its
|
||||
applied launch but no token (`:466`). Every Codex launch, fresh, fork or resume,
|
||||
also carries `-c check_for_update_on_startup=false`, so a managed seat leaves Codex
|
||||
upgrades to the operator (`kernel-authority.ts:60`, added to the posture at
|
||||
`codex-runtime-adapter.ts:363`).
|
||||
- **Network default.** On the plain `-s workspace-write` floor,
|
||||
`domain/codex-network-default.ts` asks a one-shot `codex app-server` for the
|
||||
effective configuration; when it allows it, the launch adds
|
||||
`-c sandbox_workspace_write.network_access=true` (`:19`). Otherwise it adds
|
||||
nothing.
|
||||
(`:290`, `:551`); `skill_install` → `<cwd>/.agents/skills/<name>/` (`:240`,
|
||||
`:296`); skills resolve under `.agents/skills/<id>` (`:630`).
|
||||
- **Launches/resumes**: fresh = `codex<posture> -C <cwd> …` (`:415`), then
|
||||
capture a fresh thread id (`:431`); resume is built by
|
||||
`buildCodexResumeCore` (`:414`) as `codex<posture> resume
|
||||
[<queueStateDirArg>] <token>` (`native-resume-probe.ts:81`); fork = `codex<posture> fork<queueStateDirArg>
|
||||
<parentId>` (`:386`). `<posture>` is `codexPostureArg(...)`
|
||||
(`yolo-mode.ts:59`): the `-p <profile>` argument, `-s workspace-write`, or
|
||||
`-s danger-full-access`. Each command may also carry `--no-daemon` (`:366`)
|
||||
and `-m <model>` (`:337`), plus `-c 'model_reasoning_effort="<effort>"'`
|
||||
when effort is selected (`codex-runtime-adapter.ts:339`). With a thread id it
|
||||
returns `{ ok: true,
|
||||
resumeToken: threadId, resumeType: "codex_id" }` (`:401`, `:428`, `:434`);
|
||||
a fresh launch whose thread id is not captured returns `{ ok: true }` without
|
||||
a token (`:437`).
|
||||
- Refuses `resumeToken` + `forkSource` together with a clear error
|
||||
(`:350–351`) — honors the mutual-exclusivity contract.
|
||||
(`:331–332`) — honors the mutual-exclusivity contract.
|
||||
|
||||
### TerminalAdapter (`terminal-adapter.ts:19`)
|
||||
|
||||
@@ -349,54 +147,27 @@ resume launches (`codex-runtime-adapter.ts:378`, `codex-resume.ts:103`).
|
||||
- **All operations are no-ops** — "the shell is immediately interactive"
|
||||
(`terminal-adapter.ts:15`): no-op `project`/`deliverStartup`, a
|
||||
`launchHarness` (`:34`) that returns `{ ok: true }`, and a `checkReady` that
|
||||
returns ready unconditionally (`:47–48`). Used for infrastructure nodes. A
|
||||
terminal node cannot fork: `launchHarness` refuses a `forkSource` with a
|
||||
clear error (`:38–42`), as the runtime-adapter docstring requires of
|
||||
adapters without fork (`runtime-adapter.ts:129–130`).
|
||||
returns ready unconditionally (`:47–48`). Used for infrastructure nodes —
|
||||
servers, log tails, build watchers. A terminal node cannot fork:
|
||||
`launchHarness` refuses a `forkSource` with a clear error (`:38–42`), as the
|
||||
runtime-adapter docstring requires of adapters without fork
|
||||
(`runtime-adapter.ts:120–121`).
|
||||
|
||||
### Pi, Oh My Pi and stub adapters
|
||||
|
||||
- `PiRuntimeAdapter` (`pi-runtime-adapter.ts:64`), `runtime` `"pi"` (`:65`).
|
||||
- `PiRuntimeAdapter` (`pi-runtime-adapter.ts:60`), `runtime` `"pi"` (`:61`).
|
||||
- `OmpRuntimeAdapter` (`omp-runtime-adapter.ts:7`) extends it with
|
||||
`runtime = "omp"` (`:8`).
|
||||
- `StubRuntimeAdapter` (`stub-runtime-adapter.ts:69`), `runtime` defaulting to
|
||||
`"stub"` (`:81`).
|
||||
|
||||
Pi and stub launch an OpenRig runner inside the seat's tmux pane (header
|
||||
comments `pi-runtime-adapter.ts:1–10`, `stub-runtime-adapter.ts:1–14`). Pi
|
||||
and Oh My Pi support fork and report `pi_session_file` or `omp_session_file`
|
||||
resume tokens; the stub refuses fork and reports `stub_session`.
|
||||
comments `pi-runtime-adapter.ts:1–10`, `stub-runtime-adapter.ts:1–8`); their
|
||||
projection, launch and readiness behaviour is not detailed here.
|
||||
|
||||
`createDaemon` constructs the adapters (`startup.ts:778`, `:779`, `:782`,
|
||||
`:783`, `:788`) and creates the terminal adapter inline in the runtime adapter
|
||||
maps (`startup.ts:989`, `:1259`); see `daemon-core.md` §4 "Startup sequence".
|
||||
|
||||
### Terminal providers
|
||||
|
||||
Opening a seat in a terminal app goes through `TerminalProvider`s under
|
||||
`packages/daemon/src/domain/terminal/`, served by `/api/terminal`:
|
||||
`HerdrAdapter` (`herdr-adapter.ts:351`), the default
|
||||
(`terminal-service.ts:55–58`), and `CmuxProviderAdapter`
|
||||
(`cmux-provider-adapter.ts:52`), which is best effort and refuses with
|
||||
`cmux_unavailable` when cmux is not connected. A request that names no
|
||||
provider takes the first of Herdr, then cmux, that is available and alive,
|
||||
and stays on Herdr when neither is (`providerNameFor`,
|
||||
`terminal-service.ts:175`); a named provider is used as named. These place existing tmux
|
||||
sessions in views; they do not launch harnesses.
|
||||
|
||||
`RexAdapter` (`rex-adapter.ts`) opens a view as a new Rex session through
|
||||
the `rex` CLI (`rex --autostart=false api call <method> -`, `rex-transport.ts`):
|
||||
it creates an empty session (`session.create`), adds one window per grid page
|
||||
(`session.new_window`), and checks the tiles once after a short wait. It is used only when named;
|
||||
the CLI and TUI name it when they run inside Rex (`openRexView`,
|
||||
`packages/cli/src/terminal-window-rex.ts`), and an omitted provider never picks
|
||||
it. It refuses with `rex_unavailable` when the Rex server does not answer.
|
||||
Discovery (`server.version` and `server.status`) has a 1 s budget, and
|
||||
`status()` and `liveness()` share one probe. A request whose reply is lost (a
|
||||
timeout, a killed client, an unreadable reply) is `unknown`, not failed: the
|
||||
adapter never closes a session on it and reports `rex_outcome_unknown`.
|
||||
Herdr and Rex build their layout trees from one grid helper
|
||||
(`buildTileGrid`, `tile-layout.ts`).
|
||||
`createDaemon` constructs the adapters (`startup.ts:755`, `:756`, `:759`,
|
||||
`:760`, `:765`) and creates the terminal adapter inline in the runtime adapter
|
||||
map (`startup.ts:945`); see `daemon-core.md` §4 "Startup sequence".
|
||||
|
||||
## 3. Resume honesty
|
||||
|
||||
@@ -412,21 +183,13 @@ command + pane content and returns one of four honest statuses
|
||||
|
||||
- `resumed` — runtime-specific indicators confirm a resumed session.
|
||||
- `failed` — terminal failure (e.g. Claude printed "No conversation found" →
|
||||
code `no_conversation_found`, `:99–104`).
|
||||
code `no_conversation_found`, `:92–95`).
|
||||
- `inconclusive` — we don't know yet (e.g. Claude trust gate, code
|
||||
`trust_gate`, `:113–118`).
|
||||
`trust_gate`, `:106–109`).
|
||||
- `attention_required` — alive and recoverable but **needs operator action**
|
||||
(e.g. Claude resume-selection prompt, code `claude_resume_selection_prompt`,
|
||||
`:106–111`). This is the proxy for "an operator must choose the
|
||||
conversation"; it is *distinct* from `inconclusive` and `failed` (comment
|
||||
`:4–6`).
|
||||
|
||||
Other codes include `bypass_consent_gate`, `mcp_gate`, `login_required` and
|
||||
`returned_to_shell` for Claude, and `codex_client_incompatible`,
|
||||
`no_saved_session`, `codex_auth_refusal` and `model_selection_gate` for Codex;
|
||||
an unknown runtime gets `unsupported_runtime`. For Claude, `assessManagedProbe`
|
||||
upgrades an auto-mode or composer-only screen to `resumed` only after a stable
|
||||
native process match on a single pane.
|
||||
`:99–102`). This is the proxy for "an operator must choose the conversation";
|
||||
it is *distinct* from `inconclusive` and `failed` (comment `:4–6`).
|
||||
|
||||
`buildNativeResumeCommand` (`:32`) builds the resume command per runtime:
|
||||
claude → `claude --resume <token> [--name <name>]` (`:41`); codex →
|
||||
@@ -437,40 +200,33 @@ At the adapter level (Architecture Rule 15, §4), the adapter's
|
||||
`verifyResumeLaunch` returns `ok:false` with a `retry_fresh` recovery hint and
|
||||
never relaunches itself. Acting on that hint is the caller's choice:
|
||||
`StartupOrchestrator` retries once fresh on `retry_fresh` unless the caller
|
||||
passes `allowFreshFallback: false` (`startup-orchestrator.ts:319–330`), and the
|
||||
passes `allowFreshFallback: false` (`startup-orchestrator.ts:260–268`), and the
|
||||
restore orchestrator passes `false` when a pod-aware node requested resume
|
||||
(`restore-orchestrator.ts:1224`).
|
||||
(`restore-orchestrator.ts:1399`).
|
||||
|
||||
### `resume-metadata-refresher.ts`
|
||||
|
||||
`ResumeMetadataRefresher` (`resume-metadata-refresher.ts:59`) records which
|
||||
sessions can be resumed, without overwriting a token it can't re-derive
|
||||
exactly. `refresh(sessions, opts?)` (`:124`) works in two modes:
|
||||
|
||||
- **At shutdown** (default): a Codex session without a token gets its thread
|
||||
id captured. For a Claude session with a token, it first reads Claude's live
|
||||
per-process session file, and only if that read fails runs
|
||||
`probeClaudeResume` (`:216`) — a real launch of the resume command in a
|
||||
throwaway probe tmux session (`rigged-refresh-<name>-<ts>`, `:301`),
|
||||
returning `"resumable" | "not_resumable" | "inconclusive"`. The probe result
|
||||
is recorded without clearing the token.
|
||||
- **`fillNullOnly`** (`:127`): a missing Claude token is filled from the
|
||||
status-line sidecar, and a present Claude or Codex token is re-stamped
|
||||
resumable only when it matches what the runtime reports. No probe runs.
|
||||
`ResumeMetadataRefresher` (`resume-metadata-refresher.ts:52`). Post-launch
|
||||
resume-token capture: `refresh(sessions, opts?)` (`:112`) skips `codex`
|
||||
sessions that already have a `resumeToken` (`:128`, `:144`) and otherwise
|
||||
captures the thread id (`:147–150`). For `claude-code` sessions with a token
|
||||
it runs a `probeClaudeResume` returning `"resumable" | "not_resumable" |
|
||||
"inconclusive"` (`:37`, `:194`) — a real launch of the resume command in a
|
||||
throwaway probe tmux session (`:251–254`), not a metadata guess. In
|
||||
`fillNullOnly` mode (`:121`) it skips that probe (`:177`).
|
||||
|
||||
### `codex-thread-id.ts`
|
||||
|
||||
Codex thread-id extraction (`codex-thread-id.ts`). Reads the Codex thread id
|
||||
from the Codex *logs* SQLite databases in the Codex home (`CODEX_HOME` when
|
||||
set, else `~/.codex`, `:40`): `readCodexThreadIdFromCandidateHomes(...)`
|
||||
(`:34`) → `readCodexThreadIdFromLogs(...)` (`:244`) →
|
||||
`resolveCodexDbPaths(homeDir, kind)` (`:302`), which globs
|
||||
`logs_<N>.sqlite` (`:308`) and falls back to `logs_1.sqlite`. The logged
|
||||
thread ids are then checked against the `threads` table in `state_<N>.sqlite`
|
||||
(falling back to `state_5.sqlite`, `:320`; query `:269–280`); an id is
|
||||
returned only when exactly one CLI conversation matches (`:282`). Uses
|
||||
`better-sqlite3` (`:6`). Resolves the home dir by the harness PID
|
||||
(`defaultResolveHomeDirByPid`, `:16`).
|
||||
from the Codex *logs* SQLite databases under `~/.codex/`:
|
||||
`readCodexThreadIdFromCandidateHomes(...)` (`:32`) →
|
||||
`readCodexThreadIdFromLogs(...)` (`:237`) → `resolveCodexDbPaths(homeDir,
|
||||
kind)` (`:294`) which globs `<homeDir>/.codex/logs_<N>.sqlite` (regex
|
||||
`^${kind}_(\d+)\.sqlite$`, `:300`) and falls back to `logs_1.sqlite` (`:312`).
|
||||
The logged thread ids are then checked against the `threads` table in
|
||||
`state_<N>.sqlite` (`:262–272`); an id is returned only when exactly one CLI
|
||||
conversation matches (`:274`). Uses `better-sqlite3` (`:6`). Resolves the home
|
||||
dir by the harness PID (`defaultResolveHomeDirByPid`, `:16`).
|
||||
|
||||
## 4. Relevant Architecture Rules
|
||||
|
||||
@@ -479,24 +235,22 @@ section cites them by number with the adapter-level evidence checked for this
|
||||
module.
|
||||
|
||||
- **Rule 1** — §2: **0** files in `adapters/` import Hono.
|
||||
- **Rule 5** — restore picks a node's adapter by that node's own runtime: the
|
||||
saved startup context's runtime, else the node's (`restore-orchestrator.ts:1115–1116`),
|
||||
used to choose the replay adapter (`:1138`).
|
||||
- **Rule 5** — restore picks a node's adapter by that node's own `runtime`
|
||||
(`restore-orchestrator.ts:1253`).
|
||||
- **Rule 13** — the readiness loop is `StartupOrchestrator.waitForReady`
|
||||
(`startup-orchestrator.ts:562`; 1 s doubling to a 16 s cap), which calls each
|
||||
adapter's `checkReady` (§2). The timeout comes from the
|
||||
`runtime.readiness_timeout_seconds` setting (default 30, range 1–600,
|
||||
`domain/readiness-timeout.ts:3`).
|
||||
(`startup-orchestrator.ts:488`; 1 s doubling to a 16 s cap, `:494–495`,
|
||||
`:510`; default timeout 30 s, `:491`), which calls each adapter's
|
||||
`checkReady` (§2).
|
||||
- **Rule 14** — the probe's `attention_required` (§3) reaches the restore
|
||||
result through `HarnessLaunchResult.recovery` and `evidence` (§1), which
|
||||
become `RestoreNodeResult.status` (`types.ts:457`, `:475`) and
|
||||
`attentionEvidence` (`types.ts:478`). A startup's `continuityOutcome` is a
|
||||
separate field that also allows `forked` (`startup-orchestrator.ts:101`).
|
||||
become `RestoreNodeResult.status` (`types.ts:458`, `:476`) and
|
||||
`attentionEvidence` (`types.ts:479`). A startup's `continuityOutcome` is a
|
||||
separate field that also allows `forked` (`startup-orchestrator.ts:69`).
|
||||
- **Rule 15** — adapters return `ok:false` and never relaunch (§2, §3);
|
||||
restore passes `allowFreshFallback: false` for pod-aware resume
|
||||
(`restore-orchestrator.ts:1224`), and a resume that concludes failed rolls
|
||||
back to zero sessions as `awaiting-decision` (`restore-orchestrator.ts:1055`,
|
||||
`:1243`).
|
||||
(`restore-orchestrator.ts:1399`), and a resume that concludes failed rolls
|
||||
back to zero sessions as `awaiting-decision` (`restore-orchestrator.ts:1230`,
|
||||
`:1417`).
|
||||
|
||||
## See also
|
||||
|
||||
@@ -507,6 +261,5 @@ module.
|
||||
snapshot/restore (resume vs rebuild vs fresh).
|
||||
- `architecture-rules-and-event-system.md` — the full architecture rule list.
|
||||
- Source roots: `packages/daemon/src/domain/runtime-adapter.ts`,
|
||||
`packages/daemon/src/adapters/{claude-code-adapter,codex-runtime-adapter,pi-runtime-adapter,omp-runtime-adapter,stub-runtime-adapter,terminal-adapter,yolo-mode,non-interruptive,kernel-authority}.ts`,
|
||||
`packages/daemon/src/domain/{native-resume-probe,resume-metadata-refresher,codex-thread-id,claude-managed-launch,codex-network-default,native-permission-store}.ts`,
|
||||
`packages/daemon/src/domain/permission-policy/policy-ref.ts`.
|
||||
`packages/daemon/src/adapters/{claude-code-adapter,codex-runtime-adapter,pi-runtime-adapter,omp-runtime-adapter,stub-runtime-adapter,terminal-adapter}.ts`,
|
||||
`packages/daemon/src/domain/{native-resume-probe,resume-metadata-refresher,codex-thread-id}.ts`.
|
||||
@@ -11,8 +11,8 @@ applies-when: |
|
||||
resolve and preserve identity.
|
||||
siblings: [daemon-core.md, adapters-and-runtimes.md, lifecycle-snapshot-restore.md, packaging-bootstrap-bundles.md]
|
||||
prerequisite-reads: [../README.md, daemon-core.md]
|
||||
last-verified-against-source: e8f0ab340db773392ec8be75b072d1c0f3068a50
|
||||
last-updated: 2026-10-08
|
||||
last-verified-against-source: b6d37bfadcc189be8fd61e35abfc09676437bf48
|
||||
last-updated: 2026-10-03
|
||||
---
|
||||
|
||||
# Agent/Rig Spec, Resolution, Startup, Identity
|
||||
@@ -22,44 +22,41 @@ and identity-addressable topology. The spec-and-startup contract: parse →
|
||||
resolve → project → deliver pre-launch files → persist replay context → launch
|
||||
→ wait → deliver post-launch files.
|
||||
|
||||
> Verified against source at main `e8f0ab340db773392ec8be75b072d1c0f3068a50`. `domain/…` and `routes/…` paths
|
||||
> Verified against source at main `b6d37bfadcc189be8fd61e35abfc09676437bf48`. `domain/…` and `routes/…` paths
|
||||
> are under `packages/daemon/src/`; a bare file name such as
|
||||
> `rigspec-schema.ts:119` is in `packages/daemon/src/domain/`. Each count sits
|
||||
> `rigspec-schema.ts:115` is in `packages/daemon/src/domain/`. Each count sits
|
||||
> beside the command that produces it; run the command from the repository
|
||||
> root to refresh it.
|
||||
|
||||
## 1. Canonical spec and topology types
|
||||
|
||||
- **AgentSpec** (`types.ts:941`) — parsed from `agent.yaml`
|
||||
- **AgentSpec** (`types.ts:938`) — parsed from `agent.yaml`
|
||||
(`agent-resolver.ts:150`). Owns imports, defaults, startup, resources, and
|
||||
profiles. Canonical parse/normalize/validate is `domain/agent-manifest.ts`.
|
||||
- **RigSpec** (`types.ts:1172`) — canonical pod-aware rig topology. Uses
|
||||
- **RigSpec** (`types.ts:1169`) — canonical pod-aware rig topology. Uses
|
||||
`version: "0.2"` and `pods[]`; owns cross-pod `edges[]`, rig-level startup
|
||||
overlays, and `cultureFile`, plus the optional `summary`, `permissionPolicy`,
|
||||
`nonInterruptive`, `managedBlocks`, `docs`, `services` and `workspace` fields.
|
||||
An authored `non_interruptive` must be a boolean (`rigspec-schema.ts:179`) and
|
||||
sets the rig's saved non-interruptive choice at instantiation unless an
|
||||
explicit launch option is given (`rigspec-instantiator.ts:1345`).
|
||||
`managedBlocks`, `docs`, `services` and `workspace` fields.
|
||||
|
||||
`version` is the spec-schema version, not the package version. It is not a
|
||||
code constant: `RigSpecSchema.validate` requires only a non-empty string
|
||||
(`rigspec-schema.ts:119`) and `RigSpecSchema.normalize` carries the authored
|
||||
value through (`rigspec-schema.ts:253`). `"0.2"` is the canonical authored
|
||||
(`rigspec-schema.ts:115`) and `RigSpecSchema.normalize` carries the authored
|
||||
value through (`rigspec-schema.ts:243`). `"0.2"` is the canonical authored
|
||||
value, and the pod-aware exporter writes it (`rigspec-exporter.ts:223`).
|
||||
|
||||
- **RigServicesSpec** (`types.ts:1221`) — optional `services` block on a
|
||||
- **RigServicesSpec** (`types.ts:1216`) — optional `services` block on a
|
||||
pod-aware RigSpec. Shipped kind is Compose-backed env management
|
||||
(`kind: "compose"`) with `composeFile`, `projectName?`, `profiles?`,
|
||||
`downPolicy?`, `waitFor?`, `surfaces?`, `checkpoints?`.
|
||||
- **RigSpecPod** (`types.ts:1128`) — pod-local bounded context with
|
||||
- **RigSpecPod** (`types.ts:1125`) — pod-local bounded context with
|
||||
`members[]`, pod-local `edges[]`, pod startup, optional continuity policy.
|
||||
- **RigSpecPodMember** (`types.ts:1072`) — member-level runtime/startup
|
||||
- **RigSpecPodMember** (`types.ts:1069`) — member-level runtime/startup
|
||||
surface: `agentRef`, `profile`, `runtime`, `model?`, `effort?`, `cwd`, `restorePolicy?`,
|
||||
member startup overlays (`startup?`), plus `label?`, `codexConfigProfile?`,
|
||||
`role?`, `permissionPolicy?`, `compactionStrategy?`, `mechanic?`,
|
||||
`sessionSource?` and `starterRef?`.
|
||||
- **Pod** (`types.ts:10`) — persisted DB entity for a pod.
|
||||
- **ContinuityState** (`types.ts:20`) — persisted live continuity row keyed by
|
||||
- **Pod** (`types.ts:8`) — persisted DB entity for a pod.
|
||||
- **ContinuityState** (`types.ts:18`) — persisted live continuity row keyed by
|
||||
`podId + nodeId` (`PRIMARY KEY (pod_id, node_id)`,
|
||||
`packages/daemon/src/db/migrations/014_agentspec_reboot.ts:24`).
|
||||
|
||||
@@ -68,28 +65,24 @@ resolve → project → deliver pre-launch files → persist replay context →
|
||||
Restore/snapshot types are detailed in `lifecycle-snapshot-restore.md`; the
|
||||
spec/projection types live here.
|
||||
|
||||
- **ResolvedNodeConfig** (`profile-resolver.ts:33`) — output of profile
|
||||
- **ResolvedNodeConfig** (`profile-resolver.ts:31`) — output of profile
|
||||
resolution. Carries effective runtime/model/effort/cwd, narrowed restore policy,
|
||||
selected resources, layered startup block, resolved spec identity, and the
|
||||
resolved compaction strategy, continuity mechanic, lifecycle, activity and
|
||||
skill loadout.
|
||||
- **ProjectionPlan** (`projection-planner.ts:42`) — runtime projection plan for
|
||||
selected resources, layered startup block, resolved spec identity.
|
||||
- **ProjectionPlan** (`projection-planner.ts:41`) — runtime projection plan for
|
||||
a node: runtime, cwd, projection entries, startup block, diagnostics,
|
||||
conflict/no-op classifications.
|
||||
- **RuntimeAdapter** (`runtime-adapter.ts:143`) — the five-method contract
|
||||
- **RuntimeAdapter** (`runtime-adapter.ts:134`) — the five-method contract
|
||||
(adapter detail in `adapters-and-runtimes.md`): `listInstalled(binding)`
|
||||
(`runtime-adapter.ts:153`), `project(plan, binding)` (`:156`),
|
||||
`deliverStartup(files, binding, sendInteractiveText?)` (`:160`),
|
||||
`launchHarness(binding, opts)` (`:170`), `checkReady(binding)` (`:176`). The
|
||||
interface also declares an optional `claudeManagedLaunch` property (`:145`)
|
||||
and an optional method, `skillTargetPath?(...)` (`:150`). Required methods:
|
||||
**5**
|
||||
(`runtime-adapter.ts:144`), `project(plan, binding)` (`:147`),
|
||||
`deliverStartup(files, binding)` (`:150`), `launchHarness(binding, opts)`
|
||||
(`:160`), `checkReady(binding)` (`:166`). The interface also declares one
|
||||
optional method, `skillTargetPath?(...)` (`:141`). Required methods: **5**
|
||||
(`sed -n '/^export interface RuntimeAdapter /,/^}/p' packages/daemon/src/domain/runtime-adapter.ts | grep -c -E '^ [a-zA-Z]+\('`).
|
||||
- **HarnessLaunchResult** (`runtime-adapter.ts:97`) — returned by
|
||||
- **HarnessLaunchResult** (`runtime-adapter.ts:88`) — returned by
|
||||
`launchHarness`: either `{ ok: true, resumeToken?, resumeType?,
|
||||
appliedLaunch? }` or `{ ok: false, error, recovery?, evidence? }`, where
|
||||
`recovery` is `"retry_fresh"` or `"attention_required"` (`:95`).
|
||||
- **StartupOrchestrator** (`startup-orchestrator.ts:140`) — drives the full
|
||||
`recovery` is `"retry_fresh"` or `"attention_required"` (`:86`).
|
||||
- **StartupOrchestrator** (`startup-orchestrator.ts:107`) — drives the full
|
||||
startup sequence (§4 below).
|
||||
|
||||
## 3. Parsing, validation, resolution pipeline
|
||||
@@ -119,126 +112,32 @@ them imports Hono: **0**
|
||||
- `startup-resolver.ts` — additive startup layering.
|
||||
- `projection-planner.ts` — runtime resource projection planning.
|
||||
|
||||
### Profile resolution during launch
|
||||
|
||||
Preflight already resolves profiles in `profile-resolution-worker.ts`. Previously,
|
||||
the pod-aware apply path, materialized-member launch and first-start retry called
|
||||
the synchronous resolver again on the daemon's request thread. A fallback skill
|
||||
scan or managed-catalog inspection could therefore delay every other request even
|
||||
after preflight had finished ([#1653](https://github.com/mvschwarz/openrig/issues/1653)).
|
||||
Those three launch paths now await the same resolver in a worker before projecting
|
||||
resources or starting the member. Configuration precedence and launch order still
|
||||
come from the existing resolver and instantiator.
|
||||
|
||||
An apply operation reuses one lazy worker across its members and terminates it on
|
||||
success or failure. Unlike preflight, launch supplies no `scanScope`: each member
|
||||
reads current files, including changes made by an earlier member's startup.
|
||||
Standalone member launches and first-start retries use a short-lived worker for
|
||||
their resolution. This adds worker startup and context-copy costs; it does not
|
||||
reuse the preflight result or cache configuration between requests. The helper's
|
||||
existing synchronous fallback for a deleted process working directory remains.
|
||||
|
||||
Worker errors become configuration-failure results. Apply can then follow the
|
||||
existing all-members-failed cleanup, including service rollback and restoration
|
||||
of replaced generations. Materialized launches report a failed member, and
|
||||
first-start retries refuse before writing retained state.
|
||||
|
||||
`profile-resolution-worker.test.ts` holds a real fallback scan open with a FIFO,
|
||||
requires an HTTP health response while that FIFO is still blocked, then checks
|
||||
that the selected skill reaches projection. It covers all three launch paths and
|
||||
a skill edit between members. These fixtures use SQLite and the real instantiator
|
||||
with a simulated runtime; they do not establish native provider behavior or
|
||||
responsiveness during other synchronous parts of startup.
|
||||
|
||||
## 4. Startup orchestration (the spec-startup contract)
|
||||
|
||||
`StartupOrchestrator.startNode` (`startup-orchestrator.ts:172`, a thin wrapper
|
||||
over `startNodeWithWarnings`, `:178`) drives, in source order: apply the seat's
|
||||
permission selection and the rig's non-interruptive setting to the binding
|
||||
(`NativePermissionStore.apply`, `:183`; `:193`) → mark pending (`:209`) and
|
||||
select the startup proof (`:210`) → project resources (`:224`) → deliver
|
||||
pre-launch files (`:266`) → persist startup context (`:282`) → launch harness,
|
||||
recording any resume token (`:301`, `:313`) → wait for ready (`:384`) → deliver
|
||||
the session identity prompt and interactive files (`:420`, `:473`) → execute
|
||||
`after_files` then the remaining `after_ready` actions (`:495`, `:502`; see
|
||||
the resume preload below) → check readiness
|
||||
again and, for a Claude resume, that the launched session agrees with the
|
||||
requested token (`:507`–`535`) → mark ready (`:538`). The class doc comment
|
||||
(`startup-orchestrator.ts:120`–`139`) lists ten steps; the code persists the
|
||||
startup context before the harness launch.
|
||||
`StartupOrchestrator.startNode` (`startup-orchestrator.ts:129`) drives, in
|
||||
source order: mark pending (`:156`) → project resources (`:167`) → deliver
|
||||
pre-launch files (`:207`) → persist startup context (`:222`) → launch harness,
|
||||
recording any resume token (`:237`) → wait for ready (`:322`) → deliver
|
||||
interactive files (`:403`) → execute `after_files` then `after_ready` actions
|
||||
(`:426`, `:432`) → mark ready (`:466`). The class doc comment
|
||||
(`startup-orchestrator.ts:90`–`101`) still lists persistence as step 9, after
|
||||
the actions; the code persists the startup context before the harness launch.
|
||||
|
||||
**Pre-launch vs interactive delivery split** — the load-bearing seam:
|
||||
|
||||
- Pre-launch (filesystem, before harness boot): `guidance_merge`,
|
||||
`skill_install` (`startup-orchestrator.ts:126` — "Deliver pre-launch files
|
||||
(guidance_merge, skill_install → filesystem)"; delivered at `:266`). Any
|
||||
file that is not `send_text` is delivered here.
|
||||
`skill_install` (`startup-orchestrator.ts:93` — "Deliver pre-launch files
|
||||
(guidance_merge, skill_install → filesystem)"; delivered at `:207`).
|
||||
- Post-launch (TUI, after harness is ready): `send_text`
|
||||
(`startup-orchestrator.ts:130`; held for post-launch and delivered after
|
||||
readiness at `:473`). Rebuild artifacts are put in front of these files.
|
||||
- **Fresh launch:** the builtin `session_identity` action
|
||||
(`rigspec-instantiator.ts:2655`) is sent as one turn together with the first
|
||||
`send_text` file (`deliverInitialSessionPrompt`, `startup-orchestrator.ts:663`).
|
||||
- **Resume, fork or rebuild:** applicable `after_ready` `send_text` actions are
|
||||
sent ahead of the first `send_text` file as one turn.
|
||||
(`startup-orchestrator.ts:97`; partition by concrete hint at `:182`,
|
||||
`send_text` files held for post-launch at `:200`, delivered after readiness
|
||||
at `:403`).
|
||||
|
||||
The orchestrator persists replay context for future restores (consumed by
|
||||
`lifecycle-snapshot-restore.md`): the projection entries, resolved startup
|
||||
files, startup actions and runtime go to `node_startup_context`
|
||||
(`startup-orchestrator.ts:282`), and a resume token returned by the launch is
|
||||
written to the session row (`updateResumeToken`, `:313`).
|
||||
|
||||
**Checked startup text (Claude Code).** Interactive text for a Claude seat goes
|
||||
through `sendInteractiveText` (`:777`): paste, wait 200 ms, press Enter, wait
|
||||
200 ms, then read 200 lines of the pane. `inspectStartupStagedText`
|
||||
(`startup-submission-evidence.ts:36`) classifies the composer as clear, staged
|
||||
or unverified. While the composer shows Claude's own collapsed-paste label for
|
||||
this text (`startupOwnCollapsedPaste`, `:49`), `settleOwnPaste`
|
||||
(`startup-orchestrator.ts:867`) looks again, up to 25 times 200 ms apart,
|
||||
without pressing anything. Text still staged gets one guarded Enter-only retry
|
||||
(`:823`), and then a "press Enter in that pane" warning (`:836`). An
|
||||
unverified or staged result is a warning, never a startup failure, and is
|
||||
reported in a `submission` block on `node.startup_ready` and on the result.
|
||||
|
||||
**Startup proof.** A seat can be `ready` without being oriented.
|
||||
`resolveStartupProof` (`startup-resolver.ts:81`) selects the last applicable
|
||||
authored `startup_proof` action; the default is none. For a fresh launch on a
|
||||
non-terminal runtime in `authenticated` mode, the orchestrator issues a
|
||||
challenge after readiness (`issueStartupChallenge`, `startup-proof.ts:90`),
|
||||
recorded as `node.startup_challenged` with a hash of the resolved startup files.
|
||||
The expected answer is derived from the challenge and that hash
|
||||
(`computeExpectedAnswer`, `:53`) and is never stored. The challenge text is
|
||||
appended to the identity prompt, or sent on its own when there is no identity
|
||||
action (`startup-orchestrator.ts:487`). On Claude, a short proof instruction
|
||||
line (`STARTUP_PROOF_INSTRUCTION_LINE`, `startup-proof.ts:63`) is sent only
|
||||
after the startup prompt was confirmed submitted (`sendProofInstruction`,
|
||||
`startup-orchestrator.ts:760`). The seat answers with
|
||||
`rig startup-proof submit --challenge-id … --answer …`
|
||||
(`packages/cli/src/commands/startup-proof.ts:99`), which posts to the activity
|
||||
hook route (`routes/activity.ts:239`); `verifyStartupProof`
|
||||
(`startup-proof.ts:133`) records `node.startup_proof_verified` or
|
||||
`node.startup_proof_rejected`. Orientation status is derived from those events
|
||||
(`startup-proof.ts:239`), never from `startup_status`. Other fresh launches (no
|
||||
proof selected, or a terminal runtime) record `node.startup_proof_skipped`
|
||||
(`startup-orchestrator.ts:374`); resume, fork and rebuild keep the existing proof
|
||||
history.
|
||||
|
||||
**Pending startup context and `rig seat continue`.** When a fresh launch stops at
|
||||
a native prompt before its context is delivered, `fail()` (`:806`) marks the
|
||||
failure `freshContextPending` and adds "run: rig seat continue <session>". A
|
||||
Codex fork whose own id isn't verified at launch, or whose readiness times out,
|
||||
ends `attention_required` with `forkContextPending` (its parent token) instead:
|
||||
the role waits, and nothing is saved for an unverified child.
|
||||
`canContinueStartup` (`:764`, using `readPendingStartupContext`, `:46`) allows
|
||||
continuation only while that failure is the occupant's latest startup event.
|
||||
`continueStartup` (`seat-lifecycle-service.ts:723`) re-checks the binding,
|
||||
pane and runtime, then runs startup again on the same conversation without
|
||||
relaunching the harness. A fork continuation first re-verifies the child with
|
||||
`captureForkIdentity` (`codex-runtime-adapter.ts:668`; `startup-orchestrator.ts:559`)
|
||||
and needs the exact pending event it started from; a fresh continuation keeps
|
||||
the plain "still pending" check. It is reached by `rig seat continue`,
|
||||
`POST /api/seat/continue/:seatRef` and the per-seat startup route's `continue`
|
||||
action (`routes/startup.ts:159`).
|
||||
files and startup actions go to `node_startup_context`
|
||||
(`startup-orchestrator.ts:225`), and a resume token returned by the launch is
|
||||
written to the session row (`updateResumeToken`, `:254`).
|
||||
|
||||
**Startup layering is additive and ordered** (`resolveStartup`,
|
||||
`startup-resolver.ts:15`–`22`): (1) agent base, (2) profile, (3) rig culture
|
||||
@@ -248,41 +147,31 @@ deduplication (`startup-resolver.ts:24`). This is the spec-startup contract's
|
||||
invariant; the cross-cutting architecture rules are collected in
|
||||
`architecture-rules-and-event-system.md`.
|
||||
|
||||
The launch path takes only the actions from `resolveStartup`. It builds the
|
||||
startup *file* chain itself (`buildResolvedStartupFiles`,
|
||||
`rigspec-instantiator.ts:2518`), in this order: agent base, profile, the shipped
|
||||
`CULTURE-default.md` floor (`:327`), the rig `culture_file`, rig, pod, member,
|
||||
the shipped `openrig-start.md` (`:2572`), and, for fresh launches when enabled,
|
||||
the onboarding files (`:2582`). Managed-block guidance is deduplicated, and a
|
||||
`starter_ref` layer is put in front when a member names one (`:2243`).
|
||||
|
||||
**Startup action constraints** (`startup-validation.ts`): startup entries must
|
||||
be files (`:22`); no shell startup actions (`:65`); action types are
|
||||
`slash_command`, `send_text` and `startup_proof` (`:7`), and a `startup_proof`
|
||||
action must be idempotent with a value of `authenticated` or `none` (`:73`);
|
||||
non-idempotent actions must not apply on restore (`:100`). Retrying a failed
|
||||
startup is handled as a restore, which is why the orchestrator skips
|
||||
non-idempotent actions on restore (`startup-orchestrator.ts:634`,
|
||||
"retry-as-restore safety"). The exception is
|
||||
`PodRigInstantiator.retryFirstStart` (`rigspec-instantiator.ts:1147`), which
|
||||
**Startup action constraints** (`startup-validation.ts`): no shell startup
|
||||
actions (`:65`); action types are `slash_command`, `send_text` and
|
||||
`startup_proof` (`:7`); non-idempotent actions must not apply on restore
|
||||
(`:100`). Retrying a failed startup is handled as a restore, which is why the
|
||||
orchestrator skips non-idempotent actions on restore
|
||||
(`startup-orchestrator.ts:556`, "retry-as-restore safety"). The exception is
|
||||
`PodRigInstantiator.retryFirstStart` (`rigspec-instantiator.ts:1146`), which
|
||||
re-runs a first start that failed at projection, before any harness launch.
|
||||
|
||||
**Remote import constraints**: `agent_ref` and AgentSpec imports accept
|
||||
`local:<relative path>` and `path:<absolute path>` only
|
||||
(`rigspec-schema.ts:41`, `agent-manifest.ts:40`); a terminal member uses the
|
||||
`builtin:terminal` sentinel (`rigspec-schema.ts:532`). Remote `agent_ref`
|
||||
`builtin:terminal` sentinel (`rigspec-schema.ts:519`). Remote `agent_ref`
|
||||
sources remain unsupported: RigSpec validation rejects them
|
||||
(`rigspec-schema.ts:563`), `rigPreflight` runs that validation
|
||||
(`rigspec-preflight.ts:252`), and the resolver refuses a remote import again
|
||||
(`rigspec-schema.ts:550`), `rigPreflight` runs that validation
|
||||
(`rigspec-preflight.ts:249`), and the resolver refuses a remote import again
|
||||
(`agent-resolver.ts:203`).
|
||||
|
||||
## 5. Instantiation, preflight, export
|
||||
|
||||
- `runtime-adapter.ts` — adapter contract + bridge types.
|
||||
- `rigspec-preflight.ts` — dual-stack legacy preflight (`RigSpecPreflight`,
|
||||
`rigspec-preflight.ts:26`) plus rebooted `rigPreflight(...)` (`:246`).
|
||||
`rigspec-preflight.ts:25`) plus rebooted `rigPreflight(...)` (`:241`).
|
||||
- `rigspec-instantiator.ts` — dual-stack `RigInstantiator`
|
||||
(`rigspec-instantiator.ts:33`) plus `PodRigInstantiator` (`:475`).
|
||||
(`rigspec-instantiator.ts:33`) plus `PodRigInstantiator` (`:474`).
|
||||
- `rigspec-exporter.ts` — dual-format live rig export to YAML/JSON.
|
||||
- `pod-repository.ts` — pod CRUD plus live continuity-state CRUD.
|
||||
|
||||
@@ -297,7 +186,7 @@ preflight (`rigPreflight({ rigSpecYaml, rigRoot, … })` vs
|
||||
`rigspec-exporter.ts:105`).
|
||||
|
||||
The import validation route delegates to `validateRigSpecImport`
|
||||
(`routes/rigspec.ts:215–223`, `spec-validation-service.ts:10–19`). The same
|
||||
(`routes/rigspec.ts:214–222`, `spec-validation-service.ts:10–19`). The same
|
||||
helper powers local `rig spec validate` without contacting the daemon
|
||||
(`packages/cli/src/commands/rig.ts:204–207`); it selects the pod-aware or legacy
|
||||
validator and distinguishes YAML parse failures from validator exceptions.
|
||||
@@ -310,9 +199,7 @@ anchor, not sovereign truth. `whoami-service.ts:8` declares
|
||||
`resolvedBy: "node_id" | "session_name"`. The route requires `nodeId` or
|
||||
`sessionName` (`routes/whoami.ts:19`–`23`). The CLI resolves identity
|
||||
(`packages/cli/src/commands/whoami.ts:142`–`148`) in this order: explicit
|
||||
`--node-id` → explicit `--session` → env vars (`OPENRIG_NODE_ID` /
|
||||
`OPENRIG_SESSION_NAME`, or the legacy `RIGGED_NODE_ID` /
|
||||
`RIGGED_SESSION_NAME`, `whoami.ts:158`) → tmux metadata → raw tmux
|
||||
`--node-id` → explicit `--session` → env vars → tmux metadata → raw tmux
|
||||
session-name fallback.
|
||||
|
||||
- Managed sessions prefer projected `OPENRIG_NODE_ID` /
|
||||
@@ -323,7 +210,7 @@ session-name fallback.
|
||||
The tmux metadata keys use the `@rigged_` prefix:
|
||||
`ClaimService.setRiggedMetadata` writes `@rigged_node_id` /
|
||||
`@rigged_session_name` / `@rigged_rig_id` / `@rigged_rig_name` /
|
||||
`@rigged_logical_id` (`claim-service.ts:182`–`186`), called from `bind`,
|
||||
`@rigged_logical_id` (`claim-service.ts:180`–`184`), called from `bind`,
|
||||
`reconcileSession` and `createAndBindToPod`;
|
||||
`RigLifecycleService.unclaimSession` clears the same five keys
|
||||
(`rig-lifecycle-service.ts:209`–`213`); and `rig whoami` reads
|
||||
@@ -332,8 +219,8 @@ session-name fallback.
|
||||
different prefix, `rig_*` (`packages/cli/src/mcp-server.ts`).
|
||||
|
||||
**Materialize / bind / adopt**: `POST /api/rigs/import/materialize`
|
||||
(`routes/rigspec.ts:176`) creates a pod-aware topology without launching
|
||||
sessions and refuses a legacy spec (`routes/rigspec.ts:189`);
|
||||
(`routes/rigspec.ts:174`) creates a pod-aware topology without launching
|
||||
sessions and refuses a legacy spec (`routes/rigspec.ts:187`);
|
||||
`POST /api/discovery/:id/bind` (`routes/discovery.ts:77`) attaches a
|
||||
discovered live session to an existing logical node (`logicalId`), or creates
|
||||
a member in a pod (`podNamespace` + `memberName`) and binds it;
|
||||
@@ -344,23 +231,9 @@ immediately). On the CLI, `rig bind` calls the bind route
|
||||
topology and then calls the bind route for each session
|
||||
(`packages/cli/src/commands/adopt.ts:163`, `:212`). Authored pod namespace is
|
||||
preserved through adoption so logical ids stay `${podNamespace}.${memberName}`
|
||||
(`claim-service.ts:663`). Adopted-session parity is tmux-metadata parity, not
|
||||
(`claim-service.ts:661`). Adopted-session parity is tmux-metadata parity, not
|
||||
fake env-var parity.
|
||||
|
||||
## 7. Specialist rosters
|
||||
|
||||
A roster is an authored list of recommended specialist seats, kept outside the
|
||||
specs. `rig roster list`, `show <id>` and `find <query>`
|
||||
(`packages/cli/src/commands/roster.ts`) read version-1 roster JSON files from
|
||||
`<workspace.root>/rosters/` (or `--folder`); they are read-only and need no
|
||||
daemon route. Each roster names a purpose and a curator, and each member names
|
||||
a seat, host, capabilities, engagement, `use_when` and `why`. `show` and
|
||||
`find` add current observations of each member by matching host and seat
|
||||
against `rig ps --nodes`, read from the configured daemon and again across
|
||||
registered hosts, and report a gap rather than guessing when no node matches. A roster is a
|
||||
recommendation, not an assignment or an authority. It is unrelated to the
|
||||
topology roster a snapshot records (see `lifecycle-snapshot-restore.md`).
|
||||
|
||||
## See also
|
||||
|
||||
- `daemon-core.md` — createDaemon wiring; the migration/route surface.
|
||||
|
||||
@@ -11,8 +11,8 @@ applies-when: |
|
||||
compatibility limits that still describe the shipped system.
|
||||
siblings: [daemon-core.md, coordination-primitive.md]
|
||||
prerequisite-reads: [../README.md, daemon-core.md]
|
||||
last-verified-against-source: e8f0ab340db773392ec8be75b072d1c0f3068a50
|
||||
last-updated: 2026-10-08
|
||||
last-verified-against-source: b6d37bfadcc189be8fd61e35abfc09676437bf48
|
||||
last-updated: 2026-10-03
|
||||
---
|
||||
|
||||
# Architecture Invariants, Event System, Compatibility Notes
|
||||
@@ -21,7 +21,7 @@ This module collects the cross-cutting invariants that do not belong to any
|
||||
single subsystem: the architecture rules the codebase holds itself to, the
|
||||
event-system shape, and the intentional compatibility limits.
|
||||
|
||||
> Verified against source at main `e8f0ab340db773392ec8be75b072d1c0f3068a50`. Each count below sits beside the
|
||||
> Verified against source at main `b6d37bfadcc189be8fd61e35abfc09676437bf48`. Each count below sits beside the
|
||||
> command that produces it; run the command from the repository root to refresh
|
||||
> it.
|
||||
|
||||
@@ -33,7 +33,7 @@ see `agent-spec-and-startup.md` for their flow detail; they are restated here as
|
||||
system-level invariants.
|
||||
|
||||
1. No runtime Hono in `domain/` and `adapters/`. `adapters/` has none; `domain/`
|
||||
has type-only Hono imports (`import type`) in **4** files
|
||||
has type-only Hono imports (`import type`) in **3** files
|
||||
(`git grep -l 'from "hono' -- packages/daemon/src/domain packages/daemon/src/adapters | wc -l`).
|
||||
2. Routes depend on the domain; the domain does not depend on routes at
|
||||
runtime. **1** type-only import crosses back:
|
||||
@@ -56,27 +56,26 @@ system-level invariants.
|
||||
10. Restore replay uses classification-free projection intent, not stale
|
||||
startup-time `no_op` / conflict classifications.
|
||||
11. Startup status is explicit session state: `pending`, `ready`,
|
||||
`attention_required`, `failed` (`types.ts:102`).
|
||||
`attention_required`, `failed` (`types.ts:100`).
|
||||
12. Session recency depends on monotonic ULIDs: `session-registry.ts` uses
|
||||
`monotonicFactory()`. Restore does not pick the newest session by max
|
||||
ULID; it resolves the active occupant recorded in the snapshot
|
||||
(`resolveActiveSnapshotSession`, `active-occupant.ts:74`, called at
|
||||
`restore-orchestrator.ts:774` and `:971`).
|
||||
`restore-orchestrator.ts:1171`).
|
||||
13. Readiness checking is a retry loop with exponential backoff and
|
||||
configurable timeout, using adapter-specific probes (Claude TUI
|
||||
indicator, Codex ready message, terminal immediate).
|
||||
14. Restore outcome states are a fixed set (`RestoreNodeResult.status`,
|
||||
`types.ts:475`): `resumed`, `rebuilt`, `fresh-primed`,
|
||||
`types.ts:473`): `resumed`, `rebuilt`, `fresh-primed`,
|
||||
`awaiting-decision`, `attention_required`, `failed`, plus
|
||||
`operator_recovered` (set only by later reconciliation), `fresh`
|
||||
(retained only for the legacy continuity-restoring skip path) and
|
||||
`left_attached` (a seat joined with `rig attach` as an external CLI, which
|
||||
restore leaves as it is). `rebuilt` = new process assembled from artifacts.
|
||||
`operator_recovered` (set only by later reconciliation) and `fresh`
|
||||
(retained only for the legacy continuity-restoring skip path). `rebuilt` =
|
||||
new process assembled from artifacts.
|
||||
15. Restore honesty: a failed resume stops loudly as `awaiting-decision`, with
|
||||
the blank session rolled back and no session running
|
||||
(`restore-orchestrator.ts:1055`). No automatic fresh fallback. Fresh launch
|
||||
is explicit follow-up only (`rig up --fresh <seats...>`,
|
||||
`packages/cli/src/commands/up.ts:99`).
|
||||
(`restore-orchestrator.ts:1230`). No automatic fresh fallback. Fresh launch
|
||||
is explicit follow-up only (`rig up --fresh <logicalId>`,
|
||||
`packages/cli/src/commands/up.ts:85`).
|
||||
16. Post-command handoff required on `up`, `down`, `restore`,
|
||||
`snapshot create`: what happened + current state + next action.
|
||||
17. Session naming: `{pod}-{member}@{rig}` — human-authored,
|
||||
@@ -84,17 +83,13 @@ system-level invariants.
|
||||
18. Communication: tmux is transport, not truth. `send/capture/broadcast`
|
||||
wrap tmux reliably with honest errors.
|
||||
19. Transcripts: bounded capture — a periodic `tmux capture-pane` snapshot of
|
||||
the trailing lines (default 1000, every 2 s for an active seat) replaces
|
||||
the transcript file, replacing pipe-pane (`transcript-rotation.ts:3`,
|
||||
`:27`–`28`; started at `node-launcher.ts:181`). An idle seat is captured
|
||||
less often, within the 10-second freshness window (`:29`–`33`,
|
||||
`:162`–`163`), and the file is rewritten only when the captured bytes
|
||||
change (`:270`). `readTail` and `grep` strip ANSI; `readFull` returns the
|
||||
content unfiltered. `rig ask` transcript search: `rg`
|
||||
preferred, `grep -E` fallback.
|
||||
the trailing lines (default 1000, every 2 s) overwrites the transcript
|
||||
file, replacing pipe-pane (`transcript-rotation.ts:3`, `:27`–`28`; started
|
||||
at `node-launcher.ts:181`). ANSI strip on read. `rig ask` transcript
|
||||
search: `rg` preferred, `grep -E` fallback.
|
||||
20. Config precedence: CLI flag > env var > config file
|
||||
(`~/.openrig/config.json`, or `$OPENRIG_HOME/config.json` when
|
||||
`OPENRIG_HOME` is set; `packages/cli/src/config-store.ts:939`) > default.
|
||||
`OPENRIG_HOME` is set; `packages/cli/src/config-store.ts:915`) > default.
|
||||
21. Semi-deterministic calibration: build what agents use constantly. Agent
|
||||
handles edge cases from error messages.
|
||||
22. `rig ask` is context engineering: gathers evidence, does NOT call an
|
||||
@@ -120,45 +115,15 @@ system-level invariants.
|
||||
|
||||
The reboot supports `local:...` and `path:/abs/...` agent refs. Remote
|
||||
`agent_ref` sources remain unsupported and fail in preflight (schema
|
||||
validation, `rigspec-schema.ts:563`; restated in compat note 1).
|
||||
|
||||
### Startup, delivery and launch invariants
|
||||
|
||||
These hold across the startup, transport and adapter code and are stated in its
|
||||
comments:
|
||||
|
||||
- **`ready` is not "submitted" and not "oriented".** A seat can reach
|
||||
`startupStatus: ready` while its startup text is unverified or still staged;
|
||||
`node.startup_ready` carries a `submission` block saying which
|
||||
(`types.ts:220`). Orientation is a separate, challenge-verified proof:
|
||||
`ready` never means oriented (`types.ts:222`–`227`). See
|
||||
`agent-spec-and-startup.md`.
|
||||
- **Default sends never block on busy or unknown.** `--wait-for-idle` is the
|
||||
caller's opt-in to wait, and a failed wait returns without sending. Otherwise
|
||||
only positive evidence of an open
|
||||
picker or approval prompt refuses a send; a busy or unknown seat gets the
|
||||
message with an advisory warning (`session-transport.ts:1427`–`1433`). The
|
||||
audited `--dangerously-interact` override is the only way past an open prompt.
|
||||
- **Non-interruptive mode is per-launch flags only.** It never changes
|
||||
permissions or native settings files, applies only to full-bypass Claude Code
|
||||
and Codex seats, and is saved per rig, off by default
|
||||
(`adapters/non-interruptive.ts:9`–`26`; `rigs.non_interruptive`, migration
|
||||
`095`). A rig spec can author it as `non_interruptive` (`rigspec-schema.ts:179`).
|
||||
- **Inside a notify envelope, events are delivered from the log.** Within
|
||||
`withNotifyEnvelope` (`event-bus.ts:106`–`112`), every event persisted through
|
||||
the event bus must be registered before the callback returns; after commit
|
||||
the bus delivers the committed rows from the log, and an unreadable row
|
||||
emits `event.delivery_poisoned`. Legacy callers outside an envelope persist
|
||||
inside their own transaction and notify subscribers explicitly after commit
|
||||
(`persistWithinTransaction`, `:70`; for example `node-launcher.ts:241`).
|
||||
validation, `rigspec-schema.ts:550`; restated in compat note 1).
|
||||
|
||||
## 2. Event system
|
||||
|
||||
The daemon's event surface is the single `RigEvent` discriminated union.
|
||||
|
||||
`RigEvent` is declared at `packages/daemon/src/domain/types.ts:108`
|
||||
(`export type RigEvent =`) and runs through `types.ts:313`. It has **98 union
|
||||
members** declaring **99** `type` literals: one member (`types.ts:109`) carries
|
||||
`RigEvent` is declared at `packages/daemon/src/domain/types.ts:106`
|
||||
(`export type RigEvent =`) and runs through `types.ts:311`. It has **98 union
|
||||
members** declaring **99** `type` literals: one member (`types.ts:107`) carries
|
||||
both `proof.judged` and `proof.sources_changed`.
|
||||
|
||||
- Members:
|
||||
@@ -179,30 +144,30 @@ List them with:
|
||||
### Per-prefix event families
|
||||
|
||||
Each count below is the number of `type` literals per prefix in the union body
|
||||
(`types.ts:108`–`313`):
|
||||
(`types.ts:106`–`311`):
|
||||
`sed -n '/^export type RigEvent =/,/^export type PersistedEvent/p' packages/daemon/src/domain/types.ts | grep -oE '"[a-z_]+(\.[a-z_]+)+"' | tr -d '"' | cut -d. -f1 | sort | uniq -c | sort -rn`.
|
||||
|
||||
| Prefix | Types | Sample / role |
|
||||
|---|---|---|
|
||||
| `node.*` | 15 | `node.added` (`types.ts:126`) … `node.startup_proof_rejected` (`:229`) — lifecycle/startup |
|
||||
| `node.*` | 15 | `node.added` (`types.ts:124`) … `node.startup_proof_rejected` (`:227`) — lifecycle/startup |
|
||||
| `workflow.*` | 8 | workflow runtime (detail in `workflow-runtime.md`) |
|
||||
| `session.*` | 8 | session discovery / status / detach / vanish / stop / clean / resume-token audit |
|
||||
| `rig.*` | 7 | `rig.created` / `rig.deleted` / `rig.imported` / `rig.stopped` / `rig.archived` / `rig.unarchived` / `rig.expanded` (`:241`) |
|
||||
| `watchdog.*` | 5 | `watchdog.evaluation_fired` (`:280`) … `watchdog.job_stopped` (`:284`) |
|
||||
| `seat.*` | 5 | `seat.model_divergence` (`:115`) … `seat.handover_completed` (`:200`) — model divergence, fresh launch, attention clear, handover |
|
||||
| `queue.*` | 5 | queue lifecycle (`:249`–`:252`, `:262`; detail in `coordination-primitive.md`) |
|
||||
| `rig.*` | 7 | `rig.created` / `rig.deleted` / `rig.imported` / `rig.stopped` / `rig.archived` / `rig.unarchived` / `rig.expanded` (`:239`) |
|
||||
| `watchdog.*` | 5 | `watchdog.evaluation_fired` (`:278`) … `watchdog.job_stopped` (`:282`) |
|
||||
| `seat.*` | 5 | `seat.model_divergence` (`:113`) … `seat.handover_completed` (`:198`) — model divergence, fresh launch, attention clear, handover |
|
||||
| `queue.*` | 5 | queue lifecycle (`:247`–`:250`, `:260`; detail in `coordination-primitive.md`) |
|
||||
| `package.*` | 5 | legacy package/install engine events |
|
||||
| `mission_control.*` | 4 | audit/notification (`:308`–`:313`; detail in `mission-control.md`) |
|
||||
| `mission_control.*` | 4 | audit/notification (`:306`–`:311`; detail in `mission-control.md`) |
|
||||
| `bootstrap.*` | 5 | legacy bootstrap-run events |
|
||||
| `restore.*` | 4 | restore start/complete/subset-complete/reconcile (detail in `lifecycle-snapshot-restore.md`) |
|
||||
| `classifier.*` | 4 | classifier-lease lifecycle |
|
||||
| `qitem.*` | 2 | `qitem.fallback_routed` (`:253`), `qitem.closure_overdue` (`:254`) |
|
||||
| `proof.*` | 2 | `proof.judged`, `proof.sources_changed` — one union member (`:109`) |
|
||||
| `pod.*` | 2 | `pod.created` (`:215`), `pod.deleted` (`:216`) |
|
||||
| `inbox.*` | 2 | `inbox.absorbed` (`:255`), `inbox.denied` (`:256`) |
|
||||
| `continuity.*` | 2 | `continuity.sync` (`:230`), `continuity.degraded` (`:231`) |
|
||||
| `agent.*` | 2 | `agent.activity` (`:151`), `agent.session_identity` (`:158`) |
|
||||
| singletons | 12 | one type each: `workflow_spec.*`, `view.*`, `transport.*` (`:155`), `topology.*` (`:138`), `stream.*` (`:245`), `snapshot.*`, `project.*`, `kernel.*`, `event.*` (`:110`), `chat.*` (`:239`), `bundle.*`, `binding.*` |
|
||||
| `qitem.*` | 2 | `qitem.fallback_routed` (`:251`), `qitem.closure_overdue` (`:252`) |
|
||||
| `proof.*` | 2 | `proof.judged`, `proof.sources_changed` — one union member (`:107`) |
|
||||
| `pod.*` | 2 | `pod.created` (`:213`), `pod.deleted` (`:214`) |
|
||||
| `inbox.*` | 2 | `inbox.absorbed` (`:253`), `inbox.denied` (`:254`) |
|
||||
| `continuity.*` | 2 | `continuity.sync` (`:228`), `continuity.degraded` (`:229`) |
|
||||
| `agent.*` | 2 | `agent.activity` (`:149`), `agent.session_identity` (`:156`) |
|
||||
| singletons | 12 | one type each: `workflow_spec.*`, `view.*`, `transport.*` (`:153`), `topology.*` (`:136`), `stream.*` (`:243`), `snapshot.*`, `project.*`, `kernel.*`, `event.*` (`:108`), `chat.*` (`:237`), `bundle.*`, `binding.*` |
|
||||
|
||||
Family counts sum to 99 type literals (18 multi-type families totalling 87 +
|
||||
12 singletons).
|
||||
@@ -221,47 +186,14 @@ SSE delivery surfaces include the following. The daemon has **11**
|
||||
(`git grep -o 'streamSSE(' -- packages/daemon/src/routes | wc -l`;
|
||||
`git grep -l 'streamSSE(' -- packages/daemon/src/routes | wc -l`).
|
||||
|
||||
- `GET /api/events` — global stream of all events (`server.ts:730`
|
||||
`app.route("/api/events", eventsRoute)`); `?rigId=` keeps one rig's. Each
|
||||
event's SSE `id` is its `seq`. Before going live, a connection replays
|
||||
stored events, read and written 500 at a time (`routes/events.ts`):
|
||||
- with a `Last-Event-ID` header (an `EventSource` sends it when it
|
||||
reconnects), every event after that `seq`, whatever `replay` says;
|
||||
- otherwise `?replay=<n>`: the newest `n` events (of the rig, with
|
||||
`rigId`); `replay=0` starts from now; `replay=all`, no `replay`, a
|
||||
count past the log's size, or any other value, replays the whole log.
|
||||
|
||||
Either way the replay ends at the newest event stored as the connection
|
||||
subscribes; the events stored meanwhile were buffered and follow it, each
|
||||
once and in order, before the stream goes live.
|
||||
- `GET /api/events` — global stream of all events (`server.ts:731`
|
||||
`app.route("/api/events", eventsRoute)`).
|
||||
- `GET /api/stream/watch` — new stream items (`routes/stream.ts:194`).
|
||||
- `GET /api/queue/watch` — queue/inbox coordination events
|
||||
(`routes/queue.ts:1054`, with a `/sse` alias at `:1055`).
|
||||
(`routes/queue.ts:994`).
|
||||
- The chat SSE stream `GET /api/rigs/:rigId/chat/watch` delivers
|
||||
`chat.message` for one rig (`routes/chat.ts:82`, mounted at `server.ts:782`;
|
||||
`chat.message` for one rig (`routes/chat.ts:68`, mounted at `server.ts:783`;
|
||||
rig-scoped; see compat note 6).
|
||||
- The other SSE routes are activity events and the watch or `sse` routes for
|
||||
mission control, projects, views, watchdog and workflow; list them with
|
||||
`git grep -n 'streamSSE(' -- packages/daemon/src/routes`.
|
||||
|
||||
### Telemetry read surface
|
||||
|
||||
`/api/telemetry` (`server.ts:822`; `routes/telemetry.ts`) is a read-only,
|
||||
paged view over the event log and queue history, built by
|
||||
`readTelemetryPage()` in `packages/daemon/src/domain/finite-telemetry.ts`. It
|
||||
serves three streams: `GET /api/telemetry/v1/events`, `/v1/queue-transitions`
|
||||
(active and archived transitions) and `/v1/nodes/:nodeId/tenures` (a node's
|
||||
occupant tenures). Each page is one read with no writes or subscription,
|
||||
bounded at 128 rows and 128 KiB (`TELEMETRY_LIMITS`), and resumed with a
|
||||
cursor. Rows carry metadata only, never event payloads, notes or bodies, and
|
||||
the response names gaps in the history it could not vouch for (for example a
|
||||
daemon restart boundary or rows before the retained floor) instead of
|
||||
presenting a partial history as complete. The page records the source host and
|
||||
the daemon's boot epoch. Bad input returns `400 telemetry_invalid_request`; a
|
||||
failed read returns `503 telemetry_read_unavailable`. The same route also
|
||||
serves the usage series behind `rig usage` (`/usage/series`, `/usage/top`).
|
||||
`rig telemetry events|transitions|tenures`
|
||||
(`packages/cli/src/commands/telemetry.ts`) prints one bounded page.
|
||||
|
||||
## 3. Remaining compatibility notes
|
||||
|
||||
@@ -278,15 +210,9 @@ Intentional limits that still describe the shipped system:
|
||||
5. `rig ask` transcript search prefers `rg`, falls back to `grep -E`
|
||||
(`history-query.ts:252`, `:267`); quality/perf varies by backend.
|
||||
6. Chat is rig-scoped only — no cross-rig channels or DMs.
|
||||
7. `--verify` on `rig send` reports what the pane shows, not agent
|
||||
acknowledgement. By default it compares the message (whole for a
|
||||
header-carrying send, the first 40 characters for a raw one) in captures
|
||||
before and after the send, leaving out the current input box; with
|
||||
`transport.verify_input_box` on, Claude Code and Codex sends are verified
|
||||
only for a seat proven idle before the paste and on input-box evidence; a
|
||||
busy or unknown seat reads unconfirmed (`transport-and-transcripts.md` §3
|
||||
step 5).
|
||||
When it cannot confirm, it reports `rendered-unconfirmed`, not a failure.
|
||||
7. `--verify` on `rig send` checks pane content for message visibility, not
|
||||
agent acknowledgement: it compares occurrences of the message's first 40
|
||||
characters before and after the send (`session-transport.ts:1413`–`1415`).
|
||||
8. Terminal node readiness is shell-ready only — no service health probes.
|
||||
9. Managed-app service surfaces are descriptive only — OpenRig does not
|
||||
auto-inject service URLs/tokens into agent prompts beyond authored
|
||||
|
||||
@@ -7,13 +7,13 @@ domains: [engineering-advisor, operating-advisor]
|
||||
applies-when: |
|
||||
Tracing allowlisted file access, conflict-checked writes, progress indexing,
|
||||
steering composition, or the daemon health-summary endpoints.
|
||||
last-verified-against-source: e8f0ab340db773392ec8be75b072d1c0f3068a50
|
||||
last-updated: 2026-10-08
|
||||
last-verified-against-source: 254122872cf477511514979a4300b695d77cd1f7
|
||||
last-updated: 2026-10-03
|
||||
---
|
||||
|
||||
# Content Surfaces — Files, Progress, Steering, and Health
|
||||
|
||||
Source snapshot: `e8f0ab340db773392ec8be75b072d1c0f3068a50`. This describes the source at that commit;
|
||||
Source snapshot: `254122872cf477511514979a4300b695d77cd1f7`. This describes the source at that commit;
|
||||
it does not establish the version or behavior of a running daemon.
|
||||
|
||||
The daemon exposes filesystem content through the files, progress, and
|
||||
@@ -34,11 +34,8 @@ resolves environment overrides, then settings-file values, then defaults.
|
||||
`files.allowlist` and `progress.scan_roots` both default to
|
||||
`workspace:<resolved-workspace-root>`. Their environment overrides are
|
||||
`OPENRIG_FILES_ALLOWLIST` and `OPENRIG_PROGRESS_SCAN_ROOTS`. Thus, an unset
|
||||
or empty environment variable, or an empty settings-file value, does **not**
|
||||
imply an empty allowlist in normal daemon startup. A non-empty value is not
|
||||
validated: the decoders silently skip malformed entries (no `name:` prefix, or
|
||||
a relative path), so a malformed value can leave no configured roots. Some source comments and route hints still say
|
||||
otherwise or point only at the environment variable. The standalone `readAllowlistFromEnv` helper has different inputs
|
||||
environment variable does **not** imply an empty allowlist in normal daemon
|
||||
startup. The standalone `readAllowlistFromEnv` helper has different inputs
|
||||
and retains its legacy environment fallback.
|
||||
|
||||
Roots use comma-separated `name:/absolute/path` pairs. The decoders skip
|
||||
@@ -61,11 +58,7 @@ is shared by the HTTP reader and the local TUI reader. It returns content,
|
||||
absolute and root-relative resolved paths, mtime, full-file SHA-256, size,
|
||||
binary classification, and truncation metadata. The returned text is capped
|
||||
at **1,048,576 bytes**, but the full file is read and hashed. The cap limits
|
||||
the response, not the memory required to read the file. The TUI's local
|
||||
reader runs as a CLI subprocess without the daemon: it resolves
|
||||
`files.allowlist` from the CLI configuration, offers four fixed workspace
|
||||
targets as roots, and hides dot-prefixed entries in listings
|
||||
(`packages/cli/src/local-reading.ts`).
|
||||
the response, not the memory required to read the file.
|
||||
|
||||
## Writes and audit
|
||||
|
||||
@@ -80,9 +73,6 @@ the read/compare/replace sequence.
|
||||
`createAtomic` handles new files. It creates and fsyncs a temporary file, then
|
||||
uses an exclusive hard link to establish the target. If the target already
|
||||
exists, it returns the `target_exists` error instead of overwriting it.
|
||||
`createAtomic` is used by the Living Notes freeze export, and `writeAtomic`
|
||||
also backs the freeze-time `MISSION_BRIEF.md` spine update; both append to the
|
||||
same audit file.
|
||||
|
||||
Both operations append a JSONL audit record containing actor/provenance,
|
||||
paths, timestamps, hashes, and byte-count delta. An audit append failure
|
||||
@@ -94,10 +84,6 @@ daemon startup overrides it with the active OpenRig home as described above.
|
||||
## HTTP surface
|
||||
|
||||
[`server.ts`](../../../packages/daemon/src/server.ts) mounts these families.
|
||||
All of them sit behind the daemon's `/api/*` browser boundary
|
||||
(`middleware/browser-boundary.ts`), which accepts only known host names, and
|
||||
browser `Origin`s only from the daemon's own UI or `OPENRIG_ALLOWED_ORIGINS`;
|
||||
the file allowlist is a separate check.
|
||||
[`filesRoutes`](../../../packages/daemon/src/routes/files.ts) implements:
|
||||
|
||||
| Method and path | Result / important behavior |
|
||||
@@ -105,17 +91,13 @@ the file allowlist is a separate check.
|
||||
| `GET /api/files/roots` | Configured roots; an empty list carries a setup hint. |
|
||||
| `GET /api/files/list?root=…&path=…` | Directory entries with metadata, including dotfiles. |
|
||||
| `GET /api/files/read?root=…&path=…` | `readAllowedFile` result. |
|
||||
| `GET /api/files/asset?root=…&path=…` | Raw asset; single byte-range support (`206`, invalid range `416`), five-minute cache. HTML and source files default to plain text and unknown types to `application/octet-stream`; `render=1` opts into HTML rendering. SVG is served as `image/svg+xml`. A `render=1` HTML preview or an SVG is served with no content-security or frame headers, so it can run script in the daemon's origin (`routes/files.ts:153–157`). |
|
||||
| `GET /api/files/asset?root=…&path=…` | Raw asset; single byte-range support (`206`, invalid range `416`), five-minute cache. HTML defaults to plain text; `render=1` opts into HTML rendering. |
|
||||
| `POST /api/files/write` | Requires root, path, string content, expected mtime and hash. Stale reads return `409 write_conflict`; an absent write service returns `503`. |
|
||||
|
||||
Writes resolve actor/provenance through `resolveActorWithDeferral`. Missing
|
||||
route dependencies return `503`; unknown roots and invalid paths return
|
||||
`400`. A failed stat returns `404` on reads, lists and assets; on a write, a
|
||||
missing or unreadable target returns `500 stat_failed`, because
|
||||
`POST /api/files/write` only replaces existing files
|
||||
(`domain/files/file-write-service.ts:120–128`; `routes/files.ts:264–265`). An
|
||||
audit failure can return `500` even though the file write succeeded, so an
|
||||
error is not proof of no effect.
|
||||
`400`, and failed file stats return `404`. An audit failure can return `500`
|
||||
even though the file write succeeded, so an error is not proof of no effect.
|
||||
|
||||
## Progress indexing
|
||||
|
||||
@@ -145,17 +127,13 @@ combines resolved workspace settings with `OPENRIG_STEERING_WORKSPACE`,
|
||||
| Field | Source and selection |
|
||||
|---|---|
|
||||
| `priorityStack` | Verbatim `STEERING.md`, mtime, and byte count. |
|
||||
| `roadmapRail` | `roadmap/PROGRESS.md` `[ ]`/`[x]` rows (`[~]` rows are not read); the first unchecked row is marked next. |
|
||||
| `laneRails` | Every `PROGRESS.md` and `STEERING.md` under `delivery-ready`, using a depth-3 `ProgressIndexer` (lane ID `mode-N` for `mode-N/PROGRESS.md`, else the relative path); first non-done/non-blocked checkbox is next pull. Default top 3 prefers non-done rows, then fills with done rows. |
|
||||
| `roadmapRail` | `roadmap/PROGRESS.md` checkbox rows; the first unchecked row is marked next. |
|
||||
| `laneRails` | Progress files under `delivery-ready`, using a depth-3 `ProgressIndexer`; first non-done/non-blocked checkbox is next pull. Default top 3 prefers non-done rows, then fills with done rows. |
|
||||
|
||||
Missing/unreadable sections become `unavailableSources`. `isReady` means at
|
||||
least one path resolves; it does not guarantee that every read succeeds.
|
||||
[`GET /api/steering`](../../../packages/daemon/src/routes/steering.ts)
|
||||
returns `503` when the composer is absent or no source path resolves. Because
|
||||
`workspace.steering_path` always has a value (default
|
||||
`<workspace.root>/STEERING.md`), the daemon's composer is normally ready, and
|
||||
a missing `STEERING.md` appears as a `priorityStack` read failure in
|
||||
`unavailableSources` with a `200`, not a `503`.
|
||||
returns `503` when the composer is absent or no source path resolves.
|
||||
Queue and health state are fetched through their own endpoints.
|
||||
|
||||
## Health summaries
|
||||
@@ -167,17 +145,12 @@ exposes four reads under `/api/health-summary`:
|
||||
|---|---|
|
||||
| `/nodes` | `computeNodeHealthSummary`: node inventory aggregated across rigs, grouped by session/lifecycle status, with an attention-required count. |
|
||||
| `/context` | `computeContextHealthSummary`: `context_usage` rows grouped by urgency and sample freshness. |
|
||||
| `/version` | `getDaemonVersion`: the build-stamped version, else the daemon package version, else `unknown`; always `200`. |
|
||||
| `/version` | `getDaemonVersion`: the running daemon's version, or `unknown` on read failure. |
|
||||
| `/gateway` | The injected gateway subsystem's `status()`; `503` if unavailable. |
|
||||
|
||||
`/nodes` and `/context` return `503 health_summary_unavailable` when the rig
|
||||
repository is not wired.
|
||||
|
||||
The [context aggregation](../../../packages/daemon/src/domain/steering/health-summary.ts)
|
||||
uses **80%** for critical, **60%** for warning, and **300 seconds** for
|
||||
freshness. These are constants in this module: they do not follow the
|
||||
`health.context_pressure.*` settings (defaults 95% and 99%) that the health
|
||||
detectors use, so the two surfaces can disagree about the same session. A missing usage value is unknown; a missing timestamp has no
|
||||
freshness. A missing usage value is unknown; a missing timestamp has no
|
||||
freshness sample. The SQL read catches errors and falls back to an empty
|
||||
sample set, so zero counts alone are not a database-health guarantee.
|
||||
|
||||
|
||||
@@ -10,8 +10,8 @@ applies-when: |
|
||||
transactional handoff guarantee, or where queue closure is enforced.
|
||||
siblings: [workflow-runtime.md, mission-control.md, daemon-core.md]
|
||||
prerequisite-reads: [../README.md, daemon-core.md]
|
||||
last-verified-against-source: e8f0ab340db773392ec8be75b072d1c0f3068a50
|
||||
last-updated: 2026-10-08
|
||||
last-verified-against-source: b6d37bfadcc189be8fd61e35abfc09676437bf48
|
||||
last-updated: 2026-10-03
|
||||
---
|
||||
|
||||
# Coordination Primitive — Stream/Queue/Inbox/Outbox
|
||||
@@ -24,7 +24,7 @@ filesystem path remains untouched, and the daemon-backed `rig queue` /
|
||||
only to SQLite (`packages/cli/src/commands/queue.ts:19`,
|
||||
`packages/cli/src/commands/stream.ts:11`).
|
||||
|
||||
> Verified against source at main `e8f0ab340db773392ec8be75b072d1c0f3068a50`. Each count below sits beside the
|
||||
> Verified against source at main `b6d37bfadcc189be8fd61e35abfc09676437bf48`. Each count below sits beside the
|
||||
> command that produces it; run the command from the repository root to refresh
|
||||
> it.
|
||||
|
||||
@@ -44,7 +44,7 @@ Five host-scoped tables back the primitive, one per migration `023`–`027` in
|
||||
`archived_at` may be set, `stream-store.ts:217`).
|
||||
- **`queue_items`** (`024_queue_items.ts`) — L3 owned-work queue.
|
||||
Unless `--id` is supplied, the CLI generates the create request's `qitem_id` (TEXT PK) before sending as `qitem-<UTC YYYYMMDDHHMMSS>-<16 hex>` (64 random bits) and prints it to stderr as a request identity, not proof of persistence; reuse that ID with `--id` and the unchanged payload after an unknown outcome, while daemon callers without an ID still use `newQitemId()` and its `qitem-<UTC YYYYMMDDHHMMSS>-<8 hex>` form.
|
||||
State enum (**8** values, `QUEUE_STATES` at `queue-repository.ts:33`;
|
||||
State enum (**8** values, `QUEUE_STATES` at `queue-repository.ts:32`;
|
||||
`sed -n '/^export const QUEUE_STATES/,/] as const/p' packages/daemon/src/domain/queue-repository.ts | grep -c '^ "'`):
|
||||
`pending | in-progress | done | blocked | failed | denied | canceled |
|
||||
handed-off`. Carries `closure_reason`, `closure_target`,
|
||||
@@ -56,10 +56,7 @@ Five host-scoped tables back the primitive, one per migration `023`–`027` in
|
||||
every transition of a terminal item whose last transition is older than the
|
||||
retention window into `queue_transitions_archive`
|
||||
(`054_queue_transitions_archive.ts`), insert and delete in one transaction
|
||||
(`packages/daemon/src/domain/queue-retention.ts:203`). Only `done` and
|
||||
`handed-off` items are archived; the default window is 30 days, and items
|
||||
still on a live workflow frontier are skipped (`queue-retention.ts:69`–`75`,
|
||||
`:158`–`171`).
|
||||
(`packages/daemon/src/domain/queue-retention.ts:203`).
|
||||
- **`inbox_entries`** (`026_inbox_entries.ts`) — mailbox-style asynchronous
|
||||
deposit; idempotent on `inbox_id`. State: `pending | absorbed | denied`
|
||||
(`INBOX_STATES`, `inbox-handler.ts:5`).
|
||||
@@ -70,9 +67,9 @@ Five host-scoped tables back the primitive, one per migration `023`–`027` in
|
||||
`pending | sending | delivered | failed | indeterminate | retained |
|
||||
retired`.
|
||||
|
||||
These five are migrations `023`–`027` of the daemon's **96**
|
||||
These five are migrations `023`–`027` of the daemon's **93**
|
||||
(`git ls-files packages/daemon/src/db/migrations | wc -l`), applied in the
|
||||
order of `ALL_MIGRATIONS` (`packages/daemon/src/db/all-migrations.ts:107`).
|
||||
order of `ALL_MIGRATIONS` (`packages/daemon/src/db/all-migrations.ts:102`).
|
||||
Later migrations add columns to these tables; `daemon-core.md` covers the
|
||||
migration set.
|
||||
|
||||
@@ -89,29 +86,26 @@ Routes import these; services are Hono-free:
|
||||
every filter before taking the newest bounded page, then returns that page
|
||||
chronologically.
|
||||
- **`queue-repository.ts`** — L3 queue: create (`:1391`), claim/unclaim
|
||||
(`:2186`, `:2271`), update (general state mutator with hot-potato
|
||||
strict-rejection on `done`, `:2334`), transactional handoff (close source as
|
||||
`handed-off` plus create new owned qitem in a single transaction, `:1656`;
|
||||
`handoffAndComplete`, `:1833`, closes the source as `done` instead),
|
||||
pod-fallback rerouting (`routeToFallback`, `:3678`), overdue lookup
|
||||
(`findOverdue`, `:3378`), nudge-result tracking (`recordNudgeAttempt`,
|
||||
`:3663`). Nothing in the daemon writes the `last_heartbeat` column
|
||||
(`:2165`, `:2247`), update (general state mutator with hot-potato
|
||||
strict-rejection on `done`, `:2310`), transactional handoff (close source as
|
||||
`handed-off` plus create new owned qitem in a single transaction, `:1634`;
|
||||
`handoffAndComplete`, `:1811`, closes the source as `done` instead),
|
||||
pod-fallback rerouting (`routeToFallback`, `:3580`), overdue lookup
|
||||
(`findOverdue`, `:3333`), nudge-result tracking (`recordNudgeAttempt`,
|
||||
`:3565`). Nothing in the daemon writes the `last_heartbeat` column
|
||||
(`queue-pickup.ts:16`). Cross-rig validation hook exposed as `validateRig`
|
||||
constructor option (`queue-repository.ts:717`).
|
||||
constructor option (`queue-repository.ts:711`).
|
||||
- **`queue-transition-log.ts`** — append-only state-transition log; used by
|
||||
`queue-repository.ts`, exposed as the read-only property
|
||||
`QueueRepository.transitionLog` (`queue-repository.ts:666`).
|
||||
`QueueRepository.transitionLog` (`queue-repository.ts:660`).
|
||||
- **`hot-potato-enforcer.ts`** — pure validator for the load-bearing API
|
||||
contract (see §3).
|
||||
- **`inbox-handler.ts`** — mailbox handler: drop (idempotent on `inbox_id`,
|
||||
`:100`), absorb (promotes a pending entry to a `queue_item`, idempotent,
|
||||
`:155`), deny (records reason, `:215`). The handler has no auth hook
|
||||
(`inbox-handler.ts:71`); identity comes from the route. `POST /inbox/drop`
|
||||
takes the sender only from the `X-OpenRig-Session` header through
|
||||
`requireSenderIdentity` (`routes/queue.ts:1094`) and answers 400
|
||||
`actor_required` without it. Absorb and deny (`:1121`, `:1135`) use the
|
||||
header when present; otherwise they accept the body's `receiverSession` and
|
||||
record it as `claimed:v1` (`routes/require-sender-identity.ts:83`–`92`).
|
||||
`:99`), absorb (promotes a pending entry to a `queue_item`, idempotent,
|
||||
`:154`), deny (records reason, `:214`). The handler has no auth hook: the
|
||||
inbox routes take the sender or receiver from the `X-OpenRig-Session` header
|
||||
through `requireSenderIdentity` (`routes/queue.ts:1034`), never from the body
|
||||
(`inbox-handler.ts:71`).
|
||||
- **`outbox-handler.ts`** — sender-side outbox: idempotent record (`:130`),
|
||||
delivery-state marks (`markDelivered` `:239`, `markFailed` `:256`,
|
||||
`markIndeterminate` `:280`), list (`listForSender` `:339`). It also holds the
|
||||
@@ -119,151 +113,13 @@ Routes import these; services are Hono-free:
|
||||
messages the seat delivery guard retains (`retain` `:181`, `retire` `:217`),
|
||||
so it is not audit-only. Emits no event-bus events.
|
||||
|
||||
Create, handoff and handoff-and-complete return the committed row without
|
||||
waiting for terminal delivery. Each stages a deterministic
|
||||
`wake-intent-<qitem>` outbox row in its transaction and delivers it after
|
||||
commit (`queue-repository.ts:1412`–`1424`, `:1475`–`1483`). The returned
|
||||
`lastNudgeResult` is therefore normally null; `rig queue show <id>` reads the
|
||||
wake result later. If create cannot retain the intent, the task is still saved
|
||||
and the row records `failed:wake not retained: <reason>`. Startup reconciles
|
||||
and drains intents left pending by a crash once (`startup.ts:2361`–`2362`).
|
||||
`maybeNudge` remains only as the path for a repository with no outbox.
|
||||
|
||||
**Which field answers "did it reach them".** `deliveryOutcome` is the gateway
|
||||
(human-delivery) ledger, derived at read time
|
||||
(`QueueRepository.deliveryOutcomeFor`): `posted` or `transport-failed` from the
|
||||
row's Slack receipt notes, or `never-posted` when a gateway-routed row still
|
||||
has no receipt once the post window has passed. A task delivered only to an
|
||||
agent's pane has no such receipt, so it reads `null`. A task that also has a
|
||||
gateway or human-notification side can carry a value, and the CLI then reports
|
||||
that gateway side too. For the pane side, read:
|
||||
|
||||
- `lastNudgeWireResult`: the wake send's result as stored (for example
|
||||
`verified`, `delivered-ack-pending`, `indeterminate:…`, `retained:…`,
|
||||
`failed:…`). A claim never rewrites it; a later wake replaces it.
|
||||
- `lastNudgeResult`: the result as presented. It is the stored result, except
|
||||
that a claimed row whose stored result is `delivered-ack-pending` or
|
||||
`indeterminate:…` reads `claimed` (`presentedNudgeResult`). Unclaiming shows
|
||||
the stored result again.
|
||||
- `claimedAt`: when the destination claimed the row. Closing doesn't clear it.
|
||||
- `pickup`: the derived pickup receipt (`unclaimed`, `working`, `needs-input`,
|
||||
`stalled-after-claim`, `parked`, `terminal`), computed at read time.
|
||||
|
||||
A claimed item whose owner's activity reports outstanding input reads
|
||||
`needs-input`, with the reason in `pickup.evidence`. That covers an item in
|
||||
progress and a `pending` item that kept its claim, after an update back to
|
||||
`pending` or a reopen. A Codex permission request the daemon couldn't confirm on
|
||||
screen reads `owner may need input (not verified: permission_request_unverified)`.
|
||||
The input signal can outlast the prompt it reported, so it never pauses
|
||||
recovery. When the claim would otherwise read `stalled-after-claim`, the receipt
|
||||
keeps that evidence in `pickup.stall`, and the stuck sweep's finding, its
|
||||
backstop and manual dispositions behave exactly as for `stalled-after-claim`.
|
||||
Queue reads, the pickup view and the execution view share this receipt
|
||||
(`queue-pickup.ts`). Unclaimed, blocked and terminal items keep their receipts.
|
||||
|
||||
A claim isn't proof that the body was read or that the terminal render was
|
||||
verified, and closing a task isn't a new delivery receipt: a claimed task that
|
||||
is later closed still reads `claimed` when its stored result was unconfirmed
|
||||
(`delivered-ack-pending` or `indeterminate:…`); a `verified` or `failed:…`
|
||||
result reads as stored. For such an unconfirmed, claimed item,
|
||||
`rig queue create --verify` says "Terminal receipt unconfirmed, but the seat
|
||||
has claimed the item (claimed)."; for any claimed item it adds "A claim shows
|
||||
the seat took the item; it does not prove the body was read."
|
||||
(`terminalDeliveryResult`, `packages/cli/src/commands/queue.ts`).
|
||||
|
||||
The standing detector in `queue-stuck-sweep.ts` creates findings through the
|
||||
queue repository, with `evidenceRef: rig queue show <source-qitem-id>` pointing
|
||||
to the underlying durable work row. Unclaimed and undelivered findings go to
|
||||
the destination's orchestrator when one is derivable, otherwise to the
|
||||
destination itself, and that seat may be dead. Overdue claims go to their
|
||||
destination. Repeated detections reuse the existing finding without changing
|
||||
its route; when the source condition resolves, the sweep closes its own finding.
|
||||
Previously, falling out of a reporting query could itself close a delivery or
|
||||
unclaimed finding. An unconfirmed retry, a fresh human-notification post window,
|
||||
an unreadable human registry or a larger reporting-age setting could therefore
|
||||
look like successful recovery. These findings now require source evidence:
|
||||
closure, pickup or parking of the work, a verified/accepted wake, or a posted
|
||||
notification for the current human recipient and episode, as appropriate to the
|
||||
finding. `delivered-ack-pending`, `indeterminate:…`, missing results and unrelated
|
||||
legacy human receipts do not prove resolution. Uncertainty keeps an existing
|
||||
finding open without itself sending another wake or creating another finding.
|
||||
A verified wake resolves a wake failure, not an unclaimed obligation: delivery
|
||||
does not prove pickup.
|
||||
|
||||
A legacy human notice with no owner-notification history can still resolve from
|
||||
the existing item-scoped posted ledger when its recipient is confirmed human.
|
||||
This covers older pending asks and parks without inventing an episode that was
|
||||
never recorded. A registered alias needs a readable registry to establish its
|
||||
human recipient; reserved human references remain known during an outage.
|
||||
Legacy receipts carry no recipient key, so a destination reroute requires a new
|
||||
matching notification episode. A legacy park is accepted only when no earlier
|
||||
notice or reroute predates it, and later history contains only receipts or
|
||||
asking-agent reroutes within that park. A re-park, an exit from the park or an
|
||||
ambiguous append cannot establish the same recipient without owner history;
|
||||
the finding waits for a new matching episode or other source resolution.
|
||||
Rerouting only the asking agent within an otherwise unchanged park preserves
|
||||
its human recipient (`blockedOn`).
|
||||
Modern notifications still require their current episode, and an unrelated
|
||||
legacy human receipt cannot resolve an agent wake.
|
||||
|
||||
A known hold still leaves recovery with the existing mechanism: an ask on
|
||||
Steering without an alert, a wake held by the seat typing guard, or a live
|
||||
quiet-release job. Its closure note names that disposition rather than claiming
|
||||
delivery or pickup. An unreadable quiet hold is not positive closure evidence.
|
||||
Claimed work in either `pending` or `in-progress` uses the same pickup derivation;
|
||||
returning a row to `pending` while retaining its claim no longer hides a later
|
||||
stall or closes its existing stalled-claim finding. A retained failed wake cannot
|
||||
override that pickup evidence. The agent's claim still does not establish delivery
|
||||
of a separate notification to a person.
|
||||
|
||||
That automatic closure records `stuck-sweep@system` as the actor in both the
|
||||
transition and the `queue.updated` audit event, with the source evidence in the
|
||||
delivery and unclaimed-obligation closure notes. Previously it credited the finding's source agent
|
||||
with the detector's action. The finding's source,
|
||||
destination and claim remain its existing ownership records; the underlying work
|
||||
is not reassigned, and existing transition history is not rewritten.
|
||||
|
||||
`queue-stuck-sweep-resolution.test.ts` checks unconfirmed retries, retained
|
||||
claims, current human-notification episodes and registry outages with migrated
|
||||
SQLite, including positive recovery controls and no repeated send on an
|
||||
unresolved retry. `quiet-hold-custody.test.ts` checks existing findings with
|
||||
readable and unreadable quiet custody. `queue-stuck-sweep.test.ts` checks that
|
||||
pending and claimed findings close once, name the sweep in their transition and
|
||||
event, and keep their ownership. The posted-human-notice case also checks the actor while leaving
|
||||
the person's original ask open. These checks exercise the detector and queue
|
||||
repository, not a live agent or connector.
|
||||
|
||||
The sweep reports six finding kinds. Its custody check covers closures that
|
||||
name a successor qitem or a seat (`closure_reason = handed_off_to`) in the last
|
||||
24 hours, plus older closures with open findings. A seat target is satisfied by
|
||||
a local successor carrying this row's lineage, and any target by a
|
||||
`custody-verified: <target> …` note on the closed row. A new custody finding for
|
||||
a human destination goes to the agent that closed the item, using the closing
|
||||
transition from active or archived history. Later notes and notification
|
||||
receipts do not change that owner. If the closing actor is missing, human, system
|
||||
machinery or not admitted by this host's queue, the asking agent receives the
|
||||
finding if its address is admitted. Human identity includes reserved references
|
||||
and registered aliases, independent of terminal bindings. Admission uses the
|
||||
queue's existing address check and does not require a live seat. An agent
|
||||
destination keeps its existing route; if neither closer nor source is an admitted
|
||||
agent, the human destination remains the durable fallback. This routing does not
|
||||
change custody verification or suppress unresolved findings.
|
||||
|
||||
If the human registry is unavailable when a custody candidate's owner needs
|
||||
classification, that candidate keeps its original destination, and one log line
|
||||
per candidate names it and the registry error. This doesn't infer an agent
|
||||
identity from an unreadable registry, which may not exist before the first human
|
||||
is registered. In a pass with no finding to save for a `<name>@external` person,
|
||||
which includes an install with no registry yet, work bound for agents keeps
|
||||
routing and repaired findings still close. Such a finding still needs the
|
||||
registry to admit it when it's saved, so during an outage a pass that must save
|
||||
one fails at that finding, as it did before this routing. Findings not yet
|
||||
created in that pass, and the closing of repaired findings, wait for the next
|
||||
pass that completes. Once the registry can be read again, the next pass creates
|
||||
the finding and routes it to the closer. Registry recovery restores owner refinement
|
||||
for new findings; existing findings keep their established route. Reserved human
|
||||
references and legacy agent names keep their known classifications without a
|
||||
registry read.
|
||||
queue repository, with `evidenceRef: rig queue show <source-qitem-id>`
|
||||
(`queue-stuck-sweep.ts:523`) pointing to the underlying durable work row. This
|
||||
satisfies the existing human-route evidence contract without changing
|
||||
destination resolution: an admitted finding can still be unroutable. Repeated
|
||||
detections refresh the existing finding; when the source condition resolves,
|
||||
the sweep closes its own finding (`:549`).
|
||||
|
||||
## 3. The hot-potato closure contract (where queue closure is enforced)
|
||||
|
||||
@@ -272,17 +128,15 @@ contract. `validateClosure` (`hot-potato-enforcer.ts:59`) checks a transition
|
||||
against `CLOSURE_REASONS` (`:18`; **7** values:
|
||||
`sed -n '/^export const CLOSURE_REASONS/,/] as const/p' packages/daemon/src/domain/hot-potato-enforcer.ts | grep -c '^ "'`):
|
||||
|
||||
`state=done` requires `closure_reason ∈ {handed_off_to, denied,
|
||||
`state=done` requires `closure_reason ∈ {handed_off_to, blocked_on, denied,
|
||||
canceled, no-follow-on, escalation, superseded}`. The reasons
|
||||
`handed_off_to | escalation` additionally require
|
||||
`handed_off_to | blocked_on | escalation` additionally require
|
||||
`closure_target` (`:86`):
|
||||
|
||||
- `handed_off_to` — work continues with a different seat (`closure_target` =
|
||||
new owner).
|
||||
- `blocked_on` — an active `state=blocked` park record, rejected with `state=done`.
|
||||
To wait for a qitem, use `rig queue block <id> --on <child>` or
|
||||
`rig queue update <id> --state blocked --blocked-on <child>`; the item returns
|
||||
to pending when its blocker completes.
|
||||
- `blocked_on` — work is parked pending another qitem (`closure_target` =
|
||||
blocker `qitem_id`).
|
||||
- `denied` — receiver rejected the work (`closure_target` = reason text).
|
||||
- `canceled` — sender or receiver withdrew (`closure_target` = note).
|
||||
- `no-follow-on` — terminal completion, nothing else needed.
|
||||
@@ -291,37 +145,18 @@ canceled, no-follow-on, escalation, superseded}`. The reasons
|
||||
- `superseded` — the row was replaced by cancel-and-replace
|
||||
(`closure_target` = the successor qitem). The update path records it on
|
||||
`state=canceled` and refuses it there without a `closure_target`
|
||||
(`queue-repository.ts:2629`).
|
||||
(`queue-repository.ts:2566`).
|
||||
|
||||
Tier→SLA mapping for `closure_required_at` also lives in
|
||||
`hot-potato-enforcer.ts` (`TIER_SLA_SECONDS`, `:115`). This validator is
|
||||
`hot-potato-enforcer.ts` (`TIER_SLA_SECONDS`, `:114`). This validator is
|
||||
invoked by `QueueRepository.update()` (and `updateWithinTransaction()`), both
|
||||
through the call at `queue-repository.ts:2531`, so closure is enforced at the
|
||||
through the call at `queue-repository.ts:2484`, so closure is enforced at the
|
||||
daemon transaction boundary — the workflow runtime *projects* on closure but
|
||||
does not otherwise gate it (see `workflow-runtime.md`). The one
|
||||
workflow-aware check is in the queue: `update()` refuses a terminal close of a
|
||||
live workflow frontier packet from a non-workflow verb
|
||||
(`workflow_frontier_packet`, `queue-repository.ts:2557`), through a predicate
|
||||
startup injects. "Terminal" there is the queue's terminal set, `done` and
|
||||
`handed-off` (`queue-repository.ts:52`).
|
||||
|
||||
Closure fields are stored only on `state=done`, the park record (`blocked`
|
||||
with `blocked_on`), the handoff close (`handed-off` with `handed_off_to`) and
|
||||
the superseded cancel; any other transition carrying them is refused with
|
||||
`closure_fields_not_admitted`, and `blocked_on` outside `blocked` with
|
||||
`blocked_on_not_admitted`. A `done`, `canceled` or `handed-off` row accepts a
|
||||
note without a state change as an append-only transition; moving it to
|
||||
another state requires an explicit reopen with a note. A `qitem-` blocker must
|
||||
exist and be live on this daemon; when a blocker leaves the active states,
|
||||
each row parked on it follows the blocker's handoff successor or returns to
|
||||
`pending` with a durable wake (`queue-repository.ts:2407`–`2529`,
|
||||
`:2612`–`2656`, `:2931`–`3008`). Claiming a parked row clears its
|
||||
`blocked_on`; the claim transition keeps the former gate as a `closure_target`
|
||||
audit pointer with no closure reason, which a re-park without `--blocked-on`
|
||||
reuses (`queue-repository.ts:2233`–`2254`, `:2571`–`2577`).
|
||||
`human-route-enforcer.ts` is a second pure validator at the same boundary: a
|
||||
`human-gate` row, a row addressed to a human seat, or a park on one must carry
|
||||
`summary` and `evidence_ref`.
|
||||
(`workflow_frontier_packet`, `queue-repository.ts:2510`), through a predicate
|
||||
startup injects.
|
||||
|
||||
## 3b. Cross-host queue routing
|
||||
|
||||
@@ -331,19 +166,17 @@ Three queue write routes are host-aware — `POST /create`,
|
||||
a write body may carry an out-of-band `hostId` envelope. The destination
|
||||
session stays `member@rig`; the 3-part `agent@rig@host` form is CLI input
|
||||
sugar that `resolveQueueHostDestination`
|
||||
(`packages/cli/src/commands/queue.ts:394`) splits into the destination and
|
||||
`hostId` before the request leaves the CLI. The same split applies to
|
||||
`--host <id>`; queue verbs never follow `rig host select`, and naming two
|
||||
different hosts is refused with `host_qualifier_conflict`. The mechanism
|
||||
follows the forward-then-strip shape of mission-control's remote action
|
||||
(`routes/mission-control.ts:352`): one shared route-layer helper
|
||||
(`forwardQueueWrite`, `routes/queue.ts:214`) resolves the host registry
|
||||
(`packages/cli/src/commands/queue.ts:364`) splits into the destination and
|
||||
`hostId` before the request leaves the CLI. The mechanism follows the
|
||||
forward-then-strip shape of mission-control's remote action
|
||||
(`routes/mission-control.ts:353`): one shared route-layer helper
|
||||
(`forwardQueueWrite`, `routes/queue.ts:197`) resolves the host registry
|
||||
daemon-side (bearers never reach the caller), rejects ssh-declared hosts
|
||||
(`unsupported-transport` — the daemon→daemon path is http-only), and forwards
|
||||
the whole body, with `hostId` stripped, via `remoteJsonRequest` (`:248`) under
|
||||
the whole body, with `hostId` stripped, via `remoteJsonRequest` (`:231`) under
|
||||
a named write-class deadline (`QUEUE_FORWARD_TIMEOUT_MS`, `:41`). The origin's
|
||||
response returns verbatim; failures map to a structured host-named error
|
||||
(`remote_queue_write_failed`, HTTP 502, `:234`) whose `failureClass` is one of
|
||||
(`remote_queue_write_failed`, HTTP 502, `:217`) whose `failureClass` is one of
|
||||
registry / unknown-host / unsupported-transport / unreachable / auth-failed /
|
||||
remote-error. No local row is ever written on the cross-host path.
|
||||
|
||||
@@ -351,37 +184,33 @@ remote-error. No local row is ever written on the cross-host path.
|
||||
message-passing closure (never 2PC).**
|
||||
|
||||
- **Origin-owns-the-record.** The qitem lives in the TARGET host's DB; that
|
||||
row is THE record. The target daemon wakes the destination on ITS local
|
||||
tmux: its own `create` stages a durable wake intent and delivers it after
|
||||
commit (§2; the forwarded body carries the `nudge` flag) — the sending
|
||||
daemon never reaches across a host boundary. Before forwarding, the
|
||||
forwarding daemon stamps its own host id, when it has one, onto the source
|
||||
session (`stampSelfHostSuffix`, `queue-repository.ts:548`; called at
|
||||
`routes/queue.ts:378` and `:509`), so the target row records the sender as
|
||||
row is THE record. The target daemon's OWN `maybeNudge` fires on ITS local
|
||||
tmux (the forwarded body includes the `nudge` flag) — the sending daemon
|
||||
never reaches across a host boundary. Before forwarding, the forwarding
|
||||
daemon stamps its own host id, when it has one, onto the source session
|
||||
(`stampSelfHostSuffix`, `queue-repository.ts:542`; called at
|
||||
`routes/queue.ts:359` and `:465`), so the target row records the sender as
|
||||
`member@rig@<forwarding host>`.
|
||||
- **Idempotency.** On create, the forwarding daemon mints the `qitemId` before
|
||||
the forward unless the caller supplied one (`routes/queue.ts:501`). The
|
||||
the forward unless the caller supplied one (`routes/queue.ts:457`). The
|
||||
forward is a single request, so a retry dedups only when it carries the same
|
||||
id (a caller re-sending `--id`, or a handoff re-drive, whose successor id is
|
||||
derived). Dedup rides the existing `qitem_id TEXT PRIMARY KEY`. On PK
|
||||
conflict the origin returns the stored row when destination and source
|
||||
match (idempotent absorb) and a structured `qitem_id_reuse` error (409) when
|
||||
they differ (`QueueRepository.create()` catch path,
|
||||
`queue-repository.ts:1431`–`1472`, with `isQitemPrimaryKeyConflict`,
|
||||
`:461`). When destination and source match but the body differs, the stored
|
||||
row is returned unchanged with `createWarning: qitem_body_not_saved`; the
|
||||
supplied body is not saved (`:1450`–`1454`).
|
||||
`queue-repository.ts:1440`, with `isQitemPrimaryKeyConflict`, `:455`).
|
||||
- **Cross-host handoff choreography.** The local atomic close+create cannot
|
||||
span two DBs, so the route-layer choreography (`crossHostHandoff`,
|
||||
`routes/queue.ts:316`) runs: successor-create on the target host FIRST (via
|
||||
the one forward helper, `:397`), local source-close SECOND
|
||||
(`QueueRepository.closeCrossHostHandoffSource`, `queue-repository.ts:2031`)
|
||||
`routes/queue.ts:299`) runs: successor-create on the target host FIRST (via
|
||||
the one forward helper, `:378`), local source-close SECOND
|
||||
(`QueueRepository.closeCrossHostHandoffSource`, `queue-repository.ts:2000`)
|
||||
— never the reverse. A crash between the two leaves a live duplicate that
|
||||
the idempotent re-drive converges; the reverse order would leave a closed
|
||||
source pointing at a successor that does not exist (a dropped potato — the
|
||||
one forbidden outcome). The successor id is DERIVED, not minted:
|
||||
`deriveCrossHostSuccessorId(source, destination, host)`
|
||||
(`queue-repository.ts:489`) → `qitem-xh-<sha256[:16]>` — a pure stateless
|
||||
(`queue-repository.ts:483`) → `qitem-xh-<sha256[:16]>` — a pure stateless
|
||||
function, so a re-drive re-derives the same id across daemon restarts and
|
||||
absorbs on the target PK. *(Residual, inherent to at-least-once delivery
|
||||
without 2PC: a re-drive naming a DIFFERENT destination derives a different
|
||||
@@ -390,21 +219,21 @@ message-passing closure (never 2PC).**
|
||||
disagreement.)*
|
||||
- **Closure across the boundary.** The source closes with
|
||||
`closure_reason=handed_off_to` and
|
||||
`closure_target=<successor qitem id>@<host>` (`routes/queue.ts:351`); a
|
||||
`closure_target=<successor qitem id>@<host>` (`routes/queue.ts:332`); a
|
||||
source already closed with the older `member@rig@<host>` target keeps it,
|
||||
and a re-drive matches against it (`:352`–`356`). `closure_target` is OPAQUE
|
||||
and a re-drive matches against it (`:333`). `closure_target` is OPAQUE
|
||||
audit metadata, never parsed for routing; the standing stuck sweep reads it
|
||||
only to check successor custody (`queue-stuck-sweep.ts:519`–`554`). The
|
||||
only to check successor custody (`queue-stuck-sweep.ts:468`). The
|
||||
host-qualified key appears only in the `closure_target` column on
|
||||
`queue_items` and its verbatim mirror on `queue_transitions`: the minted
|
||||
cross-host close note names the 2-part `toSession` only
|
||||
(`queue-repository.ts:2087`), and `handed_off_to` and the
|
||||
(`queue-repository.ts:2056`), and `handed_off_to` and the
|
||||
`queue.handed_off` event stay 2-part.
|
||||
Re-drive semantics: already-terminal + MATCHING `closure_target` = absorb;
|
||||
MISMATCH = structured `cross_host_close_conflict` (409), checked in the route
|
||||
before any forward (`routes/queue.ts:359`) and again in the repository. The
|
||||
before any forward (`routes/queue.ts:343`) and again in the repository. The
|
||||
successor carries `chain_of_record = [...source.chain, source.qitemId]`
|
||||
(`routes/queue.ts:384`) — A-side ids are opaque lineage identifiers on B
|
||||
(`routes/queue.ts:365`) — A-side ids are opaque lineage identifiers on B
|
||||
(they do not dereference in B's DB) — plus provenance tags `cross-host` +
|
||||
`from-host:<self-declared name>` (the forwarding daemon's OS hostname,
|
||||
`routes/queue.ts:54`; honest best-effort, not authenticated identity).
|
||||
@@ -420,16 +249,16 @@ message-passing closure (never 2PC).**
|
||||
|
||||
## 4. Coordination events
|
||||
|
||||
The `RigEvent` union (`packages/daemon/src/domain/types.ts:108`) has **98**
|
||||
The `RigEvent` union (`packages/daemon/src/domain/types.ts:106`) has **98**
|
||||
members
|
||||
(`sed -n '/^export type RigEvent =/,/^export type PersistedEvent/p' packages/daemon/src/domain/types.ts | grep -c 'type: "'`);
|
||||
this module covers only the coordination families below.
|
||||
|
||||
Coordination events emitted by these services: `stream.emitted`
|
||||
(`StreamStore.emit`, declared at `types.ts:245`); `queue.created` /
|
||||
(`StreamStore.emit`, declared at `types.ts:243`); `queue.created` /
|
||||
`queue.handed_off` / `queue.claimed` / `queue.unclaimed` / `queue.updated` /
|
||||
`qitem.fallback_routed` / `qitem.closure_overdue` (QueueRepository); `inbox.absorbed` (`types.ts:255`) /
|
||||
`inbox.denied` (InboxHandler). `qitem.closure_overdue` (`types.ts:254`) is
|
||||
`qitem.fallback_routed` / `qitem.closure_overdue` (QueueRepository); `inbox.absorbed` (`types.ts:253`) /
|
||||
`inbox.denied` (InboxHandler). `qitem.closure_overdue` (`types.ts:252`) is
|
||||
emitted by `QueueRepository.recordClosureOverdue` when swept by `queue-stuck-sweep`
|
||||
and passed through the queue watch filter (**2** files contain its literal:
|
||||
`git grep -l -F 'type: "qitem.closure_overdue"' -- packages/daemon/src | wc -l`).
|
||||
@@ -439,58 +268,26 @@ The `stream|queue|inbox|qitem` families declare **10** event types (`stream` 1
|
||||
|
||||
Two SSE surfaces stream coordination events (**2**:
|
||||
`cat packages/daemon/src/routes/stream.ts packages/daemon/src/routes/queue.ts | grep -c 'return streamSSE('`):
|
||||
`/api/stream/watch` (aliased `/api/stream/sse`, `routes/stream.ts:194`–`195`),
|
||||
which first replays up to 50 unarchived items in chronological order (the
|
||||
oldest, `:174`–`181`) and then streams new items, and `/api/queue/watch`
|
||||
(aliased `/api/queue/sse`, `routes/queue.ts:1054`–`1055`) for queue/inbox
|
||||
events — every coordination type except `stream.emitted` and `queue.updated`
|
||||
(filter at `routes/queue.ts:1031`–`1038`). The event log remains append-only and
|
||||
`/api/stream/watch` (aliased `/api/stream/sse`, `routes/stream.ts:194`–`195`)
|
||||
for new stream items, and `/api/queue/watch` (aliased `/api/queue/sse`,
|
||||
`routes/queue.ts:994`–`995`) for queue/inbox events — every coordination type
|
||||
except `stream.emitted` and `queue.updated` (filter at
|
||||
`routes/queue.ts:971`–`978`). The event log remains append-only and
|
||||
SQLite-backed. `rig stream watch` is a thin, single-connection consumer of
|
||||
`/api/stream/sse` (`packages/cli/src/commands/stream.ts:191`); it does not add
|
||||
a daemon route or reconnect policy.
|
||||
|
||||
## 5. Route surface
|
||||
|
||||
The TUI FEED reads `/api/attention` for human requests and current explicit
|
||||
human-addressed updates. Its independent update query filters open states and
|
||||
strict human destinations before the 1001-row sentinel, serves at most 1000
|
||||
updates with critical then urgent rows first, and requires no transport receipt. These local
|
||||
FYIs create no approval obligation. `/api/queue/human-updates` remains confirmed
|
||||
delivery history; the TUI suppresses a history card when the same queue item is
|
||||
in the current update window. Current-update coverage is independent of the
|
||||
receipt window, so an unavailable current reader cannot retain closed delivery
|
||||
history beyond a successful history read. Both reads leave queue state intact.
|
||||
|
||||
- `/api/stream` (`server.ts:783`) — `POST /emit` (`routes/stream.ts:56`),
|
||||
- `/api/stream` (`server.ts:784`) — `POST /emit` (`routes/stream.ts:56`),
|
||||
`GET /list` (`:91`, including `sourceSession`, `hintDestination`, `hintTag`,
|
||||
`since`, `until` and `direction` filters), `GET /watch` + `/sse` SSE
|
||||
(`:194`), `GET /:streamItemId` (`:198`), `POST /:streamItemId/archive`
|
||||
(`:207`).
|
||||
- `/api/queue` (`server.ts:784`) — `POST /create` (`routes/queue.ts:450`),
|
||||
`POST /:qitemId/claim` (`:545`), `POST /:qitemId/unclaim` (`:561`),
|
||||
`POST /:qitemId/update` (`:600`), plus handoff (`:650`, `:732`),
|
||||
`POST /:qitemId/fallback` (`:808`), list (`:902`) and watch (`:1054`)
|
||||
surfaces; reads `GET /whoami`, `/attention-aggregate`, `/human-updates`,
|
||||
`/overdue`, `/undelivered`, `/recent-transitions`, `/:qitemId/transitions`
|
||||
and `/:qitemId` (`:822`–`1067`); inbox routes `POST /inbox/drop`,
|
||||
`/inbox/:id/absorb`, `/inbox/:id/deny` and `GET /inbox/pending`,
|
||||
`/inbox/list` (`:1076`–`1152`); outbox routes `POST /outbox/record` and
|
||||
`GET /outbox/list` (`:1161`, `:1190`).
|
||||
|
||||
Every write route derives its actor through `requireSenderIdentity`
|
||||
(`routes/require-sender-identity.ts:76`): the `X-OpenRig-Session` header wins
|
||||
over a body actor. On a direct request from a known origin it is recorded as
|
||||
`transport:v1`; `resolveRecordedProvenance` (`:199`) instead records
|
||||
`origin-unknown:v1` when the origin-unknown marker is set or a relayed request
|
||||
carried `origin-unknown:v1` (`:207`), `relay:v1` for a relayed request that
|
||||
carried `transport:v1`, and `claimed:v1` for other relayed requests. `transport:v1`
|
||||
says the name came from that header, which the CLI sets from the seat's
|
||||
`OPENRIG_SESSION_NAME`; it isn't an authentication. Without the
|
||||
header, the
|
||||
body actor is recorded as `claimed:v1`; with neither (or, for inbox drop,
|
||||
without the header) the route answers 400 `actor_required`. The stamp lands in
|
||||
`identity_provenance` on transitions, inbox, outbox and stream rows
|
||||
(migrations `067`, `082`).
|
||||
- `/api/queue` (`server.ts:785`) — `POST /create` (`routes/queue.ts:402`),
|
||||
`POST /:qitemId/claim` (`:501`), `POST /:qitemId/unclaim` (`:517`),
|
||||
`POST /:qitemId/update` (`:556`), plus handoff (`:606`, `:682`), list
|
||||
(`:842`) and watch (`:994`) surfaces.
|
||||
|
||||
## See also
|
||||
|
||||
|
||||
@@ -9,8 +9,8 @@ applies-when: |
|
||||
graph, the SQLite schema/migration set, or the route-mount surface.
|
||||
siblings: [coordination-primitive.md, agent-spec-and-startup.md, lifecycle-snapshot-restore.md]
|
||||
prerequisite-reads: [../README.md]
|
||||
last-verified-against-source: e8f0ab340db773392ec8be75b072d1c0f3068a50
|
||||
last-updated: 2026-10-08
|
||||
last-verified-against-source: b6d37bfadcc189be8fd61e35abfc09676437bf48
|
||||
last-updated: 2026-10-03
|
||||
---
|
||||
|
||||
# Daemon Core — Wiring, DB, Migrations, Startup
|
||||
@@ -20,7 +20,7 @@ OpenRig is a local control plane for multi-agent coding topologies. The daemon
|
||||
(`@openrig/cli`), the terminal UI (`@openrig/tui`), the web UI (`@openrig/ui`)
|
||||
and the MCP server all sit on top of.
|
||||
|
||||
> Verified against source at main `e8f0ab340db773392ec8be75b072d1c0f3068a50`. Each count below sits beside the
|
||||
> Verified against source at main `b6d37bfadcc189be8fd61e35abfc09676437bf48`. Each count below sits beside the
|
||||
> command that produces it; run the command from the repository root to refresh
|
||||
> it.
|
||||
|
||||
@@ -29,7 +29,7 @@ and the MCP server all sit on top of.
|
||||
For what OpenRig is and how its packages fit together, read `ARCHITECTURE.md` at
|
||||
the repository root. This module covers the daemon's own wiring.
|
||||
|
||||
### Source footprint at `e8f0ab340db773392ec8be75b072d1c0f3068a50`
|
||||
### Source footprint at `b6d37bfadcc189be8fd61e35abfc09676437bf48`
|
||||
|
||||
The footprint counts use non-test TypeScript files under each package's `src/`
|
||||
(tests live in separate `packages/*/test/` directories):
|
||||
@@ -37,26 +37,26 @@ The footprint counts use non-test TypeScript files under each package's `src/`
|
||||
|
||||
| Metric | Count | Directory or command |
|
||||
|---|---|---|
|
||||
| All packages | **1205** | `packages/*/src` |
|
||||
| Daemon | **660** (**431** under `domain/`, **29** under `adapters/`) | `packages/daemon/src`, `…/src/domain`, `…/src/adapters` |
|
||||
| CLI | **174** | `packages/cli/src` |
|
||||
| All packages | **1158** | `packages/*/src` |
|
||||
| Daemon | **629** (**409** under `domain/`, **26** under `adapters/`) | `packages/daemon/src`, `…/src/domain`, `…/src/adapters` |
|
||||
| CLI | **162** | `packages/cli/src` |
|
||||
| Web UI | **304** | `packages/ui/src` |
|
||||
| TUI | **67** | `packages/tui/src` |
|
||||
| Database migrations | **96** (`001_core_schema.ts` … `097_thread_part_map.ts`; no `093`) | `git ls-files packages/daemon/src/db/migrations \| wc -l` |
|
||||
| Files in `routes/` | **68**, of which **65** create a Hono router | `git ls-files packages/daemon/src/routes \| wc -l`; `git grep -l 'new Hono' -- packages/daemon/src/routes \| wc -l` |
|
||||
| TUI | **63** | `packages/tui/src` |
|
||||
| Database migrations | **93** (`001_core_schema.ts` … `094_usage_samples_latest_indexes.ts`; no `093`) | `git ls-files packages/daemon/src/db/migrations \| wc -l` |
|
||||
| Files in `routes/` | **67**, of which **65** create a Hono router | `git ls-files packages/daemon/src/routes \| wc -l`; `git grep -l 'new Hono' -- packages/daemon/src/routes \| wc -l` |
|
||||
| `app.route(...)` mounts in `server.ts` | **69** | `grep -c 'app.route(' packages/daemon/src/server.ts` |
|
||||
| Top-level `rig` commands | **87** | `grep -c 'program.addCommand(' packages/cli/src/index.ts` |
|
||||
| Top-level `rig` commands | **85** | `grep -c 'program.addCommand(' packages/cli/src/index.ts` |
|
||||
| MCP tools | **18**, all named `rig_*` | `grep -c 'server.tool(' packages/cli/src/mcp-server.ts` |
|
||||
| Runtime adapter classes | **5**: Claude Code, Codex, Pi, Stub, Terminal | `git grep -l 'implements RuntimeAdapter' packages/daemon/src \| wc -l` |
|
||||
|
||||
`OmpRuntimeAdapter` (Oh My Pi) extends `PiRuntimeAdapter`, so the daemon wires
|
||||
six runtime keys — `claude-code`, `codex`, `pi`, `omp`, `stub`, `terminal`
|
||||
(`startup.ts:989`).
|
||||
(`startup.ts:945`).
|
||||
|
||||
### The stack
|
||||
|
||||
```text
|
||||
CLI (87 top-level commands) / TUI / web UI / MCP (24 tools)
|
||||
CLI (85 top-level commands) / TUI / web UI / MCP (18 tools)
|
||||
|
|
||||
v
|
||||
Hono daemon routes (69 app.route() mounts + direct handlers for /healthz,
|
||||
@@ -73,9 +73,9 @@ Hono daemon routes (69 app.route() mounts + direct handlers for /healthz,
|
||||
+-- coordination routes (stream / queue / workflow / mission control)
|
||||
|
|
||||
v
|
||||
Framework-free domain services (431 files under packages/daemon/src/domain)
|
||||
Framework-free domain services (409 files under packages/daemon/src/domain)
|
||||
|
|
||||
+-- SQLite state (96 migrations)
|
||||
+-- SQLite state (93 migrations)
|
||||
+-- tmux / cmux / resume adapters
|
||||
+-- runtime adapters (Claude Code / Codex / Pi / Oh My Pi / Stub / Terminal)
|
||||
+-- rig environment services (compose adapter, service readiness, orchestrator)
|
||||
@@ -88,10 +88,10 @@ handoff → inspect/attach → work → repeat`.
|
||||
|
||||
## 2. Database schema
|
||||
|
||||
The migrations live in `packages/daemon/src/db/migrations/` (96 files,
|
||||
`001_core_schema.ts` … `097_thread_part_map.ts`, with no `093`).
|
||||
`ALL_MIGRATIONS` (`packages/daemon/src/db/all-migrations.ts:107`) lists all 96, and `createDaemon`
|
||||
applies them with `migrate(db, ALL_MIGRATIONS)` (`startup.ts:298`). `migrate.ts`
|
||||
The migrations live in `packages/daemon/src/db/migrations/` (93 files,
|
||||
`001_core_schema.ts` … `094_usage_samples_latest_indexes.ts`, with no `093`).
|
||||
`ALL_MIGRATIONS` (`packages/daemon/src/db/all-migrations.ts:102`) lists all 93, and `createDaemon`
|
||||
applies them with `migrate(db, ALL_MIGRATIONS)` (`startup.ts:283`). `migrate.ts`
|
||||
sorts them by name (`:29`) and records each applied name in `schema_migrations`
|
||||
(`:15`).
|
||||
|
||||
@@ -111,8 +111,7 @@ in `003_events.ts`, `snapshots` (serialized rig state) in `004_snapshots.ts`, an
|
||||
`checkpoints`.
|
||||
- `015_startup_context.ts` — persisted startup replay context for restore.
|
||||
- `016_chat_messages.ts` — durable rig-scoped chat (SQLite-backed; transcripts
|
||||
remain filesystem-backed, written by bounded periodic `capture-pane` snapshots;
|
||||
see `transport-and-transcripts.md`).
|
||||
remain filesystem-backed via pipe-pane).
|
||||
- `017_pod_namespace.ts` — first-class authored pod namespace for export/adoption.
|
||||
- `018_context_usage.ts` — per-node context-usage snapshots.
|
||||
- `019_external_cli_attachment.ts` — binding-row extension for external CLI attach.
|
||||
@@ -129,8 +128,8 @@ in `003_events.ts`, `snapshots` (serialized rig state) in `004_snapshots.ts`, an
|
||||
- `031_watchdog_jobs.ts`, `032_watchdog_history.ts` — watchdog tables.
|
||||
- `033_workflow_specs.ts`, `034_workflow_instances.ts`,
|
||||
`035_workflow_step_trails.ts` — workflow runtime tables (detail in
|
||||
`workflow-runtime.md`). `036_watchdog_policy_enum_extension.ts` runs no DDL (its
|
||||
SQL is a no-op `SELECT 1 WHERE 0`); it documents an enum extension.
|
||||
`workflow-runtime.md`). `036_watchdog_policy_enum_extension.ts` runs no SQL; it
|
||||
documents an enum extension.
|
||||
- `037_mission_control_actions.ts` — the mission control audit table
|
||||
(`037_mission_control_actions.ts:58`; detail in `mission-control.md`).
|
||||
- `038_workspace_primitive.ts`, `039_queue_target_repo.ts` — the typed workspace
|
||||
@@ -138,13 +137,8 @@ in `003_events.ts`, `snapshots` (serialized rig state) in `004_snapshots.ts`, an
|
||||
- `040_workflow_specs_diagnostic.ts` — `ALTER TABLE workflow_specs ADD COLUMN`
|
||||
for parser/validator diagnostics (no new table).
|
||||
|
||||
Migrations `041`–`092` and `094`–`097` continue in the same directory; list them with
|
||||
`git ls-files packages/daemon/src/db/migrations`. `095_rig_non_interruptive.ts` adds
|
||||
`rigs.non_interruptive` (0 or 1, default 0), the saved per-rig choice behind
|
||||
`rig up --non-interruptive`; `096_rig_install_root.ts` adds `rigs.install_root`, the rig's
|
||||
bundle materialization folder (`rig-repository.ts:169`). The newest, `097_thread_part_map.ts`,
|
||||
adds `thread_part_map`, which maps each message OpenRig posts into an ask's Slack thread to
|
||||
that ask and its seat.
|
||||
Migrations `041`–`092` and `094` continue in the same directory; list them with
|
||||
`git ls-files packages/daemon/src/db/migrations`.
|
||||
|
||||
The package, bootstrap and discovery tables remain: `packages`
|
||||
(`008_packages.ts`), `package_installs` and `install_journal`
|
||||
@@ -154,81 +148,67 @@ The package, bootstrap and discovery tables remain: `packages`
|
||||
|
||||
## 3. Route-mount surface
|
||||
|
||||
`createApp(deps)` (`packages/daemon/src/server.ts:442`) mounts **69**
|
||||
`app.route()` route groups (`server.ts:723`–`839`) plus direct handlers:
|
||||
`GET /healthz` (`:664`), `GET /api/rigs/:rigId/spec` (`handleExportYaml`,
|
||||
`:735`), `GET /api/rigs/:rigId/spec.json` (`handleExportJson`, `:736`), a JSON
|
||||
`createApp(deps)` (`packages/daemon/src/server.ts:441`) mounts **69**
|
||||
`app.route()` route groups (`server.ts:724`–`839`) plus direct handlers:
|
||||
`GET /healthz` (`:665`), `GET /api/rigs/:rigId/spec` (`handleExportYaml`,
|
||||
`:736`), `GET /api/rigs/:rigId/spec.json` (`handleExportJson`, `:737`), a JSON
|
||||
`404 not_found` for any other `/api/*` path (`:844`), and the static/deep-link
|
||||
`app.get("*")` catch-all (`:853`).
|
||||
|
||||
The 69 is the count of `app.route(` lines in `server.ts`; `packages/daemon/src/routes/`
|
||||
has 68 files, 65 of which create a Hono router.
|
||||
has 67 files, 65 of which create a Hono router.
|
||||
|
||||
Mount families include the rig, session and spec routes plus the coordination
|
||||
routes (`/api/stream` `server.ts:783`, `/api/queue` `:784`, `/api/workflow`
|
||||
`:789`, `missionControlRoutes(...)` `:792`), `/api/seat` (`:781`, the seat
|
||||
lifecycle verbs such as handover, launch, continue, stop and the typing guard),
|
||||
`/api/startup` (`:747`), `/api/terminal` (`:809`), `/api/telemetry` (`:822`),
|
||||
`/api/health-summary` (`:829`), `/api/rigs/:rigId/env` (`:835`) and
|
||||
`/api/restore-check` (`:836`). List every mount with
|
||||
`grep -n 'app.route(' packages/daemon/src/server.ts`.
|
||||
|
||||
Before the routes, `createApp` installs middleware in this order: the request-phase
|
||||
observer (`:497`), JSON body-parse error tracking, which turns a malformed body into
|
||||
`400 invalid_json` (`:499`), dependency injection, route timing, slow-operation
|
||||
recording, the browser boundary on `/api/*` (`:647`, Host and Origin checks; see
|
||||
`OPENRIG_ALLOWED_HOSTS` and `OPENRIG_ALLOWED_ORIGINS`), and host read-through.
|
||||
routes (`/api/stream` `server.ts:784`, `/api/queue` `:785`, `/api/workflow`
|
||||
`:790`, `missionControlRoutes(...)` `:793`), `/api/health-summary` (`:829`),
|
||||
`/api/rigs/:rigId/env` (`:835`) and `/api/restore-check` (`:836`).
|
||||
|
||||
`createAppWithWebSocket(deps)` (`server.ts:893`) sets `enableNodeWebSocket` and
|
||||
calls `createApp`; the terminal WebSocket is registered only when the web UI is
|
||||
also enabled (`server.ts:756`). Otherwise only its bearer-auth handler is
|
||||
registered (`registerTerminalAuthOnly`, `:762`).
|
||||
also enabled (`server.ts:757`).
|
||||
|
||||
## 4. Startup sequence (`createDaemon`)
|
||||
|
||||
`createDaemon(opts?)` is `packages/daemon/src/startup.ts:287` (async, returns
|
||||
`createDaemon(opts?)` is `packages/daemon/src/startup.ts:274` (async, returns
|
||||
`DaemonResult`). It returns `{ app, db, deps, contextMonitor, eventLoopMonitor,
|
||||
injectWebSocket }` (`startup.ts:2506`). In source order, it:
|
||||
injectWebSocket }` (`startup.ts:2450`). In source order, it:
|
||||
|
||||
1. Opens SQLite and applies all 96 migrations (`migrate(db, ALL_MIGRATIONS)`,
|
||||
`startup.ts:298`).
|
||||
2. Constructs the coordination stores early: `StreamStore` (`:330`),
|
||||
`QueueRepository` (`:428`) and `OutboxHandler` (`:443`).
|
||||
3. Constructs `TranscriptStore` (`:555`) and the rig environment services
|
||||
`ComposeServicesAdapter` and `ServiceOrchestrator` (`:644`–`645`).
|
||||
4. Constructs `StartupOrchestrator` (`:776`) and the runtime adapters:
|
||||
`ClaudeCodeAdapter` (`:778`), `CodexRuntimeAdapter` (`:779`),
|
||||
`PiRuntimeAdapter` (`:782`), `OmpRuntimeAdapter` (`:783`) and
|
||||
`StubRuntimeAdapter` (`:788`); the terminal adapter is created inline in the
|
||||
runtime adapter maps (`:989`, `:1259`).
|
||||
5. Constructs `PodRigInstantiator` (`:985`), `PodBundleSourceResolver` (`:1014`)
|
||||
and `BootstrapOrchestrator` (`:1016`).
|
||||
6. Constructs `ContextUsageStore` (`:1095`), `ResumeMetadataRefresher`
|
||||
(`:1129`), `SpecReviewService` (`:1154`) and `WhoamiService` (`:1157`).
|
||||
7. Builds `AppDeps` (`const deps: AppDeps`, `:1191`). `SessionTransport`
|
||||
(`:1262`), `ChatRepository` (`:1296`), `InboxHandler` (`:1300`), `AskService`
|
||||
(`:1349`) and `SpecLibraryService` (`:1387`) are constructed inside that
|
||||
object literal. `InboxHandler` receives the same queue repository instance
|
||||
1. Opens SQLite and applies all 93 migrations (`migrate(db, ALL_MIGRATIONS)`,
|
||||
`startup.ts:283`).
|
||||
2. Constructs the coordination stores early: `StreamStore` (`:315`),
|
||||
`QueueRepository` (`:413`) and `OutboxHandler` (`:428`).
|
||||
3. Constructs `TranscriptStore` (`:540`) and the rig environment services
|
||||
`ComposeServicesAdapter` and `ServiceOrchestrator` (`:621`–`622`).
|
||||
4. Constructs `StartupOrchestrator` (`:753`) and the runtime adapters:
|
||||
`ClaudeCodeAdapter` (`:755`), `CodexRuntimeAdapter` (`:756`),
|
||||
`PiRuntimeAdapter` (`:759`), `OmpRuntimeAdapter` (`:760`) and
|
||||
`StubRuntimeAdapter` (`:765`); the terminal adapter is created inline in the
|
||||
runtime adapter map (`:945`).
|
||||
5. Constructs `PodRigInstantiator` (`:941`), `PodBundleSourceResolver` (`:970`)
|
||||
and `BootstrapOrchestrator` (`:972`).
|
||||
6. Constructs `ContextUsageStore` (`:1046`), `ResumeMetadataRefresher`
|
||||
(`:1077`), `SpecReviewService` (`:1102`) and `WhoamiService` (`:1105`).
|
||||
7. Constructs `SessionTransport` (`:1210`), `ChatRepository` (`:1244`),
|
||||
`InboxHandler` (`:1248`), `AskService` (`:1297`) and `SpecLibraryService`
|
||||
(`:1335`). `InboxHandler` receives the same queue repository instance
|
||||
(`queueRepoInstance`) that serves `/api/queue`, so absorbed inbox items and the
|
||||
queue route write to one store.
|
||||
8. Constructs `ContextMonitor` (`:2407`), then assigns later fields onto `deps`
|
||||
(among them the terminal service, the request-phase observer and the gateway
|
||||
subsystem).
|
||||
9. Calls `createAppWithWebSocket(deps)` (`startup.ts:2504`) to mount the full
|
||||
route tree.
|
||||
8. Constructs `ContextMonitor` (`:2353`).
|
||||
9. Builds `AppDeps` and calls `createAppWithWebSocket(deps)` (`startup.ts:2448`)
|
||||
to mount the full route tree.
|
||||
|
||||
Node inventory is a set of functions (`getNodeInventory` and friends in
|
||||
`domain/node-inventory.ts`), imported where needed rather than constructed at
|
||||
startup.
|
||||
|
||||
The daemon entrypoint `packages/daemon/src/index.ts:306` calls
|
||||
The daemon entrypoint `packages/daemon/src/index.ts:298` calls
|
||||
`createDaemon({ dbPath, bearerToken, terminalBearerToken, … })`.
|
||||
|
||||
## 5. Test files
|
||||
|
||||
A static count of tracked test files at `e8f0ab340db773392ec8be75b072d1c0f3068a50` (no pass counts are claimed
|
||||
here; CI runs the suites in `.github/workflows/tests.yml`): daemon **927**,
|
||||
CLI **261**, web UI **198**, TUI **105**
|
||||
A static count of tracked test files at `b6d37bfadcc189be8fd61e35abfc09676437bf48` (no pass counts are claimed
|
||||
here; CI runs the suites in `.github/workflows/tests.yml`): daemon **821**,
|
||||
CLI **216**, web UI **198**, TUI **96**
|
||||
(`git ls-files 'packages/<package>/**/*.test.ts' 'packages/<package>/**/*.test.tsx' | wc -l`).
|
||||
|
||||
## See also
|
||||
|
||||
@@ -11,8 +11,8 @@ applies-when: |
|
||||
and the CLI restore-packet command work.
|
||||
siblings: [daemon-core.md, agent-spec-and-startup.md, transport-and-transcripts.md]
|
||||
prerequisite-reads: [../README.md, agent-spec-and-startup.md]
|
||||
last-verified-against-source: e8f0ab340db773392ec8be75b072d1c0f3068a50
|
||||
last-updated: 2026-10-08
|
||||
last-verified-against-source: 254122872cf477511514979a4300b695d77cd1f7
|
||||
last-updated: 2026-10-03
|
||||
---
|
||||
|
||||
# Lifecycle — Snapshot, Restore, Continuity
|
||||
@@ -22,7 +22,7 @@ The durable-state half of the core product loop:
|
||||
captures serialized rig state; restore replays it honestly (no silent
|
||||
fresh-fallback); restore-check is a separate read-only readiness probe.
|
||||
|
||||
> Verified against source at main `e8f0ab340db773392ec8be75b072d1c0f3068a50`. Each count below sits beside the
|
||||
> Verified against source at main `254122872cf477511514979a4300b695d77cd1f7`. Each count below sits beside the
|
||||
> command that produces it; run the command from the repository root to refresh
|
||||
> it.
|
||||
|
||||
@@ -31,76 +31,51 @@ fresh-fallback); restore-check is a separate read-only readiness probe.
|
||||
All in `packages/daemon/src/domain/types.ts`. The spec/projection types live in
|
||||
`agent-spec-and-startup.md`; the snapshot/restore types live here.
|
||||
|
||||
- **NodeRestoreOutcome** (`types.ts:500`) — the per-node restore outcome
|
||||
- **NodeRestoreOutcome** (`types.ts:501`) — the per-node restore outcome
|
||||
projected into `rig ps`. **9** values
|
||||
(`grep '^export type NodeRestoreOutcome' packages/daemon/src/domain/types.ts | grep -o '"[^"]*"' | wc -l`):
|
||||
`resumed`, `rebuilt`, `fresh`, `fresh-primed`, `awaiting-decision`,
|
||||
`failed`, `attention_required`, `operator_recovered`, `n-a`. The restore
|
||||
result itself, `RestoreNodeResult.status` (`types.ts:475`), has the same
|
||||
values without `n-a`, plus `left_attached`: **9**
|
||||
result itself, `RestoreNodeResult.status` (`types.ts:476`), has the same
|
||||
values without `n-a`: **8**
|
||||
(`grep -E '^ status: "resumed"' packages/daemon/src/domain/types.ts | grep -o '"[^"]*"' | wc -l`).
|
||||
`left_attached` isn't a `NodeRestoreOutcome`; the inventory projects it as `n-a`.
|
||||
Where `restore-orchestrator.ts` sets each one:
|
||||
- `resumed` — `baseStatus = "resumed"` after a legacy resume (`:1030`); the
|
||||
status is returned only by `finishJoinedResume` (defined `:1320`, called
|
||||
`:1244` and `:1311`, returning `resumed` at `:1380`) after it has rebound
|
||||
and verified the pane; otherwise that becomes `attention_required`
|
||||
(`:1352`, `:1376`).
|
||||
- `rebuilt` — a checkpoint file was written (`:1090`).
|
||||
- `resumed` — `baseStatus = "resumed"` after a legacy resume (`:1212`); the
|
||||
status is returned only by `finishJoinedResume` (`:1499`, `:1561`) after
|
||||
it has rebound and verified the pane, otherwise that becomes
|
||||
`attention_required` (`:1533`).
|
||||
- `rebuilt` — a checkpoint file was written (`:1272`).
|
||||
- `fresh-primed` — the default for a deliberate non-resume launch
|
||||
(`:987`).
|
||||
(`:1194`).
|
||||
- `fresh` — only the skip path for a pod node whose live continuity state
|
||||
is already `restoring` (`:785`).
|
||||
is already `restoring` (`:992`).
|
||||
- `awaiting-decision` — the seat could not resume and nothing is running:
|
||||
before launch (`:820`), or after launch once the blank session is rolled
|
||||
back (`:1026`, `:1048`, `:1061`, `:1077`, `:1236`).
|
||||
before launch (`:1027`), or after launch once the blank session is rolled
|
||||
back (`:1208`, `:1230`, `:1243`, `:1259`, `:1417`).
|
||||
- `attention_required` — a live session waiting on a runtime prompt
|
||||
(`:1039`, `:1262`) or a harness that never started (`:1125`).
|
||||
- `failed` — occupant ambiguity (`:772`, `:969`), launch failure (`:911`),
|
||||
a checkpoint that cannot be delivered (`:1086`, `:1092`), a missing
|
||||
required startup file (`:1161`), or a startup error (`:1271`, `:1282`,
|
||||
`:1292`, `:1300`).
|
||||
(`:1221`, `:1443`) or a harness that never started (`:1307`).
|
||||
- `failed` — occupant ambiguity (`:979`), launch failure (`:1118`), a
|
||||
checkpoint that cannot be delivered (`:1268`, `:1274`), a missing
|
||||
required startup file (`:1343`), or a startup error.
|
||||
- `operator_recovered` — only from later reconciliation,
|
||||
`reconcileNodeRuntimeTruth` (`:1590`, event at `:1727`).
|
||||
- `left_attached` — a seat joined with `rig attach` as an external CLI,
|
||||
returned first in `restoreNodeWithCompensation`: nothing is launched and
|
||||
its binding and claim stay as they were. It doesn't count against the
|
||||
rollup, and its forecast in `restore-plan-preview.ts` is `leave-attached`.
|
||||
- **RestoreRigResult** (`types.ts:444`) — the rig-level rollup, **4** values
|
||||
`reconcileNodeRuntimeTruth` (`:1759`, event at `:1902`).
|
||||
- **RestoreRigResult** (`types.ts:445`) — the rig-level rollup, **4** values
|
||||
(`grep '^export type RestoreRigResult' packages/daemon/src/domain/types.ts | grep -o '"[^"]*"' | wc -l`):
|
||||
`fully_restored`, `partially_restored`, `failed`, `not_attempted`.
|
||||
`rollupRestoreRigResult` (`restore-orchestrator.ts:81`) produces only the
|
||||
first three; `not_attempted` is set when pre-restore validation fails
|
||||
(`:281`).
|
||||
- **SnapshotData** (`types.ts:351`) — the serialized snapshot payload. It has
|
||||
**8** optional fields, kept optional so older snapshots still load
|
||||
`fully_restored`, `partially_restored`, `failed`, `not_attempted`
|
||||
(`rollupRestoreRigResult`, `restore-orchestrator.ts:82`).
|
||||
- **SnapshotData** (`types.ts:352`) — the serialized snapshot payload. It has
|
||||
**7** optional fields, kept optional so older snapshots still load
|
||||
(`sed -n '/^export interface SnapshotData/,/^}/p' packages/daemon/src/domain/types.ts | grep -c '?:'`):
|
||||
`activeSessionIdByNode?`, `activeOccupantsByNode?`, `periodicResumeSourcesByNode?`,
|
||||
`topologyRoster?`, `pods?`, `continuityStates?`, `nodeStartupContext?`, `envReceipt?`.
|
||||
Periodic snapshots retain a down agent's whole authoritative resume-source
|
||||
session in `periodicResumeSourcesByNode`, without marking it running. A named
|
||||
single-agent launch using automatic periodic selection can resume that exact
|
||||
carried source; an explicit snapshot or whole-rig restore still asks about an
|
||||
absent agent with resumable history. Tokenless and non-resume-policy agents
|
||||
keep their existing fresh path. Only the node's newest session with a token
|
||||
and `resume_if_possible` policy is carried; a current fresh-successor relation
|
||||
must agree. Named launch rechecks the live newest session, resume policy and
|
||||
fresh-successor relation under its lifecycle lease, before changing any seat
|
||||
state; a source retired after capture stops and asks without launching.
|
||||
Idle-shell carry advice uses automatic selection again, not an
|
||||
explicit snapshot that disables carry. The selected source is shared by preflight and post-launch
|
||||
restore; explicit reviewed-history selection keeps its existing checks.
|
||||
Ranking, periodic cadence and `--fresh` are unchanged. Retention is best-effort
|
||||
if the earlier-source lookup fails: capture still records current crash
|
||||
insurance and logs that the resume sources were unavailable.
|
||||
- **NodeStartupSnapshot** (`types.ts:344`) — persisted restore replay input:
|
||||
`activeSessionIdByNode?`, `activeOccupantsByNode?`, `topologyRoster?`,
|
||||
`pods?`, `continuityStates?`, `nodeStartupContext?`, `envReceipt?`.
|
||||
- **NodeStartupSnapshot** (`types.ts:345`) — persisted restore replay input:
|
||||
classification-free projection entries, resolved startup files, startup
|
||||
actions, runtime.
|
||||
- **PersistedProjectionEntry** (`types.ts:332`) — the classification-free
|
||||
- **PersistedProjectionEntry** (`types.ts:333`) — the classification-free
|
||||
restore replay seam: persists only entry identity + source metadata, NOT
|
||||
stale `classification`, `conflicts`, or `noOps` (Architecture Rule 10).
|
||||
Restore rebuilds each entry as `safe_projection` with empty `conflicts` and
|
||||
`noOps` (`restore-orchestrator.ts:1177`, `:1182`, `:1183`).
|
||||
`noOps` (`restore-orchestrator.ts:1352`, `:1357`, `:1358`).
|
||||
|
||||
## 2. Snapshot, restore, continuity domain services
|
||||
|
||||
@@ -115,310 +90,190 @@ All under `packages/daemon/src/domain/`:
|
||||
and the env receipt (`:116–123`).
|
||||
- `snapshot-repository.ts` — snapshot CRUD and restore-source selection:
|
||||
`findLatestRestoreUsable` (`:72`) and `selectRestoreUsable` (`:94`), which
|
||||
accept only snapshots that pass `isRestoreUsableSnapshotData` (`:250`).
|
||||
accept only snapshots that pass `isRestoreUsableSnapshotData` (`:283`).
|
||||
- `restore-orchestrator.ts` — resume, checkpoint delivery, startup replay,
|
||||
live continuity consultation, topology ordering (`computeRestorePlan`,
|
||||
`:676`, ordering only `delegates_to` and `spawned_by` edges, `:71`, among
|
||||
the roster's intended nodes, `:677`), and service boot gating before agent
|
||||
restore (`serviceOrchestrator.boot`, `:331`).
|
||||
- `restore-preconditions.ts` — `validatePreRestore` (`:7`), the one
|
||||
pre-restore validation shared by restore and restore-check (§3, §5.1).
|
||||
- `restore-topology.ts` — `resolveSnapshotRestoreTopology` (`:12`), which
|
||||
splits a snapshot's nodes into intended and excluded (§3).
|
||||
- `restore-attempt-receipt.ts` — `deriveRestoreAttemptReceipt` (`:42`), the
|
||||
read-only per-attempt receipt (§4).
|
||||
- `rehydrate-eligibility.ts` — `snapshotMatchesCurrentOccupants` (`:20`) and
|
||||
`assessCurrentStateRehydrateEligibility` (`:69`), shared by `routes/up.ts`
|
||||
and `routes/restore-check.ts`.
|
||||
`:876`, ordering only `delegates_to` and `spawned_by` edges, `:72`), and
|
||||
service boot gating before agent restore (`serviceOrchestrator.boot`,
|
||||
`:328`).
|
||||
- `active-occupant.ts` — the shared rule for which snapshot session row is a
|
||||
node's occupant (`resolveActiveSnapshotSession`, `:73`).
|
||||
node's occupant (`resolveActiveSnapshotSession`, `:74`).
|
||||
|
||||
## 3. Restore flow and restore honesty
|
||||
|
||||
Restore behavior, each point checked in `restore-orchestrator.ts`:
|
||||
|
||||
- Selects the snapshot with `selectRestoreUsable` even when a snapshot id is
|
||||
given (`:251–252`), so wrong-rig and unusable snapshots are refused before
|
||||
any mutation. The selection (`RestoreSnapshotSelection`, `types.ts:396`)
|
||||
records whether it was explicit or automatic, why, and any newer usable
|
||||
alternative; it is carried on the result and on `restore.started`.
|
||||
- Restores only the nodes the snapshot's topology roster intends
|
||||
(`SnapshotData.topologyRoster`, `types.ts:370`). The roster comes from the
|
||||
latest `topology.roster_recorded` event (`snapshot-capture.ts:171`), from
|
||||
`rig snapshot <rigId> --intended-seats` (`packages/cli/src/commands/snapshot.ts:20`),
|
||||
or, for older snapshots, all current nodes. `resolveSnapshotRestoreTopology`
|
||||
(`restore-topology.ts:12`) reports every other node as excluded with reason
|
||||
`historical_not_in_intended_roster` (`:27`); the result carries
|
||||
`intendedRoster` and `excludedNodes` (`types.ts:440–441`).
|
||||
- Resolves each node's occupant from the snapshot's recorded active-occupant
|
||||
maps, not by picking the newest session row
|
||||
(`resolveActiveSnapshotSession`, `active-occupant.ts:74`, called at
|
||||
`restore-orchestrator.ts:774` and `:971`). An ambiguous occupant fails the
|
||||
`restore-orchestrator.ts:974` and `:1171`). An ambiguous occupant fails the
|
||||
node loudly (`activeOccupantAmbiguityError`, `active-occupant.ts:97`).
|
||||
- Consults live `continuity_state`; preserves state when a node is already
|
||||
`restoring` (`:777–791` — `SELECT status FROM continuity_state …` at
|
||||
`:780`; if `status === "restoring"` the node is skipped with a warning and
|
||||
reported as `fresh`, `:783–785`; `degraded` only adds a warning).
|
||||
- Reuses the seat's durably bound tmux session name when the prior binding
|
||||
has a usable one (`:840`), and otherwise falls back to the derived name
|
||||
with a warning (`:869`).
|
||||
`restoring` (`:985–998` — `SELECT status FROM continuity_state …` at
|
||||
`:987`; if `status === "restoring"` the node is skipped with a warning and
|
||||
reported as `fresh`, `:990–992`; `degraded` only adds a warning).
|
||||
- Replays restore-safe startup using persisted startup context;
|
||||
prefilters missing optional artifacts into warnings; **hard-fails a node if
|
||||
a required startup file is missing** (`:1161` — status `"failed"`, error
|
||||
a required startup file is missing** (`:1343` — status `"failed"`, error
|
||||
"Missing required startup files: …"). Before any mutation,
|
||||
`validatePreRestore` (`restore-preconditions.ts:7`, called from
|
||||
`RestoreOrchestrator.restore`) finds a node that will consume replay and is
|
||||
missing a required startup file (`required_startup_file_missing`, or
|
||||
`startup_owner_root_missing`). Restore holds only that node: it is not
|
||||
launched and is reported `failed` ("Not launched: …" with the blocker's
|
||||
message and remediation), and the rest of the rig restores. When every node
|
||||
the restore would launch is held, or for any other blocker, the whole restore
|
||||
stops before any mutation (outcome `pre_restore_validation_failed`). Its other
|
||||
blockers are `invalid_snapshot_data` (`restore-preconditions.ts:27`),
|
||||
`invalid_topology_roster` (`:78`), `checkpoint_missing_node_cwd` (`:91`),
|
||||
`service_rig_root_missing` (`:187`) and `service_compose_file_missing`
|
||||
(`:197`). The `/api/up` route returns
|
||||
that outcome as HTTP 409 with `status: "not_attempted"`
|
||||
(`routes/up.ts:162`). A node that resumes its exact native session replays
|
||||
no startup files, actions, guidance or skills (`replayContained`,
|
||||
`restore-orchestrator.ts:1114`); its saved Claude activity-hook selection
|
||||
is reapplied before native resume. A skipped hook reapply adds a warning
|
||||
without changing the restore outcome.
|
||||
`validatePreRestore` (`:585`) already blocks the whole restore when a node
|
||||
that will consume replay is missing a required startup file
|
||||
(`required_startup_file_missing`, `:729`; outcome
|
||||
`pre_restore_validation_failed`, `:290`). A node that resumes its exact
|
||||
native session replays no startup files, actions, guidance or skills
|
||||
(`replayContained`, `:1288`); its saved Claude activity-hook selection is
|
||||
reapplied before native resume. A skipped hook reapply adds a warning without
|
||||
changing the restore outcome.
|
||||
- Writes a **transcript boundary marker before re-launch**
|
||||
(`writeBoundaryMarker`, `:900`, called before `launchNode` at `:911`) when
|
||||
the transcript store is enabled.
|
||||
- Refuses to restore over live sessions (`:259–262` — `rig_not_stopped`: "Rig …
|
||||
has live sessions. Stop the rig with 'rig down' before restoring, or use the
|
||||
latest auto-pre-down snapshot."). A tmux probe that fails also blocks it
|
||||
(`classifyRunningSessions`, `:612`).
|
||||
(`writeBoundaryMarker`, `:1100`, called before `launchNode`).
|
||||
- Refuses to restore over live sessions (`:258–261` — `rig_not_stopped`: "Rig …
|
||||
has live sessions. Stop the rig with 'rig down' before restoring"). A tmux
|
||||
probe that fails also blocks it (`classifyRunningSessions`, `:812`).
|
||||
- Checks that the harness actually resumed. The resume adapters judge the
|
||||
pane with `assessNativeResumeProbe` (`domain/native-resume-probe.ts:84`). A
|
||||
pod-aware resume counts as resumed only when startup reports `resumed`
|
||||
continuity or the launched session row carries the snapshot's resume type
|
||||
and token (`launchedSessionMatchesSnapshotResume`,
|
||||
`restore-orchestrator.ts:1390`); a reported `fresh` continuity without that
|
||||
proof rolls back to `awaiting-decision` (`:1228–1245`).
|
||||
- Saves a `rig up --non-interruptive` or `--no-non-interruptive` choice on
|
||||
the rig only after the live-session check and pre-restore validation pass
|
||||
(`:301`); see [adapters-and-runtimes.md](adapters-and-runtimes.md) for the
|
||||
launch flags.
|
||||
|
||||
`launchNodeSubset` (`:392`) and `launchSingleNode` restore chosen seats rather
|
||||
than the whole rig; unlike a full restore, a failed tmux probe there proceeds
|
||||
with a `liveness_probe_unknown` warning (`:517`).
|
||||
`restore-orchestrator.ts:1564`); a reported `fresh` continuity without that
|
||||
proof rolls back to `awaiting-decision` (`:1405–1419`).
|
||||
|
||||
**Restore-honesty rules** (texts in `architecture-rules-and-event-system.md`;
|
||||
cited here by number with the code that carries them):
|
||||
|
||||
- Rule 7 — `RESTORE_POLICY_LEVEL`
|
||||
(`packages/daemon/src/domain/profile-resolver.ts:106`) orders the three
|
||||
policies, and `resolveRestorePolicy` (`profile-resolver.ts:589`) rejects a
|
||||
(`packages/daemon/src/domain/profile-resolver.ts:103`) orders the three
|
||||
policies, and `resolveRestorePolicy` (`profile-resolver.ts:488`) rejects a
|
||||
profile or member value that broadens it.
|
||||
- Rule 14 — the outcome set is `RestoreNodeResult.status` (`types.ts:475`,
|
||||
- Rule 14 — the outcome set is `RestoreNodeResult.status` (`types.ts:476`,
|
||||
§1); `rebuilt` is set only when a checkpoint is written
|
||||
(`restore-orchestrator.ts:1097`).
|
||||
(`restore-orchestrator.ts:1272`).
|
||||
- Rule 15 — in `restore-orchestrator.ts`, a `resume_if_possible` seat with a
|
||||
session but no token stops as `awaiting-decision` before launch unless
|
||||
`--fresh` names it (`:812–831`); a failed resume kills the blank session
|
||||
(`rollbackToZeroSession`, `:940`) and returns `awaiting-decision`
|
||||
(`:1055`); pod-aware resume passes
|
||||
`allowFreshFallback: !(isPodAware && resumeRequested)` (`:1224`). Fresh
|
||||
launch is explicit: `rig up --existing <rig> --fresh <seats...>`
|
||||
(`packages/cli/src/commands/up.ts:99`). On a terminal, `rig up` asks
|
||||
yes or no for each `awaiting-decision` seat and re-posts with the accepted
|
||||
seats as fresh (`up.ts:589`).
|
||||
`--fresh` names it (`:1020–1029`); a failed resume kills the blank session
|
||||
(`rollbackToZeroSession`, `:1140`) and returns `awaiting-decision`
|
||||
(`:1230`); pod-aware resume passes
|
||||
`allowFreshFallback: !(isPodAware && resumeRequested)` (`:1399`). Fresh
|
||||
launch is explicit: `rig up --existing <rig> --fresh <seat...>`
|
||||
(`packages/cli/src/commands/up.ts:85`).
|
||||
- Rule 16 — `rig down` prints the snapshot id and a restore command
|
||||
(`packages/cli/src/commands/down.ts:293–303`); `rig up` on an existing rig
|
||||
(`packages/cli/src/commands/down.ts:236–246`); `rig up` on an existing rig
|
||||
prints per-node statuses and the attach command
|
||||
(`packages/cli/src/commands/up.ts:554–587`).
|
||||
(`packages/cli/src/commands/up.ts:540–560`).
|
||||
|
||||
(The full rule list lives in `architecture-rules-and-event-system.md`.)
|
||||
|
||||
## 4. Auto-snapshot and existing-rig power-on
|
||||
|
||||
- `rig down <rig>` (name or id, `packages/cli/src/commands/down.ts:144`)
|
||||
first prints the rig's recorded agent sessions and their activity, best
|
||||
effort and only without `--json` (`showAgentsBeforeDown`, `down.ts:28`), then
|
||||
- `rig down <rig>` (name or id, `packages/cli/src/commands/down.ts:104`)
|
||||
auto-captures an `auto-pre-down` snapshot before teardown when the rig has
|
||||
live sessions (`packages/daemon/src/domain/rig-teardown.ts:117`, capture
|
||||
at `:128`, after refreshing resume metadata at `:119`; an already-stopped
|
||||
rig returns at `:93–115` without one).
|
||||
live sessions (`packages/daemon/src/domain/rig-teardown.ts:116`; an
|
||||
already-stopped rig returns at `:89–109` without one).
|
||||
- `rig up <rig-name>`: a source with no `/` and no
|
||||
`.yaml`/`.yml`/`.rigbundle`/`.rigtopology` extension is a rig name
|
||||
(`packages/daemon/src/domain/up-command-router.ts:49–50`). The CLI refuses
|
||||
a name that matches only archived rigs, with `rig unarchive` guidance
|
||||
(`packages/cli/src/commands/up.ts:256`). It then checks the spec library
|
||||
unless `--existing` is given, and refuses a name that matches both
|
||||
(`up.ts:306–325`); when `first-project` resolves to the built-in `starter`
|
||||
spec, the archived and existing-rig checks also apply to `starter`
|
||||
(`up.ts:314–317`). The daemon finds the rig by name, preferring unarchived
|
||||
rigs (`packages/daemon/src/routes/up.ts:223–226`), and restores from
|
||||
`selectRestoreUsable` (`routes/up.ts:106`), which prefers the newest
|
||||
`auto-pre-down` or `auto-periodic` snapshot, then the newest other usable
|
||||
one (`snapshot-repository.ts:75`).
|
||||
- `rig up <rig-name> --plan` is a read-only restore preview that never
|
||||
captures a snapshot (`routes/up.ts:127`).
|
||||
(`packages/daemon/src/domain/up-command-router.ts:49–50`). The CLI first
|
||||
checks the spec library unless `--existing` is given, and refuses a name
|
||||
that matches both (`packages/cli/src/commands/up.ts:287–302`). The daemon
|
||||
finds the rig by name (`packages/daemon/src/routes/up.ts:222`) and
|
||||
restores from `selectRestoreUsable` (`routes/up.ts:105`), which prefers the
|
||||
newest `auto-pre-down` or `auto-periodic` snapshot, then the newest other
|
||||
usable one (`snapshot-repository.ts:75`).
|
||||
- If no usable snapshot exists, or the chosen one names an older occupant
|
||||
(`snapshotMatchesCurrentOccupants`, `routes/up.ts:110`), `rig up` captures
|
||||
(`snapshotMatchesCurrentOccupants`, `routes/up.ts:109`), `rig up` captures
|
||||
an `auto-rehydrate` snapshot of current DB state when that state is
|
||||
eligible (`routes/up.ts:137–146`). Otherwise it errors with code
|
||||
eligible (`routes/up.ts:136–145`). Otherwise it errors with code
|
||||
`no_snapshot` and guidance ("… current DB state is insufficient for
|
||||
rehydrate. Start fresh with: rig up <spec-path>", `routes/up.ts:118–123`).
|
||||
rehydrate. Start fresh with: rig up <spec-path>", `routes/up.ts:117–122`).
|
||||
- Post-command handoff: `down` output includes the snapshot ID and
|
||||
`To restore: rig up <name>` (or `rig restore <snapshotId> --rig <rigId>`
|
||||
when the name is not unique); `up` output includes node statuses and an
|
||||
`Attach:` command (anchors under Rule 16 above).
|
||||
- `rig restore status <attemptId> --rig <rigId>`
|
||||
(`packages/cli/src/commands/restore.ts:120`) reads
|
||||
`GET /api/rigs/:rigId/restore/status/:attemptId`
|
||||
(`packages/daemon/src/routes/snapshots.ts:76`). `deriveRestoreAttemptReceipt`
|
||||
(`restore-attempt-receipt.ts:42`) folds that attempt's events into a
|
||||
per-node view without writing anything.
|
||||
|
||||
### Single-seat recovery and handover
|
||||
|
||||
- **`rig seat continue <seat>`** — when a fresh launch stops at a native
|
||||
prompt before its startup context is delivered, the startup orchestrator
|
||||
fails it as `attention_required` and adds "run: rig seat continue
|
||||
<session>" (`startup-orchestrator.ts:822`). The command
|
||||
(`packages/cli/src/commands/seat.ts:816`) calls
|
||||
`POST /api/seat/continue/:seatRef` (`routes/seat.ts:367`), which runs
|
||||
`continueStartup` (`seat-lifecycle-service.ts:723`): it re-checks the
|
||||
binding, pane and runtime, then delivers the pending context to the same
|
||||
conversation without relaunching. In a restore, a pod-aware seat in this
|
||||
state reports `attention_required` (`restore-orchestrator.ts:1265`). See
|
||||
[agent-spec-and-startup.md](agent-spec-and-startup.md) for the startup side.
|
||||
- **Per-seat startup decision** — `POST /api/startup/:rigId/:logicalId`
|
||||
(`routes/startup.ts:142`) takes `resume`, `start`, `fresh` or `continue`
|
||||
for one seat. `resume` captures an eligibility-checked `auto-rehydrate`
|
||||
snapshot when none exists and goes through `launchSingleNode`.
|
||||
- **Seat handover** — `rig seat handover <seat> --source
|
||||
fresh|rebuild|fork:<id>|discovered:<id> --reason <reason> [--dry-run]`
|
||||
(the reason is required, dry run included; without it the command exits 2
|
||||
before contacting the daemon)
|
||||
(`packages/cli/src/commands/seat.ts:364`) calls
|
||||
`POST /api/seat/handover/:seatRef` (`routes/seat.ts:94`), which runs
|
||||
`SeatHandoverService.handover` (`seat-handover-service.ts:266`).
|
||||
`SuccessorSessionLauncher` (`successor-session-launcher.ts:92`) respawns
|
||||
the same pane in place, so the session name stays the same. The fresh
|
||||
source delivers a daemon-built restore packet (`buildRestorePacket`,
|
||||
`seat-handover-service.ts:1151`), which is separate from the CLI
|
||||
`rig restore-packet` below. The rebuild source primes from the seat's
|
||||
durable chain (`buildRebuildPrimingChain`, `rebuild-priming-chain.ts:22`).
|
||||
|
||||
## 5. Daemon-side restore-check and CLI restore-packet
|
||||
|
||||
### 5.1 `rig restore-check` — readiness probe
|
||||
|
||||
`GET /api/restore-check?rig=<name>&noQueue=true&noHooks=true&compact=1&ready=1`
|
||||
(`routes/restore-check.ts:220–221`). The route calls
|
||||
`createRestoreCheckService` (`:151`), which assembles a framework-free
|
||||
`RestoreCheckDeps` (`:155–216`) over existing daemon projections —
|
||||
`listRigs` from `rigRepo` (`:175–178`), `getNodeInventory` (joining
|
||||
`node_id` by `logical_id`, `:26–31`, `:179–185`), `getStartupContext` (reads
|
||||
(`routes/restore-check.ts:205–206`). The route calls
|
||||
`createRestoreCheckService` (`:149`), which assembles a framework-free
|
||||
`RestoreCheckDeps` (`:153–201`) over existing daemon projections —
|
||||
`listRigs` from `rigRepo` (`:172–175`), `getNodeInventory` (joining
|
||||
`node_id` by `logical_id`, `:24–29`, `:176–182`), `getStartupContext` (reads
|
||||
`node_startup_context`, parses `projection_entries_json` /
|
||||
`resolved_files_json` / `startup_actions_json`, `:49–143`), `hasSnapshot`
|
||||
/ `getLatestSnapshot` from `snapshotRepo` (`:189–195`), `getRestoreInputs`
|
||||
(`:196–207`), `probeQueueStore` (`:158–170`), `getClaudeActivityHookEvents`
|
||||
(`:171–174`), and `probeDaemonHealth` (self-evident: "We're inside the
|
||||
daemon — if this route is responding, daemon is healthy", `:208–211`). It
|
||||
then runs `service.check(...)` (`:231–232`).
|
||||
`resolved_files_json` / `startup_actions_json`, `:47–141`), `hasSnapshot`
|
||||
/ `getLatestSnapshot` from `snapshotRepo` (`:186–192`), `probeQueueStore`
|
||||
(`:155–167`), `getClaudeActivityHookEvents` (`:168–171`), and
|
||||
`probeDaemonHealth` (self-evident: "We're inside the daemon — if this route
|
||||
is responding, daemon is healthy", `:193–196`). It then runs
|
||||
`service.check(...)` (`:216–217`).
|
||||
|
||||
`RestoreCheckService.check()` (`restore-check-service.ts:259`) layers:
|
||||
`RestoreCheckService.check()` (`restore-check-service.ts:243`) layers:
|
||||
|
||||
1. **Host checks** — `checkDaemonReachable` (probe-throw → `verdict:
|
||||
unknown`, NOT `not_restorable`, `:270–280`), `checkStateDirWritable`
|
||||
(`:282`, impl `:498`), `checkHostInfraDeclaration` (`:283`, impl `:515`).
|
||||
2. **Rig enumeration** — `listRigs()` throw → `buildUnknown` (`:286–295`);
|
||||
`--rig` filter; unknown rig → red `rig.<name>.exists` (`:297–305`).
|
||||
3. **Per-rig checks** — `checkSnapshot` (`:311`, impl `:784`),
|
||||
`checkSpecPresent` (`:316`, impl `:1161`), and
|
||||
`rig.<name>.restore-preconditions` (`checkRestorePreconditions`, `:338`,
|
||||
impl `:422`). The last runs the same `validatePreRestore` that restore
|
||||
runs (`:446`) on the inputs from `getRestoreInputs`: red on a blocker,
|
||||
yellow on a warning, green otherwise. Without a usable snapshot it is
|
||||
yellow when current-state rehydrate is eligible and red when it isn't;
|
||||
when the inputs can't be read it is yellow and the rig's rollup becomes
|
||||
`unknown` (see Verdict). The rig-status route sets
|
||||
`recoveryOnly` (`routes/rigs.ts:272`), which skips this check when every
|
||||
seat is ready (`restore-check-service.ts:337`).
|
||||
4. **Per-seat checks** — `checkSeatReadiness` (`:346`), `checkStartupContext`
|
||||
(`:360`, impl `:886`; `unknownChecks` → `buildUnknown`, `:361–366`),
|
||||
`checkTranscript` (`:382`), `checkResumePath` (`:386`), and unless opted
|
||||
unknown`, NOT `not_restorable`, `:256–263`), `checkStateDirWritable`
|
||||
(`:265`), `checkHostInfraDeclaration` (`:266`, impl `:432`).
|
||||
2. **Rig enumeration** — `listRigs()` throw → `buildUnknown` (`:271–278`);
|
||||
`--rig` filter; unknown rig → red `rig.<name>.exists` (`:280–287`).
|
||||
3. **Per-rig checks** — `checkSnapshot` (`:294`, impl `:701`),
|
||||
`checkSpecPresent` (`:299`, impl `:1064`).
|
||||
4. **Per-seat checks** — `checkSeatReadiness` (`:315`), `checkStartupContext`
|
||||
(`:329`, impl `:789`; `unknownChecks` → `buildUnknown`, `:330–335`),
|
||||
`checkTranscript` (`:351`), `checkResumePath` (`:355`), and unless opted
|
||||
out: the daemon SQLite `queue_items` availability probe `checkQueueStore`
|
||||
(`:390–394`, gated by `--no-queue`; impl `:1007`) and `checkHooks`
|
||||
(`:395–399`, gated by `--no-hooks`; impl `:1030`). Queue continuity is
|
||||
represented by the shared daemon store; an empty queue is valid
|
||||
(`routes/restore-check.ts:160–163`). Claude hook readiness follows the
|
||||
(`:360`, gated by `--no-queue`; impl `:910`) and `checkHooks` (`:365`,
|
||||
gated by `--no-hooks`; impl `:933`). Queue continuity is represented by
|
||||
the shared daemon store; an empty queue is valid
|
||||
(`routes/restore-check.ts:159–160`). Claude hook readiness follows the
|
||||
persisted `claude_activity_hooks` runtime-resource selection
|
||||
(`restore-check-service.ts:1053–1060`) and the adapter's projection: the
|
||||
hook settings in the seat CWD and the activity relay under the OpenRig
|
||||
home's `state/claude-activity-hooks/` (`restore-check-service.ts:1071–1072`). A seat
|
||||
(`restore-check-service.ts:957`) and the adapter's activity-relay
|
||||
projection in the seat CWD (`restore-check-service.ts:974–975`). A seat
|
||||
that deliberately omits that resource is not applicable. In compact mode
|
||||
without `ready=1`, a seat whose readiness check is green gets only the
|
||||
startup-context check (`restore-check-service.ts:358`, `:368–380`); that
|
||||
check still counts toward the verdict.
|
||||
5. **Verdict** — `buildResult` (`:1205`) aggregates: any red →
|
||||
`not_restorable`; else any rig rollup with status `unknown` → `unknown`
|
||||
(`:1223–1224`); else any yellow → `restorable_with_caveats`; else
|
||||
`restorable` (`:1220–1229`). A rig rollup is `unknown` when its restore
|
||||
inputs could not be read (`:1549–1551`). A probe that can't be inspected
|
||||
at all also gives `unknown` (`buildUnknown`, `:1238`). Plus a
|
||||
`RecoveryPlan` (`buildRecovery`, `:1342`) and a `RepairStep[]` packet
|
||||
(`buildRepairPacket`, `:1581`; `null` when fully restorable, `:1582`).
|
||||
startup-context check (`restore-check-service.ts:327`, `:347–349`); that
|
||||
check still counts toward the verdict (`:337–340`).
|
||||
5. **Verdict** — `buildResult` (`:1106`) aggregates: any red →
|
||||
`not_restorable`; any yellow → `restorable_with_caveats`; else
|
||||
`restorable` (`:1121–1128`); probe-uninspectable → `unknown`
|
||||
(`buildUnknown`, `:1137`). Plus a `RecoveryPlan` (`buildRecovery`,
|
||||
`:1241`) and a `RepairStep[]` packet (`buildRepairPacket`, `:1475`;
|
||||
`null` when fully restorable, `:1476`).
|
||||
|
||||
The result shape is `RestoreCheckResult` (`restore-check-service.ts:148–160`):
|
||||
The result shape is `RestoreCheckResult` (`restore-check-service.ts:144–156`):
|
||||
`verdict`, `readiness`, `continuity`, `rigs[]`, `hostInfra`, `recovery`,
|
||||
`counts {red,yellow,green}`, `classCounts`, `checks[]`, `repairPacket`. With
|
||||
`compact=1` the route returns a reduced body (`routes/restore-check.ts:234–261`).
|
||||
`compact=1` the route returns a reduced body (`routes/restore-check.ts:219–245`).
|
||||
|
||||
**Honest-error design:** a daemon-probe *exception* produces
|
||||
`verdict: unknown` (uninspectable state), distinct from a daemon
|
||||
definitely-down state which is `red` / `not_restorable`
|
||||
(`restore-check-service.ts:270–280`, `checkDaemonReachable` `:476–496`). The
|
||||
(`restore-check-service.ts:253–263`, `checkDaemonReachable` `:393–413`). The
|
||||
route's catch-all returns the same `unknown`-shaped body with HTTP 500 + a
|
||||
`probe.error` red check (`routes/restore-check.ts:264–312`).
|
||||
`probe.error` red check (`routes/restore-check.ts:249–297`).
|
||||
`CheckEntry.remediationSafe` defaults to `false` (conservative —
|
||||
unclassified remediations are NOT auto-execution-safe,
|
||||
`restore-check-service.ts:23–28`, applied at `:1596`).
|
||||
`restore-check-service.ts:19–24`, applied at `:1490`).
|
||||
|
||||
CLI surface (`../cli-reference.md` `### restore-check`; options in
|
||||
CLI surface (`../cli-reference.md` `### rig restore-check`; options in
|
||||
`packages/cli/src/commands/restore-check.ts:222–227`):
|
||||
`rig restore-check [--rig <name>] [--full] [--ready] [--no-queue] [--no-hooks] [--json]`.
|
||||
Output is compact unless `--full` (`:313`). Exit codes: `0` restorable (or
|
||||
with caveats), `1` not restorable (red), `2` unknown / probe error
|
||||
(`:214–217`). When the daemon is down, the CLI builds a local
|
||||
`not_restorable` result and exits 1 (`:269`).
|
||||
(`:214–217`).
|
||||
|
||||
### 5.2 `rig restore-packet` — cross-runtime restore packet
|
||||
|
||||
CLI-side, no restore-packet daemon route. `commands/restore-packet.ts`
|
||||
(**541** lines, `wc -l < packages/cli/src/commands/restore-packet.ts`)
|
||||
(**539** lines, `wc -l < packages/cli/src/commands/restore-packet.ts`)
|
||||
implements **3** subcommands
|
||||
(`grep -c 'cmd.command(' packages/cli/src/commands/restore-packet.ts`;
|
||||
`../cli-reference.md` `### restore-packet`): `write [options]` (`:218`;
|
||||
`../cli-reference.md` `### rig restore-packet`): `write [options]` (`:216`;
|
||||
generate a packet directory from a source session or JSONL file, with
|
||||
`omitted-records` accounting; `--source-session` reads the transcript from the
|
||||
daemon's `/api/transcripts/<session>/full`, `:156`), `read <packet-dir> [--json]`
|
||||
(`:373`; render contents; non-mutating), `validate <packet-dir> [--json]`
|
||||
(`:452`; validate against the v0 schema; non-mutating). Packet shape is the
|
||||
(`:371`; render contents; non-mutating), `validate <packet-dir> [--json]`
|
||||
(`:450`; validate against the v0 schema; non-mutating). Packet shape is the
|
||||
cross-runtime v0 standard — Claude Code and Codex transcripts both supported
|
||||
via runtime parsers + redaction (`packages/cli/src/restore-packet/`).
|
||||
|
||||
### Shared history inspection
|
||||
|
||||
`GET /api/startup/:rigId/nodes/:nodeId/history` lists captured histories for one durable node in the current, policy-ranked restore snapshot. `POST` to the same path plus `/validate` with exactly `{ "snapshotId": "…", "historySessionId": "…" }` rechecks one listed choice. Both routes use startup's terminal bearer authentication. The CLI exposes the same server decisions with `rig seat history --rig <rig-id> --node-id <node-id> --json`; pass both `--snapshot-id` and `--history-session-id` to validate. These calls perform no snapshot capture, token refresh, launch, or database write.
|
||||
|
||||
The list includes captured Claude and Codex rows that the current restore policy and native resume adapter can structurally attempt. Codex requires an explicit `codex_id` and token; implicit `codex_last` cannot name a particular history. Claude accepts `claude_id` and `claude_name` with tokens. The server checks exact rig and node membership, the snapshot's intended roster and runtime, and the node's current occupant compatibility. A change to a sibling node does not retarget or invalidate this node's list. A changed or pruned snapshot, removed history row, same-name replacement node, ambiguous current occupant, or incompatible source is refused; validation never substitutes another history.
|
||||
|
||||
`tokenState` (`present`, `stale`, or `unverified` for listed rows) describes the saved verification record and its age. Eligibility means a future launch may **attempt** native resume. A stored row can share a native token with another row, and neither listing nor validation proves that a native conversation still exists.
|
||||
|
||||
### Selected history startup
|
||||
|
||||
`GET /api/startup/:rigId/nodes/:nodeId?snapshotId=<listed-id>&historySessionId=<listed-id>` returns a read-only review for one listed choice: the selected row's forecast, current terminal observation, consumed launch setting sources (including a member permission envelope or Claude rules), and an opaque revision. The permission view uses restore's pure policy resolution: a readable custom policy's current launch posture can supersede its persisted cache, and a changed resolved decision requires re-review. It refuses a captured row whose native type/token, provenance, restore policy, or harness no longer agrees with the live registry row. The response contains no native token. `POST /api/startup/:rigId/nodes/:nodeId` accepts exactly `{ "action": "resume", "snapshotId": "…", "historySessionId": "…", "revision": "…" }`. Both routes require startup's terminal bearer token. The selected route accepts no fresh, continue, arbitrary token, or alternate target. Review does not capture a snapshot or prepare a provider. `rig seat history` also uses a strictly read-only daemon status check, so inspection does not remove stale daemon state.
|
||||
|
||||
Apply revalidates the same current compatible source, durable node and saved launch settings after prerequisite and presence checks. The existing narrow restore engine carries that exact historical row through legacy and pod-aware native resume, with a second identity check at native dispatch after preparation. Before the new registry row is committed, selected startup also checks that no other attachment or running occupant claimed the node during terminal creation or pane observation; a collision leaves that claimant intact and reports the terminal outcome for inspection. An occupied or uncertain terminal blocks the attempt. No alternate history or fresh conversation is selected. The response projects exact typed references and outcome fields; only diagnostic text is redacted, so even a short native name cannot corrupt an ID. It names the selected source row and the newly registered result row when one exists; only the engine's joined native continuity proof produces success. If a change occurs after shell creation, the result reports a partial or uncertain attempt for inspection. The existing engine handles native prerequisites, compensation and proof. This surface adds no separate per-agent prelaunch probe; native checks remain at execution. Physical tmux cleanup still addresses sessions by name, so it cannot prove ownership against an external same-name replacement outside the selected registry guard.
|
||||
|
||||
## See also
|
||||
|
||||
- `agent-spec-and-startup.md` — StartupOrchestrator persists the replay
|
||||
@@ -429,8 +284,6 @@ Apply revalidates the same current compatible source, durable node and saved lau
|
||||
- `transport-and-transcripts.md` — transcript boundary markers written on
|
||||
restore.
|
||||
- Source roots: `packages/daemon/src/domain/{restore-orchestrator,
|
||||
restore-preconditions,restore-topology,restore-attempt-receipt,
|
||||
rehydrate-eligibility,snapshot-capture,snapshot-repository,checkpoint-store,
|
||||
active-occupant,restore-check-service}.ts`,
|
||||
`packages/daemon/src/routes/{restore-check,up,snapshots}.ts`,
|
||||
`packages/cli/src/commands/{restore-packet,restore-check,restore}.ts`.
|
||||
snapshot-capture,snapshot-repository,checkpoint-store,active-occupant,
|
||||
restore-check-service}.ts`, `packages/daemon/src/routes/{restore-check,up}.ts`,
|
||||
`packages/cli/src/commands/{restore-packet,restore-check}.ts`.
|
||||
@@ -7,13 +7,13 @@ domains: [engineering-advisor, operating-advisor]
|
||||
applies-when: |
|
||||
Tracing slice, mission, rig, or fleet review data back to scope documents,
|
||||
proof artifacts, judgments, queue state, or frozen exports.
|
||||
last-verified-against-source: e8f0ab340db773392ec8be75b072d1c0f3068a50
|
||||
last-updated: 2026-10-08
|
||||
last-verified-against-source: 254122872cf477511514979a4300b695d77cd1f7
|
||||
last-updated: 2026-10-03
|
||||
---
|
||||
|
||||
# Living Notes — Composed Review and Frozen Exports
|
||||
|
||||
Source snapshot: `e8f0ab340db773392ec8be75b072d1c0f3068a50`. This describes the source at that commit;
|
||||
Source snapshot: `254122872cf477511514979a4300b695d77cd1f7`. This describes the source at that commit;
|
||||
it does not establish the version or behavior of a running daemon.
|
||||
|
||||
Living Notes builds review payloads from existing documents and recorded
|
||||
@@ -47,13 +47,6 @@ possible evidence was discovered follows from that read.
|
||||
and composes a mission board, completion ledger, attention union, agents,
|
||||
and brief spine. `composeRig` reads queue/activity state and reports current
|
||||
holders, recent holders, overdue work, settled work, and workflow exceptions.
|
||||
"Recent" is the current UTC day; overdue is in-progress slice-tagged work past
|
||||
`closure_required_at`; settled is today's `handed_off_to` transitions; and
|
||||
attention is any active item that is `human-gate`, addressed to a `human…`
|
||||
session, or blocked on one (`gather.ts`). Of the three review reads, the TUI
|
||||
calls only `/fleet`, from its broad hydration (`packages/tui/src/hydrate.ts`);
|
||||
its client also defines methods for `/agents` and `/rig`, which nothing in the
|
||||
TUI calls.
|
||||
|
||||
## Slice source selection and phase
|
||||
|
||||
@@ -108,15 +101,11 @@ stamps are also not a substitute for the delivered-item join.
|
||||
`ReviewGatherer.gatherApproval` reads `approved-spec-by`/`approved-spec-at`
|
||||
and `approved-by`/`approved-at`, alongside matching `mission_control_actions`
|
||||
approval audit records. The resulting locks preserve who/when/audit facts.
|
||||
A frontmatter stamp with no matching `approve` audit row still locks the
|
||||
phase, but carries `auditVerified: false`, and the frozen export shows it as
|
||||
an UNVERIFIED stamp. The approval writer is the separate
|
||||
The approval writer is the separate
|
||||
[`scope-approve` route](../../../packages/daemon/src/routes/scope-approve.ts).
|
||||
|
||||
`composeNeedsYou` combines recorded queue attention with derived exceptions;
|
||||
`deriveWorkflowExceptions` adds workflow-specific observations. When
|
||||
readiness is not configured, a slice whose `PROOF.md` claims PASS without a
|
||||
recorded green verdict also gets a `confirm-faithful` needs-you item. Mission
|
||||
`deriveWorkflowExceptions` adds workflow-specific observations. Mission
|
||||
composition deduplicates attention identities across slice and mission views.
|
||||
Media references outside the slice's relative-path contract produce defect
|
||||
entries instead of disappearing silently.
|
||||
@@ -124,18 +113,14 @@ entries instead of disappearing silently.
|
||||
Git facts are optional. [`startup.ts`](../../../packages/daemon/src/startup.ts)
|
||||
passes `OPENRIG_REVIEW_GIT_REPO` to the gatherer. The gatherer reads that
|
||||
repository's `HEAD`, searches merge messages keyed by scope ID, and computes
|
||||
ancestry/behind facts when possible. Each git read has a 4-second timeout; the
|
||||
merge search looks for `Merge <id>` in `HEAD` history and needs the scope's
|
||||
frontmatter `id`; the behind-tip count is computed only for unmerged slices
|
||||
with a candidate SHA. Unavailable facts remain unknown; this is not a fresh
|
||||
remote GitHub merge-status query.
|
||||
ancestry/behind facts when possible. Unavailable facts remain unknown; this
|
||||
is not a fresh remote GitHub merge-status query.
|
||||
|
||||
`composeMissionReview` derives `cutComplete` from a nonempty ledger in which
|
||||
every slice is green, has a merge SHA, and has no needs-human items. Configured
|
||||
slice readiness supplies the green predicate; otherwise recorded verdicts
|
||||
do. With configured readiness, a slice's board cell also shows the proof
|
||||
readiness state and revision. That computed field is not itself a
|
||||
publication or higher-level outcome decision.
|
||||
do. That computed field is not itself a publication or higher-level outcome
|
||||
decision.
|
||||
|
||||
## HTTP routes
|
||||
|
||||
@@ -157,21 +142,11 @@ of the agents-scope parameter.
|
||||
|
||||
## Freeze and media
|
||||
|
||||
Nothing invokes the freeze automatically: `POST /api/scope/approve` writes
|
||||
the stamp and audit row and always returns `freezeFired: false`
|
||||
(`domain/scope/scope-approve.ts:326`), and the route comment that says the
|
||||
approve flow invokes the freeze describes wiring that does not exist. A
|
||||
frozen export exists only after something calls `POST /api/review/freeze`.
|
||||
|
||||
[`freezeSliceExport`](../../../packages/daemon/src/domain/review/freeze.ts)
|
||||
requires a delivery lock and an allowlisted slice directory. It writes
|
||||
`REVIEW-<scope-id-or-name>-<approval-date>.html` through
|
||||
`FileWriteService.createAtomic`. An existing target is treated as already
|
||||
frozen; it is not rewritten. A failed export does not undo approval. The
|
||||
route needs the file write service (a non-empty `files.allowlist`; otherwise
|
||||
503) and returns 409 `stamp_missing` without a delivery stamp, 403
|
||||
`allowlist_missing` outside every allowlist root, and 500 otherwise; success
|
||||
returns `{ ok, path, alreadyFrozen, briefWrite }` (`routes/review.ts`).
|
||||
frozen; it is not rewritten. A failed export does not undo approval.
|
||||
|
||||
The export embeds contained images as data URIs and links videos with an
|
||||
optional poster. `containedMediaPath` checks both resolved paths and existing
|
||||
@@ -193,11 +168,6 @@ payloads. Its default fan-out concurrency is **4**, with a shared
|
||||
**4-second** read budget. Synchronous local work cannot be preempted by that
|
||||
timer; elapsed local work reduces the remaining remote budget.
|
||||
|
||||
Each remote host is read through its own `GET /api/review/rig`: SSH-only
|
||||
registry entries report `unsupported-transport`, auth refusals report
|
||||
`auth-failed`, and timeouts, malformed payloads and other errors report
|
||||
`unreachable`.
|
||||
|
||||
`unionFleet` keys attention by host plus item identity and retains host
|
||||
status. Unavailable hosts have absent counts, not synthetic zeros. A missing
|
||||
registry produces a local-only result; an unreadable existing registry is
|
||||
|
||||
@@ -6,13 +6,13 @@ topics: [coordination, observability]
|
||||
domains: [engineering-advisor, operating-advisor, orchestrator, human-operator]
|
||||
applies-when: |
|
||||
Need to know how the daemon-backed Mission Control surface works — the
|
||||
seven views, the nine write verbs, the action audit table, the
|
||||
seven views, the eight write verbs, the action audit table, the
|
||||
bearer-token middleware, or how queue observability maps to the
|
||||
coordination primitive's sources.
|
||||
siblings: [coordination-primitive.md, workflow-runtime.md, ../ui/project-and-for-you.md]
|
||||
prerequisite-reads: [../README.md, coordination-primitive.md]
|
||||
last-verified-against-source: e8f0ab340db773392ec8be75b072d1c0f3068a50
|
||||
last-updated: 2026-10-08
|
||||
last-verified-against-source: 254122872cf477511514979a4300b695d77cd1f7
|
||||
last-updated: 2026-10-03
|
||||
---
|
||||
|
||||
# Mission Control — Queue Observability + Verb Contract
|
||||
@@ -20,12 +20,12 @@ last-updated: 2026-10-08
|
||||
Mission Control is the daemon's queue-observability and operator-action
|
||||
surface, mounted at `/api/mission-control` over the coordination primitive's
|
||||
`queue_items` and `stream_items` (see `coordination-primitive.md`). It has
|
||||
seven views, nine verbs, a recent-ships cap of 10
|
||||
seven views, eight verbs, a recent-ships cap of 10
|
||||
(`mission-control-read-layer.ts:107`), and a daemon-backed action audit
|
||||
table. In the web UI the old `/mission-control` page now redirects to
|
||||
`/for-you`, and the For You feed carries the verb actions (§6).
|
||||
|
||||
> Verified against source at main `e8f0ab340db773392ec8be75b072d1c0f3068a50`. A bare file name such as
|
||||
> Verified against source at main `254122872cf477511514979a4300b695d77cd1f7`. A bare file name such as
|
||||
> `mission-control-read-layer.ts:31` is in
|
||||
> `packages/daemon/src/domain/mission-control/`; `domain/…`, `routes/…`,
|
||||
> `middleware/…`, `db/…`, `index.ts`, `server.ts` and `startup.ts` are under
|
||||
@@ -55,18 +55,13 @@ Required row fields: **9** — `sed -n '/^export interface CompactStatusRow {/,/
|
||||
each view to its source:
|
||||
|
||||
- `my-queue` / `human-gate` / `active-work` / `recent-ships` query
|
||||
`queue_items` via `QueueRepository`. `my-queue` uses the `operatorSession`
|
||||
query parameter when given, else `workspace.operator_seat_name` (default
|
||||
empty), else the only registered human; when none is found, or more than
|
||||
one, it returns no rows and a `degradedFields` note rather than widening the
|
||||
view (`mission-control-read-layer.ts:137–141`, `:166–168`;
|
||||
`routes/mission-control.ts:521`).
|
||||
`queue_items` via `QueueRepository`.
|
||||
- `fleet` calls `MissionControlFleetCliCapability.rollupFleet()`
|
||||
(`mission-control-read-layer.ts:197`;
|
||||
`mission-control-fleet-cli-capability.ts:109`), which walks the rig
|
||||
registry (`:110`), summarises each rig's `queue_items` (`:135`), and runs a
|
||||
per-rig CLI capability probe (`makeLocalCliCapabilityProbe`, `:77`, wired
|
||||
at `startup.ts:1597`).
|
||||
at `startup.ts:1547`).
|
||||
- `recently-active` delegates to the view projector's built-in
|
||||
`ViewProjector.show("recently-active")` (`mission-control-read-layer.ts:246`).
|
||||
- `recent-observations` reads the latest 50 `stream_items` via `StreamStore`
|
||||
@@ -81,18 +76,16 @@ There is no filesystem fallback. When no `StreamStore` is wired,
|
||||
|
||||
> Scope note: this module describes the daemon's verb vocabulary. It does
|
||||
> NOT enumerate which verbs the For You cards offer; that surface is
|
||||
> described in `../ui/project-and-for-you.md`. The terminal UI opened by bare
|
||||
> `rig` or `rig tui` is called the "mission-control TUI" in source
|
||||
> (`packages/tui/README.md:1`), but it does not call these routes.
|
||||
> described in `../ui/project-and-for-you.md`.
|
||||
|
||||
## 2. The nine verbs (the write contract)
|
||||
## 2. The eight verbs (the write contract)
|
||||
|
||||
`MISSION_CONTROL_VERBS` (`mission-control-action-log.ts:14–29`) is the verb
|
||||
`MISSION_CONTROL_VERBS` (`mission-control-action-log.ts:14–26`) is the verb
|
||||
list. The verbs execute through `MissionControlWriteContract.act`
|
||||
(`mission-control-write-contract.ts:131`); the closure mapping is
|
||||
`verbToClosure` (`:509`).
|
||||
|
||||
Verbs: **9** — `sed -n '/^export const MISSION_CONTROL_VERBS = \[/,/\] as const;/p' packages/daemon/src/domain/mission-control/mission-control-action-log.ts | grep -c '^ "'`
|
||||
Verbs: **8** — `sed -n '/^export const MISSION_CONTROL_VERBS = \[/,/\] as const;/p' packages/daemon/src/domain/mission-control/mission-control-action-log.ts | grep -c '^ "'`
|
||||
|
||||
| Verb | Effect |
|
||||
|---|---|
|
||||
@@ -103,23 +96,10 @@ Verbs: **9** — `sed -n '/^export const MISSION_CONTROL_VERBS = \[/,/\] as cons
|
||||
| `hold` | `state="blocked"`, `closure_reason="blocked_on"` |
|
||||
| `drop` | `state="done"`, `closure_reason="canceled"` |
|
||||
| `handoff` | same closure and new destination item as `route`; the 4-step shape (see below) |
|
||||
| `resolve` | for a `blocked` item parked on a human seat or a well-formed typed gate (`external:`, `fold:`, `auth:`): moves it to `in-progress` with required decision/satisfaction evidence in the transition note; typed waits are recorded as blocker resolutions, not human decisions. Qitem dependencies, malformed gates and non-blocked items are refused; no closure and no new item (`:369`, `:386`, `:410–411`). After commit it sends a best-effort nudge with the decision text to the item's owner unless `notify: false` (`:450–467`); the CLI wrapper is `rig queue resolve <qitemId> --decision <text>` (`packages/cli/src/commands/queue.ts:828`) |
|
||||
| `answer` | only for a `pending` ask addressed to the acting person: a choice (`questionId` + `optionId`) through `QueueRepository.recordHumanAnswer`, or their words (`decision`) through `resolveDirectHumanReply`, each with its existing meaning (a partial choice set stays pending; words fill the first unanswered question). Once answered, one reply row goes to the asking seat (`human-answer` tag, `replyTo` the ask, an id derived from the ask) and then the ask closes once with `human-decision-resolved`, the order Slack's answer continuation uses. With neither a choice nor words, a complete question set whose return didn't finish is sent again with exactly its recorded answers. A closed ask answers 409 `qitem_already_terminal` and records nothing; a refused answer is 400 `answer_not_recorded`; 409 `answer_not_closed` means the ask stayed open: its return failed, it changed before its close, or a retry came in other words than the reply already returned (that retry isn't sent). The TUI's Feed sends it |
|
||||
| `resolve` | only for a `blocked` item parked on a human seat: moves it to `in-progress` with the required decision text as the transition note; no closure and no new item (`:369`, `:386`, `:410–411`) |
|
||||
|
||||
`annotate` requires `annotation`, `hold` and `drop` require `reason`, `route`
|
||||
and `handoff` require `destinationSession`, and `resolve` requires a non-empty
|
||||
`decision`. A missing `annotation`, `destinationSession` or `decision` returns
|
||||
400. A `drop` without `reason` passes the queue closure check and is refused by
|
||||
the audit record instead; the wrapped `reason_required` error has no status
|
||||
mapping, so it returns 500 (`mission-control-action-log.ts:128–133`,
|
||||
`mission-control-write-contract.ts:245–248`). Items already `done` or
|
||||
`handed-off` are refused with 409 `qitem_already_terminal`, except under
|
||||
`resolve`, which answers 409 `qitem_not_leg1_parked` for any item that is not
|
||||
blocked on a human seat or a well-formed typed gate (`external:`, `fold:`, `auth:`). An unknown item returns 404 `qitem_not_found`
|
||||
(`routes/mission-control.ts:240–251`, `:330–341`).
|
||||
|
||||
Each verb except `answer` is one atomic daemon transaction (`answer`'s queue writes are the repository's own, in the order above, then its audit row and event): the queue mutation via
|
||||
`QueueRepository.updateWithinTransaction()` (`domain/queue-repository.ts:2371`,
|
||||
Each verb is one atomic daemon transaction: the queue mutation via
|
||||
`QueueRepository.updateWithinTransaction()` (`domain/queue-repository.ts:2337`,
|
||||
which keeps the hot-potato closure validation — see
|
||||
`coordination-primitive.md` §3), an audit row in `mission_control_actions`
|
||||
(`mission-control-write-contract.ts:207`), and a persisted
|
||||
@@ -135,7 +115,7 @@ created in the same transaction (`createWithinTransaction`, `:173`), along
|
||||
with the successor's wake intent (`stageWakeIntent`, `:195`, checked by
|
||||
`assertTerminalClosureHasIntent`, `:242`). The wake itself runs after commit
|
||||
(`deliverWakeForSuccessor`, `:264`). It is on unless the caller passes
|
||||
`notify: false` (`domain/queue-repository.ts:1182`), and a notify failure
|
||||
`notify: false` (`domain/queue-repository.ts:1174`), and a notify failure
|
||||
does NOT roll back durable mutations (`mission-control-write-contract.ts:272–275`).
|
||||
A failed destination create rolls back the source closure, the audit row and
|
||||
the new item together
|
||||
@@ -154,18 +134,8 @@ NULL ISO timestamp, `037_mission_control_actions.ts:63`);
|
||||
indexes `(acted_at DESC, action_verb)`, `(qitem_id, acted_at DESC)`,
|
||||
`(actor_session, acted_at DESC)` (`037_mission_control_actions.ts:72–77`).
|
||||
One later migration adds a nullable `identity_provenance` column
|
||||
(`db/migrations/065_identity_provenance.ts:18`). The acting session comes
|
||||
from the `X-OpenRig-Session` header when present (the CLI sends it); a
|
||||
headerless browser request falls back to the body `actorSession`. The row
|
||||
records how the actor was established: `transport:v1`, `relay:v1` for a
|
||||
forwarded request, `claimed:v1` for a headerless body actor, or
|
||||
`origin-unknown:v1` (`routes/mission-control.ts:347–351`;
|
||||
`routes/require-sender-identity.ts:120`).
|
||||
|
||||
Scope approvals (`POST /api/scope/approve`) also append `approve` rows through
|
||||
the same `MissionControlActionLog`, with `qitem_id` null and the scope target
|
||||
in `audit_notes_json` (`domain/scope/scope-approve.ts:292`). The audit browse
|
||||
(§4) reads only this table.
|
||||
(`db/migrations/065_identity_provenance.ts:18`). The audit browse (§4) reads
|
||||
only this table.
|
||||
|
||||
## 4. Bearer middleware, notifications, audit browse
|
||||
|
||||
@@ -173,50 +143,36 @@ in `audit_notes_json` (`domain/scope/scope-approve.ts:292`). The audit browse
|
||||
Constant-time comparison via Node `crypto.timingSafeEqual`
|
||||
(`constantTimeEqual`, `:36`, `:50`). `authBearerTokenMiddleware` (`:93`)
|
||||
passes every request through when no token is configured (`:98`). The
|
||||
token comes from `OPENRIG_AUTH_BEARER_TOKEN` (`index.ts:288`). The daemon
|
||||
token comes from `OPENRIG_AUTH_BEARER_TOKEN` (`index.ts:280`). The daemon
|
||||
refuses to start when the bind host is set explicitly, is neither loopback
|
||||
nor Tailscale (a hostname is resolved first), and no bearer token is set
|
||||
(`assertBindAuthInvariant`, `auth-bearer-token.ts:240`, called at
|
||||
`index.ts:296`). Bearer enforced on the write routes:
|
||||
`index.ts:288`). Bearer enforced on the write routes:
|
||||
`app.post("/action", requireAuth)` (`routes/mission-control.ts:307`) and
|
||||
`app.post("/notifications/test", requireAuth)` (`:308`). Reads are not
|
||||
bearer-gated. It is one static token; no OAuth/SSO/per-user model
|
||||
(`auth-bearer-token.ts:11–14`). Every Mission Control request, read or
|
||||
write, first passes the daemon's `/api/*` browser boundary
|
||||
(`server.ts:647`; `middleware/browser-boundary.ts`): only known target host
|
||||
names, and, when an `Origin` header is present, only the daemon's own UI
|
||||
origin or an `OPENRIG_ALLOWED_ORIGINS` entry. A valid bearer token waives
|
||||
only the host-name check.
|
||||
gated. It is one static token; no OAuth/SSO/per-user model
|
||||
(`auth-bearer-token.ts:11–14`).
|
||||
- **Notification dispatcher** — two adapters
|
||||
(`notification-adapter-ntfy.ts`, `notification-adapter-webhook.ts`) plus
|
||||
`notification-dispatcher.ts`. `OPENRIG_NOTIFICATIONS_MECHANISM` selects
|
||||
`ntfy`, `webhook` or `none`, and the default is `none`
|
||||
(`startup.ts:1642`). A dispatcher starts only when
|
||||
`OPENRIG_NOTIFICATIONS_TARGET` is also set (`:1643`, `:1650`) and the
|
||||
target URL passes validation (`:1661`); an unrecognized mechanism with a
|
||||
target set throws during daemon startup (`:1656–1659`). The ntfy adapter
|
||||
posts to a topic URL that the ntfy phone app subscribes to
|
||||
(`notification-adapter-ntfy.ts:1–6`). Notifications fire when a
|
||||
`human-gate` queue item is created, and also on each completed verb when
|
||||
`OPENRIG_NOTIFICATIONS_INCLUDE_VERB_COMPLETION=1` (`startup.ts:1648–1649`);
|
||||
each item, trigger and mechanism is sent at most once per daemon run
|
||||
(`notification-dispatcher.ts:119–134`, `:156–158`). `POST
|
||||
/notifications/test` returns 503 `notifications_unconfigured` when no
|
||||
dispatcher is running (`routes/mission-control.ts:481–492`).
|
||||
(`startup.ts:1592`). A dispatcher starts only when
|
||||
`OPENRIG_NOTIFICATIONS_TARGET` is also set (`:1593`, `:1600`) and the
|
||||
target URL passes validation (`:1611`). The ntfy adapter posts to a topic
|
||||
URL that the ntfy phone app subscribes to
|
||||
(`notification-adapter-ntfy.ts:1–6`).
|
||||
|
||||
Adapters: **2** — `git grep -l 'implements NotificationAdapter' -- packages/daemon/src | wc -l`
|
||||
- **Read-only audit-history browse** — `MissionControlAuditBrowse.query`
|
||||
(`audit-browse.ts:78`) over `mission_control_actions`, exposed at
|
||||
`GET /api/mission-control/audit` (`routes/mission-control.ts:441`) with
|
||||
filters (including `scope_tier`, `scope_id`, `scope_path` and
|
||||
`approval_scope` for scope-approval rows) and `(limit, before_id)`
|
||||
pagination cursored on SQLite `rowid` (`audit-browse.ts:134`); the page size
|
||||
defaults to 50 and is capped at 200 (`audit-browse.ts:61–62`).
|
||||
filters and `(limit, before_id)` pagination cursored on SQLite `rowid`
|
||||
(`audit-browse.ts:134`).
|
||||
|
||||
## 5. Mission Control events
|
||||
|
||||
The `RigEvent` union starts at `domain/types.ts:108`; its four
|
||||
`mission_control.*` members are at `domain/types.ts:308–313`.
|
||||
The `RigEvent` union starts at `domain/types.ts:106`; its four
|
||||
`mission_control.*` members are at `domain/types.ts:306–311`.
|
||||
|
||||
`RigEvent` members: **98** — `sed -n '/^export type RigEvent =/,/^export type PersistedEvent/p' packages/daemon/src/domain/types.ts | grep -c 'type: "'`
|
||||
|
||||
@@ -235,7 +191,7 @@ The `RigEvent` union starts at `domain/types.ts:108`; its four
|
||||
## 6. Route surface
|
||||
|
||||
`missionControlRoutes({ bearerToken })` is mounted at `/api/mission-control`
|
||||
(`server.ts:790–793`). Routes (`routes/mission-control.ts`): `GET /views`
|
||||
(`server.ts:791–794`). Routes (`routes/mission-control.ts`): `GET /views`
|
||||
(`:259`), `GET /cli-capabilities` (`:264`), `GET /destinations` (`:276`),
|
||||
`GET /sse` and its alias `GET /watch` (`:303–304`; they forward
|
||||
`action_executed` and `cli_drift_detected` events,
|
||||
@@ -243,12 +199,6 @@ The `RigEvent` union starts at `domain/types.ts:108`; its four
|
||||
`POST /notifications/test` (`:481`, auth-gated), and `GET /views/:view-name`
|
||||
(`:509`).
|
||||
|
||||
`POST /action` accepts an optional `hostId`: for a non-local host it forwards
|
||||
the same verb to that host's daemon (http-transport host entries only; 10 s
|
||||
timeout). The origin host writes the audit row and nothing is written
|
||||
locally; a forwarding failure returns 502 `remote_action_failed` with a
|
||||
`failureClass` (`routes/mission-control.ts:13`, `:352–414`).
|
||||
|
||||
In the web UI (`packages/ui/src/routes.tsx`), `/mission-control` is a
|
||||
redirect to `/for-you` (`:495–500`). `/for-you` renders the For You `Feed`
|
||||
(`:130–134`), whose cards call `POST /action` through `VerbActions`
|
||||
|
||||
@@ -9,14 +9,14 @@ applies-when: |
|
||||
source routing, bootstrap plan/apply, or the retained package install engine.
|
||||
siblings: [agent-spec-and-startup.md, plugin-agent-image-context-pack.md]
|
||||
prerequisite-reads: [../README.md, agent-spec-and-startup.md]
|
||||
last-verified-against-source: e8f0ab340db773392ec8be75b072d1c0f3068a50
|
||||
last-updated: 2026-10-08
|
||||
last-verified-against-source: 254122872cf477511514979a4300b695d77cd1f7
|
||||
last-updated: 2026-10-03
|
||||
---
|
||||
|
||||
# Packaging, bootstrap and bundles
|
||||
|
||||
This module describes source at main commit
|
||||
`e8f0ab340db773392ec8be75b072d1c0f3068a50`. Source paths below are repository-relative.
|
||||
`254122872cf477511514979a4300b695d77cd1f7`. Source paths below are repository-relative.
|
||||
An npm CLI artifact and a `.rigbundle` have different builders and consumers; neither
|
||||
source verification nor archive integrity establishes that a daemon has adopted an artifact.
|
||||
|
||||
@@ -59,94 +59,30 @@ from live state.
|
||||
| Pod-aware rig spec | `packages/daemon/src/domain/pod-bundle-assembler.ts`: `PodBundleAssembler.assemble()` produces schema-version-2 metadata, vendors resolved agent trees, and rewrites agent references to local paths. |
|
||||
| Legacy rig spec | `packages/daemon/src/domain/bundle-assembler.ts`: `LegacyBundleAssembler` (imported as `BundleAssembler` by the route) collects the referenced legacy packages and produces the legacy manifest shape. |
|
||||
|
||||
The pod builder collects culture, docs and startup material, preserves file bytes, and skips
|
||||
vendoring the terminal sentinel as an agent. A copied file keeps its source mode with owner
|
||||
read and write added. Required document collection failures stop assembly; missing declared
|
||||
skills can instead produce warnings, which are also written into the provenance notes.
|
||||
The pod builder collects culture, docs and startup material, preserves file bytes and available
|
||||
mode metadata, and skips vendoring the terminal sentinel as an agent. Required document
|
||||
collection failures stop assembly; missing declared skills can instead produce warnings.
|
||||
Inspect the builder's collection helpers when changing these distinctions.
|
||||
|
||||
Both route branches can consume a source-root `bundle.yaml` to carry declared skills,
|
||||
plugins, workflow specs, context packs, agent images and preconditions into staging before
|
||||
computing integrity. Manifest types, validation and serialization are in
|
||||
plugins, workflow specs, context packs and agent images into staging before computing
|
||||
integrity. Manifest types, validation and serialization are in
|
||||
`packages/daemon/src/domain/bundle-types.ts`. Provenance and compatibility are metadata;
|
||||
provenance is not an author signature.
|
||||
|
||||
Preconditions are carried as data. Commands containing shell operators produce a warning,
|
||||
inspect reports the block, and the behaviour view lists it under needs. The install and
|
||||
bootstrap code do not reference preconditions.
|
||||
|
||||
Two more inputs are accepted only for a pod-aware spec; the legacy branch refuses them with
|
||||
a 400:
|
||||
|
||||
- `--context-pack <dir>` (`vendorContextPackDir()` in
|
||||
`packages/daemon/src/domain/bundle-carried-context-pack.ts`) carries a pack's
|
||||
`manifest.yaml` and its declared files to `context-packs/<manifest name>/`. The pack may
|
||||
sit outside the rig folder.
|
||||
- `--project-dir <dir>` (`vendorProjectDir()` in
|
||||
`packages/daemon/src/domain/bundle-carried-project.ts`) carries a folder with a
|
||||
`project.yaml` to `project/`.
|
||||
|
||||
Create also refuses content it must not ship. `computeIntegrity()` in
|
||||
`packages/daemon/src/domain/bundle-integrity.ts` throws on sensitive paths (`.env` files,
|
||||
`*.pem`, `*.key`, `*.p12`, `credentials.*`, `tokens.*`, `.git/` and `node_modules/`).
|
||||
`assertShippableSubstance()` in `packages/daemon/src/domain/agent-resolver.ts` runs on
|
||||
vendored content and on the final staging tree, and refuses text containing
|
||||
`substrate/shared-docs/` and files declaring `taxonomy: lore`.
|
||||
|
||||
### Configurations and package identity
|
||||
|
||||
A bundle folder may declare alternate team configurations in `configurations.yaml` beside
|
||||
`rig.yaml` (`packages/cli/src/lib/bundle-configuration.ts`). `rig bundle configurations
|
||||
<spec>` lists them. `rig bundle create --preset <name>` or `--seat <member=runtime>` resolves
|
||||
one and stages a copy of the rig folder in a temporary directory with the chosen runtimes and
|
||||
profiles, so the author's folder is never changed. With a GitHub folder link, `rig up`,
|
||||
`rig bundle create`, `inspect` and `install` take the same two options and stage a copy of the
|
||||
whole checkout (`importGitHubBundle()` in `packages/cli/src/lib/bundle-source.ts`).
|
||||
|
||||
`packages/daemon/src/domain/bundle-identity.ts` defines the two identity values:
|
||||
|
||||
- `configurationId()`: every member's `pod.member=runtime`, sorted and joined with `,`.
|
||||
Create computes it from the normalized spec and returns a 400 if the client sent a
|
||||
different one.
|
||||
- `packageDigest()`: SHA-256 over the sorted `integrity.files` entries (coverage label
|
||||
`openrig.package-digest/v1`). It covers every packaged file's bytes; it does not cover
|
||||
`bundle.yaml`, the junk files the integrity walk skips, or file modes.
|
||||
|
||||
Create and inspect responses carry the source, configuration ID, package digest, archive
|
||||
hash and assembler version.
|
||||
|
||||
### Archive checks
|
||||
|
||||
`packages/daemon/src/domain/bundle-archive.ts` owns `pack()` and `unpack()`;
|
||||
`packages/daemon/src/domain/bundle-integrity.ts` owns the per-file integrity map.
|
||||
|
||||
Packing requires a `.rigbundle` output path, sorts entries, uses portable tar metadata, a
|
||||
fixed tar timestamp and gzip level 9, and writes a sibling SHA-256 file. Unpacking checks that
|
||||
digest, rejects archive links and unsafe entry paths before extraction, requires
|
||||
`bundle.yaml` and its integrity section, and verifies the extracted file inventory. Hashes
|
||||
establish consistency with the supplied manifest and digest; they do not authenticate
|
||||
whoever supplied both.
|
||||
Packing sorts entries, uses portable tar metadata and a fixed tar timestamp, and writes a
|
||||
sibling SHA-256 file. Unpacking checks that digest, rejects archive links and unsafe entry
|
||||
paths before extraction, requires `bundle.yaml` and its integrity section, and verifies
|
||||
the extracted file inventory. Hashes establish consistency with the supplied manifest and
|
||||
digest; they do not authenticate whoever supplied both.
|
||||
|
||||
The inspect handler does not call `unpack()`, because it must report a broken bundle rather
|
||||
than refuse it. It reports a missing or mismatched digest as `digestValid: false`, applies the
|
||||
same unsafe-entry pre-scan (`collectUnsafeArchiveEntries()`) and extraction filter, and runs
|
||||
`verifyIntegrity()` to report an `integrityResult`. A syntactically valid manifest alone is
|
||||
not an inspected archive.
|
||||
|
||||
Inspect also returns a behaviour view, `describeBundleBehaviour()` in
|
||||
`packages/daemon/src/domain/bundle-behaviour.ts` (schema `openrig.bundle-behaviour/v1`). It
|
||||
reads the extracted archive only, through `bundle-behaviour-inspect.ts` (regular UTF-8 files,
|
||||
at most 1 MiB each and 8 MiB in total, opened without following links). It lists the team,
|
||||
each seat's permission posture, the files seats are told to read, what else runs, where
|
||||
content is written, literal outside addresses, needs, and what can't be known before launch.
|
||||
A schema-1 archive gets `state: not_generated`. Posture comes from the member's or rig's
|
||||
`permission_policy`: `builtin:yolo` is full bypass and `builtin:auto` is auto, both by launch
|
||||
flag; `builtin:locked`, `builtin:standard` and `builtin:open` are configuration; a policy file
|
||||
is read from the archive or marked unresolved; no policy means the product default. A rig-level
|
||||
`non_interruptive` boolean is reported on each full-bypass Claude Code or Codex seat as
|
||||
`nonInterruptiveDefault`, and `true` drops the Claude bypass first-run warning. The CLI prints
|
||||
the view before `rig bundle install` and `rig up` as diagnostics only; it never changes the
|
||||
request or the exit code.
|
||||
The inspect handler unpacks through this same path before reporting the appropriate manifest
|
||||
shape. A syntactically valid manifest alone is not an inspected archive.
|
||||
|
||||
## Source routing and bootstrap
|
||||
|
||||
@@ -159,14 +95,13 @@ extensionless paths also have content detection.
|
||||
|
||||
| Input | Consumer |
|
||||
|---|---|
|
||||
| Existing rig name | Existing-rig restore path; unarchived rigs of that name are preferred. |
|
||||
| Existing rig name | Existing-rig restore path. |
|
||||
| Single rig spec or bundle | `BootstrapOrchestrator.bootstrap()` in `packages/daemon/src/domain/bootstrap-orchestrator.ts`. |
|
||||
| Topology manifest | `MultiRigLauncher`, with a single-rig bootstrap or remote-up leaf per entry. |
|
||||
|
||||
Topology plan mode is rejected. Placement belongs on the individual topology entries; a
|
||||
top-level host flag is rejected. The selected topology parser/route also rejects nested
|
||||
topologies, existing-rig-name entries and `.rigbundle` entries: topology entries are spec
|
||||
paths only. This is narrower than the single-rig `up` surface.
|
||||
topologies and existing-rig-name entries. This is narrower than the single-rig `up` surface.
|
||||
|
||||
Bootstrap distinguishes pod-aware and legacy specs, and inspects a bundle manifest to choose
|
||||
`PodBundleSourceResolver` or `LegacyBundleSourceResolver` from
|
||||
@@ -176,107 +111,48 @@ Bootstrap distinguishes pod-aware and legacy specs, and inspects a bundle manife
|
||||
For pod-aware specs, plan mode validates and runs preflight probes; apply delegates to
|
||||
`PodRigInstantiator`. Plan mode still records a bootstrap run/result: it is not a pure
|
||||
file read. Apply reports partial completion when nodes fail or require attention, preserving
|
||||
the created rig identity rather than claiming every member launched. Apply's non-interruptive
|
||||
choice is the request's, else the spec's top-level `non_interruptive`, else the
|
||||
`launch.non_interruptive` setting.
|
||||
the created rig identity rather than claiming every member launched.
|
||||
|
||||
### Durable install target
|
||||
|
||||
Bundle apply requires an explicit target root at the HTTP boundary. The CLI supplies the
|
||||
current directory as the default for `rig up <file>.rigbundle` and for a GitHub link through
|
||||
`rig up` or `rig bundle install`. `rig bundle install` with a local `.rigbundle` sends no
|
||||
default, so apply without `--target` gets a 400. For a pod bundle,
|
||||
Bundle apply requires an explicit target root at the HTTP boundary. For a pod bundle,
|
||||
`materializePodBundle()` copies the verified extraction into that durable root before
|
||||
instantiation, so local agent references and relative working directories survive removal
|
||||
of the extraction directory. It checks destination conflicts before copying, preserves
|
||||
identical files, and refuses differing files or incompatible destination types.
|
||||
|
||||
When an unarchived or running team already has the bundle's rig name (`bundleInstallContext()`
|
||||
in `packages/daemon/src/domain/bundle-install-context.ts`), pod-bundle apply refuses before
|
||||
writing if any of them is running. If the target is that team's own install folder (its
|
||||
`bundle.yaml` names the offered schema-2 bundle, or `my-bundle` or `github-bundle`, the default
|
||||
names before 0.6.7, and it is the folder recorded in `rigs.install_root` when any of those teams
|
||||
recorded one; `isExistingBundleTarget()`), bootstrap first
|
||||
confirms the old sessions are stopped; materialization then copies each conflicting path to a
|
||||
`bundle-backups/reinstall-*` folder under the OpenRig home, with a `RESTORE.json`, before
|
||||
replacing it, and leaves unrelated files in place. Any other target keeps the conflict refusal.
|
||||
The instantiator archives the stopped earlier generation. Pod-bundle apply records the
|
||||
target's real path as the new rig's `install_root` (migration `096`).
|
||||
|
||||
Pod bundles containing service definitions are refused by bootstrap; their service path
|
||||
requires a stable spec directory. Direct spec bootstrap has separate service prelaunch
|
||||
handling. See [agent-spec-and-startup.md](agent-spec-and-startup.md) for instantiation.
|
||||
|
||||
## GitHub folder links and the bundle check
|
||||
|
||||
`packages/cli/src/lib/bundle-source.ts` lets `rig up`, `rig bundle create`, `inspect` and
|
||||
`install` take a GitHub folder link (`isGitHubBundleLink()`). Only a credential-free
|
||||
`https://github.com/owner/repo[/tree/<ref>/<folder>]` link is accepted. The ref is resolved to
|
||||
the longest matching branch or tag, or taken as a full commit hash. The import:
|
||||
|
||||
- needs a healthy local daemon whose `selfHostId` matches the local origin;
|
||||
- runs Git with credential helpers, hooks and non-HTTPS protocols disabled;
|
||||
- shallow-fetches the exact commit into `bundle-imports/` under the OpenRig home, requires a
|
||||
`rig.yaml` in the folder, and refuses symlinks or agent and package references that resolve
|
||||
outside the checkout;
|
||||
- posts the folder to `/api/bundles/create` with the source recorded in provenance, refuses a
|
||||
response without a package digest or with a different source commit, and writes
|
||||
`source.json` and `build.json` in the import folder.
|
||||
|
||||
`rig bundle check <folder>` (`checkBundleFolder()` in `packages/cli/src/lib/bundle-check.ts`)
|
||||
is an advisory, file-read-only check against `openrig.bundle-standard/v1`; it makes no daemon,
|
||||
launch or provider call. Its rules are `pod_aware_rig`, `readme_in_docs`, `referenced_files`,
|
||||
`portable_agents`, `minimum_versions`, `configurations` and `credential_paths` (a filename scan
|
||||
bounded at 10,000 entries that skips `.git`, `node_modules` and symlinks). `readme_coverage`
|
||||
and `embedded_secrets` are always reported as not checked, and host-resolved resources are
|
||||
reported as checked at launch (`host_resources`). Any finding sets exit code 1.
|
||||
|
||||
## Install checks and content routing
|
||||
|
||||
The install handler in `packages/daemon/src/routes/bundles.ts` obtains a source-path
|
||||
lock, reads validated metadata, checks compatibility, and checks a declared rig name
|
||||
against same-name rigs with running sessions before bootstrap; a stopped team of that name
|
||||
doesn't block it. A conflict returns a 400 with `status: "not_attempted"`, the installed team
|
||||
and the offered bundle, and three choices: use the existing team, stop it and retry to replace
|
||||
it, or cancel. The compatibility override `skipVersionCheck` and name-conflict override `force`
|
||||
are explicit request fields; neither skips the metadata pass, which always validates the
|
||||
manifest.
|
||||
against the repository's rig list before bootstrap. The compatibility override
|
||||
`skipVersionCheck` and name-conflict override `force` are explicit request fields.
|
||||
|
||||
`packages/daemon/src/domain/bundle-conflict-detector.ts` implements the rig-name check.
|
||||
It is not a complete agent, port or filesystem collision audit; a missing rig name supplies
|
||||
no name comparison. Target-file conflicts are handled separately by materialization.
|
||||
Skipping these prechecks does not skip archive validation in bootstrap.
|
||||
|
||||
Declared content is routed by `routeBundleContents()` in
|
||||
`packages/daemon/src/domain/bundle-content-routing.ts`, which unpacks the bundle once and
|
||||
routes each kind independently. When it runs depends on the bundle schema:
|
||||
After a completed bundle install, the route separately unpacks and routes declared content:
|
||||
|
||||
- **Pod-aware (schema 2):** bootstrap runs it as `PodRigInstantiator`'s prelaunch hook, after
|
||||
the rig record exists and before any seat launches, so every seat's first turn can see the
|
||||
content.
|
||||
- **Legacy (schema 1):** there is no hook, so the install route routes after bootstrap, and
|
||||
only when the status is `completed`.
|
||||
|
||||
| Manifest content | Destination |
|
||||
| Manifest content | Destination selected by the route |
|
||||
|---|---|
|
||||
| `skills` | The OpenRig `packages` cache, stripping the legacy `packages/` prefix; this does not import a complete harness skill into the managed skill catalog. |
|
||||
| `plugins` | The OpenRig `plugins` root, through local plugin references. |
|
||||
| `workflow_specs` | `workflows/` beneath the resolved `workspaceSpecsRoot`. If that setting is empty, this kind is recorded as a routing failure. |
|
||||
| `workflow_specs` | `workflows/` beneath resolved `workspaceSpecsRoot`; unresolved settings skip this routing. |
|
||||
| `context_packs` | The configured `context.root`, matching context-library discovery. |
|
||||
| `agent_images` | The OpenRig `agent-images` root; declarations address image directories containing a manifest. |
|
||||
| `project` | Registered in the workspace catalog (`workspace.catalog_path`) with the rig associated, and its files placed under `workspace.projects_root/<id>` (`registerBundleProject()` in `packages/daemon/src/domain/workspace/project-registration.ts`). A conflict changes nothing and is a routing failure. |
|
||||
|
||||
Context packs are never merged into an installed pack of the same name: an identical one is
|
||||
reported as `already_installed`, a different one is kept unchanged as `kept_existing`. After
|
||||
routing, the live context library rescans, and a routed pack it can't load becomes a routing
|
||||
failure.
|
||||
|
||||
The per-kind implementations are the `bundle-skills-router.ts`, `bundle-plugins-router.ts`,
|
||||
`bundle-workflow-specs-router.ts`, `bundle-context-packs-router.ts` and
|
||||
`bundle-agent-images-router.ts` files under `packages/daemon/src/domain/`. Routing is best
|
||||
effort in both cases: the hook always lets the launch continue, and a failure never rolls back
|
||||
or fails the install. Failures appear in the result's `routingFailures` and `warnings`, in a
|
||||
`route_bundle_contents` stage for the hook, and in the install audit record.
|
||||
The individual implementations are the `bundle-skills-router.ts`,
|
||||
`bundle-plugins-router.ts`, `bundle-workflow-specs-router.ts`,
|
||||
`bundle-context-packs-router.ts` and `bundle-agent-images-router.ts` files under
|
||||
`packages/daemon/src/domain/`. The route treats these post-bootstrap calls as best effort:
|
||||
their failure does not roll back or turn an already completed rig install into failure.
|
||||
Inspect their returned results and warnings separately from bootstrap success.
|
||||
|
||||
Install audit records are appended best effort to `bundle-audit.jsonl` under the OpenRig
|
||||
home; the history endpoint reads that audit. Bootstrap run state and action journals are
|
||||
@@ -292,12 +168,9 @@ bootstrap calls `PackageInstallService` in
|
||||
The source chain is package resolution/manifest validation, planning and conflict policy,
|
||||
then apply/verification with repository records:
|
||||
|
||||
- `resolvePackage()` in `packages/daemon/src/domain/package-resolve-helper.ts`, which reads
|
||||
and validates through `package-manifest.ts`. `package-resolver.ts` supplies the types; its
|
||||
`PackageResolver` class has no production caller.
|
||||
- `packages/daemon/src/domain/package-resolver.ts` and `package-manifest.ts`.
|
||||
- `packages/daemon/src/domain/install-planner.ts`, `conflict-detector.ts` and
|
||||
`install-policy.ts`. The planner refuses any planned destination outside the install
|
||||
target.
|
||||
`install-policy.ts`.
|
||||
- `packages/daemon/src/domain/install-engine.ts`, `install-verifier.ts`,
|
||||
`install-repository.ts` and `package-repository.ts`.
|
||||
|
||||
|
||||
@@ -9,14 +9,14 @@ applies-when: |
|
||||
agent-image capture/fork/protection, or Claude guided-compaction behavior.
|
||||
siblings: [packaging-bootstrap-bundles.md, agent-spec-and-startup.md]
|
||||
prerequisite-reads: [../README.md, agent-spec-and-startup.md]
|
||||
last-verified-against-source: e8f0ab340db773392ec8be75b072d1c0f3068a50
|
||||
last-updated: 2026-10-08
|
||||
last-verified-against-source: 254122872cf477511514979a4300b695d77cd1f7
|
||||
last-updated: 2026-10-03
|
||||
---
|
||||
|
||||
# Content libraries and compaction
|
||||
|
||||
This module describes source at main commit
|
||||
`e8f0ab340db773392ec8be75b072d1c0f3068a50`. Source paths below are repository-relative.
|
||||
`254122872cf477511514979a4300b695d77cd1f7`. Source paths below are repository-relative.
|
||||
Context packs, plugins and agent images have filesystem-backed content and daemon-side
|
||||
discovery. Their consumers can read database identity, mutate files, deliver messages or
|
||||
launch sessions; the whole layer is not a read-only catalog.
|
||||
@@ -30,13 +30,10 @@ the entry ID is `context-pack:<ref>`.
|
||||
|
||||
### Discovery and mutation
|
||||
|
||||
Startup in `packages/daemon/src/startup.ts` configures the shipped context-pack root (when
|
||||
it exists), the resolved `context.root` and its `system` root, followed by the
|
||||
workspace-local `.openrig/context-packs` root. The workspace root is registered even before
|
||||
it exists, so a folder created later is found by the next sync; it is left out only when it
|
||||
is the same path as one of the other two. The library scans recursively, stops descending
|
||||
when it finds a pack manifest, skips `.tmp-add-*` staging folders, and does not follow
|
||||
directory symlinks.
|
||||
Startup in `packages/daemon/src/startup.ts` configures the shipped context-pack root,
|
||||
the resolved `context.root` and its system root, followed by an existing workspace-local
|
||||
`.openrig/context-packs` root. The library scans recursively, stops descending when it
|
||||
finds a pack manifest, and does not follow directory symlinks.
|
||||
|
||||
The first configured root to encounter a physical pack owns that directory. For distinct
|
||||
physical packs with the same ref, the later root wins. This distinction prevents overlapping
|
||||
@@ -69,9 +66,7 @@ Situation composition selects fresh atoms for `fresh`, fresh plus handover atoms
|
||||
selection is Claude or Codex, with `any` atoms applicable to either. Required atoms join
|
||||
the selection; missing dependencies or runtime-incompatible dependencies fail composition.
|
||||
The output is ordered by atom order, then ID. Profile-only atoms are excluded from ordinary
|
||||
situation selection, but the dependency closure doesn't check that flag, so one can still join
|
||||
as a dependency of a selected atom. Post-compaction composition skips an absent
|
||||
`seat:RECAP.md` and reports it as skipped instead of failing.
|
||||
situation selection.
|
||||
|
||||
The profile route resolves configured tree sources through
|
||||
`packages/daemon/src/domain/context-packs/profile-source-resolver.ts`.
|
||||
@@ -90,59 +85,11 @@ reports overage and drop candidates without silently truncating the profile. Ato
|
||||
`/api/context-packs`. Its library handlers cover list, sync, compose, read/delete by ref,
|
||||
preview, pieces, addressed reads and profile composition.
|
||||
|
||||
`packages/cli/src/commands/context.ts` implements `rig context`, including `list`, `show`,
|
||||
`preview`, `get`, `profile`, `compose`, `add`, `rm` and `sync`, plus `work-install`, `trace`,
|
||||
`source inspect|update` and `recap-write`. The library read/compose routes do not themselves
|
||||
send a pack to a running seat. Several verbs write: `add` installs into `context.root` (from
|
||||
a folder, a URL, or Git with `--git`), `source update` fetches and merges a Git-installed pack
|
||||
and resyncs, `work-install --apply-skills` reconciles skill projections, and `recap-write`
|
||||
writes a seat recap. Inspect the selected CLI verb before treating a context command as
|
||||
read-only. `rig context work-install` resolves a project position and its declared context
|
||||
without the daemon; [workspace-primitive.md](workspace-primitive.md) covers project
|
||||
resolution.
|
||||
|
||||
On a profile read, the route adds each piece's `sha256` and provenance, with a warning when a
|
||||
piece's bytes come from outside the granted folder. Rig and seat selectors grant the seat's
|
||||
folder as a source root and supply a default `seat:LEARNED.md` atom to named profiles whose
|
||||
phases request seat context. An ordinary situation profile includes that file only when the
|
||||
pack authors a seat atom; the selectors alone don't add it.
|
||||
|
||||
### System World, seat recaps and skill loadouts
|
||||
|
||||
`packages/daemon/src/domain/system-world.ts` reads the System World manifest (schema
|
||||
`openrig.system-world/v0alpha1`): an id, a version, the context packs every seat starts from,
|
||||
and system skills. The `context.system_world` setting selects the default manifest at
|
||||
`system/system-world.yaml` under `context.root`, disables it, or names another manifest file.
|
||||
The default (`openrig-default`) names the `onboarding-width` and `world-public` packs and no
|
||||
skills; it is seeded when missing.
|
||||
|
||||
`rig context recap-write --rig <rig> --seat <seat> --file <file>` writes the seat's
|
||||
`RECAP.md` through `packages/daemon/src/domain/context-packs/seat-recap-store.ts`. The previous
|
||||
recap is kept byte-for-byte under `recap-superseded/`. A recap that isn't addressable Markdown
|
||||
is refused; the other content checks are advisory.
|
||||
|
||||
`packages/daemon/src/domain/skill-catalog.ts` resolves a seat's skill loadout from the
|
||||
catalog at `skills.root` (`catalog.yaml`, schema `openrig.skill-catalog/v1`) and the system,
|
||||
topology and project selections. For a working directory it projects skills into
|
||||
`<cwd>/.claude/skills` or `<cwd>/.agents/skills` and tracks what it owns in
|
||||
`<cwd>/.openrig/skill-loadouts/<runtime>.json`. For a Claude or Codex team seat it takes a
|
||||
`location` instead: the seat's own storage outside the project, with its `skill-loadout.json`
|
||||
there, and for Claude the `openrig:<id>` names its generated plugin gives. Each projection
|
||||
reports `current`, `missing`, `shadowed`, `stale` or `conflicting`.
|
||||
`rig skill loadout --runtime <runtime>` inspects the composed projection for a working
|
||||
directory, `rig skill loadout --seat <session|self>` does the same for one seat's own skills,
|
||||
and both reconcile only with `--apply`; `rig skill audit` is a separate
|
||||
read-only provenance and freshness audit. Launch applies the selected loadout per seat.
|
||||
|
||||
For a Claude Code or Codex seat, the profile resolver also adds each selected plugin's skills to
|
||||
that loadout (`packages/daemon/src/domain/profile-resolver.ts:309–330`, with
|
||||
`resolvePluginSkills()` at `skill-catalog.ts:460`). Neither runtime reads skills from the plugin
|
||||
folder projected into the working directory. The skills are projected under their plain names,
|
||||
and a skill the profile already selects keeps its source. A kept plugin copy (an edited or
|
||||
user-owned one, or OpenRig's own copy whose plugin source changed or moved after the loadout
|
||||
was resolved, `skill-catalog.ts:1060–1068`) gives a `plugin_skill_kept` warning, and an unreadable one gives
|
||||
`plugin_skill_skipped`. If plugin skills can't be projected at all, the seat starts without them
|
||||
and gets a `plugin_skills_not_projected` warning (`rigspec-instantiator.ts:2045`).
|
||||
`packages/cli/src/commands/context.ts` implements `rig context`, including
|
||||
`get`, `profile`, `compose`, `add`, `rm` and `sync`, plus work-install,
|
||||
trace, source and recap operations. The library read/compose routes do not themselves send
|
||||
a pack to a running seat. Delivery and installation consumers have their own behavior;
|
||||
inspect the selected CLI verb before treating a context command as read-only.
|
||||
|
||||
## Agent images and forks
|
||||
|
||||
@@ -181,19 +128,9 @@ contribute protection reasons. The route applies the guard to deletion/pruning u
|
||||
`force` is explicit. Prune defaults to dry-run. Its protection view depends on the supplied
|
||||
spec roots; it is not an inventory of every reference anywhere on the host.
|
||||
|
||||
The guard keys its result by image name, not version: every version of one name gets the
|
||||
status computed for the last-listed version, carrying that version's image ID. The delete
|
||||
route looks up by image ID, so on delete only that last-listed version of a name is matched,
|
||||
and its other versions are deleted without `force` even when pinned. `rig agent-image prune`
|
||||
sends a dry run unless `--force` is given, and `--force` also overrides the guard, so a
|
||||
guarded real prune is reachable only through the HTTP route.
|
||||
|
||||
The routes mount at `/api/agent-images` and expose list/sync, snapshot/fork,
|
||||
entry/preview, pin/unpin, delete and prune.
|
||||
`packages/cli/src/commands/agent-image.ts` owns the image library commands. The top-level
|
||||
`rig fork` verb (`packages/cli/src/commands/fork.ts`) drives `POST /fork`; `--keep-image`
|
||||
also captures a pinned image. Forking a Claude Code seat needs Claude Code 2.0.73 or later,
|
||||
because the fork is launched with its own `--session-id`.
|
||||
`packages/cli/src/commands/agent-image.ts` owns the image library commands.
|
||||
|
||||
## Plugins
|
||||
|
||||
@@ -216,9 +153,7 @@ harness loading a plugin.
|
||||
|
||||
The service constructor is not read-only: it retires obsolete refocus hook registrations
|
||||
from the older bundled plugin and rejects duplicate vendored hook registrations across
|
||||
providers. Cached plugin versions are excluded from that duplicate-provider check. Startup
|
||||
constructs the service while building the daemon's dependencies and doesn't catch that
|
||||
rejection, so a duplicate vendored hook stops daemon creation.
|
||||
providers. Cached plugin versions are excluded from that duplicate-provider check.
|
||||
|
||||
`packages/daemon/src/routes/plugins.ts` exposes GET-only inspection at `/api/plugins`:
|
||||
list, detail, used-by and file list/read. The file routes use the discovered plugin root as
|
||||
@@ -232,18 +167,11 @@ At this pin, the route's source filter accepts vendored, Claude-cache and Codex-
|
||||
`ensureVendored()` seeds absent plugins or advances an older numeric manifest version.
|
||||
Equal/newer installed versions preserve installed bytes; equal versions can reconcile file
|
||||
modes on byte-identical files. Missing target version authority is preserved rather than
|
||||
overwritten; invalid or conflicting manifest versions are errors. Advancing a version writes
|
||||
changed files but never deletes files the new version dropped.
|
||||
overwritten; invalid or conflicting manifest versions are errors.
|
||||
|
||||
`ensureSkillGlobally()` projects a named plugin skill using a vendor-version marker.
|
||||
An existing unversioned global skill remains externally owned. Startup wires this service
|
||||
and its filesystem implementation; inspect that wiring when changing projection roots. At
|
||||
startup only `openrig-core` is vendored, and its `openrig-skills` and `refocusing` skills are
|
||||
projected globally into `~/.claude/skills` and `~/.agents/skills`
|
||||
(`packages/daemon/src/startup.ts:877–886`). The packaged `rigs` skill
|
||||
(`packages/daemon/assets/skills/rigs`) is not a plugin skill: `ensureSkillDirGlobally()`
|
||||
projects it into the same roots under the daemon version, so each upgrade refreshes it
|
||||
(`startup.ts:891–899`). A failed global projection is logged and does not stop startup.
|
||||
and its filesystem implementation; inspect that wiring when changing projection roots.
|
||||
|
||||
`ensureLatest()` performs local vendoring before `attemptAutoFetch()`. The latter
|
||||
requests a release asset with a bounded timeout and logs failures; even its successful
|
||||
@@ -262,61 +190,11 @@ and the manual-compaction route consumers.
|
||||
`packages/daemon/src/domain/user-settings/settings-store.ts` resolves the
|
||||
`policies.claude_compaction.*` settings; automatic compaction defaults to disabled.
|
||||
|
||||
`maybeAutoCompact()` applies the delivery guard when one exists and the runtime is Claude
|
||||
Code. Its implementation requires Claude Code, observed usage and a valid integer threshold
|
||||
(default 80). Above-threshold automatic work additionally checks enablement, the
|
||||
post-restore cooldown (10 minutes), the deduplication window (60 seconds) and the
|
||||
already-triggered latch; an active manual attempt also blocks it.
|
||||
|
||||
While the policy is enabled with a valid threshold (`managedCompactionActive` in
|
||||
`packages/daemon/src/adapters/kernel-authority.ts`, using the enforcer's exported `isValidThresholdPercent`),
|
||||
`operationalLaunchArgs` merges `idleCompaction: false` into the Claude launch's one `--settings` value, adding one
|
||||
when there is none. Fresh launch, fork, resume (`claude-code-adapter.ts`) and restore (`claude-resume.ts`) all build
|
||||
their Claude arguments there. The policy is read at each launch; a running session keeps the settings it was launched
|
||||
with. Claude Code before 2.1.290 ignores the key, Claude's managed settings take precedence over `--settings`, and
|
||||
`autoCompactEnabled` is not set.
|
||||
|
||||
`/compact` is held behind a preparation attempt:
|
||||
|
||||
1. The first above-threshold tick starts an attempt with its own ID, the seat's occupant
|
||||
generation, a restore-map path and a completion marker, then sends only the prep prompt.
|
||||
An unknown occupant generation stops the attempt at once.
|
||||
2. The agent writes `RESTORE-MAP.md.tmp` with its file-edit tool, completion marker last.
|
||||
Later ticks return `preparation_pending` until that exact map is complete. The map path is under the seat's working directory
|
||||
(`.openrig/compaction/preparation/<session>/<attempt>/`, with a `.gitignore` of `*`) when
|
||||
that is writable, otherwise under `compaction/preparation/` in the OpenRig home. An explicit
|
||||
`policies.claude_compaction.preparation_root` instead places maps at `<root>/<session>/<attempt>/`
|
||||
for both manual and automatic attempts; failure to prepare that root stops the attempt without fallback.
|
||||
3. The daemon atomically renames the completed temp file to `RESTORE-MAP.md` in its existing
|
||||
final send checks, after rechecking the attempt and occupant. An already-complete final map
|
||||
remains compatible. Only then is `/compact` sent, with the final map path appended to the
|
||||
compact instruction. Publication failure cannot authorize `/compact`.
|
||||
4. The continuation then runs below the threshold: turn boundary, restore prompt, then a
|
||||
read-depth audit prompt (each item marked `FULL`, `PARTIAL` or `NOT_READ`), one stage per
|
||||
poll tick. A seat refreshes its usage sample only when it takes a turn, so when the sample is
|
||||
stale, unknown or has no percentage and a stage is pending, the monitor drains that stage
|
||||
without one (`context-monitor.ts:175`, `claude-compaction-enforcer.ts:436`). Only a fresh,
|
||||
known sample can start a compaction. The sample-less drain reads readiness from the pane alone
|
||||
and counts a timer-less live status row, such as `✻ Compacting conversation…`, as work
|
||||
(`session-transport.ts:153-161`); a recent hook showing work or a waiting person still
|
||||
refuses. It records no width receipt, because the only figure would be the pre-compact one.
|
||||
|
||||
An automatic attempt has a 25-minute ceiling that starts once the prep is delivered. A stale
|
||||
occupant generation, the policy becoming disabled, or the deadline passing stops it. A prep
|
||||
that clearly wasn't sent is retried at most three times; an uncertain prep or `/compact` is
|
||||
never replayed.
|
||||
|
||||
The restore prompt names a restore-pending marker at
|
||||
`compaction/restore-pending/<session>.json` in the OpenRig home, which the `openrig-core`
|
||||
PreCompact hook writes. A per-seat `compaction/post-compact-extra/<session>.md` is preferred
|
||||
over the global extra file, and an extra file that declares a different seat is refused.
|
||||
|
||||
`rig compact <session>` (`packages/cli/src/commands/compact.ts`) runs the same sequence
|
||||
manually through `/api/compaction/trigger`, `cancel` and `state`, which use the terminal
|
||||
bearer-token middleware; it passes every request through when no token is configured.
|
||||
`--skip-map` skips the map requirement once, `--cancel` ends the preparation, and `--state`
|
||||
shows the attempt, its expected map and its deadline. Ordinary approval prompts during preparation can be answered within that same deadline; OpenRig waits without answering them. A manual attempt has 180 seconds for
|
||||
preparation and the idle wait.
|
||||
`maybeAutoCompact()` applies the delivery guard when available. Its implementation
|
||||
requires Claude Code, observed usage and a valid integer threshold. Above-threshold
|
||||
automatic work additionally checks enablement, deduplication, cooldown and the
|
||||
already-triggered latch. It sends prep, then compact, and queues the below-threshold
|
||||
continuation: turn boundary, restore prompt, then compliance prompt.
|
||||
|
||||
The below-threshold continuation checks policy enablement too, except for an explicitly
|
||||
operator-initiated manual sequence. A known occupant-generation mismatch invalidates the
|
||||
@@ -324,8 +202,7 @@ queued stages; an unknown generation does not prove a match. Failed or retained
|
||||
do not advance the stage. The manual trigger shares this continuation while having its
|
||||
own initiation checks.
|
||||
|
||||
Stage, deduplication, cooldown and preparation-attempt maps are in memory; the restore maps
|
||||
are files. Startup supplies live generation
|
||||
Stage, deduplication and cooldown maps are in memory. Startup supplies live generation
|
||||
resolution and a post-restore callback that records a managed-width receipt, so the wider
|
||||
operation also has persistent effects. Do not infer durable lifecycle completion from
|
||||
a library read or one successfully queued message.
|
||||
|
||||
@@ -11,8 +11,8 @@ applies-when: |
|
||||
vs tmux-metadata-key naming distinction.
|
||||
siblings: [daemon-core.md, lifecycle-snapshot-restore.md]
|
||||
prerequisite-reads: [../README.md, daemon-core.md]
|
||||
last-verified-against-source: e8f0ab340db773392ec8be75b072d1c0f3068a50
|
||||
last-updated: 2026-10-08
|
||||
last-verified-against-source: 254122872cf477511514979a4300b695d77cd1f7
|
||||
last-updated: 2026-10-03
|
||||
---
|
||||
|
||||
# Transport, Transcripts, Chat, Ask
|
||||
@@ -22,7 +22,7 @@ capture/broadcast wrap tmux with honest errors; transcripts are bounded
|
||||
`tmux capture-pane` snapshots written to files; chat is daemon-backed SQLite;
|
||||
the daemon's `rig ask` service gathers evidence and never calls an LLM.
|
||||
|
||||
> Verified against source at main `e8f0ab340db773392ec8be75b072d1c0f3068a50`. Each count below sits beside the
|
||||
> Verified against source at main `254122872cf477511514979a4300b695d77cd1f7`. Each count below sits beside the
|
||||
> command that produces it; run the command from the repository root to refresh
|
||||
> it.
|
||||
|
||||
@@ -33,19 +33,18 @@ blanket-replaced: `rigged` → `rig` is a per-occurrence question, not a global
|
||||
substitution.
|
||||
|
||||
**Axis 1 — MCP tool names are `rig_*`.** `packages/cli/src/mcp-server.ts`
|
||||
registers **24** tools, all named `rig_*`
|
||||
registers **18** tools, all named `rig_*`
|
||||
(`grep -c 'server.tool(' packages/cli/src/mcp-server.ts`), including
|
||||
`rig_rig_nodes` (`mcp-server.ts:290`), `rig_send` (`:307`),
|
||||
`rig_capture` (`:341`), `rig_chatroom_send` (`:366`) and `rig_chatroom_watch`
|
||||
(`:402`), the five queue tools `rig_queue_create`, `_show`, `_list`, `_claim`
|
||||
and `_update`, and `rig_telemetry_events`. No `rigged_*` name other than the tmux keys below remains in product
|
||||
`rig_rig_nodes` (`mcp-server.ts:288`), `rig_send` (`:305`),
|
||||
`rig_capture` (`:339`), `rig_chatroom_send` (`:364`) and `rig_chatroom_watch`
|
||||
(`:400`). No `rigged_*` name other than the tmux keys below remains in product
|
||||
source: **0** hits
|
||||
(`git grep -n 'rigged_' -- ':(glob)packages/*/src/**' | grep -v -c '@rigged_'`).
|
||||
|
||||
**Axis 2 — tmux metadata keys are `@rigged_*`, and are correct as-is.** The
|
||||
tmux metadata keys written at claim/bind time are a separate thing from MCP
|
||||
tool names and were not renamed. `setRiggedMetadata` in
|
||||
`packages/daemon/src/domain/claim-service.ts:182`–`186` writes exactly **5**
|
||||
`packages/daemon/src/domain/claim-service.ts:180`–`184` writes exactly **5**
|
||||
keys (`grep -c '@rigged_' packages/daemon/src/domain/claim-service.ts`):
|
||||
`@rigged_node_id`, `@rigged_session_name`, `@rigged_rig_id`,
|
||||
`@rigged_rig_name`, `@rigged_logical_id`. Do not blanket-sed `rigged` → `rig`.
|
||||
@@ -61,7 +60,7 @@ All under `packages/daemon/src/domain/`:
|
||||
and mid-work detection), honest error reporting, and list/pod/rig/global
|
||||
targeting.
|
||||
- `transcript-store.ts` — transcript file management: path convention, ANSI
|
||||
stripping for tail and grep reads, boundary markers, `readTail`, `readFull`, `grep`.
|
||||
stripping on read, boundary markers, `readTail`, `readFull`, `grep`.
|
||||
Filesystem-backed, NOT SQLite. The capture that writes the files is
|
||||
`transcript-rotation.ts` (§4).
|
||||
- `history-query.ts` — transcript + chat search. Prefers `rg`, falls back to
|
||||
@@ -86,273 +85,37 @@ Routes: `packages/daemon/src/routes/{transport,transcripts,ask,chat,whoami}.ts`
|
||||
`SessionTransport.send()`:
|
||||
|
||||
1. Resolve the session name (`resolveBySessionName`,
|
||||
`session-transport.ts:963`): not found → 404; the same name in more than
|
||||
one rig → 409. A tmux probe of the session can also refuse it as missing or
|
||||
tmux as unavailable (`:1317`–`1334`). Pod, rig, global and `--to` list
|
||||
targets go through `POST /api/transport/broadcast`, which resolves them
|
||||
with `resolveSessions` and sends to each recipient in turn.
|
||||
2. Take the seat's delivery lease. Every write runs under a per-seat,
|
||||
serialized lease from the seat delivery guard, installed at daemon start
|
||||
(`send`, `:1155`). With the seat's typing guard on, the message is held
|
||||
instead of typed: the result is `outcome: "retained"` with HTTP 200
|
||||
(`routes/transport.ts:115`); operators use `rig seat set-typing-guard` and
|
||||
`rig seat held-messages`. This same typing guard has `off` (default),
|
||||
`draft-aware`, and `hold` modes. The legacy enabled boolean selects hold/off.
|
||||
`DraftAwareDelivery` makes one attempt for opted-in seats and immediately returns
|
||||
the exact refusal reason and original held IDs when input is unavailable.
|
||||
Migration `100_typing_guard_modes` extends existing guard/audit rows and adds
|
||||
non-executable receipt metadata to the original outbox; it creates no tables
|
||||
or retry scheduler. Combined wakes preserve every original ID/body.
|
||||
Legacy storage bits fail safe to hold on rollback; newer legacy audit writes
|
||||
supersede older saved modes on re-upgrade, including same-value writes.
|
||||
3. Classify send readiness. Only a positive interactive-prompt reading
|
||||
`session-transport.ts:729`): not found → 404; the same name in more than
|
||||
one rig → 409. Pod, rig, global and `--to` list targets go through
|
||||
`POST /api/transport/broadcast`, which resolves them with
|
||||
`resolveSessions`.
|
||||
2. Classify send readiness. Only a positive interactive-prompt reading
|
||||
(`needs_input`) refuses, with `target_needs_input`
|
||||
(`session-transport.ts:1482`), unless the caller passes
|
||||
`--dangerously-interact --reason`; that override persists an audit record
|
||||
before sending and refuses the send if it can't
|
||||
(`prompt_override_audit_unavailable`, `:1471`). A pane that reads `unknown` while the seat's
|
||||
latest runtime hook says it waits on a person reads as `needs_input` (`session-transport.ts:1878–1889`). A mid-work reading (`running`, from a
|
||||
(`session-transport.ts:1272`), unless the caller passes
|
||||
`--dangerously-interact --reason`. A mid-work reading (`running`, from a
|
||||
fresh runtime hook or the pane's mid-work patterns,
|
||||
`findPatternEvidence(recentLines, [...MID_WORK_PATTERNS, CLAUDE_LIVE_STATUS_PATTERN])`,
|
||||
`:311–315`) or an `unknown` one proceeds with an advisory `warning` (`:1495`,
|
||||
`:1503`). `--force` has no effect on this path, and combining it with
|
||||
`--wait-for-idle` is refused with 400 (`routes/transport.ts:66`–`73`).
|
||||
4. Two-step tmux send: a unique file/buffer pasted with `paste-buffer -d -r -p`
|
||||
(`packages/daemon/src/adapters/tmux.ts:625`) → ~200ms delay
|
||||
(`session-transport.ts:1558`) → separate named `Enter` (`session-transport.ts:1573–1578`). The paste
|
||||
targets the seat's registered pane ID, not the session name, and is refused
|
||||
with no input written if the session no longer holds exactly that pane.
|
||||
`findPatternEvidence(recentLines, MID_WORK_PATTERNS)`, `:225`) or an
|
||||
`unknown` one proceeds with an advisory `warning` (`:1321`). `--force` has
|
||||
no effect on this path.
|
||||
3. Two-step tmux send: a unique file/buffer pasted with `paste-buffer -d -r -p`
|
||||
at every payload size (`packages/daemon/src/adapters/tmux.ts:604`) →
|
||||
~200ms delay (`session-transport.ts:1378`) → separate named `Enter` (`:1385`).
|
||||
Bracketed paste preserves multiline input in supporting TUIs; the payload
|
||||
never enters a shell argument. A `--dangerously-interact` answer is pasted
|
||||
without `-p` (`session-transport.ts:1541`) and Enter is pressed only if the
|
||||
whole answer is still staged (`:1562`–`1570`). A successful paste proves
|
||||
transport execution, not runtime consumption.
|
||||
The transport's prompt reader uses the shared `composer-prompts.ts` matchers
|
||||
from Mr-Neutr0n's #635. Its cursor-aware extension preserves capture styling
|
||||
and excludes a wholly dim autocomplete suffix after the cursor. The daemon
|
||||
directly depends on `string-width` to compare Unicode terminal cell widths
|
||||
with cursor positions and exact staged text; a dependency hoisted from the
|
||||
TUI would not declare this daemon runtime requirement. Default seats retain
|
||||
their existing advisory recognition and staged-text verification behavior.
|
||||
For draft-aware seats, `TmuxAdapter` checks the current composer after buffer
|
||||
preparation and again immediately before keys. The delivery lease records
|
||||
the pasted text and any observed collapsed-paste label; Enter requires that
|
||||
owned input. Late human input, changed recipients or stopped queue wakes refuse
|
||||
further input or hold the message; ambiguous writes remain indeterminate. Nothing
|
||||
is retried automatically. Unicode cell widths use the daemon's direct
|
||||
`string-width` dependency. See [per-seat terminal delivery](../../reference/seat-delivery.md)
|
||||
for activation, persistence, inspection and lifecycle tradeoffs.
|
||||
5. Optional `--verify`: capture the last 30 pane lines before the paste and,
|
||||
500 ms after Enter, again, leaving out the current input box (the last
|
||||
prompt line and its continuation, `verificationTranscript`). A send
|
||||
carrying OpenRig's From/To header is matched as the whole message with
|
||||
whitespace normalized (`countEnvelopeOccurrences`); a raw send is matched
|
||||
by its first 40 characters (`verificationSnippet`). More occurrences after
|
||||
the send report `outcome: "delivered"`; otherwise the outcome is
|
||||
`rendered-unconfirmed`: text and Enter landed but the capture could not
|
||||
re-confirm the render, which is not a failure. The outcome values are
|
||||
`delivered`, `rendered-unconfirmed`, `failed` and `retained`.
|
||||
With `transport.verify_input_box` on (off by default), a Claude Code or
|
||||
Codex send is verified only when the seat was proven idle before the paste
|
||||
and the input box shows the message, and is unconfirmed otherwise:
|
||||
|
||||
- **Seat idle before the paste** (`readSeatBeforePaste`). The `--verify`
|
||||
capture taken before the paste (the whole screen) must match an idle
|
||||
allow-list (`SEAT_IDLE_SHAPES`) built from real Claude Code 2.1.296 and
|
||||
Codex 0.160.0 frames and, where no frame was captured, from the Claude
|
||||
Code 2.1.296 bundle, the Codex 0.160.0 source and OpenRig's own launch
|
||||
code. Claude Code: the empty box or its `Try "…"` suggestion between two
|
||||
rules; the opening rule plain, or carrying this seat's own session name
|
||||
the way Claude Code draws `--name` (`─…─ <session> ─`, or `──` as in
|
||||
earlier versions, as wide as the closing rule; OpenRig launches every
|
||||
Claude seat with `--name`); the footer row of the seat's permission
|
||||
posture, one for each mode OpenRig can launch: bypass
|
||||
(`⏵⏵ bypass permissions on (shift+tab to cycle) · ← for agents`), accept
|
||||
edits (OpenRig's default), auto, don't ask, plan, and default
|
||||
(`⏸ manual mode on · ← for agents`); no statusLine row between the
|
||||
closing rule and the footer (OpenRig's statusLine collector prints
|
||||
nothing); a blank, effort or tmux-notice row above the box; and above
|
||||
that, in the status slot, the completion row of the seat's last turn
|
||||
(`✻ <verb> for <duration> · done <time>` at column 0, matched by the
|
||||
Claude Code 2.1.296 bundle's grammar: one of its eight past-tense verbs,
|
||||
its duration format, and the time of a turn finished today on a 12- or
|
||||
24-hour en-US clock). A blank slot counts only under that completion
|
||||
row, with only blank rows between them (as in the fullscreen renderer),
|
||||
or, before the first turn, under the last row of the Claude Code v2.1.296
|
||||
welcome banner. OpenRig launches Claude in the classic renderer, where the
|
||||
box follows the transcript, so an idle seat that has finished a turn
|
||||
shows that turn's completion row in the slot; real frames of idle seats
|
||||
OpenRig launched show it. A configured statusLine, which OpenRig installs
|
||||
on every Claude seat, makes Claude Code drop the footer's hints, so a
|
||||
running turn draws the same footer row as an idle one, without
|
||||
`esc to interrupt`: the status slot is what tells them apart. The 2.1.296
|
||||
bundle draws the live status row (the spinner) there only while no
|
||||
streamed text with a complete line is on screen
|
||||
(`isLoading && (!hasDisplayedStreamingText || tailBlank || …)`); while
|
||||
streamed text is shown it draws nothing in its place, and the last
|
||||
streamed row moves into the slot. That row never matches the completion
|
||||
row, because Claude Code draws a message behind its `●` column. The
|
||||
bundle does not show that the last streamed row is never blank, so a
|
||||
blank slot under transcript text reads `unknown`: that case is left
|
||||
unconfirmed rather than read as idle. Codex: the empty box over its
|
||||
status line and a `? for shortcuts` hint row, with the completion row or
|
||||
the fresh session's greeting as the last row above the box. The
|
||||
completion row is matched by the grammar Codex 0.160.0 prints it with
|
||||
(`Worked for <elapsed> • <time>`, a 12- or 24-hour clock, a date before
|
||||
the time on another day, runtime metrics after it). No row anywhere may
|
||||
be a running, streaming, queued, pending-input or paste-hint row (a live
|
||||
status row, `esc to interrupt`, `paste again to expand`, a queued label,
|
||||
Codex's pending-input headers or `↳` rows, a spinner). Any other frame,
|
||||
including every running, streaming, steer-preview, paste-hint or unknown
|
||||
layout, another seat's name, a statusLine that prints a row, a background
|
||||
shell in the footer and a fullscreen renderer with a statusLine (which
|
||||
reserves a row for it), reads `seat: not-idle` or
|
||||
`unknown`, and the send reads unconfirmed. This holds when a running turn
|
||||
hides its signal (Codex hides its `• Working` row while it streams;
|
||||
Claude Code shows only `paste again to expand` in its footer for 8 s
|
||||
after a paste, and no `esc to interrupt` under a statusLine). So a send to
|
||||
a busy or unknown seat always reads unconfirmed.
|
||||
|
||||
**Versions.** The layouts were recorded from Claude Code 2.1.296 and
|
||||
Codex 0.160.0 (the versioned frames under
|
||||
`packages/daemon/test/fixtures/input-box/`, with their limits in that
|
||||
folder's README). A frame that visibly names another client version reads
|
||||
`unknown` before the paste and `unrecognized` in the box: Claude Code's
|
||||
welcome banner (`Claude Code v2.1.297`), Codex's session header
|
||||
(`>_ OpenAI Codex (v0.161.0)`) or its update notice, whose first version
|
||||
is the running one (`Update available! 0.159.0 -> …`). Most frames
|
||||
show no version (the banner and header scroll away), and there a matching
|
||||
layout is evidence about the layout only, not proof of the client
|
||||
version: another version that draws the same rows reads the same. There is
|
||||
no version discovery and no extra read for it.
|
||||
|
||||
Which Claude seats OpenRig launches can verify: an idle Claude Code
|
||||
seat in any posture OpenRig launches, after any number of turns, whose
|
||||
status slot holds its last turn's completion row as above, or a fresh
|
||||
seat whose slot is blank under the welcome banner. It reads `unknown`
|
||||
when that row is anything else: a blank row under transcript text, a
|
||||
completion row with more after the time (a still-running note, hidden
|
||||
messages, a budget), the weekday or date of a turn that finished on an
|
||||
earlier day, another locale's or a custom time format, an interrupted
|
||||
turn, or a row printed after the turn. And only a text Claude Code shows
|
||||
inline in its box can verify (see the box reading below): a multi-line
|
||||
text, which includes every `rig send` envelope and every queue wake,
|
||||
collapses to a paste label and stays unconfirmed.
|
||||
- **The box held exactly this message before Enter.** One extra capture
|
||||
between the paste and Enter must show exactly the sent text in the input
|
||||
box with its word boundaries kept (`readInputBox`, `boxHoldsText`): runs
|
||||
of whitespace, including Unicode spaces, compare as one space, so a box
|
||||
holding `nowhere` is not the text `now here`. A row break counts as a
|
||||
space only where it must be whitespace of the box's text. Claude Code
|
||||
2.1.296 wraps its input at spaces only (wrap-ansi). Codex 0.160.0 wraps
|
||||
it with textwrap (FirstFit, UAX #14 break opportunities, the hyphen
|
||||
splitter), which also breaks with no space drawn after a hyphen or a
|
||||
slash and between ideographs. So a break counts where the next row's
|
||||
first word would have fit on the row before it (both wrappers fill a row
|
||||
first, so the text has a line break there), or where it falls between
|
||||
two ASCII letters or digits, or before a hyphen, a slash, a closing
|
||||
bracket or `.,:;!?`, and the two words it separates, joined, fit in the
|
||||
box's widest row, but only after a row whose text starts at its first
|
||||
cell with a printable ASCII character and whose last word is ASCII
|
||||
letters, digits, `'` and `.,:;` only. Codex keeps a word that fits in a
|
||||
row whole only where the word starts on a row that already holds text:
|
||||
a row holding only indentation absorbs the next word and splits it
|
||||
where the row fills, and a word after a hyphen or a slash can be split
|
||||
the same way in a row that took the next textwrap line. So on Codex a
|
||||
split between two letters is not always the text's space; after an
|
||||
indented row, or after a last word with a break opportunity inside it,
|
||||
only the first rule reads the break. The first rule has one known
|
||||
residual on Codex, found in a model of the rust-v0.160.0 source, not in
|
||||
a live capture: once an indented row has absorbed and split a word, the
|
||||
re-pass can end a later row early at a hyphen, so a break with no
|
||||
whitespace can pass the first rule. Every such box in that model also
|
||||
holds the earlier split after the indented row, which reads `ambiguous`,
|
||||
so the box never reads `exact`. The widest row is counted in
|
||||
printable ASCII cells only, so combining marks, joiners and zero-width
|
||||
characters never widen it. Any other break, and a break inside a word of
|
||||
the text, reads `ambiguous` and the send stays unconfirmed. A collapsed paste label, Claude's
|
||||
queued-messages label or `Try "…"` suggestion, or another draft is never
|
||||
the message. The default `--verify` matcher above is unchanged.
|
||||
- **The box is empty after Enter on the same pane process.** The capture
|
||||
after Enter must show the box empty, with the pane process
|
||||
(`#{pane_pid}`) and the seat's binding unchanged.
|
||||
|
||||
These readings stay internal to the send; the result carries only the
|
||||
verdict (`verified`, `outcome`). An empty box reads `queued` instead of
|
||||
`empty` where the frames say the message may wait behind a turn: Codex's
|
||||
pending-input rows or a row under its running-turn status, or a running
|
||||
turn in the frame read before Enter (Codex's `• Working` row; for Claude
|
||||
Code, `esc to interrupt` or a live status row above the box, including
|
||||
above a box of several rows). The verdict uses these readings: verified
|
||||
needs `empty`, so for a seat that was idle before the paste they are the
|
||||
only check that rejects a message queued behind a turn that started after
|
||||
the pre-paste capture. An audited prompt answer (step 4) reads no box: with
|
||||
the setting on it stays unconfirmed, whatever the default matcher would
|
||||
say.
|
||||
The readings decide the verification verdict, not whether Enter is sent:
|
||||
the seat is read from the capture `--verify` already takes, and none of
|
||||
the extra reads decides whether Enter is sent. Each has
|
||||
a 500 ms deadline, which is a budget, not a guarantee: the pre-Enter read
|
||||
comes after the existing 200 ms wait and can add about 500 ms before
|
||||
Enter, and the post-Enter process read can add about another 500 ms
|
||||
before the reply. A read that misses its deadline reads `unavailable`, the
|
||||
send stays unconfirmed, and Enter is still sent once. With a deliberately
|
||||
slowed screen read, review measured about 718 to 721 ms from paste to
|
||||
Enter, against about 216 to 219 ms on main under the same slowdown.
|
||||
Limits: the seat is read once, before the paste, and Enter
|
||||
follows about 200 ms later. A turn can start in that window, from a person
|
||||
typing in the pane or from the agent itself (Claude Code and Codex start
|
||||
turns on their own when a background task finishes, a scheduled wake-up
|
||||
fires or a teammate's message arrives). Such a turn is caught only when
|
||||
the frame read before Enter shows it; a Codex turn already streaming
|
||||
there hides its `• Working` row and is not seen. An empty box after an
|
||||
exact one means the box was cleared, normally by our Enter; a clear by
|
||||
something else at that moment (a person's C-c) looks the same, and so
|
||||
does a text the TUI runs as a command (a Claude Code `/command`, a Codex
|
||||
`!command`), which clears the box without the model reading a message.
|
||||
`#{pane_pid}` is the pane's root process (the shell for most launches), so
|
||||
an agent restarted under the same shell is not caught by the pane process
|
||||
check, and the same pane and binding are not proof of the same native
|
||||
conversation.
|
||||
An empty box means the TUI took the text, not that the model read it.
|
||||
Consumers see only the report. With the setting on, a queue wake that
|
||||
reads unconfirmed records the existing `delivered-ack-pending` state, as
|
||||
an unconfirmed wake does today. Every queue wake to Claude Code is
|
||||
unconfirmed under the setting, because its multi-line envelope collapses
|
||||
to a paste label, and so is a wake to a busy or not-proven-idle Claude
|
||||
Code or Codex seat. A pending, unclaimed handoff with no pickup evidence
|
||||
can then enter the wake ladder's existing escalation path after
|
||||
`queue.wake_unconfirmed_window_minutes` (default 30). It is not blindly
|
||||
re-sent: the ladder's unconfirmed path skips its retry rung
|
||||
(`queue-wake-ladder.ts`), and nothing in the send path retries or
|
||||
re-sends.
|
||||
6. CLI `--verify` goes further (`packages/cli/src/commands/send.ts:596`): it
|
||||
looks for the text still unsubmitted at the prompt, makes one guarded
|
||||
Enter-only retry through the daemon's `submitOnly` path
|
||||
(`session-transport.ts:1344`, which refuses with `staged_mismatch` unless the
|
||||
pane shows the expected staged text), and ends `staged-not-consumed` with
|
||||
exit code 1 if it is still there.
|
||||
7. Honest result with reason on failure. Reasons missing from the send
|
||||
route's status map (among them the runtime-identity refusals) are returned
|
||||
with HTTP 500 (`routes/transport.ts:118`–`140`).
|
||||
|
||||
The sender comes from the `X-OpenRig-Session` header; an unsigned send gets an
|
||||
unknown-sender notice. The CLI adds a From/To envelope, and the daemon appends
|
||||
a delivered-latency note for delays of 10 s or more.
|
||||
never enters a shell argument. A successful paste proves transport
|
||||
execution, not runtime consumption.
|
||||
4. Optional `--verify`: capture the last 30 pane lines before and after the
|
||||
send and count the message's first 40 characters in each. A higher count
|
||||
after the send reports `outcome: "delivered"`; otherwise the outcome is
|
||||
`rendered-unconfirmed` — text and Enter landed but the capture could not
|
||||
re-confirm the render, which is not a failure (`session-transport.ts:472`
|
||||
`verify?`; `:1403` `if (opts?.verify)`; `:1415`
|
||||
`verified = postCount > preCount`).
|
||||
5. Honest result with reason on failure.
|
||||
|
||||
Architecture rule 18 (`architecture-rules-and-event-system.md`): tmux is
|
||||
transport, not truth — `send/capture/broadcast` wrap tmux reliably with honest
|
||||
errors.
|
||||
|
||||
The daemon runs tmux without a shell: argv straight to the tmux binary found on
|
||||
`PATH`. `OPENRIG_TMUX_SHELL=1` at daemon start runs every tmux call through
|
||||
`/bin/sh` instead (Linux and macOS; Windows always uses argv). A binary that
|
||||
can't be started at all (a script without `#!`, a missing interpreter) runs
|
||||
through `/bin/sh -c 'exec "$0" "$@"' tmux …`, which finds tmux as the shell
|
||||
path does; nothing ran before, so no command runs twice. The resolved path is
|
||||
cached, so a different tmux installed earlier on `PATH` takes effect after a
|
||||
daemon restart.
|
||||
|
||||
### 3b. Cross-host coordination verbs
|
||||
|
||||
`rig send/capture/transcript/broadcast --host <id>` (and the `agent@rig@host`
|
||||
@@ -381,13 +144,13 @@ remote daemon's ordinary local routes; the cross-host logic is in the CLI.
|
||||
- **Terminal-bearer posture (`/api/transport/*` only).** The remote's
|
||||
transport routes (send/capture/broadcast) gate on its terminal bearer
|
||||
(`routes/transport.ts:26`; `OPENRIG_TERMINAL_BEARER_TOKEN`,
|
||||
`packages/daemon/src/index.ts:291`). With no token configured the
|
||||
`packages/daemon/src/index.ts:283`). With no token configured the
|
||||
middleware passes every request through
|
||||
(`packages/daemon/src/middleware/auth-bearer-token.ts:99`) — the tailnet is
|
||||
the auth boundary by design — except that a daemon bound to an explicit
|
||||
address that is neither local nor tailnet falls back to
|
||||
`OPENRIG_AUTH_BEARER_TOKEN`
|
||||
(`index.ts:297`). The CLI presents the registry bearer from `hosts.yaml`
|
||||
(`index.ts:289`). The CLI presents the registry bearer from `hosts.yaml`
|
||||
when one is configured; for a URL-only anonymous host the `Authorization`
|
||||
header is omitted. A remote enforcing a different terminal bearer answers
|
||||
401, which surfaces as the structured `permission-gate` step
|
||||
@@ -395,20 +158,17 @@ remote daemon's ordinary local routes; the cross-host logic is in the CLI.
|
||||
Remedy: set the remote terminal bearer equal to the paired registry bearer,
|
||||
or rely on the tailnet boundary. **The transcript read is deliberately
|
||||
outside this class:** `/api/transcripts/*` mounts with no bearer middleware
|
||||
(`packages/daemon/src/server.ts:748`, beside the gated `/api/transport` at
|
||||
`:749`), and credential-shaped text is redacted on the `/full` route only
|
||||
(`packages/daemon/src/server.ts:749`, beside the gated `/api/transport` at
|
||||
`:750`), and credential-shaped text is redacted on the `/full` route only
|
||||
(`routes/transcripts.ts:292`). So a wrong terminal bearer that
|
||||
permission-gates `send --host` does NOT gate `transcript --host` — the read
|
||||
keeps succeeding for a Host name the remote's browser boundary accepts
|
||||
(`server.ts:647`; it applies to every `/api/*` route), and the auth-failure
|
||||
class is not uniform across the four verbs. The route's own comment (`routes/transcripts.ts:250`) leaves a
|
||||
keeps succeeding, and the auth-failure class is not uniform across the four
|
||||
verbs. The route's own comment (`routes/transcripts.ts:250`) leaves a
|
||||
coherent transcript-read auth policy across tail/grep/full for later.
|
||||
- **The 3-part form is CLI-edge sugar only.** `resolveCrossHostTarget`
|
||||
(`packages/cli/src/cross-host-target.ts:58`) strips the suffix only when it
|
||||
resolves to a registered host, or equals this host's own id, which routes
|
||||
home (`:95`; only `rig send` passes the self id,
|
||||
`packages/cli/src/commands/send.ts:398`, so `capture` and `transcript` treat
|
||||
their own id as unknown); otherwise the string passes through unchanged with a loud
|
||||
home (`:95`); otherwise the string passes through unchanged with a loud
|
||||
host hint. Every session string that reaches any daemon stays
|
||||
`member@rig`; the host travels out-of-band. Durable cross-host
|
||||
coordination stays the queue's cross-host routing
|
||||
@@ -418,43 +178,30 @@ remote daemon's ordinary local routes; the cross-host logic is in the CLI.
|
||||
|
||||
1. `NodeLauncher` starts transcript rotation right after tmux session
|
||||
creation, before the harness boots
|
||||
(`NodeLauncher`, `startTranscriptRotation`).
|
||||
2. Each rotation tick captures the trailing lines and atomically overwrites
|
||||
(temp file + rename in `startTranscriptRotation`)
|
||||
`transcripts/{rig-name}/{session-name}.log` under the OpenRig home (or
|
||||
the `transcripts.path` setting). It skips the write when the captured bytes
|
||||
are unchanged. Defaults: 1000 trailing lines every 2 s
|
||||
(`DEFAULT_TRANSCRIPT_LINES`, `DEFAULT_TRANSCRIPT_POLL_INTERVAL_MS`); an idle seat is captured less often,
|
||||
within the 10-second freshness window. Both are tunable with
|
||||
`OPENRIG_TRANSCRIPTS_LINES` and `OPENRIG_TRANSCRIPTS_POLL_INTERVAL_SECONDS`
|
||||
or the matching `transcripts.*` settings. This bounded capture replaced the
|
||||
earlier `tmux pipe-pane` stream (see the header comment of `transcript-rotation.ts`), so the file
|
||||
holds a trailing window, not the whole session. Sessions on one adapter
|
||||
tick on one shared timer, and the captures due in a tick share
|
||||
`capturePanesContent`: one chained call per chunk of 24, with a
|
||||
`list-sessions` started beside it on every batch, whose result is consulted
|
||||
only when the chain fails, each chunk on its own (`captureBatch` in
|
||||
`transcript-rotation.ts` → `capturePanesContent` in `adapters/tmux.ts`).
|
||||
A session the batch leaves out, a lone due session, or a pane or window
|
||||
target reads per target with `capturePaneContent` (`adapters/tmux.ts`).
|
||||
3. `TranscriptStore` owns path convention, ANSI stripping for `readTail` and
|
||||
`grep`, boundary
|
||||
markers, `readTail`, `readFull`, `grep`. `readFull` returns the raw bytes
|
||||
(`TranscriptStore.readFull`); the `/full` route redacts them. The transcript
|
||||
routes check capture health first and can start capture lazily for a seat
|
||||
that has none.
|
||||
(`packages/daemon/src/domain/node-launcher.ts:181`).
|
||||
2. Each rotation tick runs `tmux capture-pane -p -S -<lines>`
|
||||
(`adapters/tmux.ts:1020`) and atomically overwrites (temp file + rename,
|
||||
`transcript-rotation.ts:146`)
|
||||
`~/.openrig/transcripts/{rig-name}/{session-name}.log`. Defaults: 1000
|
||||
trailing lines every 2 s (`transcript-rotation.ts:27`–`28`), tunable with
|
||||
`OPENRIG_TRANSCRIPTS_LINES` and `OPENRIG_TRANSCRIPTS_POLL_INTERVAL_SECONDS`.
|
||||
This bounded capture replaced the earlier `tmux pipe-pane` stream
|
||||
(`transcript-rotation.ts:3`), so the file holds a trailing window, not the
|
||||
whole session.
|
||||
3. `TranscriptStore` owns path convention, ANSI stripping on read, boundary
|
||||
markers, `readTail`, `readFull`, `grep`.
|
||||
4. `rig transcript <session> --tail N / --grep "pattern"` provides
|
||||
agent-facing access.
|
||||
5. On restore: a `--- SESSION BOUNDARY: … ---` marker is written before
|
||||
re-launch (`RestoreOrchestrator`); each rotation tick keeps each
|
||||
distinct boundary line once, as a header above the fresh capture
|
||||
(`startTranscriptRotation`, boundary header). (Restore-side detail in
|
||||
re-launch (`restore-orchestrator.ts:1100`); each rotation tick keeps every
|
||||
boundary line as a header above the fresh capture
|
||||
(`transcript-rotation.ts:122`). (Restore-side detail in
|
||||
`lifecycle-snapshot-restore.md`.)
|
||||
6. `rig ask` gathers rig summary plus transcript excerpts, chat excerpts,
|
||||
insufficiency state, and guidance.
|
||||
|
||||
Architecture rule 19, as the code implements it: transcripts are a bounded
|
||||
`capture-pane` snapshot (not pipe-pane), ANSI-stripped on tail and grep reads; `rg`
|
||||
`capture-pane` snapshot (not pipe-pane), ANSI-stripped on read; `rg`
|
||||
preferred, `grep -E` fallback. Rule 22: the daemon's `rig ask` is context
|
||||
engineering — it gathers evidence and does NOT call an external LLM; the
|
||||
agent IS the LLM. The one exception is the explicit CLI flag `rig ask --wake`
|
||||
@@ -462,57 +209,22 @@ agent IS the LLM. The one exception is the explicit CLI flag `rig ask --wake`
|
||||
Claude or Codex session (`claude -p --resume` / `codex exec resume`,
|
||||
`packages/cli/src/ask-wake.ts:58`–`60`) to answer one question.
|
||||
|
||||
### Current-generation records for `rig walk`
|
||||
|
||||
`rig walk` checks a delivered piece against the current conversation through
|
||||
`GET /api/sessions/:sessionName/generation-record` (`routes/sessions.ts`).
|
||||
Without `sinceBytes`, the route returns record identity and size; with it, the
|
||||
route also reads a bounded suffix from the same open file. This terminal-class
|
||||
endpoint uses the terminal bearer gate.
|
||||
|
||||
For Codex, the current occupant must have a verified identity for its bound
|
||||
pane. The route compares tmux's current root PID with the identity's
|
||||
`observedPanePid`, falling back to `observedPid` for older verdicts that only
|
||||
recorded one PID. Previously it always compared the root with the native Codex
|
||||
PID, refusing a verified Codex running beneath a shell or launcher. Recording
|
||||
both PIDs lets that wrapper pass without accepting a changed pane root or
|
||||
changing the identity schema.
|
||||
|
||||
For dual-PID verdicts, the selected thread must also be the thread resolved for
|
||||
`observedPid`. All candidate threads still participate in the ambiguity check;
|
||||
another process's resolvable thread cannot stand in for a missing or
|
||||
unresolvable verified native process. This reuses the same process observation
|
||||
and thread lookups, without an additional census.
|
||||
|
||||
The existing thread lookup still requires a Codex descendant with one
|
||||
resolvable thread, a thread-table record path and a matching rollout header.
|
||||
The route rechecks occupant generation, pane binding and root PID after the
|
||||
thread lookup. These are bounded observations, not an atomic process snapshot.
|
||||
An unresolved identity still returns 409; `rig walk` reports consumption as
|
||||
unverified instead of claiming it read the record. Route regressions in
|
||||
`packages/daemon/test/walk-consumption-primitives.test.ts` cover shell and
|
||||
launcher wrappers, legacy verdicts, root changes, replaced or unresolved native
|
||||
processes, and changes during thread resolution with synthetic process
|
||||
observations and actual SQLite/JSONL
|
||||
fixtures; they do not exercise a live Codex conversation.
|
||||
|
||||
## 5. Chat flow
|
||||
|
||||
1. `rig chatroom send <rig> "message"` → `POST
|
||||
/api/rigs/:rigId/chat/send` → `ChatRepository.send()`
|
||||
(`routes/chat.ts:43`); the route then emits `chat.message` (`:45`).
|
||||
(`routes/chat.ts:35`); the route then emits `chat.message` (`:37`).
|
||||
2. SSE: `GET /api/rigs/:rigId/chat/watch` delivers real-time messages.
|
||||
3. History: `GET /api/rigs/:rigId/chat/history` returns channel history in id
|
||||
order, 100 messages unless `limit` says otherwise
|
||||
(`chat-repository.ts:68`), filterable by `topic`, `after`, `since` and
|
||||
`sender` (a `since` SQLite cannot parse is refused with 400,
|
||||
`routes/chat.ts:73`); `POST /api/rigs/:rigId/chat/topic` persists topic markers.
|
||||
`sender`; `POST /api/rigs/:rigId/chat/topic` persists topic markers.
|
||||
4. UI: a `RigChatPanel` component exists
|
||||
(`packages/ui/src/components/RigChatPanel.tsx`), but no UI view mounts it:
|
||||
**1** file under `packages/ui/src` names it, its own
|
||||
(`git grep -l 'RigChatPanel' -- packages/ui/src | wc -l`).
|
||||
5. MCP: **`rig_chatroom_send` + `rig_chatroom_watch`** (`mcp-server.ts:366`,
|
||||
`:402`).
|
||||
5. MCP: **`rig_chatroom_send` + `rig_chatroom_watch`** (`mcp-server.ts:364`,
|
||||
`:400`).
|
||||
6. Source of truth: daemon-backed SQLite (`chat_messages` table), NOT tmux
|
||||
scrollback.
|
||||
|
||||
@@ -530,14 +242,10 @@ The intentional limits in this layer (numbered as in
|
||||
- Note 5 — transcript search prefers `rg` but falls back to `grep -E`;
|
||||
search quality/performance varies by backend.
|
||||
- Note 6 — chat is rig-scoped only: no cross-rig channels or DMs.
|
||||
- Note 7 — `--verify` on `rig send` reports what the pane shows, not agent
|
||||
acknowledgement. By default it compares the message (whole for a
|
||||
header-carrying send, the first 40 characters for a raw one) in captures
|
||||
before and after the send, leaving out the current input box; with
|
||||
`transport.verify_input_box` on, Claude Code and Codex sends are verified
|
||||
only for a seat proven idle before the paste and on input-box evidence; a
|
||||
busy or unknown seat reads unconfirmed (§3 step 5). When it cannot confirm,
|
||||
it reports `rendered-unconfirmed`, not a failure.
|
||||
- Note 7 — `--verify` on `rig send` checks the pane for the message by
|
||||
comparing snippet counts before and after the send (§3 step 4); when the
|
||||
capture cannot re-confirm the render it reports `rendered-unconfirmed`,
|
||||
not a failure.
|
||||
|
||||
(The full compatibility-notes list lives in
|
||||
`architecture-rules-and-event-system.md`.)
|
||||
@@ -552,8 +260,9 @@ The intentional limits in this layer (numbered as in
|
||||
markers.
|
||||
- `coordination-primitive.md` — cross-host queue routing (the two-sided
|
||||
daemon-forward twin of §3b's one-sided CLI-direct verbs).
|
||||
- `../cli-reference.md` — each verb's registered `--host <id>` option; run
|
||||
`rig <verb> --help` for its cross-host behaviour.
|
||||
- `../cli-reference.md` § Cross-host execution (`--host <id>`) — the per-verb
|
||||
transport table, the `agent@rig@host` parse rules, and the structured
|
||||
failure modes.
|
||||
- Source roots: `packages/daemon/src/domain/{session-transport,transcript-store,transcript-rotation,history-query,ask-service,chat-repository}.ts`,
|
||||
`packages/daemon/src/routes/{transport,transcripts,ask,chat}.ts`,
|
||||
`packages/cli/src/mcp-server.ts`,
|
||||
|
||||
@@ -7,13 +7,13 @@ domains: [engineering-advisor, operating-advisor]
|
||||
applies-when: |
|
||||
Following workflow validation, instantiation, projection, routing, failure
|
||||
recovery, lifecycle graph revisions, or the corresponding CLI/API.
|
||||
last-verified-against-source: e8f0ab340db773392ec8be75b072d1c0f3068a50
|
||||
last-updated: 2026-10-08
|
||||
last-verified-against-source: 254122872cf477511514979a4300b695d77cd1f7
|
||||
last-updated: 2026-10-03
|
||||
---
|
||||
|
||||
# Workflow Runtime — Specs, Packets, and Lifecycle Graphs
|
||||
|
||||
Source snapshot: `e8f0ab340db773392ec8be75b072d1c0f3068a50`. This describes the source at that commit;
|
||||
Source snapshot: `254122872cf477511514979a4300b695d77cd1f7`. This describes the source at that commit;
|
||||
it does not establish the version or behavior of a running daemon.
|
||||
|
||||
A workflow binds a specification to durable queue packets. The daemon
|
||||
@@ -56,12 +56,6 @@ harness grammar. Nonlocal host pins can validate as registered names but
|
||||
This is a workflow-step restriction, not a claim that all queue traffic is
|
||||
local-only.
|
||||
|
||||
A step whose `allowed_exits` can neither finish it nor route it on is refused as
|
||||
`step_cannot_finish` (`workflow-validator.ts:223-236`): its exits leave out `done`, none is
|
||||
mapped in `next_hop.on`, and it allows no `handoff` that routes on. In a dependency graph,
|
||||
allowing `handoff` is enough, because handoff completes a sink. `instantiate` refuses any spec
|
||||
with a validation error.
|
||||
|
||||
`allowed_exits` and `max_hops` affect validation/projection. In contrast,
|
||||
`continuation_required`, `preserve_lineage`, `closure_required`, closure
|
||||
messages, `skill_refs`, and `spawn_budget` produce
|
||||
@@ -69,11 +63,6 @@ messages, `skill_refs`, and `spawn_budget` produce
|
||||
`next_hop.mode: prefer` are rejected by the parser rather than silently
|
||||
accepted. Prerequisite cycles are rejected; a routing cycle requires a
|
||||
`max_hops` declaration and is distinct from a prerequisite cycle.
|
||||
`re_present_after_seconds` compiles to the queue's park timer on an unrouted
|
||||
`waiting` exit, and `re_present_max_seconds` turns it into a repeating
|
||||
reminder with backoff (`workflow-projector.ts:534`–`549`); a step that cannot
|
||||
reach `waiting`, or that maps `waiting` to a branch, fails validation
|
||||
(`waiting_re_presentation_unreachable`).
|
||||
|
||||
`WorkflowSpecCache.readThrough` parses the source file, hashes it, and
|
||||
updates the `(name, version)` cache row. Full `spec_json` preserves fields
|
||||
@@ -103,12 +92,8 @@ single `current_step_id` cannot describe all parallel work.
|
||||
## Instantiation and owner selection
|
||||
|
||||
`WorkflowRuntime.instantiate` resolves a cached spec name or explicit path,
|
||||
validates it, resolves the rig and the entry owner, then creates the instance
|
||||
and its single entry packet (for `steps[0]`) through the transactional
|
||||
event/queue path (`workflow-runtime.ts:433`, `:757`). The entry packet gets a
|
||||
best-effort post-commit nudge with no staged wake intent (`:843`–`845`); its
|
||||
keepalive, armed in the same transaction, and the boot sweep cover a lost
|
||||
entry nudge. An explicit
|
||||
validates it, resolves the rig and entry owners, then creates the instance
|
||||
and entry packets through the transactional event/queue path. An explicit
|
||||
unknown `targetRig` fails; an unknown spec-default rig produces an advisory
|
||||
and falls back to unbound operation. A bound rig without a required declared
|
||||
role is a different error.
|
||||
@@ -119,34 +104,8 @@ harness match when pinned. With no preferred targets and a bound rig, it uses
|
||||
a running managed agent with the declared role and required runtime, ordered
|
||||
by pending-only backlog and then canonical coordinate. Infrastructure and
|
||||
unresolvable/adopted coordinates do not become implicit replacement agents.
|
||||
Explicit owner overrides are reconciled with harness pins. Declared
|
||||
`preferred_targets` are not checked for liveness; validate and instantiate
|
||||
only warn (`role_no_live_preferred_target`) when none of a role's targets has
|
||||
a running session. A structured gate compiles by target kind (`compileGate`):
|
||||
for a human-seat target, the packet goes to the gated step's own owner and is
|
||||
parked `blocked_on` that human seat in the same transaction (summary and
|
||||
`evidence_ref` required), and the instance waits until the park is resolved;
|
||||
for a declared role, an ordinary packet goes to that handler role's seat
|
||||
(`workflow-projector.ts:1659`–`1778`).
|
||||
|
||||
A `preferred_targets` entry may end in `@{rig}`, for example `watcher@{rig}`.
|
||||
When the instance is bound to a rig (`--rig`, or the spec's `target.rig`
|
||||
default), the trailing `{rig}` becomes that rig, so one reusable spec addresses
|
||||
that rig's member, including a `builtin:terminal` member. Only a trailing
|
||||
`@{rig}` is the form: braces in the member part or a partial rig name
|
||||
(`ops-{rig}@rig-a`, `ops-watcher@prefix-{rig}`) stay literal. Literal
|
||||
`member@rig` entries are unchanged. With no bound rig the entry stays literal
|
||||
and is handled like any other destination, at the step that selects it: a
|
||||
selected `member@{rig}` is refused as an unknown destination rig
|
||||
(`unknown_destination_rig`), and `rig workflow validate` reports such an
|
||||
exception target as `unregistered`. A `{rig}` in a role that is never selected,
|
||||
or in a preferred target that is not selected, does not stop an instantiate.
|
||||
The cached spec keeps the literal `{rig}`; the expansion is computed from the
|
||||
instance's stored `bound_rig` each time its spec is read, so later hand-offs,
|
||||
resume and exception routing use the same target
|
||||
(`workflow-rig-placeholder.ts`, `WorkflowSpecCache.getForInstance`). A
|
||||
terminal member cannot act on a nudge, so it must poll its own queue for the
|
||||
packet.
|
||||
Explicit owner overrides are reconciled with harness pins. A structured gate
|
||||
resolves either a human destination or a handler role.
|
||||
|
||||
Instantiation also emits advisories for missing members in otherwise
|
||||
registered target rigs. That member check is advisory and does not imply
|
||||
@@ -159,42 +118,19 @@ packet-to-step identity, allowed exits, and applicable evidence requirements.
|
||||
For a successful advance, queue closure, successor creation, trail entries,
|
||||
frontier/version updates, durable events, and wake intent staging share the
|
||||
transactional notification envelope. Terminal delivery happens after the
|
||||
commit, and the runtime awaits it, so project, route, resume and exception
|
||||
responses return after the delivery attempt; a terminal close without its
|
||||
successor's staged intent rolls back. A committed packet or staged wake is
|
||||
not evidence that its recipient consumed the message.
|
||||
commit. A committed packet or staged wake is not evidence that its recipient
|
||||
consumed the message.
|
||||
|
||||
Each exit closes the packet through the queue's own closure path
|
||||
(`updateWithinTransaction`, hot-potato rules intact): `handoff` records
|
||||
`handed-off` with `handed_off_to` the next owner; `waiting` records `blocked`
|
||||
with `blocked_on` the supplied blocker, or `external-gate` when none is given;
|
||||
`done` records `done` with `no-follow-on`; and `failed` records `done` with
|
||||
`denied` and the result note as target (`workflow-projector.ts:1571`–`1631`).
|
||||
A dependency-graph handoff that fans out to more than one successor, or to
|
||||
none, closes the packet `done` with `no-follow-on`.
|
||||
|
||||
Both executors absorb an identical waiting replay by matching the stored
|
||||
The serial path absorbs an identical waiting replay by matching the stored
|
||||
closure intent; changed wait data is a new decision. A consumed terminal
|
||||
packet is no longer on the frontier and is refused. On the serial path a
|
||||
routed close moves the frontier to the new packet and leaves the instance
|
||||
`active`, or `waiting` when the target step is gated; an unrouted `waiting`
|
||||
keeps the closed packet on the frontier so the keepalive can find its owner;
|
||||
`failed` sets `failed`, and `done` with nothing left sets `completed`. A
|
||||
dependency graph is `waiting` while every frontier packet is blocked, and
|
||||
`failed` when the frontier empties with an unresolved occurrence.
|
||||
`max_hops` constrains routing relative to the current drive's baseline: a
|
||||
route that would exceed it becomes a `failed` exit with a `max_hops_exceeded`
|
||||
note and evidence, the packet closes and no successor is created
|
||||
(`workflow-projector.ts:419`–`443`); resume establishes a new bounded drive
|
||||
rather than erasing history.
|
||||
packet is no longer on the frontier and is refused. `max_hops` constrains
|
||||
routing relative to the current drive's baseline; resume establishes a new
|
||||
bounded drive rather than erasing history.
|
||||
|
||||
Presence of `depends_on` selects `projectDependencyGraph`. It uses durable
|
||||
packet bindings to advance eligible successors and record per-occurrence
|
||||
failures without treating an unrelated live branch as completed. A step's
|
||||
completion counts only while it is later, in trail append order, than its
|
||||
prerequisites' latest completions, so a prerequisite re-run through a routed
|
||||
exit sends its dependents round again (`workflow-projector.ts:1004`–`1019`).
|
||||
Inspection reports unknown bindings rather than inventing a step from trail order.
|
||||
failures without treating an unrelated live branch as completed. Inspection
|
||||
reports unknown bindings rather than inventing a step from trail order.
|
||||
|
||||
The injected [`createWorkflowFrontierPredicate`](../../../packages/daemon/src/domain/workflow-frontier-guard.ts)
|
||||
lets the queue refuse ordinary terminal closure of live workflow packets.
|
||||
@@ -208,8 +144,8 @@ to import the workflow domain to evaluate that predicate.
|
||||
| Operation | Meaning |
|
||||
|---|---|
|
||||
| `route` | Replace a current packet's owner while retaining the step. This is not step advancement. Multiple frontier packets require an explicit packet selection. |
|
||||
| `resume` | Redrive failed work to a newly resolved owner, recording the optional `--decision` text. A serial instance must be `failed` (`instance_not_failed`). Resume re-resolves the owner rather than copying it, re-bases `hops_baseline`, increments `resume_count`, and closes that occurrence's open exception items. Dependency failures use occurrence identity; multiple unresolved failures require selection. Identical occurrence/decision replay returns the recorded redrive, while changed decision bytes conflict. |
|
||||
| `abort` | Explicitly stop unfinished work with an actor and reason: cancels every frontier packet, records a `failed` trail row per packet, sets `aborted`, and emits `workflow.failed` with reason `aborted: <reason>`. Refused only for `completed` or `aborted` instances. |
|
||||
| `resume` | Redrive failed work with a recorded decision and newly resolved owner. Dependency failures use occurrence identity; multiple unresolved failures require selection. Identical occurrence/decision replay returns the recorded redrive, while changed decision bytes conflict. |
|
||||
| `abort` | Explicitly stop unfinished work with an actor and reason. |
|
||||
| `continue` | Read-only inspection of instance, trail, guidance, reconciliation, frontier, failures, unknowns, and boundary obligations. It does not mechanically advance a step. |
|
||||
|
||||
## Deadlines and exceptions
|
||||
@@ -221,21 +157,6 @@ claim time is absent). Pending work uses creation time plus **4 hours**.
|
||||
Blocked waits are not overdue under this evaluator. This is a diagnostic,
|
||||
not a substitute for packet existence or binding checks.
|
||||
|
||||
Instantiate and every routed projection arm a `workflow-keepalive` watchdog
|
||||
job in the same transaction (one per live packet for dependency graphs, one
|
||||
per instance for serial specs), evaluated every 15 minutes and quiet until the
|
||||
step is overdue (`workflow-keepalive-arming.ts:38`). At each daemon start the
|
||||
boot sweep re-arms keepalives for live instances, re-nudges pending frontier
|
||||
packets that were never nudged, and surfaces overdue instances
|
||||
(`workflow-boot-sweep.ts`). Neither path advances a step.
|
||||
|
||||
There are three exception classes: `unmapped_failed`, `stuck_overdue` and
|
||||
`human_gate_trip` (`workflow-exception.ts:34`–`38`). An unrouted `failed`
|
||||
exit creates one urgent `workflow-exception` queue item in the same
|
||||
transaction, with evidence `rig workflow trace <instance>` and a body naming
|
||||
the `rig workflow resume` command; a human gate's own parked packet carries the
|
||||
`human_gate_trip` identity, so no second item is created.
|
||||
|
||||
[`resolveExceptionRoute`](../../../packages/daemon/src/domain/workflow-exception-router.ts)
|
||||
selects per-class configuration, then workflow default, host default, and
|
||||
finally orchestrator-first behavior. An unresolved orchestrator route falls
|
||||
@@ -244,12 +165,8 @@ routed. Agent-routed exceptions use the ordinary workflow tier; human-routed
|
||||
ones use `human-gate`.
|
||||
|
||||
[`workflow-human-destination.ts`](../../../packages/daemon/src/domain/workflow-human-destination.ts)
|
||||
handles human selection: the registered human named by
|
||||
`workspace.operator_seat_name`, or the only registered human when it is unset;
|
||||
any other case fails with `workflow_human_destination_unavailable` (409). The
|
||||
host default dial is the setting `workflow.exception_routing`
|
||||
(`orchestrator` or `human_only`), read per exception. A valid agent route need
|
||||
not have a human fallback configured. If fallback is needed, missing/ambiguous selection is an explicit
|
||||
handles human selection. A valid agent route need not have a human fallback
|
||||
configured. If fallback is needed, missing/ambiguous selection is an explicit
|
||||
error, not an invented destination. Failure admission is transactional;
|
||||
overdue detection is handled by boot/keepalive paths. Runtime reconciliation
|
||||
closes recovered overdue occurrences against their own packets, preserving
|
||||
@@ -267,19 +184,6 @@ themselves launch work.
|
||||
`inspectGraph`, `reviseGraph`, and `recoverGraphOperation` in
|
||||
[`workflow-reconciliation.ts`](../../../packages/daemon/src/domain/workflow-reconciliation.ts)
|
||||
separate inspection from explicit graph revision and operation recovery.
|
||||
Inspection reports `current`, `source-only`, `compatible`, `incompatible`,
|
||||
`unavailable` or `unbound`. Only a live, manifest-bound instance whose specs
|
||||
are explicit dependency graphs without `next_hop.on` can be revised; a
|
||||
revision may add steps and change unstarted ones, but may not remove steps,
|
||||
touch a step with completed, live or failed work, drop a required obligation
|
||||
or its order, change workflow-wide fields other than `exception_routing`, or
|
||||
add an unstarted step with no outstanding prerequisite. A changed
|
||||
`exception_routing` applies to future occurrences only; existing obligations
|
||||
keep their owners. Applying needs the inspected version and digest, an
|
||||
operation key, an actor and a reason; the receipt is kept in the instance's
|
||||
`revisionHistory`, and replaying the same key with a different decision is
|
||||
refused with `lifecycle_revision_conflict` (`workflow-reconciliation.ts:12`,
|
||||
`:113`–`223`).
|
||||
`guidance` reads context and current packet information without interpreting
|
||||
an agent's substantive judgment.
|
||||
|
||||
@@ -305,10 +209,8 @@ are mounted under `/api/workflow`:
|
||||
| `POST` | `/:instance_id/route`, `/:instance_id/resume`, `/:instance_id/abort`, `/:instance_id/continue`, `/:instance_id/revision` |
|
||||
| `GET` | `/sse`, `/watch` (same live event stream handler) |
|
||||
|
||||
The stream carries the 8 `workflow.*` events (`instantiated`, `step_closed`,
|
||||
`next_qitem_projected`, `completed`, `failed`, `resumed`,
|
||||
`routing_table_changed`, `revised`); it is not a general queue stream or a
|
||||
stored-history replay. Route error mapping distinguishes missing
|
||||
The stream filters the named workflow events; it is not a general queue
|
||||
stream or a stored-history replay. Route error mapping distinguishes missing
|
||||
records, authoring errors, state/version conflicts, and internal failures.
|
||||
See the source mapping before assigning a meaning to a nonzero CLI result.
|
||||
|
||||
|
||||
@@ -12,8 +12,8 @@ applies-when: |
|
||||
Project UI.
|
||||
siblings: [content-surfaces.md, daemon-core.md, ../ui/project-and-for-you.md]
|
||||
prerequisite-reads: [../README.md, daemon-core.md]
|
||||
last-verified-against-source: e8f0ab340db773392ec8be75b072d1c0f3068a50
|
||||
last-updated: 2026-10-08
|
||||
last-verified-against-source: b6d37bfadcc189be8fd61e35abfc09676437bf48
|
||||
last-updated: 2026-10-03
|
||||
---
|
||||
|
||||
# Workspace Primitive — RigSpec.workspace, Migrations 038/039, Missions/Projects/Slices
|
||||
@@ -26,7 +26,7 @@ through `whoami` / node-inventory and gate per-item repo scope. Alongside it, a
|
||||
the Project UI's mission / slice surfaces.
|
||||
|
||||
> Paths are relative to `packages/daemon/src/` unless prefixed `packages/` or
|
||||
> `docs/`. Verified against source at main `e8f0ab340db773392ec8be75b072d1c0f3068a50`. Each count sits beside
|
||||
> `docs/`. Verified against source at main `b6d37bfadcc189be8fd61e35abfc09676437bf48`. Each count sits beside
|
||||
> the command that produces it; run the commands from the repository root.
|
||||
> The files / markdown / progress / steering surfaces are in the sibling
|
||||
> `content-surfaces.md`.
|
||||
@@ -60,13 +60,13 @@ Workspace initialization no longer seeds a getting-started mission (§3).
|
||||
`RigSpec.workspace` is an **optional** typed block. Rigs without it stay valid;
|
||||
`whoami` / node-inventory return a null workspace block in that case.
|
||||
|
||||
> Source: `domain/types.ts:1163–1170` (`WorkspaceSpec`), `:1153–1159`
|
||||
> (`WorkspaceRepoSpec`), `:1188` (`RigSpec.workspace?`).
|
||||
> Source: `domain/types.ts:1160–1167` (`WorkspaceSpec`), `:1150–1156`
|
||||
> (`WorkspaceRepoSpec`), `:1183` (`RigSpec.workspace?`).
|
||||
|
||||
| Field | Shape | Notes |
|
||||
|---|---|---|
|
||||
| `workspaceRoot` | string | Verbatim from spec |
|
||||
| `repos[]` | `{ name, path, kind }[]` | `path` resolved to absolute at parse time (`domain/rigspec-schema.ts:361–363`); authors may declare it relative to `workspaceRoot` in YAML |
|
||||
| `repos[]` | `{ name, path, kind }[]` | `path` resolved to absolute at parse time (`domain/rigspec-schema.ts:350–352`); authors may declare it relative to `workspaceRoot` in YAML |
|
||||
| `defaultRepo?` | string | active repo when no env override / cwd match |
|
||||
| `knowledgeRoot?` | string | treated as `kind=knowledge` when surfaced |
|
||||
|
||||
@@ -74,15 +74,7 @@ Workspace initialization no longer seeds a getting-started mission (§3).
|
||||
(`grep '^export const WORKSPACE_KINDS' packages/daemon/src/domain/types.ts | grep -o '"[a-z]*"' | wc -l`):
|
||||
`user`, `project`, `knowledge`, `lab`, `delivery`.
|
||||
|
||||
> Source: `domain/types.ts:1149–1150` (`WORKSPACE_KINDS` / `WorkspaceKind`).
|
||||
|
||||
In YAML the block is spelled `workspace: { workspace_root, repos: [{ name,
|
||||
path, kind }], default_repo?, knowledge_root? }`. Validation requires a
|
||||
non-empty `workspace_root`, a `repos` array whose names are unique and whose
|
||||
`kind` is one of the five kinds, a `default_repo` that names a declared repo,
|
||||
and a non-empty `knowledge_root` when present.
|
||||
|
||||
> Source: `domain/rigspec-schema.ts:288–347`.
|
||||
> Source: `domain/types.ts:1146–1147` (`WORKSPACE_KINDS` / `WorkspaceKind`).
|
||||
|
||||
### 1.1 Persistence — migration 038 + RigRepository
|
||||
|
||||
@@ -101,9 +93,9 @@ are **defensive no-ops** when the column is absent (`hasRigColumn` probe) —
|
||||
older test fixtures that bypass the canonical migration list don't have the
|
||||
column; the setter's contract is "best-effort persistence".
|
||||
|
||||
> Source: `domain/rig-repository.ts:184–189` (setter; column probe `:185`),
|
||||
> `:192–202` (getter; probe `:193`; parse failure → null `:199–201`);
|
||||
> `hasRigColumn` `:347`.
|
||||
> Source: `domain/rig-repository.ts:174–179` (setter; column probe `:175`),
|
||||
> `:182–192` (getter; probe `:183`; parse failure → null `:189–191`);
|
||||
> `hasRigColumn` `:324`.
|
||||
|
||||
The block is written only when declared. **3** call sites write it
|
||||
(`git grep -n 'setRigWorkspace(' -- packages/daemon/src | grep -v 'rig-repository.ts' | wc -l`):
|
||||
@@ -113,10 +105,10 @@ workspace-only import route `POST /api/rigs/import/workspace`
|
||||
(`rig import --workspace-only --target-rig <rigId>`), which validates and
|
||||
normalizes the block and writes it only when it differs from the stored one.
|
||||
|
||||
> Source: `domain/rigspec-instantiator.ts:619` (`materializeValidatedSpec`),
|
||||
> `:655–657`; `:1260` (`instantiateOnce`), `:1349–1351`;
|
||||
> `routes/rigspec.ts:134–173` (validation `:158`; compare-and-write
|
||||
> `:168–170`), mounted `server.ts:734`; CLI
|
||||
> Source: `domain/rigspec-instantiator.ts:618` (`materializeValidatedSpec`),
|
||||
> `:654–656`; `:1259` (`instantiateOnce`), `:1346–1348`;
|
||||
> `routes/rigspec.ts:133–171` (validation `:156`; compare-and-write
|
||||
> `:166–168`), mounted `server.ts:735`; CLI
|
||||
> `packages/cli/src/commands/import.ts:82`.
|
||||
|
||||
### 1.2 Runtime resolution — workspace-resolver
|
||||
@@ -127,11 +119,7 @@ normalizes the block and writes it only when it differs from the stored one.
|
||||
unknown repo name is honored, because operators set `OPENRIG_TARGET_REPO`
|
||||
consciously (the comment at `workspace-resolver.ts:35–36`); otherwise `defaultRepo` is used **only
|
||||
if it names a declared repo**. `knowledgeKind` is `"knowledge"` when
|
||||
`knowledgeRoot` is declared, else `null`. The resolver accepts `cwd` but does
|
||||
not use it (`workspace-resolver.ts:31`), so `rig whoami` reports the env
|
||||
override or the declared `defaultRepo`, never the repo containing the seat's
|
||||
working directory; node-inventory's per-node `activeRepo` (below) is the one
|
||||
that follows cwd.
|
||||
`knowledgeRoot` is declared, else `null`.
|
||||
|
||||
> Source: `domain/workspace/workspace-resolver.ts:26–52` (resolver; null
|
||||
> without a spec `:32`; env override `:39–40`; declared `defaultRepo`
|
||||
@@ -146,7 +134,7 @@ that follows cwd.
|
||||
> Source: `domain/whoami-service.ts:333–338` (`getRigWorkspace` +
|
||||
> `resolveWorkspaceContext`, env fallback `:337`); `whoami` returns
|
||||
> `workspace` in its payload `:350`; `routes/whoami.ts:29`;
|
||||
> `packages/cli/src/commands/whoami.ts:281–282`.
|
||||
> `packages/cli/src/commands/whoami.ts:261–262`.
|
||||
|
||||
`resolveNodeWorkspace({ spec, cwd })` (consumed by `node-inventory`) derives a
|
||||
per-node `NodeWorkspaceInfo` by picking the **longest declared repo path that
|
||||
@@ -159,10 +147,10 @@ so `/foo/bar` does not match `/foo/bar-other`. Node-inventory reads
|
||||
|
||||
> Source: `domain/workspace/workspace-resolver.ts:57–95` (longest match
|
||||
> `:67–73`; knowledge fallback `:77–79`; default-repo fallback `:82–88`),
|
||||
> `isInside` `:97–103`; `domain/node-inventory.ts:705`
|
||||
> (`workspace: resolveNodeWorkspace(...)`), readers `:790–799`
|
||||
> (`readRigWorkspaceJson`) and `:716–726` (`readAllRigWorkspaceJson`,
|
||||
> batched); `NodeWorkspaceInfo` `domain/types.ts:795–799`.
|
||||
> `isInside` `:97–103`; `domain/node-inventory.ts:626`
|
||||
> (`workspace: resolveNodeWorkspace(...)`), readers `:711–720`
|
||||
> (`readRigWorkspaceJson`) and `:637–647` (`readAllRigWorkspaceJson`,
|
||||
> batched); `NodeWorkspaceInfo` `domain/types.ts:792–796`.
|
||||
|
||||
### 1.3 Per-item repo scope — migration 039 + queue validation
|
||||
|
||||
@@ -171,14 +159,12 @@ Migration **039** adds `target_repo TEXT` to `queue_items` plus
|
||||
per-item typed repo scope when an operator passes `--target-repo <name>`; it
|
||||
is NULL when the item is unambiguous against the rig's `default_repo` or no
|
||||
workspace is declared, and Mission Control views surface the field for
|
||||
cross-rig handoff clarity. At M nothing in the daemon's Mission Control code
|
||||
reads it; the UI shows it as "Target repo" in the queue item viewer's full
|
||||
detail (`packages/ui/src/components/drawer-viewers/QueueItemViewer.tsx:157`).
|
||||
cross-rig handoff clarity.
|
||||
|
||||
> Source: `db/migrations/039_queue_target_repo.ts:16–22`
|
||||
> (`ALTER TABLE queue_items ADD COLUMN target_repo TEXT` at `:19`;
|
||||
> `CREATE INDEX … idx_queue_items_target_repo` at `039_queue_target_repo.ts:20`); doc comment
|
||||
> `:3–15`; CLI flag `packages/cli/src/commands/queue.ts:461`.
|
||||
> `:3–15`; CLI flag `packages/cli/src/commands/queue.ts:431`.
|
||||
|
||||
`validateTargetRepo` checks an explicit `targetRepo` against the **source
|
||||
rig's** `RigSpec.workspace.repos[]`: it parses the source session with
|
||||
@@ -189,33 +175,21 @@ is not a canonical `<member>@<rig>` name, the rig is unknown, or no workspace
|
||||
is declared — validation only bites when a workspace actively declares repos.
|
||||
|
||||
It runs on **3** routes (`grep -c 'validateTargetRepo(c,' packages/daemon/src/routes/queue.ts`):
|
||||
`POST /create` (through the shared `createInputRefusal` check, which also
|
||||
requires `destinationSession` and `body`), `POST /:qitemId/handoff` and
|
||||
`POST /create`, `POST /:qitemId/handoff` and
|
||||
`POST /:qitemId/handoff-and-complete`, each before any cross-host forwarding,
|
||||
because the source rig's workspace lives on the source host.
|
||||
`createInputRefusal` also runs in the in-process create that finishes a
|
||||
handoff an earlier self-forward started (a `hostId` equal to this daemon's own
|
||||
id). A handoff that inherits the source row's `targetRepo` without an override
|
||||
is not re-validated.
|
||||
|
||||
`--target-repo` is accepted by `rig queue create`, `handoff` and
|
||||
`handoff-and-complete`. `rig queue list --target-repo <name>`
|
||||
(`GET /api/queue/list?targetRepo=`) filters rows by exact `target_repo`
|
||||
match; the filter is skipped when the column is absent.
|
||||
because the source rig's workspace lives on the source host. A handoff that
|
||||
inherits the source row's `targetRepo` without an override is not
|
||||
re-validated.
|
||||
|
||||
> Source: `routes/queue.ts:96–123` (fail-open guards `:102`, `:106`, `:109`,
|
||||
> `:112`; `getRigWorkspace` `:111`; `unknown_target_repo` + `knownRepos`
|
||||
> `:114–120`); `createInputRefusal` `:128–141` (call `:136`), used by
|
||||
> `/create` `:490` and the self-forward create `:436`; handoff calls `:679`,
|
||||
> `:758` in handlers `:650`, `:732` (`/create` handler `:450`); ordering note
|
||||
> `:482–489`; inherited value `:676–677`, `domain/queue-repository.ts:1691`,
|
||||
> `:1868`; list filter `routes/queue.ts:906`,
|
||||
> `domain/queue-repository.ts:3236–3238`, CLI
|
||||
> `packages/cli/src/commands/queue.ts:1143`; mounted `server.ts:784`.
|
||||
> `:114–120`); calls `:452`, `:635`, `:708` in handlers `:402`, `:606`,
|
||||
> `:682`; ordering note `:444–450`; inherited value `:632–633`; mounted
|
||||
> `server.ts:785`.
|
||||
|
||||
## 2. Workspace HTTP route — frontmatter validator and doctor
|
||||
|
||||
`workspaceRoutes()` (mounted `server.ts:785` as `/api/workspace`) exposes **2**
|
||||
`workspaceRoutes()` (mounted `server.ts:786` as `/api/workspace`) exposes **2**
|
||||
endpoints (`grep -c -E 'app\.(get|post)\(' packages/daemon/src/routes/workspace.ts`).
|
||||
**Neither mutates the filesystem.**
|
||||
|
||||
@@ -227,20 +201,12 @@ endpoints (`grep -c -E 'app\.(get|post)\(' packages/daemon/src/routes/workspace.
|
||||
- `POST /api/workspace/doctor` — runs `runWorkspaceDoctor` against the
|
||||
daemon's resolved `workspace.root`, or a `workspaceRoot` given in the body,
|
||||
and returns its report. 503 `settings_unavailable` without a settings
|
||||
store; 500 `doctor_failed` when it throws. The doctor runs **8** checks in
|
||||
order (root reachable, missions folder, file allowlist, daemon points at
|
||||
this workspace, config changed since start, optional slice docs, mission
|
||||
notes, SDLC convention sections), each `ok`/`warn`/`fail` with a fix hint,
|
||||
plus a summary count. With a body `workspaceRoot`, missions are checked at
|
||||
`<workspaceRoot>/missions`. (The orchestrator's own doc comment still says
|
||||
7.)
|
||||
store; 500 `doctor_failed` when it throws.
|
||||
|
||||
> Source: `routes/workspace.ts:16` (no mutation), `:37–74` (validate;
|
||||
> root-required `:46–48`; kind check `:50–58`; 500 `:72`), `:85–160`
|
||||
> (doctor; 503 `:87`; missions root from the body `:115–118`;
|
||||
> `runWorkspaceDoctor` call `:145`; 500 `:158`);
|
||||
> `domain/workspace/workspace-doctor.ts:643–685` (the 8 checks; comment
|
||||
> `:636`); mounted `server.ts:785`.
|
||||
> (doctor; 503 `:87`; `runWorkspaceDoctor` call `:145`; 500 `:158`);
|
||||
> `domain/workspace/workspace-doctor.ts:643`; mounted `server.ts:786`.
|
||||
|
||||
`validateWorkspaceFrontmatter()` walks a root, parses each `.md` file's YAML
|
||||
frontmatter (delimited `---` on the first line), and emits a structured gap
|
||||
@@ -265,7 +231,7 @@ hard cap `maxFiles` default 10000.
|
||||
CLI surface: `rig workspace validate [root]` and `rig workspace doctor`.
|
||||
|
||||
> Source: `packages/cli/src/commands/workspace.ts:86` (`validate`), `:146`
|
||||
> (`doctor`); `docs/as-built/cli-reference.md#workspace`.
|
||||
> (`doctor`); `docs/as-built/cli-reference.md:593–594`.
|
||||
|
||||
## 3. Default project-workspace scaffold
|
||||
|
||||
@@ -307,53 +273,15 @@ are not emitted.
|
||||
> checked before writes `:117–135`; write-if-missing `:140`);
|
||||
> `domain/instance-initialization.ts:39` (`ensureOpenRigInstance`; default
|
||||
> workspace root `:44`; dry-run plan `:83`; apply `:103`); default
|
||||
> `workspace.root` `domain/user-settings/settings-store.ts:28–31`; daemon
|
||||
> `index.ts:250`; CLI `packages/cli/src/daemon-lifecycle.ts:658`;
|
||||
> `workspace.root` `domain/user-settings/settings-store.ts:27–30`; daemon
|
||||
> `index.ts:242`; CLI `packages/cli/src/daemon-lifecycle.ts:658`;
|
||||
> `packages/cli/src/commands/config-init-workspace.ts:10` (import), `:13`
|
||||
> (re-export), `:28` (`--force`), `:56–67` (`runInitWorkspace`);
|
||||
> `routes/config.ts:56–65`, mounted `server.ts:772`; `rig scope`
|
||||
> `routes/config.ts:56–65`, mounted `server.ts:773`; `rig scope`
|
||||
> `packages/cli/src/commands/scope.ts:2071`; parity
|
||||
> `packages/daemon/test/getting-started-narrative-parity.test.ts:15–25`,
|
||||
> retired entries `:43–57`.
|
||||
|
||||
### 3.1 The workspace catalog and project selection
|
||||
|
||||
`workspace.yaml` at `workspace.catalog_path` (default
|
||||
`<workspace.root>/workspace.yaml`) lists `projects[]`, each with a string `id`,
|
||||
a `root` relative to the catalog file, and an optional `rigs` list naming the
|
||||
rigs that work in that project. With one entry, that project is selected
|
||||
implicitly. With several, `rig context work-install` and the daemon's
|
||||
operating posture use an explicit `--project` first, then the calling rig's
|
||||
`rigs` association, then the unique deepest project root that contains the
|
||||
working directory, then the only entry no rig claims; otherwise they stop with
|
||||
`project_required` and the candidate ids. Duplicate ids are refused
|
||||
(`project_identity_ambiguous`), and a root that does not exist gives
|
||||
`project_root_missing`.
|
||||
|
||||
Installing a bundle that carries a project places it at
|
||||
`<workspace.projects_root>/<id>/` (default `<workspace.root>/projects`) and
|
||||
records it in the catalog before the rig's seats launch: a new entry is
|
||||
appended as text, or the rig is added to an entry's `rigs` list. Existing
|
||||
catalog bytes are never rewritten; a conflict writes nothing for that part and
|
||||
reports the exact line to add.
|
||||
|
||||
Daemon reads accept `?project=<id>`, resolved by `selectedProject()`: the id
|
||||
must be in the catalog (or be the single uncatalogued workspace project, whose
|
||||
id comes from its `project.yaml` or defaults to `workspace`), the project's
|
||||
`project.yaml` `missions.root` must stay inside the project, and a supplied
|
||||
`?projectRoot` must still match. Every failure answers 409 with its code.
|
||||
`GET /api/scopes/projects` lists the projects with their missions roots.
|
||||
|
||||
> Source: `domain/workspace/project-catalog.ts:16–25` (`readProjectCatalog`),
|
||||
> `:26–37` (`selectCatalogProject`), `:66–79` (`inferCatalogProject`, steps
|
||||
> 3–5); `domain/user-settings/settings-store.ts:489–490`
|
||||
> (`workspace.projects_root`, `workspace.catalog_path`);
|
||||
> `domain/workspace/project-registration.ts:6–29` (rules), `:36–37`
|
||||
> (projects root), `:181` (`registerBundleProject`), called from
|
||||
> `domain/bundle-content-routing.ts:184`; `domain/workspace/project-read.ts:44–60`
|
||||
> (`projectEntry`), `:61–69` (`listProjects`), `:70–81` (`selectedProject`),
|
||||
> `:83–84` (409); `routes/scopes.ts:34`, mounted `server.ts:820`.
|
||||
|
||||
## 4. File-backed missions / slices tree
|
||||
|
||||
### 4.1 SliceIndexer — 0.3.0
|
||||
@@ -370,35 +298,15 @@ type: read-only projection over existing tables (`queue_items`,
|
||||
`queue_transitions`, `mission_control_actions`) + dogfood-evidence
|
||||
directories. Listing, detail and mission-status caches are time-bounded (60 s
|
||||
default); `invalidate()` drops all three plus the queue-membership index.
|
||||
Besides the TTL, every unscoped list or detail read first compares a basis
|
||||
built from each mission's `mission.yaml` text and `slices/` listing and drops
|
||||
the caches when it changes. When the indexer is ready, startup also watches the
|
||||
workspace and invalidates the indexer when proof sources change, emitting
|
||||
`proof.sources_changed`.
|
||||
`isReady()` is true when any configured slice root exists on disk. A set
|
||||
`OPENRIG_SLICES_ROOT` still takes precedence over `workspace.slices_root`.
|
||||
|
||||
Slices are keyed by folder name alone: when two missions (or two roots) hold a
|
||||
slice with the same name, only the first one walked is indexed, and
|
||||
`/api/slices/:name` and `/project/slice/$sliceId` address it by that bare
|
||||
name. The project-scoped read (`?project=…&mission=…`, §4.3) is the one path
|
||||
that selects by mission. A slice's `qitemIds` come first from rows tagged
|
||||
`slice:<id>`, then from the legacy match on the rail item or slice name; in a
|
||||
project-scoped indexer only rows tagged `project:<id>` count, so untagged
|
||||
historical rows are not attributed to a selected project.
|
||||
`isReady()` is true when any configured slice root exists on disk.
|
||||
|
||||
> Source: `domain/slices/slice-indexer.ts:2–15` (contract + no new state),
|
||||
> `:238` (TTL), `:297–299` (`isReady`), `:331–336` (`invalidate`),
|
||||
> `:457–472` (`reconcileComposition`), `:476–521` (`readSliceLocations`;
|
||||
> first name wins `:478–483`; nested-vs-flat `:495–517`), `:61–88`
|
||||
> (`SliceRecord`: `missionId` `:65`, `slicePath` `:67`, `qitemIds` `:77`,
|
||||
> `proofPacket` `:81`), `:90–111` (`SliceListEntry`, which carries
|
||||
> `qitemCount` / `hasProofPacket` instead), `:865–875` and `:936–946` (queue
|
||||
> membership; project filter `:870`, `:942`); `domain/workspace/project-catalog.ts:132–138`
|
||||
> (`belongsToProject`); startup `startup.ts:1705`, `:1718` (`OPENRIG_SLICES_ROOT`
|
||||
> first), `:1725–1730`, `:1743–1748`, proof-source watch `:1762–1765`
|
||||
> (`domain/proof/source-watch.ts:16`); default
|
||||
> `domain/user-settings/settings-store.ts:486`.
|
||||
> `:238` (TTL), `:297–299` (`isReady`), `:331–336` (`invalidate`), `:476–521`
|
||||
> (`readSliceLocations`; nested-vs-flat `:495–517`), `:61–88` (`SliceRecord`:
|
||||
> `missionId` `:65`, `slicePath` `:67`, `qitemIds` `:77`, `proofPacket`
|
||||
> `:81`), `:90–111` (`SliceListEntry`, which carries `qitemCount` /
|
||||
> `hasProofPacket` instead); startup `startup.ts:1668`, `:1675–1680`,
|
||||
> `:1693–1698`; default `domain/user-settings/settings-store.ts:479`.
|
||||
|
||||
### 4.2 SliceDetailProjector — 0.3.0
|
||||
|
||||
@@ -420,12 +328,12 @@ behavior (`workflowBinding`, `specGraph`, `phaseDefinitions` and
|
||||
> v1 enrichment), `:16–20` (v0 phase taxonomy removed), `:64`
|
||||
> (`StoryEvent.phase`), `:177–203` (`SliceDetailPayload`), `:205–213`
|
||||
> (optional `workflowSpecCache`); startup degrade path
|
||||
> `startup.ts:1749–1760` (comment `:1749–1755`;
|
||||
> `workflowSpecCache: workflowRuntime?.specCache` `:1759`).
|
||||
> `startup.ts:1699–1710` (comment `:1699–1705`;
|
||||
> `workflowSpecCache: workflowRuntime?.specCache` `:1709`).
|
||||
|
||||
### 4.3 Slices routes — 0.3.0
|
||||
|
||||
`slicesRoutes()` (mounted `server.ts:803` as `/api/slices`) registers **5**
|
||||
`slicesRoutes()` (mounted `server.ts:804` as `/api/slices`) registers **5**
|
||||
handlers (`grep -c -E 'app\.(get|post)\(' packages/daemon/src/routes/slices.ts`):
|
||||
|
||||
- `GET /` — filter `all|active|done|blocked` (default `all`; anything else is
|
||||
@@ -454,11 +362,11 @@ shadowed.
|
||||
> `:47–53`; refresh `:54–57`; `boundToWorkflow` `:67–93`; readiness +
|
||||
> `missions` sidecar `:99–110`; `/refresh` `:119–124`; proof asset
|
||||
> `:131–154`, cache header `:235`, ranges `:237–266`; doc `:158–173`;
|
||||
> project scope `:180–190`); mounted `server.ts:803`.
|
||||
> project scope `:180–190`); mounted `server.ts:804`.
|
||||
|
||||
### 4.4 Missions route — 0.3.1
|
||||
|
||||
`missionsRoutes()` (mounted `server.ts:814` as `/api/missions`) is the
|
||||
`missionsRoutes()` (mounted `server.ts:815` as `/api/missions`) is the
|
||||
mission scope data layer, with **2** handlers
|
||||
(`grep -c -E 'app\.(get|post)\(' packages/daemon/src/routes/missions.ts`).
|
||||
|
||||
@@ -496,12 +404,12 @@ optimistic localStorage mirror. 404 `mission_not_found` when no slices match;
|
||||
> (`computeMissionTopology`); node-file precedence
|
||||
> `domain/scope/node-file.ts:17`; readiness
|
||||
> `domain/proof/judgments.ts:288–295`; UI mirror
|
||||
> `packages/ui/src/hooks/useCompletedMissions.ts:15`; mounted `server.ts:814`;
|
||||
> `packages/ui/src/hooks/useCompletedMissions.ts:15`; mounted `server.ts:815`;
|
||||
> §0: `routes/missions.ts` absent at `v0.3.0` ⇒ **0.3.1**.
|
||||
|
||||
### 4.5 Projects route — stream classifier — 0.3.0
|
||||
|
||||
`projectsRoutes()` (mounted `server.ts:786` as `/api/projects`) backs the
|
||||
`projectsRoutes()` (mounted `server.ts:787` as `/api/projects`) backs the
|
||||
`rig project` CLI verb — the **stream-item classifier** (lease lifecycle +
|
||||
idempotent classify + operator-verb reclaim + attempt ledger + SSE), NOT the
|
||||
Project *workspace UI* (that is the slices/missions surface above; the naming
|
||||
@@ -509,8 +417,7 @@ overlap is a documented seam). Endpoints:
|
||||
|
||||
- `GET /worker-sources` — requires `?project=<id>`, a workspace catalog
|
||||
project;
|
||||
- `GET /shadow`, `POST /shadow/drain`, `POST /shadow/stop` (the last two take
|
||||
an optional body `{ actor }`);
|
||||
- `GET /shadow`, `POST /shadow/drain`, `POST /shadow/stop`;
|
||||
- `POST /lease/acquire` (optional `evaluateDeadnessFirst` clears stale/dead
|
||||
leases first), `POST /lease/heartbeat`, `POST /reclaim-classifier`;
|
||||
- `POST /project` (idempotent on `stream_item_id`);
|
||||
@@ -522,13 +429,13 @@ overlap is a documented seam). Endpoints:
|
||||
**Route-order discipline:** every literal path is registered BEFORE the bare
|
||||
`/:projectId` catchall, which comes last.
|
||||
|
||||
> Source: `routes/projects.ts:27–375` (handlers; route-order notes `:25`,
|
||||
> `:240`, `:309`, `:322`, `:339–340`, `:366`); worker sources `:98–109`;
|
||||
> shadow `:111–127`; lease / reclaim / project `:129–237`
|
||||
> (`evaluateDeadnessFirst` `:142–144`); attempts and eligible `:239–306`;
|
||||
> lease and list `:308–336`; SSE `:338–364`; `/:projectId` `:366–372`;
|
||||
> Source: `routes/projects.ts:27–373` (handlers; route-order notes `:25`,
|
||||
> `:238`, `:307`, `:320`, `:337–338`, `:364`); worker sources `:98–109`;
|
||||
> shadow `:111–125`; lease / reclaim / project `:135–235`
|
||||
> (`evaluateDeadnessFirst` `:140–142`); attempts and eligible `:242–304`;
|
||||
> lease and list `:308–334`; SSE `:339–362`; `/:projectId` `:365–370`;
|
||||
> error-code → HTTP mapping `:58–95`; CLI
|
||||
> `packages/cli/src/commands/project.ts:46`; mounted `server.ts:786`.
|
||||
> `packages/cli/src/commands/project.ts:46`; mounted `server.ts:787`.
|
||||
|
||||
## 5. UI route reality — source-verified at routes.tsx
|
||||
|
||||
@@ -554,7 +461,7 @@ mission / project / slice destinations as they exist:
|
||||
> Source: `packages/ui/src/routes.tsx:136–152` (project routes), `:248–252`
|
||||
> (`/files`), `:484–530` (redirect block, which also redirects `/context` to
|
||||
> `/topology`), `:539–597` (route tree); `/api/mission-control` mounted
|
||||
> `packages/daemon/src/server.ts:790–793`.
|
||||
> `packages/daemon/src/server.ts:791–794`.
|
||||
|
||||
Net: the daemon `/api/missions` + `/api/slices` + `/api/projects` routes are
|
||||
real. The **operator-facing UI** consumes the missions and slices routes
|
||||
@@ -571,12 +478,12 @@ through the `/project*` destinations; it does not call `/api/projects`
|
||||
|
||||
- **Optional + valid-without:** rigs without a `workspace` block stay valid;
|
||||
whoami / node-inventory return null and queue target-repo validation fails
|
||||
open (`workspace-resolver.ts:32`, `:62`; `rig-repository.ts:185`, `:193`;
|
||||
open (`workspace-resolver.ts:32`, `:62`; `rig-repository.ts:175`, `:183`;
|
||||
`routes/queue.ts:112`).
|
||||
- **Defensive column access:** `RigRepository` probes for `workspace_json`
|
||||
(`rig-repository.ts:185`, `:193`), node-inventory's own reads fall back to
|
||||
null on error (`node-inventory.ts:724`, `:796–798`), and the queue
|
||||
repository detects `target_repo` (`queue-repository.ts:758`), so partial
|
||||
(`rig-repository.ts:175`, `:183`), node-inventory's own reads fall back to
|
||||
null on error (`node-inventory.ts:645`, `:717–719`), and the queue
|
||||
repository detects `target_repo` (`queue-repository.ts:752`), so partial
|
||||
test fixtures don't crash. Migrations 038/039 ship separately so a fixture
|
||||
can apply only the half it needs (`038_workspace_primitive.ts:12–14`).
|
||||
- **Read-only projection, no new state for the tree:** SliceIndexer /
|
||||
|
||||
+13
-28
@@ -9,8 +9,8 @@ applies-when: |
|
||||
what broke there before, then go and read the code.
|
||||
siblings: [README.md, test-layers.md]
|
||||
prerequisite-reads: [../../ARCHITECTURE.md]
|
||||
last-verified-against-source: e8f0ab340db773392ec8be75b072d1c0f3068a50
|
||||
last-updated: 2026-10-08
|
||||
last-verified-against-source: 1347d825
|
||||
last-updated: 2026-10-01
|
||||
---
|
||||
|
||||
# Arteries: where a small change has a large effect
|
||||
@@ -22,7 +22,7 @@ last-updated: 2026-10-08
|
||||
behaviour and risk that are not listed here exist, and some of it is riskier than anything below.
|
||||
- **It is incomplete by construction.** A pull request is not safe because its files are missing
|
||||
from this list.
|
||||
- **It may be stale.** It was checked against commit `e8f0ab34`. Files and dependencies move. If
|
||||
- **It may be stale.** It was checked against commit `1347d825`. Files and dependencies move. If
|
||||
this page and the code disagree, the code is right; fix the page.
|
||||
- **Use it to change altitude, then go to the ground:** read the code, run the commands, check the
|
||||
behaviour. When you are lost, go and look rather than leaning on this page.
|
||||
@@ -34,14 +34,14 @@ area.
|
||||
|
||||
| Artery | Key files | What depends on it | Past regressions and lessons |
|
||||
|---|---|---|---|
|
||||
| **Message delivery to seats** | `daemon/src/domain/session-transport.ts`, `daemon/src/domain/seat-delivery-guard.ts`, `daemon/src/adapters/tmux.ts` | Every `rig send`, queue wake, nudge, watchdog wake and handoff | #150 (the fix for #142) stopped typing into a bare shell. It then refused managed Codex seats (fixed by #171 before release) and every Claude seat launched with an explicit permission mode, which shipped in 0.6.2 as #197 (fixed by #220). The delivery guard's rule that a name must resolve to exactly one target, added in #109 (0.6.0), was involved in #141 (fixed by #151), the delivery half of #174 (fixed by #181) and #188 (fixed by #189). Since #310/#327, a Claude seat whose runtime can't be observed still receives ordinary messages with a warning; only a plain idle shell or the wrong recipient is refused. |
|
||||
| **Launch, relaunch, resume** | `daemon/src/adapters/claude-code-adapter.ts`, `daemon/src/domain/claude-managed-launch.ts`, `daemon/src/adapters/codex-runtime-adapter.ts`, `daemon/src/domain/codex-daemon-support.ts`, `daemon/src/adapters/pi-runtime-adapter.ts`, `daemon/src/domain/seat-launch-environment.ts`, `daemon/src/domain/native-resume-probe.ts`, `daemon/src/domain/startup-orchestrator.ts` | Every seat start, restore and permission mode, plus the non-interruptive, `permission_policy`, effort, kernel operational-authority and team permission-default settings that each launch and resume command carries | Always setting `CLAUDE_CONFIG_DIR` gave explicit-mode Claude seats a blank config (#154). #225 fixed which config home is selected, and #565 writes the onboarding and trust bootstrap into that home. Codex seats launch with `--no-daemon` only when `codex --help` shows support (#69, #77); when support is unknown, OpenRig refuses to launch, so a failing or slow `codex --help` blocks the seat. The readiness window defaults to 30 seconds and can time out under load (#182); since #643 it is configurable as `runtime.readiness_timeout_seconds` (env `OPENRIG_RUNTIME_READINESS_TIMEOUT_SECONDS`, 1–600). A git worktree's `.git` file broke the Codex sandbox (#121; see #126). #618 moved non-managed Claude, Codex and Pi launches behind the seat launch environment, and #628, #638 and #666 followed within days. Pi launch and resume carry `--thinking` from the seat's resolved effort (OMP does not). |
|
||||
| **Message delivery to seats** | `daemon/src/domain/session-transport.ts`, `daemon/src/domain/seat-delivery-guard.ts`, `daemon/src/adapters/tmux.ts` | Every `rig send`, queue wake, nudge, watchdog wake and handoff | #150 (the fix for #142) stopped typing into a bare shell. It then refused managed Codex seats (fixed by #171 before release) and every Claude seat launched with an explicit permission mode, which shipped in 0.6.2 as #197 (fixed by #220). The delivery guard's rule that a name must resolve to exactly one target, added in #109 (0.6.0), was involved in #141 (fixed by #151), the delivery half of #174 (fixed by #181) and #188 (fixed by #189). |
|
||||
| **Launch, relaunch, resume** | `daemon/src/adapters/claude-code-adapter.ts`, `daemon/src/domain/claude-managed-launch.ts`, `daemon/src/adapters/codex-runtime-adapter.ts`, `daemon/src/domain/codex-daemon-support.ts`, `daemon/src/domain/native-resume-probe.ts`, `daemon/src/domain/startup-orchestrator.ts` | Every seat start, restore and permission mode | Always setting `CLAUDE_CONFIG_DIR` gave explicit-mode Claude seats a blank config (#154; #225 fixes its config-selection part). Codex seats launch with `--no-daemon` only when `codex --help` shows support (#69, #77); when support is unknown, OpenRig refuses to launch, so a failing or slow `codex --help` blocks the seat. The fixed 30-second readiness window times out under load (#182, open). A git worktree's `.git` file broke the Codex sandbox (#121; see #126). |
|
||||
| **Queue claim, pickup, wakes** | `daemon/src/domain/queue-repository.ts`, `daemon/src/domain/queue-pickup.ts`, `daemon/src/domain/queue-wake-ladder.ts`, `daemon/src/routes/require-sender-identity.ts`, `cli/src/client.ts` | All durable work between seats | After a slow `/healthz`, the CLI host-qualified a local sender and claims failed (#131, fixed by #135). Done-and-closed items read as stalled forever (#164, fixed by #176). |
|
||||
| **Rig identity: same names, archived and deleted rigs** | `daemon/src/domain/rig-repository.ts`, `daemon/src/domain/rig-lifecycle-service.ts`, `daemon/src/domain/rig-teardown.ts`, `daemon/src/domain/seat-handover-service.ts`, `daemon/src/domain/running-name-guard.ts` | Seat resolution, `rig remove`, restore, importing a rig from YAML | Archived rigs still matched seat references, and `rig remove` killed another rig's live seat with the same name (#174, fixed by #181). Replacing stopped same-name rig generations on YAML import followed in #196. |
|
||||
| **Projection of skills and files** | `daemon/src/domain/rigspec-instantiator.ts`, `daemon/src/domain/projection-planner.ts`, and each runtime adapter's `project()` (Claude Code, Codex, Pi, OMP, stub) | What every agent is given at start | Codex seats skipped skills that a Claude sibling had already projected (#159, fixed by #162). File-shaped entries failed with ENOTDIR (fixed by #185). |
|
||||
| **Native process observation** | `daemon/src/domain/native-process-lineage.ts` (parses `ps -Ao pid,ppid,pgid,tpgid,ucomm,lstart,command`) | Liveness, identity verdicts, delivery checks | Processes whose command name contains a space were dropped (#134, fixed by #82). Non-English locales broke the date parsing (fixed by #239, which runs `ps` with `LC_ALL=C`). #220 also changed this file to recognise managed Claude seats behind launch wrappers. Claude identity proof (wrappers, launcher shims, conversation rotation, effort, version-named binaries, launch `--settings`) changed ten more times after 0.6.3. |
|
||||
| **Schema and migrations** | `daemon/src/db/migrations/`, `daemon/src/db/all-migrations.ts`, `daemon/src/db/migrate.ts` | Every install, and every upgrade of a long-lived install | Parallel pull requests pick the same next number: #112 adds `086_rig_kernel_variant` while `main` already has `086_classification_fields_and_attempts`, and #155 and #195 landed as 090 and 091. `migrate.ts` applies by migration name in name order, so a duplicate number is not skipped, but its order relative to the other migration changes; 093 is unused at `e8f0ab34`. A long-lived install upgrading across several releases applies many migrations in one start, against real data. |
|
||||
| **Restore and recovery** | `daemon/src/domain/restore-orchestrator.ts`, `daemon/src/adapters/{claude,codex,pi,omp}-resume.ts`, `daemon/src/domain/reconciler.ts`, `daemon/src/domain/restore-check-service.ts`, `daemon/src/domain/startup-orchestrator.ts`, `daemon/src/adapters/tmux.ts` | Reboots, power loss, daemon restarts | Detached seats kept stale tmux pane ids after a reboot (#141, fixed by #151 in `tmux.ts`). `restore-check` read queue files and Claude hooks from a fixed shared-docs path (#130); #139 made it use the configured root, and #328 replaced the queue-file check with a probe of the daemon's queue store and checks the selected Claude hooks. After a fresh relaunch, a stale Codex restore attention flag never clears (#116). Full-restore recovery of OMP seats is open (#41). |
|
||||
| **Projection of skills and files** | `daemon/src/domain/rigspec-instantiator.ts`, `daemon/src/domain/projection-planner.ts`, and each runtime adapter's `project()` | What every agent is given at start | Codex seats skipped skills that a Claude sibling had already projected (#159, fixed by #162). File-shaped entries failed with ENOTDIR (fixed by #185). |
|
||||
| **Native process observation** | `daemon/src/domain/native-process-lineage.ts` (parses `ps -Ao pid,ppid,pgid,tpgid,ucomm,lstart,command`) | Liveness, identity verdicts, delivery checks | Processes whose command name contains a space were dropped (#134, fixed by #82). Non-English locales broke the date parsing (fixed by #239, which runs `ps` with `LC_ALL=C`). #220 also changed this file to recognise managed Claude seats behind launch wrappers. |
|
||||
| **Schema and migrations** | `daemon/src/db/migrations/`, `daemon/src/db/all-migrations.ts`, `daemon/src/db/migrate.ts` | Every install, and every upgrade of a long-lived install | Parallel pull requests pick the same next number: open #112 adds `086_rig_kernel_variant` while `main` already has `086_classification_fields_and_attempts`, and open #155 and #195 take 090 and 091. A long-lived install upgrading across several releases applies many migrations in one start, against real data. |
|
||||
| **Restore and recovery** | `daemon/src/domain/reconciler.ts`, `daemon/src/domain/restore-check-service.ts`, `daemon/src/domain/startup-orchestrator.ts`, `daemon/src/adapters/tmux.ts` | Reboots, power loss, daemon restarts | Detached seats kept stale tmux pane ids after a reboot (#141, fixed by #151 in `tmux.ts`). `restore-check` ignores the configured shared-docs root (#130, open). After a fresh relaunch, a stale Codex restore attention flag never clears (#116, open). |
|
||||
|
||||
## How reviews use this page
|
||||
|
||||
@@ -65,7 +65,7 @@ change to an artery meets a real end-to-end check before it merges, not only a r
|
||||
|
||||
### Scenario coverage today
|
||||
|
||||
At commit `e8f0ab34`. For why the stub cannot reach some of these yet, see "What a stub can and
|
||||
At commit `1347d825`. For why the stub cannot reach some of these yet, see "What a stub can and
|
||||
cannot prove" in [test-layers.md](test-layers.md).
|
||||
|
||||
- **Queue durability across a daemon restart: covered.** CI runs
|
||||
@@ -76,11 +76,6 @@ cannot prove" in [test-layers.md](test-layers.md).
|
||||
- **Delivery (the #197 class): not covered.** The stub runtime has no input behaviour, so it cannot
|
||||
exercise delivery to a managed wrapper; `send-verify-means-rendered.yaml` is not admitted to CI
|
||||
for that reason (`packages/test-system/ci/README.md`).
|
||||
- **Addressing and rendered delivery: partial.** CI runs the transcript and capture stub scenarios
|
||||
in passing form, and the capture scenario catches a seat resolved by member-name prefix.
|
||||
`send-renders-in-addressed-pane.yaml` and `down-stops-every-seat.yaml` run with the local runner
|
||||
only. `stub-cli-journeys.integration.test.ts` checks that a verified send lands in the addressed
|
||||
pane and not its sibling. None of these proves a seat consumed a message.
|
||||
- **Restore (the #141 class): not covered.** The scenario runner does not bind the `restore` verb
|
||||
yet; it fails with `UnboundActionError`.
|
||||
- **Rig identity (the #174 class): not covered.** No library scenario sets up a same-name archived
|
||||
@@ -93,12 +88,9 @@ cannot prove" in [test-layers.md](test-layers.md).
|
||||
- **Migrations: unit guards only** (`migration-fixture-parity.test.ts`,
|
||||
`startup-migrations-mirror.test.ts`). Every scenario starts from an empty database, so upgrading
|
||||
an existing database is not covered.
|
||||
- **Launch:** every scenario's `up` goes through the real `rig up`, instantiation and startup
|
||||
orchestration with stub seats. The stub adapter types its runner directly; Claude Code, Codex
|
||||
and Pi seats launch through the seat launch environment (`seat-launch-environment.ts`), which
|
||||
no scenario reaches. Real Codex launch and handover run only in two opt-in daemon tests
|
||||
(`OPENRIG_E2E_REAL_CODEX=1`, which needs tmux, `codex` and a Codex login). The CI containers
|
||||
have no provider CLIs or credentials.
|
||||
- **Launch:** every scenario's `up` launches stub seats through the real launch path. Native Claude
|
||||
Code and Codex launches are not exercised; the CI containers have no provider CLIs or
|
||||
credentials.
|
||||
|
||||
## Regression log
|
||||
|
||||
@@ -109,10 +101,3 @@ When a regression reaches a release, add one line: date, issue, artery, and whic
|
||||
explicit-mode Claude seat; the project's own day-to-day seats use the default launch path.
|
||||
- 2026-09-29/30, #141, #174, #188 (after 0.6.0), delivery and rig identity: reviews of #109 did not
|
||||
see the downstream effect of the exactly-one-target rule.
|
||||
|
||||
- 2026-10-19, #1483, managed compaction: a helper-only command-composition check did not bind the submitted command to the precompact effect. `managed-compaction-effect.test.ts` now drives the real enforcer command into a version-bound stub input model and checks the shipped precompact marker; its 851-character pasted-command control lacks that effect despite a successful submit receipt. `rig compact` rejects stub runtimes, so this is an adapter/helper check, not an installed CLI or native compaction proof. The model uses the recorded Claude Code 2.1.282 distinction; other versions and actual context compaction remain unverified here.
|
||||
- 2026-10-19, #484, refocus orientation: script tests supplied basis strings without composing parked typed queue state through `queue whoami` and the hook. `refocus-parked-baton.yaml` plus the active-baton contrast now assert the shipped hook's own emitted context; installed-scenario runs healthy/seeded/healthy; its scratch trace-child fault moves the parked row from held work into the work candidates as current work, and the hook's emitted context must then fail with that row's slice shown as `WORK FROM QUEUE EVIDENCE`. This proves the composed diagnostic effect, not native hook scheduling or an agent reading and acting on it. With the work packet's bounds and per-runtime default, the parked scenario runs with the packet on and asserts the row as held work. `refocus-parked-baton-packet-off.yaml` keeps the labelled fallback as the packet-off control.
|
||||
- 2026-10-23, F1 (0.7.0 candidate `2fec7382`), launch (a fresh Codex kernel): a fresh Codex kernel stopped at Codex's hook review. Caught at the cut, before publication, by native first-user and daily runs. Missed by the stub layer, which has no real Codex binary. Fixed in #1824.
|
||||
- 2026-10-24, B6 (0.7.1 candidate `7badb557`), launch and resume (Codex hook trust): after an upgrade from 0.7.0, a Codex seat stopped at "Hooks need review: 6", because Codex 0.164 asks to approve a plugin's whole content again. Caught at the cut, before publication, by a native upgrade run with a real Codex. Missed by source tests and stub scenarios (a stub can't see the real Codex binary) and by the installed-upgrade check (no real Codex). Fixed in #1948. Scenario owed: a cheap real-agent Codex upgrade with approval renewal.
|
||||
- 2026-10-24, pane-only attention (#1876 on the 0.7.1 candidate), native observation: a Codex seat waiting at a prompt that only its pane showed read as working, with no attention signal. Caught at the cut, before publication, by real work on a test machine. Missed by fixtures that all carried hook signals. Fixed in #1946. Scenario owed: a stub pane showing a selector with no hook event must read as needing attention.
|
||||
- 2026-10-25, #1955, delivery (send readiness): approval-prompt text that a working Claude seat quoted in its own output read as a waiting prompt, so sends and queue wakes to that seat were refused. This one was present since 0.7.0, so it did reach a release; it was found during the 0.7.1 cut by real work on a test machine. Missed by classifier fixtures that had no working pane quoting prompt text. Fixed in #1955 for 0.7.2.
|
||||
+70
-228
@@ -9,23 +9,23 @@ applies-when: |
|
||||
the source that implements a command. Use command help for invocation details.
|
||||
siblings: [README.md, codemap.md]
|
||||
prerequisite-reads: [../reference/help.md]
|
||||
last-verified-against-source: 34fdcb80543903b054a982cc48bb302ae6871682
|
||||
last-updated: 2026-10-26
|
||||
last-verified-against-source: a350c59b5a5fb37ee4a21b1026b595068b603df1
|
||||
last-updated: 2026-10-05
|
||||
---
|
||||
|
||||
# CLI Reference — Registered Commands and Options
|
||||
|
||||
Verified against source commit `34fdcb80543903b054a982cc48bb302ae6871682`.
|
||||
Verified against source commit `a350c59b5a5fb37ee4a21b1026b595068b603df1`.
|
||||
The inventory below comes from the actual Commander tree returned by
|
||||
[`createProgram()`](../../packages/cli/src/index.ts), not a grep of command
|
||||
strings or an installed CLI from a different commit.
|
||||
|
||||
There are **90 top-level registrations**, **410 registered command objects**
|
||||
There are **87 top-level registrations**, **352 registered command objects**
|
||||
below `rig` (including groups and the hidden `restore apply` command), and
|
||||
**1,304 explicitly registered option objects**, including the root version
|
||||
**1,072 explicitly registered option objects**, including the root version
|
||||
option. Aliases do not add command objects; short/long spellings of one
|
||||
option do not add option objects. Commander-generated help is additional.
|
||||
These are counts for that source snapshot, not a claim about a deployed release.
|
||||
These are source counts, not a claim about a deployed release.
|
||||
|
||||
## Reading this reference
|
||||
|
||||
@@ -50,14 +50,11 @@ route remain the source for result/error shape and side effects.
|
||||
|
||||
## Entry points and practical routes
|
||||
|
||||
Bare `rig` opens the TUI, the status dashboard rather than an agent conversation, when both
|
||||
stdin and stdout are terminals. Arguments,
|
||||
Bare `rig` opens the TUI when both stdin and stdout are terminals. Arguments,
|
||||
pipes, and redirected streams follow normal CLI parsing.
|
||||
[`runFrontDoor` and `openMissionControl`](../../packages/cli/src/front-door.ts)
|
||||
own the entry behavior; [`tuiCommand`](../../packages/cli/src/commands/tui.ts)
|
||||
owns explicit TUI options; `rig terminal open saved:kernel --window` opens a terminal view
|
||||
of the OpenRig TUI, the operator and the advisor (in a new tab or window, or the current
|
||||
Herdr session), and `rig tui --shared` is the dashboard-only fallback when that view cannot open. A daemon-down transport result can still open the
|
||||
owns explicit TUI options. A daemon-down transport result can still open the
|
||||
recovery cockpit; it is not automatically a reason to exit before rendering.
|
||||
|
||||
| Need | Start here |
|
||||
@@ -143,7 +140,7 @@ Root: `rig`; declared option: `-V, --version`.
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig daemon` | — | — |
|
||||
| `rig daemon start` | — | `--port <port>`<br>`--host <host>`<br>`--db <path>`<br>`--allow-db-conflict`<br>`--no-kernel`<br>`--wait-for-kernel`<br>`--wait-for-kernel-ms <ms>` |
|
||||
| `rig daemon start` | — | `--port <port>`<br>`--host <host>`<br>`--db <path>`<br>`--no-kernel`<br>`--wait-for-kernel`<br>`--wait-for-kernel-ms <ms>` |
|
||||
| `rig daemon stop` | — | — |
|
||||
| `rig daemon status` | — | — |
|
||||
| `rig daemon logs` | — | `--follow` |
|
||||
@@ -152,29 +149,22 @@ Root: `rig`; declared option: `-V, --version`.
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig status` | — | `--json` |
|
||||
|
||||
`rig status --json` prints one object: `daemon`, `kernel`, `workspaceRoot`, `rigs` and `cmux`.
|
||||
`daemon.reachable` has three values. `true`: the daemon answered its health probe (it may still
|
||||
report `healthy: false`, and may carry a `reason` and `eventLoop` evidence). `false`: positively down
|
||||
(`state` is `stopped` or `stale`). `null`: not confirmed (`state` is `unverified`, or `running`
|
||||
with `reason: "unresponsive"` because `/healthz` did not answer). When `reachable` is not `true`,
|
||||
the sections that were not read are `null`.
|
||||
| `rig status` | — | — |
|
||||
|
||||
### snapshot
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig snapshot <rig>` | — | `--intended-seats <ids>` |
|
||||
| `rig snapshot list <rig>` | — | — |
|
||||
| `rig snapshot <rigId>` | — | `--intended-seats <ids>` |
|
||||
| `rig snapshot list <rigId>` | — | — |
|
||||
|
||||
### restore
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig restore` | — | — |
|
||||
| `rig restore apply <snapshotId>` (hidden) | — | `--rig <rig>` **required** |
|
||||
| `rig restore status <attemptId>` | — | `--rig <rig>` **required**<br>`--json` |
|
||||
| `rig restore apply <snapshotId>` (hidden) | — | `--rig <rigId>` **required** |
|
||||
| `rig restore status <attemptId>` | — | `--rig <rigId>` **required**<br>`--json` |
|
||||
|
||||
### crash-cart
|
||||
|
||||
@@ -188,44 +178,11 @@ the sections that were not read are `null`.
|
||||
|---|---|---|
|
||||
| `rig gateway` | — | — |
|
||||
| `rig gateway human` | — | — |
|
||||
| `rig gateway human add <entityId>` | — | `--display-name <name>` **required**<br>`--binding <kind:connectorRef:secretsRef:role[:handle=<id>]>` **required** (repeatable)<br>`--delivery-class <A\|B\|C\|D>` **required**<br>`--away`<br>`--replace`<br>`--reason <reason>`<br>`--actor <actor>`<br>`--organization <id>`<br>`--group <id>` (repeatable)<br>`--policy <text>`<br>`--policy-file <path>`<br>`--default` |
|
||||
| `rig gateway human add <entityId>` | — | `--display-name <name>` **required**<br>`--binding <kind:connectorRef:secretsRef:role[:handle=<id>]>` **required** (repeatable)<br>`--delivery-class <A\|B\|C\|D>` **required**<br>`--away`<br>`--replace`<br>`--reason <reason>`<br>`--actor <actor>` |
|
||||
| `rig gateway human list` | — | `--json` |
|
||||
| `rig gateway human quiet` | — | — |
|
||||
| `rig gateway human quiet set <entityId>` | — | `--daily <window>`<br>`--until <time>`<br>`--tz <zone>`<br>`--actor <actor>`<br>`--json` |
|
||||
| `rig gateway human quiet end <entityId>` | — | `--actor <actor>`<br>`--json` |
|
||||
| `rig gateway human quiet clear <entityId>` | — | `--actor <actor>`<br>`--json` |
|
||||
| `rig gateway human quiet show <entityId>` | — | `--json` |
|
||||
| `rig gateway human mode` | — | — |
|
||||
| `rig gateway human mode save <entityId> <name>` | — | `--availability <value>`<br>`--expected-back <when>`<br>`--decision-room <words>`<br>`--exclude <item...>`<br>`--quiet <rule>`<br>`--tz <zone>`<br>`--account <where>`<br>`--actor <actor>`<br>`--json` |
|
||||
| `rig gateway human mode saved <entityId> [name]` | — | `--json` |
|
||||
| `rig gateway human mode apply <entityId> <name>` | — | `--until <time>`<br>`--tz <zone>`<br>`--actor <actor>`<br>`--json` |
|
||||
| `rig gateway human mode current <entityId>` | — | `--json` |
|
||||
| `rig gateway human mode end <entityId>` | — | `--scheduled`<br>`--actor <actor>`<br>`--json` |
|
||||
| `rig gateway human mode account <entityId> <applicationId>` | — | `--json` |
|
||||
| `rig gateway human mode room <entityId>` | — | `--json` |
|
||||
| `rig gateway human mode decide <qitemId>` | — | `--application <id>` **required**<br>`--choose <question=option...>`<br>`--reason <why>` **required**<br>`--reversible`<br>`--irreversible`<br>`--actor <actor>`<br>`--json` |
|
||||
| `rig gateway human mode decisions <entityId> <applicationId>` | — | `--json` |
|
||||
| `rig gateway human show <entityId>` | — | `--json` |
|
||||
| `rig gateway human set <entityId> <field> <value>` | — | `--reason <reason>`<br>`--actor <actor>` |
|
||||
| `rig gateway human remove <entityId>` | — | `--force` |
|
||||
| `rig gateway channel` | — | — |
|
||||
| `rig gateway channel add <id>` | — | `--display-name <name>` **required**<br>`--binding <slack:connectorRef:secretsRef:channelId>` **required**<br>`--organization <id>`<br>`--group <id>` (repeatable)<br>`--policy <text>`<br>`--policy-file <path>`<br>`--replace` |
|
||||
| `rig gateway channel remove <id>` | — | `--force` |
|
||||
| `rig gateway org` | — | — |
|
||||
| `rig gateway org set <id>` | — | `--name <name>`<br>`--policy <text>`<br>`--policy-file <path>` |
|
||||
| `rig gateway group` | — | — |
|
||||
| `rig gateway group set <id>` | — | `--organization <id>`<br>`--name <name>`<br>`--policy <text>`<br>`--policy-file <path>` |
|
||||
| `rig gateway participants` | — | `--organization <id>`<br>`--json` |
|
||||
| `rig gateway default [entityId]` | — | `--clear` |
|
||||
|
||||
- Several people may be registered. Organizations, groups, readable policy, shared channels and the default person are
|
||||
kept in `$OPENRIG_HOME/gateway/participants.yaml`, never in a person's fragment, so an older daemon still loads every
|
||||
person after a rollback. `human set <entityId> organization|groups|policy <value>` writes there (`unset` clears;
|
||||
`@<path>` reads a policy file). `participants --json` carries each participant's `kind`, `address`, `organization`,
|
||||
`groups`, `default` and `policy` (a list of `{ source, text }`, organization first), plus `default`, `organizations`,
|
||||
`groups`, `warnings` and `participantFile`. `default` with no argument prints the current default and its source
|
||||
(`chosen` or `only-person`), or `null` with the reason. See `docs/reference/gateway-participants.md`.
|
||||
- `human set <entityId> slack-subscription <value>` — sets the person's Slack subscription: `every-ask` (the default) posts every ask to them to Slack; `urgent-only` posts only asks created with `--alert`, and other asks wait on Steering and the TUI; `unset` removes the authored subscription so the default applies. `human show` prints the value with its origin, `authored` or `default` (`slack-subscription: every-ask (default)`); `--json` carries it as `record.slackSubscription` `{ value, source }`.
|
||||
|
||||
### parked
|
||||
|
||||
@@ -237,7 +194,7 @@ the sections that were not read are `null`.
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig export <rig>` | — | `-o, --output <path>` |
|
||||
| `rig export <rigId>` | — | `-o, --output <path>` |
|
||||
|
||||
### import
|
||||
|
||||
@@ -311,7 +268,7 @@ the sections that were not read are `null`.
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig bundle` | — | — |
|
||||
| `rig bundle create <spec>` | — | `-o, --output <path>` **required**<br>`--name <name>`<br>`--bundle-version <ver>`<br>`--include-login-files`<br>`--include-packages <refs...>`<br>`--rig-root <root>`<br>`--context-pack <dir>` (repeatable)<br>`--project-dir <dir>`<br>`--preset <name>`<br>`--seat <member=runtime>` (repeatable)<br>`--notes <text>`<br>`--min-daemon-version <ver>`<br>`--min-cli-version <ver>`<br>`--allow-drift`<br>`--json` |
|
||||
| `rig bundle create <spec>` | — | `-o, --output <path>` **required**<br>`--name <name>`<br>`--bundle-version <ver>`<br>`--include-packages <refs...>`<br>`--rig-root <root>`<br>`--context-pack <dir>` (repeatable)<br>`--project-dir <dir>`<br>`--preset <name>`<br>`--seat <member=runtime>` (repeatable)<br>`--notes <text>`<br>`--min-daemon-version <ver>`<br>`--min-cli-version <ver>`<br>`--allow-drift`<br>`--json` |
|
||||
| `rig bundle configurations <spec>` | — | `--json` |
|
||||
| `rig bundle inspect <path>` | — | `--preset <name>`<br>`--seat <member=runtime>` (repeatable)<br>`--json` |
|
||||
| `rig bundle install <path>` | — | `--preset <name>`<br>`--seat <member=runtime>` (repeatable)<br>`--non-interruptive`<br>`--no-non-interruptive`<br>`--plan`<br>`--yes`<br>`--target <root>`<br>`--cwd <path>`<br>`--skip-version-check`<br>`--force`<br>`--json` |
|
||||
@@ -322,25 +279,25 @@ the sections that were not read are `null`.
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig up <source>` | — | `--non-interruptive`<br>`--no-non-interruptive`<br>`--plan`<br>`--yes`<br>`--cwd <path>`<br>`--env <KEY=VALUE>` (repeatable)<br>`--name <rig>`<br>`--target <root>`<br>`--preset <name>`<br>`--seat <member=runtime>` (repeatable)<br>`--existing`<br>`--fresh <seats...>`<br>`--json`<br>`--host <id>` |
|
||||
| `rig up <source>` | — | `--non-interruptive`<br>`--no-non-interruptive`<br>`--plan`<br>`--yes`<br>`--cwd <path>`<br>`--target <root>`<br>`--preset <name>`<br>`--seat <member=runtime>` (repeatable)<br>`--existing`<br>`--fresh <seats...>`<br>`--json`<br>`--host <id>` |
|
||||
|
||||
### down
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig down <rig>` | — | `--delete`<br>`--force`<br>`--snapshot`<br>`--yes`<br>`--json`<br>`--host <id>` |
|
||||
| `rig down <rig>` | — | `--delete`<br>`--force`<br>`--snapshot`<br>`--json`<br>`--host <id>` |
|
||||
|
||||
### archive
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig archive <rig>` | — | `--force`<br>`--json` |
|
||||
| `rig archive <rigId>` | — | `--force`<br>`--json` |
|
||||
|
||||
### unarchive
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig unarchive <rig>` | — | `--json` |
|
||||
| `rig unarchive <rigId>` | — | `--json` |
|
||||
|
||||
### host
|
||||
|
||||
@@ -354,31 +311,12 @@ the sections that were not read are `null`.
|
||||
| `rig host list` | `ls` | `--json` |
|
||||
| `rig host doctor <id>` | — | `--posture <profile>`<br>`--public-addr <ip>`<br>`--json` |
|
||||
|
||||
Registration makes a host visible in topology; remote FEED attention remains opt-in.
|
||||
The human-readable success output of `host add` and `host pair` now includes the FEED
|
||||
next step alongside the existing `host doctor` suggestion. For an HTTP entry named
|
||||
`laptop`, run this on the local instance to include its attention items:
|
||||
|
||||
```sh
|
||||
rig config set feed.subscriptions.laptop.enabled true
|
||||
```
|
||||
|
||||
The key uses the registry id, including any dots, and defaults to `false`. Registration
|
||||
does not change that setting. SSH entries instead explain that FEED needs an HTTP entry;
|
||||
ids reserved by feed settings (such as `progress`) get a different-id suggestion rather
|
||||
than an invalid command. `--json` keeps its single JSON result without these hints.
|
||||
The host CLI tests execute the advertised command against an isolated config and cover
|
||||
registration, reserved names and JSON output; pairing responses are simulated, so they
|
||||
do not establish connectivity to a live peer.
|
||||
|
||||
### ps
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig ps` | — | `--json`<br>`--no-cleanup`<br>`--resources`<br>`--nodes`<br>`--full`<br>`--verbose`<br>`--limit <n>`<br>`--fields <list>`<br>`--summary`<br>`--filter <key=value>`<br>`--active`<br>`--running`<br>`-A, --all-rigs`<br>`--rig <name>`<br>`--session <name>`<br>`--include-archived`<br>`--host <id>`<br>`--all-hosts`<br>`--hosts <ids>` |
|
||||
|
||||
- `--nodes --json` — each seat carries the daemon's served `needsAttention` flag; the CLI doesn't re-derive it, and it is absent when an older daemon doesn't serve it. `arbitratedNeedsInput` and `needsInputEvidence` (`{ rung, observedAt }` or null) come with `--full`, or by name through `--fields`.
|
||||
|
||||
### roster
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
@@ -393,20 +331,7 @@ do not establish connectivity to a live peer.
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig mcp` | — | — |
|
||||
| `rig mcp serve` | — | `--port <port>`<br>`--http`<br>`--bind <host:port>`<br>`--grant-service <url>`<br>`--grant-service-header-file <path>`<br>`--oauth-resource <url>`<br>`--oauth-issuer <url>` |
|
||||
| `rig mcp token` | — | — |
|
||||
| `rig mcp token add <name>` | — | `--seat <session>` **required**<br>`--rig <name...>`<br>`--root <name...>`<br>`--workspace`<br>`--owner` |
|
||||
| `rig mcp token list` | — | `--json` |
|
||||
| `rig mcp token revoke <name>` | — | — |
|
||||
|
||||
### acp
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig acp` | — | — |
|
||||
| `rig acp run <qitemId> <agent...>` | — | `--cwd <dir>`<br>`--permissions-to <session>`<br>`--load-session <id>`<br>`--poll-seconds <n>` |
|
||||
| `rig acp cancel <runId>` | — | — |
|
||||
| `rig acp stop <runId> [stopCommand...]` | — | — |
|
||||
| `rig mcp serve` | — | `--port <port>` |
|
||||
|
||||
### agent
|
||||
|
||||
@@ -435,7 +360,7 @@ do not establish connectivity to a live peer.
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig send [session] [text]` | — | `--to <sessions>` (repeatable)<br>`--pod <name>`<br>`--rig <name>`<br>`--verify`<br>`--force`<br>`--wait-for-idle <seconds>`<br>`--raw`<br>`--dangerously-interact`<br>`--type-without-checking`<br>`--reason <text>`<br>`--urgent`<br>`--host <id>`<br>`--from <session>`<br>`--context <ref>`<br>`--json` |
|
||||
| `rig send [session] [text]` | — | `--to <sessions>` (repeatable)<br>`--pod <name>`<br>`--rig <name>`<br>`--verify`<br>`--force`<br>`--wait-for-idle <seconds>`<br>`--raw`<br>`--dangerously-interact`<br>`--reason <text>`<br>`--host <id>`<br>`--from <session>`<br>`--context <ref>`<br>`--json` |
|
||||
|
||||
### stream
|
||||
|
||||
@@ -447,29 +372,24 @@ do not establish connectivity to a live peer.
|
||||
| `rig stream watch` | — | `--json` |
|
||||
| `rig stream show <streamItemId>` | — | `--json` |
|
||||
| `rig stream archive <streamItemId>` | — | `--json` |
|
||||
| `rig stream subscribe <readerSession>` | — | `--tags <tags>`<br>`--type <hintType>`<br>`--actor <session>`<br>`--json` |
|
||||
| `rig stream unsubscribe <readerSession>` | — | `--json` |
|
||||
| `rig stream subscriptions` | — | `--json` |
|
||||
| `rig stream read` | — | `--limit <n>`<br>`--reader <session>`<br>`--json` |
|
||||
| `rig stream act <streamItemId>` | — | `--work <qitemId>`<br>`--decline <reason>`<br>`--duplicate <id>`<br>`--reader <session>`<br>`--json` |
|
||||
|
||||
### queue
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig queue` | — | — |
|
||||
| `rig queue create` | — | `--source <session>`<br>`--destination <session>` **required**<br>`--body <text>`<br>`--body-file <path>`<br>`--body-context <ref>`<br>`--mission <id>`<br>`--slice <id>`<br>`--gate <role>`<br>`--priority <priority>`<br>`--tier <tier>`<br>`--tags <tags>`<br>`--expires-at <iso>`<br>`--id <qitemId>`<br>`--target-repo <name>`<br>`--summary <text>`<br>`--human-intent <intent>`<br>`--alert`<br>`--human-detail-file <path>`<br>`--reply-to <qitemId>`<br>`--human-questions-file <path>`<br>`--evidence-ref <path>`<br>`--host <id>`<br>`--no-nudge`<br>`--verify`<br>`--full`<br>`--json` |
|
||||
| `rig queue claim <qitemId>` | — | `--destination <session>`<br>`--full`<br>`--json` |
|
||||
| `rig queue unclaim <qitemId>` | — | `--destination <session>`<br>`--reason <text>`<br>`--full`<br>`--json` |
|
||||
| `rig queue update <qitemId>` | — | `--actor <session>`<br>`--state <state>`<br>`--reopen`<br>`--closure-reason <reason>`<br>`--closure-target <target>`<br>`--resolution <text>`<br>`--blocked-on <blocker>`<br>`--wake-watchdog <jobId>`<br>`--wake-after <duration>`<br>`--summary <text>`<br>`--evidence-ref <path>`<br>`--note <text>`<br>`--full`<br>`--json` |
|
||||
| `rig queue block <qitemId>` | — | `--on <blocker>` **required**<br>`--actor <session>`<br>`--summary <text>`<br>`--evidence-ref <path>`<br>`--note <text>`<br>`--continuation <text>`<br>`--wake-watchdog <jobId>`<br>`--wake-after <duration>`<br>`--full`<br>`--json` |
|
||||
| `rig queue create` | — | `--source <session>`<br>`--destination <session>` **required**<br>`--body <text>`<br>`--body-file <path>`<br>`--body-context <ref>`<br>`--mission <id>`<br>`--slice <id>`<br>`--gate <role>`<br>`--priority <priority>`<br>`--tier <tier>`<br>`--tags <tags>`<br>`--expires-at <iso>`<br>`--id <qitemId>`<br>`--target-repo <name>`<br>`--summary <text>`<br>`--human-intent <intent>`<br>`--human-detail-file <path>`<br>`--reply-to <qitemId>`<br>`--human-questions-file <path>`<br>`--evidence-ref <path>`<br>`--host <id>`<br>`--no-nudge`<br>`--verify`<br>`--json` |
|
||||
| `rig queue claim <qitemId>` | — | `--destination <session>`<br>`--json` |
|
||||
| `rig queue unclaim <qitemId>` | — | `--destination <session>`<br>`--reason <text>`<br>`--json` |
|
||||
| `rig queue update <qitemId>` | — | `--actor <session>`<br>`--state <state>`<br>`--reopen`<br>`--closure-reason <reason>`<br>`--closure-target <target>`<br>`--blocked-on <blocker>`<br>`--wake-watchdog <jobId>`<br>`--wake-after <duration>`<br>`--summary <text>`<br>`--evidence-ref <path>`<br>`--note <text>`<br>`--json` |
|
||||
| `rig queue block <qitemId>` | — | `--on <blocker>` **required**<br>`--actor <session>`<br>`--summary <text>`<br>`--evidence-ref <path>`<br>`--note <text>`<br>`--continuation <text>`<br>`--wake-watchdog <jobId>`<br>`--wake-after <duration>`<br>`--json` |
|
||||
| `rig queue resolve <qitemId>` | — | `--decision <text>` **required**<br>`--actor <session>`<br>`--bearer <token>`<br>`--no-notify`<br>`--json` |
|
||||
| `rig queue handoff <qitemId>` | — | `--from <session>`<br>`--to <session>` **required**<br>`--body <text>`<br>`--body-file <path>`<br>`--note <text>`<br>`--priority <priority>`<br>`--tier <tier>`<br>`--tags <tags>`<br>`--gate <role>`<br>`--target-repo <name>`<br>`--summary <text>`<br>`--evidence-ref <path>`<br>`--alert`<br>`--host <id>`<br>`--no-nudge`<br>`--full`<br>`--json` |
|
||||
| `rig queue handoff-and-complete <qitemId>` | — | `--from <session>`<br>`--to <session>` **required**<br>`--body <text>`<br>`--body-file <path>`<br>`--note <text>`<br>`--priority <priority>`<br>`--tier <tier>`<br>`--tags <tags>`<br>`--gate <role>`<br>`--target-repo <name>`<br>`--summary <text>`<br>`--evidence-ref <path>`<br>`--alert`<br>`--host <id>`<br>`--no-nudge`<br>`--full`<br>`--json` |
|
||||
| `rig queue whoami` | — | `--session <session>`<br>`--recent-limit <n>`<br>`--work-candidates`<br>`--json` |
|
||||
| `rig queue handoff <qitemId>` | — | `--from <session>`<br>`--to <session>` **required**<br>`--body <text>`<br>`--body-file <path>`<br>`--note <text>`<br>`--priority <priority>`<br>`--tier <tier>`<br>`--tags <tags>`<br>`--gate <role>`<br>`--target-repo <name>`<br>`--summary <text>`<br>`--evidence-ref <path>`<br>`--host <id>`<br>`--no-nudge`<br>`--json` |
|
||||
| `rig queue handoff-and-complete <qitemId>` | — | `--from <session>`<br>`--to <session>` **required**<br>`--body <text>`<br>`--body-file <path>`<br>`--note <text>`<br>`--priority <priority>`<br>`--tier <tier>`<br>`--tags <tags>`<br>`--gate <role>`<br>`--target-repo <name>`<br>`--summary <text>`<br>`--evidence-ref <path>`<br>`--host <id>`<br>`--no-nudge`<br>`--json` |
|
||||
| `rig queue whoami` | — | `--session <session>`<br>`--recent-limit <n>`<br>`--json` |
|
||||
| `rig queue fallback <qitemId>` | — | `--destination <session>` **required**<br>`--reason <text>`<br>`--json` |
|
||||
| `rig queue show <qitemId>` | — | `--full`<br>`--json` |
|
||||
| `rig queue transitions <qitemId>` | — | `--json`<br>`--full` |
|
||||
| `rig queue transitions <qitemId>` | — | `--json` |
|
||||
| `rig queue list` | — | `-a, --all`<br>`-A, --all-rigs`<br>`--full`<br>`--owned`<br>`--mine`<br>`-o <format>`<br>`--destination <session>`<br>`--source <session>`<br>`--state <state>`<br>`--target-repo <name>`<br>`--limit <n>`<br>`--json` |
|
||||
| `rig queue overdue` | — | `--rig <name>`<br>`-A, --all-rigs`<br>`--full`<br>`--limit <n>`<br>`--json` |
|
||||
| `rig queue undelivered` | — | `--rig <name>`<br>`-A, --all-rigs`<br>`--full`<br>`--limit <n>`<br>`--json` |
|
||||
@@ -488,14 +408,9 @@ do not establish connectivity to a live peer.
|
||||
| `rig slack setup` | — | `--channel <id>`<br>`--inbound-destination <session>`<br>`--minimum-level-that-posts <level>`<br>`--minimum-level-that-interrupts <level>`<br>`--source-label <label>`<br>`--secrets-env-file <path>`<br>`--required-scopes <csv>`<br>`--reason <reason>`<br>`--actor <actor>` |
|
||||
| `rig slack status` | — | `--json` |
|
||||
| `rig slack manifest` | — | `--url`<br>`--json` |
|
||||
| `rig slack verify` | — | `--json` |
|
||||
| `rig slack channel-map` | — | — |
|
||||
| `rig slack channel-map list` | — | `--json` |
|
||||
| `rig slack channel-map set <match> <channel>` | — | `--inbound <seat>`<br>`--reason <reason>`<br>`--actor <actor>` |
|
||||
| `rig slack channel-map remove <match>` | — | `--reason <reason>`<br>`--actor <actor>` |
|
||||
| `rig slack verify` | — | `--json`<br>`--reason <reason>`<br>`--actor <actor>` |
|
||||
| `rig slack enable` | — | `--reason <reason>`<br>`--actor <actor>` |
|
||||
| `rig slack disable` | — | `--reason <reason>` **required**<br>`--actor <actor>` |
|
||||
| `rig slack post-open-asks` | — | `--reason <reason>`<br>`--wait <seconds>`<br>`--actor <actor>`<br>`--json` |
|
||||
| `rig slack outbound` | — | `--json` |
|
||||
| `rig slack inbound` | — | — |
|
||||
|
||||
@@ -509,10 +424,8 @@ do not establish connectivity to a live peer.
|
||||
| `rig project experimental disable` | — | `--config <file>` **required**<br>`--max-requests <n>`<br>`--timeout-ms <n>`<br>`--json` |
|
||||
| `rig project experimental status` | — | `--config <file>` **required**<br>`--max-requests <n>`<br>`--timeout-ms <n>`<br>`--json` |
|
||||
| `rig project experimental capture` | — | `--config <file>` **required**<br>`--input <file>` **required**<br>`--output <file>` **required**<br>`--json` |
|
||||
| `rig project decisions` | — | — |
|
||||
| `rig project decisions status` | — | `--json` |
|
||||
| `rig project candidates` | — | `--project <id>` **required**<br>`--taxonomy <file>` **required**<br>`--classifier-version <version>` **required**<br>`--evidence-epoch <epoch>` **required**<br>`--decisions <file>`<br>`--experiment <file>`<br>`--decide`<br>`--limit <count>`<br>`--json` |
|
||||
| `rig project wake` | — | `--project <id>` **required**<br>`--taxonomy <file>` **required**<br>`--classifier-version <version>` **required**<br>`--evidence-epoch <epoch>` **required**<br>`--decisions <file>`<br>`--experiment <file>`<br>`--decide`<br>`--limit <count>`<br>`--json` |
|
||||
| `rig project candidates` | — | `--project <id>` **required**<br>`--taxonomy <file>` **required**<br>`--classifier-version <version>` **required**<br>`--evidence-epoch <epoch>` **required**<br>`--decisions <file>`<br>`--experiment <file>`<br>`--limit <count>`<br>`--json` |
|
||||
| `rig project wake` | — | `--project <id>` **required**<br>`--taxonomy <file>` **required**<br>`--classifier-version <version>` **required**<br>`--evidence-epoch <epoch>` **required**<br>`--decisions <file>`<br>`--experiment <file>`<br>`--limit <count>`<br>`--json` |
|
||||
| `rig project shadow-status` | — | — |
|
||||
| `rig project shadow-drain` | — | `--actor <name>` |
|
||||
| `rig project shadow-stop` | — | `--actor <name>` |
|
||||
@@ -538,24 +451,20 @@ do not establish connectivity to a live peer.
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig terminal` | — | — |
|
||||
| `rig terminal open <view>` | — | `--provider <name>`<br>`--session <name>`<br>`--window`<br>`--expected-plan <id>`<br>`--json` |
|
||||
| `rig terminal open <view>` | — | `--provider <name>`<br>`--json` |
|
||||
| `rig terminal views` | — | `--json` |
|
||||
| `rig terminal status` | — | `--provider <name>`<br>`--session <name>`<br>`--json` |
|
||||
|
||||
See [named terminal sessions](../reference/terminal-sessions.md) to select a
|
||||
Herdr session per request, including session-bound previews and window reuse.
|
||||
| `rig terminal status` | — | `--provider <name>`<br>`--json` |
|
||||
|
||||
### watchdog
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig watchdog` | — | — |
|
||||
| `rig watchdog register` | — | `--spec <path>`<br>`--policy <policy>` **required**<br>`--target-session <session>` **required**<br>`--interval-seconds <n>` **required**<br>`--registered-by <session>` **required**<br>`--threshold-bytes <n>`<br>`--threshold-mb <n>`<br>`--threshold-tokens <n>`<br>`--threshold-percent <n>`<br>`--watched-file <path>`<br>`--requires-job <jobId>`<br>`--message <text>`<br>`--active-wake-interval-seconds <n>`<br>`--scan-interval-seconds <n>`<br>`--json` |
|
||||
| `rig watchdog register` | — | `--spec <path>`<br>`--policy <policy>` **required**<br>`--target-session <session>` **required**<br>`--interval-seconds <n>` **required**<br>`--registered-by <session>` **required**<br>`--threshold-bytes <n>`<br>`--threshold-mb <n>`<br>`--watched-file <path>`<br>`--requires-job <jobId>`<br>`--message <text>`<br>`--active-wake-interval-seconds <n>`<br>`--scan-interval-seconds <n>`<br>`--json` |
|
||||
| `rig watchdog list` | — | `-a, --all`<br>`--full`<br>`--limit <n>`<br>`--json` |
|
||||
| `rig watchdog show <jobId>` | — | `--json` |
|
||||
| `rig watchdog status <jobId>` | — | `--json` |
|
||||
| `rig watchdog stop <jobId>` | — | `--reason <text>`<br>`--json` |
|
||||
| `rig watchdog update <jobId>` | — | `--interval-seconds <n>`<br>`--message <text>`<br>`--spec <path>`<br>`--json` |
|
||||
|
||||
### workflow
|
||||
|
||||
@@ -567,26 +476,26 @@ Herdr session per request, including session-bound previews and window reuse.
|
||||
| `rig workflow revise <instanceId>` | — | `--apply`<br>`--expected-version <number>`<br>`--expected-digest <sha256>`<br>`--operation-key <key>`<br>`--actor-session <session>`<br>`--reason <text>`<br>`--json` |
|
||||
| `rig workflow operation <key>` | — | `--json` |
|
||||
| `rig workflow instantiate-lifecycle <missionPath>` | — | `--operation-key <key>` **required**<br>`--root-objective <text>` **required**<br>`--created-by <session>` **required**<br>`--entry-owner <session>`<br>`--rig <name>`<br>`--json` |
|
||||
| `rig workflow instantiate <specPath>` | — | `--root-objective <text>` **required**<br>`--created-by <session>` **required**<br>`--entry-owner <session>`<br>`--rig <name>`<br>`--project <id>`<br>`--mission <id>`<br>`--slice <id>`<br>`--tags <tags>`<br>`--json` |
|
||||
| `rig workflow project` | — | `--instance <id>` **required**<br>`--current-packet <qitem-id>` **required**<br>`--exit <kind>` **required**<br>`--actor-session <session>` (only when the caller's session can't be derived)<br>`--result-note <text>`<br>`--evidence-ref <ref>`<br>`--wait-for-proof <scope>`<br>`--blocked-on <ref>`<br>`--next-owner <session>`<br>`--acceptance-candidate <identity>`<br>`--acceptance-verdict <verdict>`<br>`--acceptance-evidence-ref <path>`<br>`--json` |
|
||||
| `rig workflow instantiate <specPath>` | — | `--root-objective <text>` **required**<br>`--created-by <session>` **required**<br>`--entry-owner <session>`<br>`--rig <name>`<br>`--json` |
|
||||
| `rig workflow project` | — | `--instance <id>` **required**<br>`--current-packet <qitem-id>` **required**<br>`--exit <kind>` **required**<br>`--actor-session <session>` **required**<br>`--result-note <text>`<br>`--evidence-ref <ref>`<br>`--wait-for-proof <scope>`<br>`--blocked-on <ref>`<br>`--next-owner <session>`<br>`--acceptance-candidate <identity>`<br>`--acceptance-verdict <verdict>`<br>`--acceptance-evidence-ref <path>`<br>`--json` |
|
||||
| `rig workflow list` | — | `--status <s>`<br>`--json` |
|
||||
| `rig workflow specs` | — | `--json` |
|
||||
| `rig workflow guidance <instanceId>` | — | `--packet <id>`<br>`--component <id>`<br>`--full`<br>`--json` |
|
||||
| `rig workflow show <instanceId>` | — | `--json` |
|
||||
| `rig workflow trace <instanceId>` | — | `--json` |
|
||||
| `rig workflow continue <instanceId>` | — | `--json` |
|
||||
| `rig workflow run <specPath>` | — | `--root-objective <text>` **required**<br>`--created-by <session>` **required**<br>`--entry-owner <session>`<br>`--rig <name>`<br>`--project <id>`<br>`--mission <id>`<br>`--slice <id>`<br>`--tags <tags>`<br>`--json` |
|
||||
| `rig workflow run <specPath>` | — | `--root-objective <text>` **required**<br>`--created-by <session>` **required**<br>`--entry-owner <session>`<br>`--rig <name>`<br>`--json` |
|
||||
| `rig workflow watch <instanceId>` | — | `--json` |
|
||||
| `rig workflow route <instanceId>` | — | `--to <session>` **required**<br>`--actor-session <session>` (only when the caller's session can't be derived)<br>`--packet <qitem-id>`<br>`--reason <text>`<br>`--json` |
|
||||
| `rig workflow resume <instanceId>` | — | `--actor-session <session>` (only when the caller's session can't be derived)<br>`--occurrence <failed-qitem-id>`<br>`--decision <text>`<br>`--json` |
|
||||
| `rig workflow abort <instanceId>` | — | `--reason <text>` **required**<br>`--actor-session <session>` (only when the caller's session can't be derived)<br>`--json` |
|
||||
| `rig workflow route <instanceId>` | — | `--to <session>` **required**<br>`--actor-session <session>` **required**<br>`--packet <qitem-id>`<br>`--reason <text>`<br>`--json` |
|
||||
| `rig workflow resume <instanceId>` | — | `--actor-session <session>` **required**<br>`--occurrence <failed-qitem-id>`<br>`--decision <text>`<br>`--json` |
|
||||
| `rig workflow abort <instanceId>` | — | `--reason <text>` **required**<br>`--actor-session <session>` **required**<br>`--json` |
|
||||
| `rig workflow status` | — | `--json` |
|
||||
|
||||
### capture
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig capture [session]` | — | `--rig <name>`<br>`--pod <name>`<br>`--lines <n>`<br>`--history-plus-pane`<br>`--readable`<br>`--size <WxH>`<br>`--host <id>`<br>`--json` |
|
||||
| `rig capture [session]` | — | `--rig <name>`<br>`--pod <name>`<br>`--lines <n>`<br>`--host <id>`<br>`--json` |
|
||||
|
||||
### broadcast
|
||||
|
||||
@@ -604,12 +513,7 @@ Herdr session per request, including session-bound previews and window reuse.
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig ask <rig> <question>` | — | `--json`<br>`--seat <session-name>`<br>`--session <token>`<br>`--wake <target>`<br>`--runtime <runtime>`<br>`--wake-timeout <seconds>` |
|
||||
|
||||
Wake seat targets must include the rig: `member@rig` or `member@rig@N` (1 = newest tenure).
|
||||
Values without `@` go unchanged to the runtime as a session ID or title; a bare member
|
||||
name is not resolved within `<rig>`.
|
||||
Only Claude and Codex tenures can be woken.
|
||||
| `rig ask <rig> <question>` | — | `--json`<br>`--seat <session-name>`<br>`--session <token>`<br>`--wake <seat[@gen]\|token>`<br>`--runtime <runtime>`<br>`--wake-timeout <seconds>` |
|
||||
|
||||
### chatroom
|
||||
|
||||
@@ -672,7 +576,7 @@ Only Claude and Codex tenures can be woken.
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig skill` | — | — |
|
||||
| `rig skill loadout` | — | `--runtime <runtime>` (folder mode; **required** there)<br>`--seat <session>` (seat mode; `self` is this seat)<br>`--wait-for-idle <ms>`<br>`--resend`<br>`--cwd <path>`<br>`--project-root <path>`<br>`--topology <ids>`<br>`--apply`<br>`--json` |
|
||||
| `rig skill loadout` | — | `--runtime <runtime>` **required**<br>`--cwd <path>`<br>`--project-root <path>`<br>`--topology <ids>`<br>`--apply`<br>`--json` |
|
||||
| `rig skill audit` | — | `--json` |
|
||||
|
||||
### agent-image
|
||||
@@ -690,18 +594,11 @@ Only Claude and Codex tenures can be woken.
|
||||
| `rig agent-image prune` | — | `--dry-run`<br>`--force`<br>`--json` |
|
||||
| `rig agent-image sync` | — | `--json` |
|
||||
|
||||
### community-harness
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig community-harness` | — | — |
|
||||
| `rig community-harness list` | — | `--json` |
|
||||
|
||||
### fork
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig fork <source-session>` | — | `--rig <rig>` **required**<br>`--pod <pod-namespace>` **required**<br>`--member <member-id>` **required**<br>`--keep-image`<br>`--image-name <name>`<br>`--image-version <version>`<br>`--rig-root <path>`<br>`--json` |
|
||||
| `rig fork <source-session>` | — | `--rig <rig-id>` **required**<br>`--pod <pod-namespace>` **required**<br>`--member <member-id>` **required**<br>`--keep-image`<br>`--image-name <name>`<br>`--image-version <version>`<br>`--rig-root <path>`<br>`--json` |
|
||||
|
||||
### workspace
|
||||
|
||||
@@ -720,7 +617,7 @@ Only Claude and Codex tenures can be woken.
|
||||
| `rig mode show` | — | `--json` |
|
||||
| `rig mode effective` | — | `--rig <id>`<br>`--project <id>`<br>`--mission <id>`<br>`--workstream <id>`<br>`--qitem <id>`<br>`--json` |
|
||||
| `rig mode cite` | — | `--rig <id>`<br>`--project <id>`<br>`--mission <id>`<br>`--workstream <id>`<br>`--qitem <id>` |
|
||||
| `rig mode unset <scope> [qualifier]` | — | `--bearer <token>`<br>`--category <category>`<br>`--json` |
|
||||
| `rig mode unset <scope> [qualifier]` | — | `--bearer <token>`<br>`--json` |
|
||||
| `rig mode defaults` | — | `--json` |
|
||||
|
||||
### policy
|
||||
@@ -732,17 +629,17 @@ Only Claude and Codex tenures can be woken.
|
||||
| `rig policy permissions list` | — | `--spec <path>`<br>`--json` |
|
||||
| `rig policy permissions show <nameOrRef>` | — | `--spec <path>`<br>`--json` |
|
||||
| `rig policy permissions current` | — | `--spec <path>` **required**<br>`--json` |
|
||||
| `rig policy permissions apply <name>` | — | `--spec <path>`<br>`--seat <seat>`<br>`--reason <text>`<br>`--operator <address>`<br>`--json` |
|
||||
| `rig policy permissions apply <name>` | — | `--spec <path>` **required**<br>`--json` |
|
||||
| `rig policy list` | — | `--spec <path>`<br>`--json` |
|
||||
| `rig policy show <nameOrRef>` | — | `--spec <path>`<br>`--json` |
|
||||
| `rig policy current` | — | `--spec <path>` **required**<br>`--json` |
|
||||
| `rig policy apply <name>` | — | `--spec <path>`<br>`--seat <seat>`<br>`--reason <text>`<br>`--operator <address>`<br>`--json` |
|
||||
| `rig policy apply <name>` | — | `--spec <path>` **required**<br>`--json` |
|
||||
|
||||
### whoami
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig whoami` | — | `--node-id <id>`<br>`--session <name>`<br>`--host <id>`<br>`--all-hosts`<br>`--hosts <ids>`<br>`--json`<br>`--full`<br>`--verbose`<br>`--all-peers` |
|
||||
| `rig whoami` | — | `--node-id <id>`<br>`--session <name>`<br>`--host <id>`<br>`--all-hosts`<br>`--hosts <ids>`<br>`--json`<br>`--full`<br>`--verbose` |
|
||||
|
||||
### config
|
||||
|
||||
@@ -774,10 +671,10 @@ Only Claude and Codex tenures can be woken.
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig auth` | — | — |
|
||||
| `rig auth status` | — | `--runtime <runtime>`<br>`--codex-home <dir>`<br>`--host <id>` |
|
||||
| `rig auth list` | — | `--runtime <runtime>`<br>`--codex-home <dir>`<br>`--host <id>` |
|
||||
| `rig auth status` | — | `--runtime <runtime>` |
|
||||
| `rig auth list` | — | `--runtime <runtime>` |
|
||||
| `rig auth save <profile>` | — | `--runtime <runtime>` |
|
||||
| `rig auth switch <profile>` | — | `--runtime <runtime>`<br>`--codex-home <dir>`<br>`--host <id>` |
|
||||
| `rig auth switch <profile>` | — | `--runtime <runtime>` |
|
||||
| `rig auth validate <profile>` | — | `--runtime <runtime>` |
|
||||
| `rig auth seats` | — | — |
|
||||
| `rig auth seats list` | — | `--runtime <runtime>` |
|
||||
@@ -790,14 +687,12 @@ Only Claude and Codex tenures can be woken.
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig provider` | — | — |
|
||||
| `rig provider status` | — | `--json`<br>`--refresh`<br>`--provider <p>`<br>`--claude-token-file <path>`<br>`--credential-label <label>`<br>`--all-hosts`<br>`--hosts <ids>` |
|
||||
| `rig provider status` | — | `--json` |
|
||||
| `rig provider accounts` | — | `--json`<br>`--provider <p>`<br>`--account <a>` |
|
||||
| `rig provider bindings` | — | `--json`<br>`--provider <p>`<br>`--account <a>` |
|
||||
| `rig provider signals` | — | `--json`<br>`--provider <p>`<br>`--account <a>` |
|
||||
| `rig provider precheck` | — | `--seat <s>` **required**<br>`--to-account <a>`<br>`--token-file <path>`<br>`--stored-login`<br>`--json` |
|
||||
| `rig provider switch` | — | `--seat <s>` **required**<br>`--to-account <a>`<br>`--token-file <path>`<br>`--stored-login`<br>`--force-unsafe`<br>`--json` |
|
||||
| `rig provider moves` | — | `--seat <seat>`<br>`--limit <n>`<br>`--json` |
|
||||
| `rig provider moves report` | — | `--file <path>` **required**<br>`--to <seat>` **required**<br>`--follows <qitemId>`<br>`--evidence-ref <ref>`<br>`--json` |
|
||||
| `rig provider precheck` | — | `--seat <s>` **required**<br>`--to-account <a>` **required**<br>`--json` |
|
||||
| `rig provider switch` | — | `--seat <s>` **required**<br>`--to-account <a>` **required**<br>`--force-unsafe`<br>`--json` |
|
||||
|
||||
### usage
|
||||
|
||||
@@ -805,7 +700,6 @@ Only Claude and Codex tenures can be woken.
|
||||
|---|---|---|
|
||||
| `rig usage` | — | — |
|
||||
| `rig usage top` | — | `--window <duration>`<br>`--top <n>`<br>`--json` |
|
||||
| `rig usage cost` | — | `--seat <session>`<br>`--json` |
|
||||
| `rig usage series` | — | `--seat <session>`<br>`--lane <lane>`<br>`--since <iso>`<br>`--until <iso>`<br>`--limit <n>`<br>`--json` |
|
||||
|
||||
### telemetry
|
||||
@@ -842,13 +736,13 @@ Only Claude and Codex tenures can be woken.
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig expand <rig> <pod-fragment-path>` | — | `--json`<br>`--rig-root <path>` |
|
||||
| `rig expand <rig-id> <pod-fragment-path>` | — | `--json`<br>`--rig-root <path>` |
|
||||
|
||||
### add
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig add <rig> <pod-namespace> <member-fragment-path>` | — | `--json`<br>`--rig-root <path>` |
|
||||
| `rig add <rig-id> <pod-namespace> <member-fragment-path>` | — | `--json`<br>`--rig-root <path>` |
|
||||
|
||||
### create
|
||||
|
||||
@@ -862,25 +756,11 @@ Only Claude and Codex tenures can be woken.
|
||||
|---|---|---|
|
||||
| `rig grow <rig-id> <members...>` | — | `--pod <pod>`<br>`--new-pod <pod>`<br>`--runtime <runtime>`<br>`--cwd <path>`<br>`--json` |
|
||||
|
||||
### edge
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig edge` | — | — |
|
||||
| `rig edge add <rig> [from] [to]` | — | `--kind <kind>`<br>`--plan`<br>`--json` |
|
||||
| `rig edge remove <rig> <edge-id>` | — | `--plan`<br>`--json` |
|
||||
|
||||
`add` requires `from`, `to` and `--kind`, and is idempotent: a repeat reports the
|
||||
existing edge and writes nothing. `remove` deletes the edge with that ID; a repeat changes nothing and
|
||||
returns `edge_not_found` (exit 1). See
|
||||
[changing edges on an existing rig](../reference/rig-spec.md#changing-edges-on-an-existing-rig)
|
||||
for input and receipt examples, rollback, and snapshot behavior.
|
||||
|
||||
### reconcile-session
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig reconcile-session <session>` | — | `--rig <rigId>`<br>`--node <logicalId>`<br>`--no-launch`<br>`--repair-missing-pane`<br>`--json` |
|
||||
| `rig reconcile-session <session>` | — | `--rig <rigId>`<br>`--node <logicalId>`<br>`--no-launch`<br>`--json` |
|
||||
|
||||
### env
|
||||
|
||||
@@ -901,13 +781,13 @@ for input and receipt examples, rollback, and snapshot behavior.
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig release <rig>` | — | `--delete`<br>`--json` |
|
||||
| `rig release <rigId>` | — | `--delete`<br>`--json` |
|
||||
|
||||
### launch
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig launch <rig> [nodeRef]` | — | `--seats <ids>`<br>`--hold-reason <reason>`<br>`--snapshot-id <id>`<br>`--retry-startup-from <member-file>`<br>`--rig-root <path>`<br>`--plan`<br>`--json`<br>`--host <id>` |
|
||||
| `rig launch <rigId> [nodeRef]` | — | `--seats <ids>`<br>`--hold-reason <reason>`<br>`--snapshot-id <id>`<br>`--retry-startup-from <member-file>`<br>`--rig-root <path>`<br>`--plan`<br>`--json`<br>`--host <id>` |
|
||||
|
||||
### remove
|
||||
|
||||
@@ -919,7 +799,7 @@ for input and receipt examples, rollback, and snapshot behavior.
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig shrink <rig> <podRef>` | — | `--fallback <live-seat>`<br>`--json` |
|
||||
| `rig shrink <rigId> <podRef>` | — | `--fallback <live-seat>`<br>`--json` |
|
||||
|
||||
### destroy
|
||||
|
||||
@@ -931,7 +811,7 @@ for input and receipt examples, rollback, and snapshot behavior.
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig setup` | — | `--dry-run`<br>`--json`<br>`--full`<br>`--no-herdr`<br>`--ghostty`<br>`--no-ghostty`<br>`--providers <list>`<br>`--policy <name>`<br>`--spec <path>`<br>`--router-line <answer>` |
|
||||
| `rig setup` | — | `--dry-run`<br>`--json`<br>`--full`<br>`--policy <name>`<br>`--spec <path>` |
|
||||
|
||||
### restore-check
|
||||
|
||||
@@ -954,8 +834,6 @@ for input and receipt examples, rollback, and snapshot behavior.
|
||||
|---|---|---|
|
||||
| `rig compact-plan` | — | `--json`<br>`--rig <name>`<br>`--refresh`<br>`--threshold-tokens <n>`<br>`--threshold-percent <0-100>` |
|
||||
|
||||
- `--threshold-tokens` and `--threshold-percent` set the plan's own candidate thresholds (the percentage applies when a seat's context window size is missing). They are not the automatic compaction setting: the output labels them as the plan's own and shows `policies.claude_compaction` (`enabled`, `threshold_percent`) separately, for comparison only, or says it couldn't be read.
|
||||
|
||||
### compact
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
@@ -973,57 +851,21 @@ for input and receipt examples, rollback, and snapshot behavior.
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig seat` | — | — |
|
||||
| `rig seat history` | — | `--rig <id>` **required**<br>`--node-id <id>` **required**<br>`--snapshot-id <id>`<br>`--history-session-id <id>`<br>`--json` |
|
||||
| `rig seat set-typing-guard <seat>` | — | `--enabled <boolean>`<br>`--mode <mode>`<br>`--reason <text>` **required**<br>`--json` |
|
||||
| `rig seat set-typing-guard <seat>` | — | `--enabled <boolean>` **required**<br>`--reason <text>` **required**<br>`--json` |
|
||||
| `rig seat held-messages <seat>` | — | `--limit <n>`<br>`--offset <n>`<br>`--id <id>`<br>`--json` |
|
||||
| `rig seat retire-held-message <seat> <id>` | — | `--reason <text>` **required**<br>`--json` |
|
||||
| `rig seat status <seat>` | — | `--json` |
|
||||
| `rig seat handover <seat>` | — | `--source <source>`<br>`--reason <reason>`<br>`--operator <address>`<br>`--dry-run`<br>`--json` |
|
||||
| `rig seat switch-client <seat>` | — | `--to-window <n>`<br>`--client <id>`<br>`--json` |
|
||||
| `rig seat clear-attention <session>` | — | `--reason <text>`<br>`--json` |
|
||||
| `rig seat set-terminal-policy <seat>` | — | `--preset <preset>` **required**<br>`--helper <addresses...>`<br>`--rig-default`<br>`--reason <text>` **required**<br>`--operator <address>`<br>`--json`<br>`--peer-compaction <decision>`<br>`--peer-model <decision>`<br>`--self-compaction <decision>`<br>`--self-model <decision>`<br>`--openrig-compaction <decision>`<br>`--openrig-model <decision>` |
|
||||
| `rig seat set-permissions <seat>` | — | `--mode <mode>`<br>`--rules <file>`<br>`--codex-permissions <file>`<br>`--codex-profile <name>`<br>`--reason <text>` **required**<br>`--operator <address>`<br>`--json` |
|
||||
| `rig seat set-effort <seat>` | — | `--effort <level>`<br>`--clear`<br>`--reason <text>` **required**<br>`--operator <address>`<br>`--json` |
|
||||
| `rig seat effort <seat>` | — | `--json` |
|
||||
| `rig seat set-permissions <seat>` | — | `--mode <mode>` **required**<br>`--reason <text>` **required**<br>`--operator <address>`<br>`--json` |
|
||||
| `rig seat set-model <seat>` | — | `--model <id>` **required**<br>`--reason <text>` **required**<br>`--operator <address>`<br>`--json` |
|
||||
| `rig seat set-runtime <seat>` | — | `--runtime <runtime>`<br>`--reason <text>`<br>`--model <id>`<br>`--effort <level>`<br>`--codex-config-profile <name>`<br>`--permission-mode <mode>`<br>`--confirm-timeout <seconds>`<br>`--dry-run`<br>`--confirm <switch-id>`<br>`--note <text>`<br>`--recover`<br>`--json` |
|
||||
| `rig seat set-cwd <seat>` | — | `--cwd <directory>` **required**<br>`--reason <text>` **required**<br>`--operator <address>`<br>`--json` |
|
||||
| `rig seat launch <seat>` | — | `--fresh` **required**<br>`--reason <text>`<br>`--plan`<br>`--stop`<br>`--operator <address>`<br>`--json` |
|
||||
| `rig seat restart <seat>` | — | `--keep-conversation` **required**<br>`--reason <text>`<br>`--plan`<br>`--verify`<br>`--expect-account <text>`<br>`--operator <address>`<br>`--host <id>`<br>`--json` |
|
||||
| `rig seat launch <seat>` | — | `--fresh` **required**<br>`--reason <text>` **required**<br>`--stop`<br>`--operator <address>`<br>`--json` |
|
||||
| `rig seat continue <seat>` | — | `--json` |
|
||||
| `rig seat stop <seat>` | — | `--reason <text>` **required**<br>`--operator <address>`<br>`--json` |
|
||||
| `rig seat clean <seat>` | — | `--reason <text>` **required**<br>`--operator <address>`<br>`--json` |
|
||||
| `rig seat set-resume-token <session>` | — | `--token-stdin`<br>`--reason <text>` **required**<br>`--json` |
|
||||
|
||||
A `rig seat stop` that successfully kills the current session records that it
|
||||
was intentionally stopped. With other healthy members running, the rig's `lifecycleState` in
|
||||
`rig ps` and the TUI stays `running`; the stopped member no longer makes it
|
||||
`degraded`. Stopping every member
|
||||
leaves the rig `stopped`. Node JSON exposes `intentionallyStopped` in compact,
|
||||
`--full`, and `--fields` output.
|
||||
|
||||
Process counts still reflect reality: stopping one of two members leaves
|
||||
`nodeCount: 2`, `runningCount: 1`, and process `status: partial`. Node lifecycle,
|
||||
resume information, and attention diagnostics remain available. A crash or
|
||||
attention condition on another member still affects the rig lifecycle.
|
||||
|
||||
Stop intent survives daemon restarts and audit retention. It applies only to the
|
||||
latest exited session while the seat has no binding; a subsequent session status
|
||||
change clears it, and a new session starts without it. Existing exits are not
|
||||
backfilled as intentional stops. If the session disappears between the live
|
||||
probe and the stop, its unexplained exit still affects rig health. The internal
|
||||
stop in `rig seat launch --fresh --stop` does not record final stop intent, so a
|
||||
refused replacement still degrades a rig with other healthy members running.
|
||||
|
||||
`rig start --last` and `rig start --rigs <rig>` use the full per-seat lifecycle
|
||||
for restore selection. A partly running rig with an intentionally stopped member
|
||||
still appears as a `degraded` candidate and reports `rig_not_stopped` (exit 1)
|
||||
when restore is attempted. Launch scheduling and restore eligibility remain
|
||||
unchanged.
|
||||
|
||||
See [per-seat terminal delivery](../reference/seat-delivery.md) for
|
||||
off, draft-aware and hold modes, immediate refusal results and held-message inspection.
|
||||
|
||||
### handover
|
||||
|
||||
| Invocation | Aliases | Declared options |
|
||||
@@ -1072,6 +914,6 @@ off, draft-aware and hold modes, immediate refusal results and held-message insp
|
||||
| Invocation | Aliases | Declared options |
|
||||
|---|---|---|
|
||||
| `rig proof` | — | `--workspace <path>` |
|
||||
| `rig proof show [scope]` | — | `--project <id>`<br>`--json` |
|
||||
| `rig proof judge <scope-item>` | — | `--project <id>`<br>`--verdict <verdict>` **required**<br>`--reason <text>` **required**<br>`--evidence <ref>` (repeatable)<br>`--subject <kind:ref>`<br>`--comparison <ref>`<br>`--revision <revision>`<br>`--operation-id <id>`<br>`--replace`<br>`--json` |
|
||||
| `rig proof show [scope]` | — | `--json` |
|
||||
| `rig proof judge <scope-item>` | — | `--verdict <verdict>` **required**<br>`--reason <text>` **required**<br>`--evidence <ref>` (repeatable)<br>`--subject <kind:ref>`<br>`--comparison <ref>`<br>`--revision <revision>`<br>`--operation-id <id>`<br>`--replace`<br>`--json` |
|
||||
| `rig proof add <slice-path>` | — | `--mission <name>`<br>`--artifact-type <type>` **required**<br>`--verdict <verdict>` **required**<br>`--candidate-sha <sha>` **required**<br>`--money-evidence <line>` **required**<br>`--slice-id <dot-id>`<br>`--file <path>`<br>`--body <text>`<br>`--name <filename>`<br>`--replace`<br>`--evidences <refs>`<br>`--self-check <text>`<br>`--media <refs>`<br>`--json` |
|
||||
@@ -9,14 +9,14 @@ applies-when: |
|
||||
Follow the module and source entry points below, then read the implementation.
|
||||
siblings: [README.md, arteries.md, test-layers.md, cli-reference.md]
|
||||
prerequisite-reads: [README.md]
|
||||
last-verified-against-source: e8f0ab340db773392ec8be75b072d1c0f3068a50
|
||||
last-updated: 2026-10-08
|
||||
last-verified-against-source: a350c59b5a5fb37ee4a21b1026b595068b603df1
|
||||
last-updated: 2026-10-05
|
||||
---
|
||||
|
||||
# OpenRig codemap
|
||||
|
||||
The paths and named entry points below were checked at main
|
||||
`e8f0ab340db773392ec8be75b072d1c0f3068a50`. This is a navigation map, not a replacement for
|
||||
`a350c59b5a5fb37ee4a21b1026b595068b603df1`. This is a navigation map, not a replacement for
|
||||
reading the implementation. Linked documents retain their individual verification stamps.
|
||||
[README.md](README.md) lists the complete document tree and commands to derive its inventory.
|
||||
|
||||
@@ -75,14 +75,12 @@ stamp says whether it already covers them; until then, start from the source nam
|
||||
|---|---|---|
|
||||
| How does a GitHub folder link become a bundle source? | `isGitHubBundleLink()` and the bundle source in `packages/cli/src/lib/bundle-source.ts`, used by `packages/cli/src/commands/up.ts` and `packages/cli/src/commands/bundle.ts`. | [Packaging and bundles](architecture/packaging-bootstrap-bundles.md) |
|
||||
| What does `rig bundle check` read? | `checkBundleFolder()` in `packages/cli/src/lib/bundle-check.ts`: advisory file reads against `openrig.bundle-standard/v1`, with no daemon, launch or provider call. | [Packaging and bundles](architecture/packaging-bootstrap-bundles.md) |
|
||||
| How does a member's `permission_policy` become a launch posture, including `builtin:auto`? | `builtinLaunchPosture()` and `resolvePermissionPolicyAttachment()` in `packages/daemon/src/domain/permission-policy/policy-ref.ts` (`builtin:yolo` is full bypass, `builtin:auto` is auto, the other built-ins are the floor), bound per seat in `packages/daemon/src/domain/rigspec-instantiator.ts`. `packages/daemon/src/domain/bundle-behaviour.ts` is the read-only preview of the same mapping for an unopened bundle. | [Adapters and runtimes](architecture/adapters-and-runtimes.md) |
|
||||
| How does a member's `permission_policy` become a launch posture, including `builtin:auto`? | `packages/daemon/src/domain/bundle-behaviour.ts` (`builtin:yolo` is full bypass and `builtin:auto` is auto, both by launch flag; `builtin:locked`, `builtin:standard` and `builtin:open` are configuration). | [Adapters and runtimes](architecture/adapters-and-runtimes.md) |
|
||||
| What does a non-interruptive launch add? | `nonInterruptiveArgs()` in `packages/daemon/src/adapters/non-interruptive.ts` (per-launch arguments only; it never changes permissions or native settings files). The separate instance-wide YOLO setting, off by default, is in `packages/daemon/src/adapters/yolo-mode.ts`. | [Adapters and runtimes](architecture/adapters-and-runtimes.md) |
|
||||
| What launch arguments does a kernel seat get? | `operationalLaunchArgs()` and `KERNEL_CLAUDE_ALLOW` in `packages/daemon/src/adapters/kernel-authority.ts`; `NativePermissionStore.launchOverride()` in `packages/daemon/src/domain/native-permission-store.ts` decides it per launch (only the rig named `kernel`, with no explicit seat choice, permission policy or Codex profile). | [Adapters and runtimes](architecture/adapters-and-runtimes.md) |
|
||||
| What launch default does a seat in any other rig get? | Under the same conditions `launchOverride()` sets `teamPermissionDefault`: a Claude seat at the floor posture gets `TEAM_CLAUDE_ALLOW` and `TEAM_CLAUDE_ASK` from `operationalLaunchArgs()` in `packages/daemon/src/adapters/kernel-authority.ts`, whose `claudeCommandSettings()` hands the kernel or team lists to the session-only Bash hook `packages/daemon/assets/claude-team-permissions.cjs`, which returns the allow or ask decision; a workspace-write Codex seat gets `--add-dir` roots from `prepareCodexTeamWorkspace()` in `packages/daemon/src/domain/codex-team-workspace.ts`. | [Adapters and runtimes](architecture/adapters-and-runtimes.md) |
|
||||
| How does `rig seat continue` finish a fresh or Codex-fork startup that stopped before its context was delivered? | `continueStartup()` in `packages/daemon/src/domain/seat-lifecycle-service.ts`, `canContinueStartup()` and `readPendingStartupContext()` in `packages/daemon/src/domain/startup-orchestrator.ts`, `captureForkIdentity()` in `packages/daemon/src/adapters/codex-runtime-adapter.ts`, the route in `packages/daemon/src/routes/seat.ts`, and the command in `packages/cli/src/commands/seat.ts`. | [Agent spec and startup](architecture/agent-spec-and-startup.md) |
|
||||
| How does `rig seat continue` finish a fresh startup that stopped before its context was delivered? | `continueFreshStartup()` in `packages/daemon/src/domain/seat-lifecycle-service.ts`, `canContinueFresh()` in `packages/daemon/src/domain/startup-orchestrator.ts`, the route in `packages/daemon/src/routes/seat.ts`, and the command in `packages/cli/src/commands/seat.ts`. | [Agent spec and startup](architecture/agent-spec-and-startup.md) |
|
||||
| How does `rig context work-install` choose a project and position? | `resolveWorkPosition()` in `packages/cli/src/lib/work-install.ts`, `packages/cli/src/commands/context.ts`, and `packages/daemon/src/domain/workspace/project-catalog.ts`. | [Workspace](architecture/workspace-primitive.md) |
|
||||
| Where do rosters come from? | `packages/cli/src/commands/roster.ts`: `rig roster list`, `show` and `find` read JSON roster files from `<workspace.root>/rosters` (or `--folder`) and are read-only. | [Agent spec and startup](architecture/agent-spec-and-startup.md), "Specialist rosters" |
|
||||
| What telemetry can be read? | `packages/daemon/src/domain/finite-telemetry.ts` (the `events`, `queue-transitions` and `tenures` streams), `/api/telemetry` in `packages/daemon/src/routes/telemetry.ts`, and `packages/cli/src/commands/telemetry.ts`. | [Architecture rules and events](architecture/architecture-rules-and-event-system.md), "Telemetry read surface" |
|
||||
| Where do rosters come from? | `packages/cli/src/commands/roster.ts`: `rig roster list`, `show` and `find` read JSON roster files from `<workspace.root>/rosters` (or `--folder`) and are read-only. | No module page covers rosters. |
|
||||
| What telemetry can be read? | `packages/daemon/src/domain/finite-telemetry.ts` (the `events`, `queue-transitions` and `tenures` streams), `/api/telemetry` in `packages/daemon/src/routes/telemetry.ts`, and `packages/cli/src/commands/telemetry.ts`. | No module page covers telemetry. |
|
||||
|
||||
## Change and verification guides
|
||||
|
||||
|
||||
@@ -6,13 +6,13 @@ topics: [knowledge-and-context, frontmatter]
|
||||
domains: [engineering-advisor, operating-advisor]
|
||||
applies-when: |
|
||||
Writing or refreshing a source-grounded document under docs/as-built/.
|
||||
last-verified-against-source: e8f0ab340db773392ec8be75b072d1c0f3068a50
|
||||
last-updated: 2026-10-08
|
||||
last-verified-against-source: a350c59b5a5fb37ee4a21b1026b595068b603df1
|
||||
last-updated: 2026-10-05
|
||||
---
|
||||
|
||||
# As-Built Frontmatter
|
||||
|
||||
Source snapshot: `e8f0ab340db773392ec8be75b072d1c0f3068a50`. This describes the source at that commit;
|
||||
Source snapshot: `a350c59b5a5fb37ee4a21b1026b595068b603df1`. This describes the source at that commit;
|
||||
it does not establish the version or behavior of a running daemon.
|
||||
|
||||
Frontmatter makes an as-built page discoverable and records the source it
|
||||
@@ -44,8 +44,8 @@ that an installed package or a running system uses that source. Keep runtime
|
||||
observations separately qualified.
|
||||
|
||||
```yaml
|
||||
last-verified-against-source: e8f0ab340db773392ec8be75b072d1c0f3068a50
|
||||
last-updated: 2026-10-08
|
||||
last-verified-against-source: a350c59b5a5fb37ee4a21b1026b595068b603df1
|
||||
last-updated: 2026-10-05
|
||||
```
|
||||
|
||||
Check that the commit resolves with `git cat-file -t <commit>` in a checkout
|
||||
|
||||
+58
-140
@@ -7,13 +7,13 @@ applies-when: |
|
||||
request, what each check actually proves, and what CI will run for you. Also
|
||||
read it before claiming a stub-agent scenario covers a behaviour.
|
||||
siblings: [arteries.md, README.md, codemap.md]
|
||||
last-verified-against-source: e8f0ab340db773392ec8be75b072d1c0f3068a50
|
||||
last-updated: 2026-10-08
|
||||
last-verified-against-source: 1347d825
|
||||
last-updated: 2026-10-02
|
||||
---
|
||||
|
||||
# Test layers: what to run before you push, and what each layer proves
|
||||
|
||||
> **This page is a map, not the territory.** It was checked against source at `e8f0ab34`
|
||||
> **This page is a map, not the territory.** It was checked against source at `1347d825`
|
||||
> and it will drift. It is also incomplete on purpose. Before you rely on a command or a
|
||||
> claim here, read the script it names or run it. If a behaviour is missing from this page
|
||||
> (or from [arteries.md](arteries.md)), that tells you nothing about whether a change to it
|
||||
@@ -39,10 +39,10 @@ to `main`. In the PR description, say which layers you ran and which you could n
|
||||
|---|---|---|---|---|
|
||||
| Typecheck | `npm run lint` | Builds the daemon, then `tsc --noEmit` passes for daemon, ui, cli and tui | Any runtime behaviour. Formatting. | Every change |
|
||||
| Build | `npm run build` | All four workspaces compile (the UI also runs `vite build`) | That the *published* package is complete (see Packaging) | Every change |
|
||||
| Repo checks | `npm run test:repo` | Builds the daemon, then runs `node --test --test-concurrency=1 scripts/*.test.mjs`, `scripts/check-first-run-references.mjs`, `scripts/check-docs-guard.mjs`, `mirror-skills --check` (skill homes, generated copies, layout and digests) and `generate-context-packs --check` | Package behaviour | Every change. It matters most when you touch `scripts/`, `docs/` or skills. |
|
||||
| Repo checks | `npm run test:repo` | Builds the daemon, then runs `node --test --test-concurrency=1 scripts/*.test.mjs`, `scripts/check-docs-guard.mjs`, `mirror-skills --check` and `generate-context-packs --check` | Package behaviour | Every change. It matters most when you touch `scripts/`, `docs/` or skills. |
|
||||
| Package suites | `npm run test:workspaces`. One package: `npm run test -w packages/cli`. One file, from the repo root: `npx vitest run packages/cli/test/<file>.test.ts` | Vitest unit and integration tests for daemon, cli and tui. Some of them start real scenario daemons, tmux sessions and stub runners. | The installed package. Real Claude Code or Codex. CI's sandbox conditions (see CI). | Every change (`npm test` covers it) |
|
||||
| Web UI suite | `npm run test:ui` | jsdom unit tests for `packages/ui` | Real browser rendering | When you touch `packages/ui`, or a daemon API the UI reads. The web UI is in maintenance mode, so this suite is advisory locally and is not part of `npm test`. |
|
||||
| Generated files | `npm run mirror-skills:check`, `npm run generate-context-packs:check` (both part of `npm test`) | Shipped skill homes are publishable, generated copies match their homes, all edges match their recorded hashes, and every static context pack passes the daemon's own manifest parser and the leak scan | Whether the skill content is any good | Edit a shipped skill's one in-repo home, run `npm run mirror-skills` to regenerate its other copies and refresh digests, then run the checks and commit the result. The apply reads nothing outside the repository. See "A shipped skill" in [ARCHITECTURE.md](../../ARCHITECTURE.md#a-shipped-skill). |
|
||||
| Generated files | `npm run mirror-skills:check`, `npm run generate-context-packs:check` (both part of `npm test`) | Every copy of each shipped skill matches its recorded hash, and every static context pack passes the daemon's own manifest parser and the leak scan | Whether the skill content is any good | After you edit a shipped skill: edit the same file in every copy that carries it, run `node scripts/regen-edge-digests.mjs`, then the check. The full `npm run mirror-skills` apply needs maintainer-only inputs. See "A shipped skill" in [ARCHITECTURE.md](../../ARCHITECTURE.md#a-shipped-skill). |
|
||||
| Local gate | `npm run gate` | Lint plus `npm test` on a clean tree, tied to `HEAD`, one run per machine at a time, with a JSON receipt | Anything that lint and `npm test` don't already prove | Optional. Useful when several agents share one machine, or when you want a receipt tied to a commit. |
|
||||
| Packaging | `npm run build:package`, `npm run test:tui-package`, `bash scripts/smoke-fresh-install.sh` | The publishable `@openrig/cli` assembles, the packed TUI launches, and a fresh install starts a daemon | Behaviour beyond startup | When you touch dependencies, bin entries, build scripts, or files a package ships |
|
||||
| Stub scenarios, host mode | `node --import tsx packages/daemon/scripts/run-scenarios.mjs [scenario.yaml …]` | A scenario's steps and assertions pass against a scratch daemon, real tmux and `runtime: stub` seats | The installed package. Seeded-regression pairing. Everything under [What a stub can and cannot prove](#what-a-stub-can-and-cannot-prove). | While you write or debug a scenario |
|
||||
@@ -50,36 +50,8 @@ to `main`. In the PR description, say which layers you ran and which you could n
|
||||
| Live-model evals | `npm run eval -w packages/daemon -- --provider rig …` | Whether a real Claude Code seat runs the expected `rig context get <entry>` for natural prompts | Determinism. Codex. Anything without a case. | Changes to shipped skills or context entries meant to steer agents. **Uses provider credits.** |
|
||||
| Testbed runbooks | `docker/testbed/runbooks/` (manual) | The testbed image itself works as a test environment | Product behaviour | Only when you change the testbed image or the container plumbing |
|
||||
|
||||
Some package tests are gated. `OPENRIG_E2E_REAL_CODEX=1` runs two daemon e2e tests against a
|
||||
real Codex (they also need tmux, `codex` and `~/.codex/auth.json`, and they use provider
|
||||
credits). `OPENRIG_REAL_CLAUDE_INTEGRATION=1` enables only a placeholder: it requires
|
||||
`OPENRIG_PARENT_NATIVE_ID` and checks its format, and no real-Claude fork test exists yet.
|
||||
Without tmux, some tmux tests skip and others (such as `transcript-seat-env-native.test.ts`)
|
||||
fail. The CLI's release-tag tests skip without local tags unless `CI=true`, so a green local
|
||||
run without tags has skipped them. CI installs tmux and fetches full history.
|
||||
|
||||
The TUI has its own vitest suite (`npm run test -w packages/tui`, which builds the TUI first)
|
||||
and runs in the `tui` leg of `package-tests`; `npm run test:tui-package` launches the packed
|
||||
TUI in demo mode. The `tui_socket` scenario surface exists, but the only scenarios that use it
|
||||
are not yet runnable checks.
|
||||
|
||||
### Gotchas that cost people time
|
||||
|
||||
- **Running inside a seat.** The root `vitest.config.ts` makes a root-level file run use its
|
||||
package's config. The cli, daemon and TUI configs all run the shared root
|
||||
`test/hermetic-env.setup.ts` before any test file. It clears the inherited `OPENRIG_*` and `RIGGED_*` instance selectors (connection,
|
||||
database, workspace and topology roots, seat identity, bearer tokens), forces a fixture
|
||||
`OPENRIG_HOME` and fails if the home is not fixture-scoped. It also wraps `fetch`, so a real
|
||||
request to anything other than a loopback ephemeral-port fixture or a registered target fails.
|
||||
It points `HOME` and the XDG directories at a fixture user home and clears `CODEX_HOME` and
|
||||
`CLAUDE_CONFIG_DIR`. `OPENRIG_E2E_REAL_CODEX=1` keeps native homes and binaries only for
|
||||
`seat-handover-model-fidelity-e2e.test.ts` and `seat-lifecycle-set-model-resume-e2e.test.ts`;
|
||||
all other files remain isolated. The scenario scaffold always uses fixture homes and runtime stubs.
|
||||
The two native files rely on Vitest's default per-file isolation; runs without it are unsupported.
|
||||
Scenario scaffolds scrub inherited provider roots but preserve those passed in an explicit `baseEnv`.
|
||||
A test can still set its own
|
||||
overrides after setup. The UI suite (jsdom) uses its own `packages/ui/test/setup.ts`.
|
||||
|
||||
- **Stale vendored daemon.** `npm run build:package` leaves an assembled copy of the daemon at
|
||||
`packages/cli/daemon/` (gitignored). If you change daemon source afterwards,
|
||||
`scripts/check-cli-daemon-freshness.test.mjs` inside `test:repo` can fail on the stale copy.
|
||||
@@ -88,11 +60,6 @@ are not yet runnable checks.
|
||||
credentials, and outbound network blocked except to localhost (see below). A test that reads
|
||||
your real home directory, a running daemon, the network or a credential can pass on your
|
||||
machine and fail in CI.
|
||||
- **Mixed fixture clocks.** `compaction-command-submission.test.ts` uses one clock for the
|
||||
enforcer, the transport's injected `now` and sleeps, and its `Date.now` idle deadline. Previously,
|
||||
real-time transport waits could exhaust the fixture's 20 ms budget during a scheduler pause
|
||||
even though the modeled seat was idle. Restore the `Date.now` spy after each test; keep real
|
||||
deadline behavior covered by the transport tests. This changes the fixture, not production timeouts.
|
||||
- **Docs location.** `check-docs-guard` fails if a tracked file under `docs/` sits outside
|
||||
`docs/as-built/`, `docs/reference/` or `docs/releases/`. `docs/DESIGN.md` is the one allowed
|
||||
exception.
|
||||
@@ -109,17 +76,7 @@ credentials are supplied.
|
||||
| `typecheck` | ubuntu | `npm run lint` |
|
||||
| `repo-checks` | ubuntu | `npm run test:repo` |
|
||||
| `package-tests` | macOS, matrix `daemon`, `cli`, `tui`, `ui` (fail-fast off) | Installs tmux, runs `npm ci` and `npm run build`. Then runs `npm run test -w packages/<pkg>` under `env -i` with a scratch `HOME`/`TMPDIR`/`TMUX_TMPDIR` and a `sandbox-exec` profile that blocks outbound network except localhost and the job's own socket directory. `scripts/ci-macos-process-probe.mjs` runs first. |
|
||||
| `linux-seat-environment` | ubuntu | Builds all packages, then runs `seat-env-parent-session.integration.test.ts` with real CLI, daemon, tmux and stub seats. A network namespace has loopback only; tests run as the unprivileged runner user under `env -i` with scratch `HOME`/`TMPDIR`/`TMUX_TMPDIR`. Runs on pull requests and manual dispatch, like `package-tests`. |
|
||||
| `installed-scenario` | ubuntu | `bash scripts/run-pr-scenarios.sh` (fifteen container runs, described below). Uploads `dist/pr-scenarios/` as `installed-scenario-evidence`, including on failure. |
|
||||
|
||||
The Linux seat-environment job covers a gap in the macOS matrix: the integration test
|
||||
reads `/proc/<pid>/environ`, so macOS skips it. It checks both a new tmux server and an
|
||||
existing server carrying a parent's session identity. It verifies the scoped environment,
|
||||
the runtime directory and disabled session-bus default, and tmux's terminal identity in
|
||||
the launched panes; the existing owner session stays unchanged. This adds one focused
|
||||
Linux job to the existing suite. Stub seats prove the environment passed to the pane;
|
||||
native Claude image paste and Shift+Enter handling still need separate verification
|
||||
(see [#2041](https://github.com/mvschwarz/openrig/issues/2041)).
|
||||
| `installed-scenario` | ubuntu | `bash scripts/run-pr-scenarios.sh` (eight container runs, described below). Uploads `dist/pr-scenarios/` as `installed-scenario-evidence`, including on failure. |
|
||||
|
||||
A second workflow, `.github/workflows/portability-report.yml` (job `portability-report`),
|
||||
lists lines your PR adds that contain machine-specific values: credentials, home or temp
|
||||
@@ -142,8 +99,8 @@ repository.
|
||||
- refuses a dirty worktree. Refuses a `node_modules` that is a symlink, or `@openrig/*`
|
||||
workspace links that resolve outside this worktree. Both are common with shared git worktrees.
|
||||
- deletes the stale vendored daemon bundle at `packages/cli/daemon/` before the legs run.
|
||||
- writes `gate-lane-verdict.json` at the repo root, or at `OPENRIG_GATE_VERDICT`, which must
|
||||
point inside the current worktree (a path outside it exits 3 before the legs run). The file holds the `HEAD` SHA, per-leg results and durations, and a note of other
|
||||
- writes `gate-lane-verdict.json` at the repo root (or wherever `OPENRIG_GATE_VERDICT`
|
||||
points). The file holds the `HEAD` SHA, per-leg results and durations, and a note of other
|
||||
`node`/`vitest`/`tsc` processes running at the time. It fails if `HEAD` changes during the
|
||||
run. The file is not gitignored, so don't commit it.
|
||||
|
||||
@@ -158,8 +115,8 @@ Exit codes: 0 pass, 1 a leg failed, 2 lane busy, 3 the runner itself errored.
|
||||
| Piece | Where |
|
||||
|---|---|
|
||||
| `runtime: stub` adapter | `packages/daemon/src/adapters/stub-runtime-adapter.ts`, with `stub-runner.ts` (the process that runs in the pane), `stub-script.ts` (the launch-script format) and `stub-compaction.ts` / `stub-restore.ts` |
|
||||
| Scenario format and runner | `packages/daemon/test/helpers/scenario-*.ts`. Step verbs: `up`, `down`, `send`, `restart`, `daemon`, `seed_regression` are bound. `restore`, `mutate`, `policy` are rejected at load time (`UNBOUND_STEP_VERB`) because the runner has no shipped binding for them; `emit` parses but only `refocus` is bound. Assertion surfaces: `ps`, `queue`, `stream`, `scope`, `pane`, `transcript`, `tui_socket`, `policy_provenance`. |
|
||||
| Scenario library | `packages/test-system/scenarios/`: 20 scenarios, 7 stub topologies, `agents/`, `culture.md`, per-seat stub scripts in `scripts/` |
|
||||
| Scenario format and runner | `packages/daemon/test/helpers/scenario-*.ts`. Step verbs: `up`, `down`, `send`, `restart`, `daemon`, `seed_regression` are bound. `restore`, `emit`, `mutate`, `policy` parse but are unbound. Assertion surfaces: `ps`, `queue`, `stream`, `scope`, `pane`, `transcript`, `tui_socket`, `policy_provenance`. |
|
||||
| Scenario library | `packages/test-system/scenarios/`: 15 scenarios, 7 stub topologies, `agents/`, `culture.md`, per-seat stub scripts in `scripts/` |
|
||||
| Runner fixtures | `packages/daemon/test/fixtures/scenarios/` (`scenario-01-per-seat-scripts`, `scenario-02-baton`, `scenario-10-one-view-state`) |
|
||||
| Host runner | `packages/daemon/scripts/run-scenarios.mjs` |
|
||||
| In-container entry and result check | `packages/test-system/ci/run.mjs`, `packages/test-system/ci/result.mjs` |
|
||||
@@ -190,12 +147,10 @@ node --import tsx packages/daemon/scripts/run-scenarios.mjs packages/daemon/test
|
||||
|
||||
In CI the `installed-scenario` job runs `scripts/run-pr-scenarios.sh` with no arguments:
|
||||
both baton cases (`fixture` = `scenario-02-baton.yaml`, `library` = `queue-baton-survives-restart.yaml`),
|
||||
each run three times as healthy, then lost-baton, then healthy (six containers); the
|
||||
`refocus-parked` effect case runs healthy, seeded, then healthy (three containers); and the
|
||||
six passing-only cases (`transcript` = `transcript-reads-addressed-seat.yaml`, `capture` =
|
||||
`capture-returns-addressed-seat.yaml`, `daemon-restart`, `refocus-active`,
|
||||
`refocus-parked-off`, `prompt-state`) run once each, healthy only (six containers). That is
|
||||
fifteen fresh containers.
|
||||
each run three times as healthy, then lost-baton, then healthy. Then the two stub-script
|
||||
cases (`transcript` = `transcript-reads-addressed-seat.yaml`, `capture` =
|
||||
`capture-returns-addressed-seat.yaml`) run once each, healthy only. That is eight fresh
|
||||
containers.
|
||||
|
||||
To run a case before you push, point `DOCKER_HOST` at a Docker engine you control over SSH:
|
||||
|
||||
@@ -205,14 +160,10 @@ DOCKER_HOST=ssh://<your-host> bash scripts/run-pr-scenarios.sh \
|
||||
--remote --case library --mode healthy --out dist/scenario-check
|
||||
```
|
||||
|
||||
- Options: `--case fixture|library|transcript|capture|daemon-restart|refocus-parked|
|
||||
refocus-active|refocus-parked-off|prompt-state` (default: all nine), `--mode
|
||||
healthy|lost-baton|seeded` (default: healthy, lost-baton, healthy) and `--out <dir>` (default
|
||||
`dist/pr-scenarios`). `--mode` applies to the baton cases (`fixture` and `library`) and to
|
||||
the `refocus-parked` effect case; the six passing-only cases (`transcript`, `capture`,
|
||||
`daemon-restart`, `refocus-active`, `refocus-parked-off`, `prompt-state`) always run once
|
||||
each, healthy. `--mode lost-baton` leaves them out of a full run, and
|
||||
`--case transcript|capture --mode lost-baton` is refused with exit 2. Use a fresh `--out`
|
||||
- Options: `--case fixture|library|transcript|capture` (default: all four), `--mode
|
||||
healthy|lost-baton` (default: healthy, lost-baton, healthy) and `--out <dir>` (default
|
||||
`dist/pr-scenarios`). `--mode` applies to `fixture` and `library`; `transcript` and `capture`
|
||||
always run once, healthy, and `--mode lost-baton` leaves them out. Use a fresh `--out`
|
||||
directory for each run you want to keep.
|
||||
- `--remote` accepts only `ssh://` values for `DOCKER_HOST`, and it refuses if
|
||||
`DOCKER_CONTEXT` is set. The engine must be Linux on amd64 or arm64. The script reads the
|
||||
@@ -270,16 +221,16 @@ The stub does not fabricate product outputs. It runs the real daemon, tmux and C
|
||||
not Claude Code or Codex, and it differs from them in ways that decide what a stub green
|
||||
means:
|
||||
|
||||
| Area | What the stub does at `e8f0ab34` | What that means for your test |
|
||||
| Area | What the stub does at `1347d825` | What that means for your test |
|
||||
|---|---|---|
|
||||
| Consuming a message | `stub-runner.ts` runs its launch script once and then idles. It has no stdin reader, socket or other input channel. The default script prints `[stub] scripted reply: acknowledged` at boot, before anything has been sent. | A pane showing a reply, or your echoed text, does not prove the message was consumed. No stub scenario can currently prove "delivered and answered". Separately, `rig send --verify` means "appeared in the pane" (with transport.verify_input_box on, a Claude Code or Codex send means "the seat was idle before the paste and its input box took the exact text"), not acknowledgement (see `rig send --help`), and the scenario `send` step doesn't pass `--verify` at all. |
|
||||
| Launch path | `StubRuntimeAdapter` types `node <stub-runner> …` into the pane (`tmux.sendText`, then Enter). Claude Code with an explicit permission mode launches through a managed launch (`ClaudeManagedLaunch.prepare`, `tmux.sendShellCommand`). Otherwise Claude Code, Codex and Pi launch through `SeatLaunchEnvironment.command` and `tmux.sendShellCommand`; the stub adapter does not get that environment. The shell-foreground check in `session-transport.ts` (`unverifiedShellForeground`) runs for every runtime except `terminal` and `claude-code`, and only `codex` has a native-process proof; Claude Code ordinary delivery applies its own uncertainty policy at the input boundary. | A stub seat doesn't exercise the seat launch environment, managed launch, wrappers or native-process identity (the class behind #197). Wrapping the stub in a shell wouldn't change that. |
|
||||
| Permissions | `validateNativePermissionSelection` accepts only `codex` and `claude-code`. The stub carries the resolved `floor` / `full_bypass` posture, including one set by a declarative `permission_policy`, into its runner's `--posture` argument and READY line. It ignores non-interruptive launches, and it doesn't exercise Claude or Codex native permission behaviour. | Testing Claude permission modes or per-seat permission selection needs a real runtime. |
|
||||
| Consuming a message | `stub-runner.ts` runs its launch script once and then idles. It has no stdin reader, socket or other input channel. The default script prints `[stub] scripted reply: acknowledged` at boot, before anything has been sent. | A pane showing a reply, or your echoed text, does not prove the message was consumed. No stub scenario can currently prove "delivered and answered". Separately, `rig send --verify` means "appeared in the pane", not acknowledgement (see `rig send --help`), and the scenario `send` step doesn't pass `--verify` at all. |
|
||||
| Launch path | `StubRuntimeAdapter` types `node <stub-runner> …` into the pane (`tmux.sendText`, then Enter). Claude Code with an explicit permission mode launches through a managed launch (`ClaudeManagedLaunch.prepare`, `tmux.sendShellCommand`); without one it uses `sendText`. The shell-foreground check in `session-transport.ts` (`unverifiedShellForeground`) runs for every runtime except `terminal`, but its native-process proof is limited to `codex` and `claude-code`. | A stub seat doesn't exercise wrapper, managed-launch or native-process-identity behaviour (the class behind #197). Wrapping the stub in a shell wouldn't change that. |
|
||||
| Permissions | `validateNativePermissionSelection` accepts only `codex` and `claude-code`. The stub models only the `floor` / `full_bypass` launch posture. | Testing Claude permission modes or per-seat permission selection needs a real runtime. |
|
||||
| Queue pickup and wake | No stub worker reacts to a nudge by claiming an item, working on it and handing it back. | The baton scenarios prove the claim *survives a restart*. They don't prove delivery, pickup or wake. |
|
||||
| Reboot / tmux reset | `daemon: {op: restart}` restarts only the scenario daemon, and the tmux server keeps running. No step resets tmux. | Recycled pane IDs and stale bindings after a real reboot (the class behind #141) are not covered by a daemon restart. |
|
||||
| Multi-rig and same-name identities | The `up` step always uses the scenario's top-level `topology` and ignores a per-step override. No step archives or removes a rig. | Cross-rig scope, same-name generations and archive/remove routing (the class behind #174) need runner work before they can be tested. |
|
||||
| Step-time restore, compaction, mutation, policy | `restore`, `mutate` and `policy` steps are refused at load time (`UNBOUND_STEP_VERB`); `emit` parses but a non-`refocus` behavior throws `UnboundActionError` when the runner reaches it. Behaviours run only from a per-seat launch script (`env.stub_scripts`). A seat `restart` step maps to `rig launch`, which is not native resume or fork. | Step-time compaction and restore, and native resume and fork, are not covered. |
|
||||
| Skill projection | The stub projects skills into `<cwd>/.openrig/stub/skills/`. Claude Code projects a team seat's skills into the seat's generated plugin in OpenRig's state, and into `<cwd>/.claude/skills/` only for a seat without one. | A stub green says nothing about provider-specific projection (the class behind #159). |
|
||||
| Step-time restore, compaction, mutation, policy | `restore`, `emit`, `mutate` and `policy` parse, but the runner throws `UnboundActionError` when it reaches them. Behaviours run only from a per-seat launch script (`env.stub_scripts`). A seat `restart` step maps to `rig launch`, which is not native resume or fork. | Step-time compaction and restore, and native resume and fork, are not covered. |
|
||||
| Skill projection | The stub projects skills into `<cwd>/.openrig/stub/skills/`. Claude Code projects into `<cwd>/.claude/skills/`. | A stub green says nothing about provider-specific projection (the class behind #159). |
|
||||
| Model and provider | No model, no tokens. Stub scripts refuse `usage_limit` because it only exists on real runtimes. | Model behaviour, provider usage limits and real context usage need live evals or a real runtime. |
|
||||
| Platform | CI's scenario job runs in a Linux container. | macOS process behaviour is covered by the macOS `package-tests` jobs, not by scenarios. |
|
||||
|
||||
@@ -287,29 +238,18 @@ The most useful next pieces of harness work, roughly in dependency order:
|
||||
|
||||
1. A stub that consumes input and answers a fresh nonce.
|
||||
2. A model-free test entry point shaped like a provider, that goes through the real native
|
||||
adapter and managed launch. Package tests such as `claude-interactive-launch.test.ts` and
|
||||
the `*-native.test.ts` files already drive the real adapters through tmux against an
|
||||
offline recorder; they prove command resolution and arguments.
|
||||
`claude-executable-foreground.test.ts` holds that recorder open in private Bash, zsh, dash and ksh panes
|
||||
to check parent PID, process-group ownership, tmux's pane command and parent-shell
|
||||
restoration for unmanaged fresh, fork and resume launches. These fixtures do not prove
|
||||
native readiness, history or answers.
|
||||
adapter and managed launch.
|
||||
3. Lifecycle and identity steps (tmux reset, archive/remove).
|
||||
4. Then pickup, wake and restore scenarios.
|
||||
|
||||
### Library status
|
||||
|
||||
Seven library scenarios run in CI: `queue-baton-survives-restart` (since #243) and
|
||||
`refocus-parked-baton` with their seeded pairs, and `transcript-reads-addressed-seat`,
|
||||
`capture-returns-addressed-seat`, `daemon-restart-preserves-team-identity`,
|
||||
`refocus-active-baton` and `refocus-parked-baton-packet-off` in passing form only. The
|
||||
`fixture` case runs the `scenario-02-baton` test fixture through the same seeded pair.
|
||||
Three more, `down-stops-every-seat`, `send-renders-in-addressed-pane` and
|
||||
`up-relaunch-restores-a-two-seat-team`, run with the local runner but not in CI, and
|
||||
`compaction-restore-resumes-role` runs the compaction round-trip's success path the same
|
||||
way. Those ten later scenarios are not in this table; "Status today" under
|
||||
[Help wanted](#help-wanted-command-families-without-a-behavioural-scenario) covers seven
|
||||
of them. The other nine scenarios are authored but not yet runnable as meaningful checks:
|
||||
Three scenarios run in CI: `queue-baton-survives-restart` (since #243) with its seeded pair,
|
||||
and `transcript-reads-addressed-seat` and `capture-returns-addressed-seat` in passing form
|
||||
only. Two more, `down-stops-every-seat` and `send-renders-in-addressed-pane`, run with the
|
||||
local runner but not in CI. Those four later scenarios are not in this table; see "Status
|
||||
today" under [Help wanted](#help-wanted-command-families-without-a-behavioural-scenario). The
|
||||
other ten scenarios are authored but not yet runnable as meaningful checks:
|
||||
|
||||
| Scenario | Why it doesn't run as a check yet | Smallest useful next step |
|
||||
|---|---|---|
|
||||
@@ -318,10 +258,11 @@ of them. The other nine scenarios are authored but not yet runnable as meaningfu
|
||||
| `ps-scope-honesty` | The second `up` reuses the first topology, and the expected match tolerates the other rig | Make `up` honour the per-step topology, then assert the exclusion |
|
||||
| `send-verify-means-rendered` | The `send` step drops `verify`, and the stub has no input loop | Build the input-consuming stub and assert a response derived from the nonce |
|
||||
| `home-divergence-preseed-visible` | The pipeline ignores `env.pre_existing_tmux`, and the default script never prints the expected `trust reached` | Recreate the real HOME split and whatever consumes it |
|
||||
| `compaction-restore-resumes-role` | Step-time `emit` is unbound | Input-triggered hooks plus evidence specific to one seat |
|
||||
| `stream-emit-durable-replay-live` | Step-time `emit` is unbound | Assert the actual stream contract |
|
||||
| `policy-posture-survives-structural-edit` | The validator refuses its `policy` and `mutate` steps at load time (`UNBOUND_STEP_VERB` — no shipped runner binding) | Rewrite around current per-seat permission selection and an observed launch |
|
||||
| `locked-restore-never-permissive` | The validator refuses its `policy` and `restore` steps at load time (`UNBOUND_STEP_VERB` — no shipped runner binding) | Keep the invariant (the selection survives a restore) and use current modes |
|
||||
| `one-view-state-after-mutation-storm` | The validator rejects its bare-list `equals` (`EQUALS_NOT_DECLARATIVE`) and refuses its `mutate` steps at load time (`UNBOUND_STEP_VERB`) | Declare the comparable fields and real mutations |
|
||||
| `policy-posture-survives-structural-edit` | `policy` and `mutate` are unbound | Rewrite around current per-seat permission selection and an observed launch |
|
||||
| `locked-restore-never-permissive` | `policy` and `restore` are unbound | Keep the invariant (the selection survives a restore) and use current modes |
|
||||
| `one-view-state-after-mutation-storm` | The validator rejects its bare-list `equals` (`EQUALS_NOT_DECLARATIVE`), and `mutate` is unbound | Declare the comparable fields and real mutations |
|
||||
| `kill-daemon-mid-handoff` | A pane `send` doesn't create the queue item the next assertion expects, and later assertions use a shape the queue reader doesn't return | Rebuild the setup before treating a red result as meaningful |
|
||||
|
||||
In most of these files, `seed_regression` steps that come *after* the assertions are
|
||||
@@ -347,19 +288,6 @@ above remain pending: pane rendering does not prove input consumption, durable
|
||||
stream replay does not prove live subscription, and this test does not exercise
|
||||
native providers, restore or policy changes.
|
||||
|
||||
`packages/daemon/test/rig-edge-cli.integration.test.ts` uses the same private
|
||||
scenario daemon and tmux helpers for edge repair. It removes a stub seat, re-adds
|
||||
its logical ID with the terminal runtime, then restores its cross-pod edges with one
|
||||
`rig edge add` per edge. It checks repeat IDs and edge counts, refusal without a
|
||||
write, unchanged sibling node/binding identities and pane PIDs, export,
|
||||
snapshot capture and exact rollback. It models the cross-runtime replacement
|
||||
workaround without invoking Claude Code or Codex. The YAML runner has no bound
|
||||
edge/remove/add verbs, so this journey drives the real CLI directly:
|
||||
|
||||
```sh
|
||||
npm test -w @openrig/daemon -- test/rig-edge-cli.integration.test.ts
|
||||
```
|
||||
|
||||
## If your change touches an artery, add or extend a scenario (or say why not)
|
||||
|
||||
[arteries.md](arteries.md) lists the behaviours that everything else depends on. If your
|
||||
@@ -427,8 +355,8 @@ not as current status.
|
||||
## Help wanted: command families without a behavioural scenario
|
||||
|
||||
> This list may be stale. It was taken from the `rig --help` tree of 0.6.3: 85 visible
|
||||
> top-level families. At `e8f0ab34`, `packages/cli/src/index.ts` registers 87 top-level
|
||||
> commands; `roster` and `telemetry` were added since and have no row yet. Before picking one up, check `packages/test-system/scenarios/`, the cases in
|
||||
> top-level families. At `1347d825`, `packages/cli/src/index.ts` registers 85 top-level
|
||||
> commands. Before picking one up, check `packages/test-system/scenarios/`, the cases in
|
||||
> `scripts/run-pr-scenarios.sh`, and the current `rig --help`.
|
||||
> One scenario doesn't cover a family's every option, sequence or platform. A `--help`
|
||||
> check only proves the command is discoverable. Existing unit tests are not counted here.
|
||||
@@ -447,29 +375,12 @@ that seat's `rig transcript --tail 200 --json`. `capture` has partial coverage i
|
||||
pane. The scenario catches a capture that resolves the seat by a prefix match on its member
|
||||
name (so `dev-impl` also matches `dev-impl2`) and takes the first hit, or any resolver that
|
||||
returns the same pane for both seats; it does not exercise a prefix match on the full seat
|
||||
name. All six run with the local runner (`run-scenarios.mjs`). The transcript, capture and daemon
|
||||
scenarios also run in the CI job, in passing form only; the down, send and up scenarios don't.
|
||||
name. All four run with the local runner (`run-scenarios.mjs`). The transcript and capture
|
||||
scenarios also run in the CI job, in passing form only; the down and send scenarios don't.
|
||||
They do not prove that panes are gone or that a seat consumed a message. The transcript
|
||||
case does not establish ordering, uniqueness, sibling-token absence, tail limits or restart
|
||||
persistence. `up` has partial coverage in `up-relaunch-restores-a-two-seat-team.yaml`: a
|
||||
two-seat stub team comes up, goes down, and the same spec starts a new team in place of the
|
||||
stopped one with the same name, exactly two seats, both running, not archived, so a
|
||||
relaunch that re-records the old seats into the team's row fails on the final `ps` counts.
|
||||
It does not prove that conversations survive the round trip (that is the `--existing`
|
||||
restore path), that a seat consumed a message, or that the panes are gone after `down`.
|
||||
`daemon` has partial coverage in `daemon-restart-preserves-team-identity.yaml`: a two-seat
|
||||
stub team is up, the runner restarts the scratch daemon, and `rig ps --json` must report the
|
||||
same name still running with exactly two seats, both running, not archived, so a restart
|
||||
that loses the team's row, or changes its seat counts or status, fails on the post-restart `ps`;
|
||||
`rig down` then records it stopped, so the restart left a governable team. It does not prove
|
||||
that queue items survive the restart (that is `queue-baton-survives-restart.yaml`), that a
|
||||
kill inside a handoff window is reconciled (that is `kill-daemon-mid-handoff.yaml`), the
|
||||
port-and-process half of the row, or that the panes are gone after `down`.
|
||||
`compaction-restore-resumes-role` covers the compaction round-trip's success path: the
|
||||
seat's launch script (delivered through `env.stub_scripts`) fires the real precompact and
|
||||
restore seams in order, and impl's own pane carries the injected directive. It runs with
|
||||
the local runner, not in CI (container mode refuses `env.stub_scripts` loud and named), and
|
||||
its seeded wrong-seat-restore negative case is not armed yet.
|
||||
persistence. `up` and `daemon` are used by the existing scenarios but have no scenario of their
|
||||
own. Everything else has none.
|
||||
|
||||
Before you start, two honest constraints:
|
||||
|
||||
@@ -482,18 +393,17 @@ Before you start, two honest constraints:
|
||||
`contains` is a substring, so "the sibling received nothing", "the panes are gone" or "no
|
||||
duplicates" can't be asserted yet. An exact field value, such as `runningCount: 0` on the
|
||||
`ps` surface, is the closest available form.
|
||||
- The `restart` step runs `rig launch <rig> <node> --json` and passes no other flag; the node
|
||||
is the logical ID (for example `dev.qa`). A stub seat has no resume token. `rig launch` has
|
||||
no `--fresh` option: a deliberate fresh start of a stub seat after `down` goes through
|
||||
`rig up --existing <rig> --fresh <seat>` or `rig seat launch <seat> --fresh --reason "<why>"`, so the
|
||||
`launch` row needs a runner binding to one of those first.
|
||||
- The `restart` step runs `rig launch <rig> <node>` with no flags, and the node is the logical
|
||||
ID (for example `dev.qa`). A stub seat has no resume token, so relaunching it after `down`
|
||||
stops at `awaiting-decision` and asks for `--fresh`. The `launch` row needs that flag passed
|
||||
through first.
|
||||
|
||||
| Group | Family | Proposed first check (observable result) |
|
||||
|---|---|---|
|
||||
| lifecycle | `start` | Restore two stopped stub seats. Both answer distinct fresh nonces, and no second daemon starts. |
|
||||
| lifecycle | `daemon` (partial) | Restart-preserving-the-persisted-team-row is covered by `daemon-restart-preserves-team-identity.yaml`. Next: port and process agreement through public commands, and `stop`, which needs a runner binding. |
|
||||
| lifecycle | `daemon` | start/status/stop/restart. Port, process and persisted queue identity agree through public commands. |
|
||||
| lifecycle | `bootstrap` | Bootstrap a minimal stub spec. Seats come up ready and the selected spec is the one used. |
|
||||
| lifecycle | `up` (partial) | Relaunch-not-duplicating-identities is covered by `up-relaunch-restores-a-two-seat-team.yaml`. Next: each seat consumes its own send, which needs the input-consuming stub. |
|
||||
| lifecycle | `up` | Launch two stub seats. Each consumes its own send. Relaunching doesn't duplicate identities. |
|
||||
| lifecycle | `down` | (partial) Next: its panes are gone, a sibling rig still answers, retained data follows the docs. |
|
||||
| lifecycle | `create` | Create a one-seat rig through the public path. It appears and answers without a hand-written topology. |
|
||||
| lifecycle | `launch` | Fresh, relaunch, resume and fork on provider-shaped fixtures. Correct restored token, one live process. |
|
||||
@@ -592,10 +502,18 @@ How to make a case useful:
|
||||
|
||||
Read these with care. This page notes them and proposes no changes.
|
||||
|
||||
- The headers of `transcript-reads-addressed-seat.yaml` and `capture-returns-addressed-seat.yaml`
|
||||
say "host mode only". Both run in the CI container job, which executes the host-mode pipeline
|
||||
inside the image.
|
||||
- `packages/test-system/README.md`: says the scenarios "DO NOT run" until a runner lands.
|
||||
The runner exists, and three library scenarios run in CI. Its layout lists `fixtures/*.yaml`,
|
||||
a directory that no longer exists (the topologies live in `scenarios/`). It also says the
|
||||
emit behaviours don't exist yet. Launch-script `emit` now exists, but step-time `emit` is
|
||||
still unbound. `packages/test-system/ci/README.md` is the current description of the CI
|
||||
scenario job.
|
||||
- `packages/test-system/scripts/README.md` and `packages/test-system/ROUTING.md` are
|
||||
dependency-routing notes from when the scenarios were first written. Several of the items
|
||||
they list have since landed. Treat them as history.
|
||||
- `packages/test-system/evals/README.md`: says cases are `cases/*.ts`. They are
|
||||
`cases/selection.yaml` and `cases/loading.yaml`. Its "build in progress" status line is old.
|
||||
- `docs/reference/developing.md`: says "There is no external CI at this tip". In fact
|
||||
`.github/workflows/tests.yml` runs on every PR to `main`, and its `package-tests` matrix
|
||||
includes `ui`. Its description of `test:repo` leaves out the `generate-context-packs --check` step.
|
||||
- `docker/testbed/runbooks/`: see above. They are manual procedures that predate the CI job.
|
||||
+2
-2
@@ -11,8 +11,8 @@ applies-when: |
|
||||
named ui/ module.
|
||||
siblings: [README.md, codemap.md, architecture.md]
|
||||
prerequisite-reads: []
|
||||
last-verified-against-source: e8f0ab340db773392ec8be75b072d1c0f3068a50
|
||||
last-updated: 2026-10-08
|
||||
last-verified-against-source: 7eaf524c
|
||||
last-updated: 2026-05-16
|
||||
---
|
||||
|
||||
# ui.md was reorganized into the modular as-built tree
|
||||
|
||||
@@ -6,13 +6,12 @@ topics: [specification-and-bundles, observability]
|
||||
domains: [engineering-advisor, product-advisor]
|
||||
applies-when: |
|
||||
Need to know how the Library (`/specs`) UI is assembled — the spec/skills/
|
||||
plugins surfaces, the spec-review + spec-library flows that feed it, and
|
||||
how seat details open — or where the canonical visual/design-system spec
|
||||
lives.
|
||||
plugins surfaces, the spec-review + spec-library + live-identity flows that
|
||||
feed it — or where the canonical visual/design-system spec lives.
|
||||
siblings: [shell-and-routing.md]
|
||||
prerequisite-reads: [../README.md, shell-and-routing.md]
|
||||
last-verified-against-source: e8f0ab340db773392ec8be75b072d1c0f3068a50
|
||||
last-updated: 2026-10-08
|
||||
last-verified-against-source: 7eaf524c
|
||||
last-updated: 2026-05-16
|
||||
---
|
||||
|
||||
# UI Library/Specs Surfaces + Design-System Pointer
|
||||
@@ -21,122 +20,101 @@ The Library destination keeps `/specs` as the route and presents the product
|
||||
label "Library": specs, applications, context packs, agent specs, agent
|
||||
images, plugins, and skills.
|
||||
|
||||
> Verified against source at `e8f0ab34`; package version 0.6.7. Component and
|
||||
> primitive names below are reconciled against `packages/ui/src/components/`,
|
||||
> not taken on trust from `DESIGN.md`'s lists. The web UI is in maintenance
|
||||
> mode (`docs/reference/developing.md`).
|
||||
> Verified against source at HEAD `7eaf524c`; package version **0.3.1**
|
||||
> (slice-00 §1.1). Component/primitive names below are reconciled against
|
||||
> `packages/ui/src/components/` at HEAD — NOT taken on trust from `ui.md`'s
|
||||
> or `DESIGN.md`'s lists.
|
||||
|
||||
## 1. Library / specs surfaces
|
||||
|
||||
Components in `packages/ui/src/components/specs/`:
|
||||
Components in `packages/ui/src/components/specs/` (re-confirmed at HEAD):
|
||||
|
||||
- `SpecsLibraryPage.tsx` — the `/specs` Library page (also mounted at
|
||||
`/specs/applications`): a sectioned grid of Rig Specs, Workspace Specs
|
||||
(placeholder), Workflow Specs, Context Packs, Agent Specs, Agent Images
|
||||
and Applications, then full-width Plugins and Skills sections.
|
||||
Service-backed rigs (`hasServices`) appear under Applications, not Rig
|
||||
Specs.
|
||||
- `SpecsTreeView.tsx` — the Explorer tree. (`SpecsTable.tsx` is still in
|
||||
the folder but nothing imports it.)
|
||||
- `SkillsIndexPage.tsx`, `SkillDetailPage.tsx` — skills. The Explorer
|
||||
groups skills into category folders; each skill is a single row, not
|
||||
expandable into files. Opening a skill goes to a detail route that
|
||||
defaults to `SKILL.md` (case-insensitive) and renders its own docs
|
||||
browser: a file tree with breadcrumbs beside a viewer, `MarkdownViewer`
|
||||
for `.md`/`.mdx`, `SyntaxHighlight` for other text, preformatted text
|
||||
otherwise. Files come from `/api/skills/:id/files/list` and `/files/read`
|
||||
(`hooks/useSkillFiles.ts`).
|
||||
- `SpecsLibraryPage.tsx` — the `/specs` Library page (unified list:
|
||||
All / Apps / Rigs / Agents; service-backed entries render as `APP`).
|
||||
- `SpecsTable.tsx`, `SpecsTreeView.tsx` — list + Explorer tree.
|
||||
- `SkillsIndexPage.tsx`, `SkillDetailPage.tsx` — folder-based skills.
|
||||
The skill tree treats each skill as a folder; clicking a skill opens a
|
||||
detail route defaulting to `skill.md` case-insensitively, rendered via the
|
||||
shared `FileViewer` in the center workspace (no second in-page file
|
||||
browser — file navigation belongs in the Explorer tree).
|
||||
- `PluginsIndexPage.tsx`, `PluginDetailPage.tsx`, `AgentPluginsList.tsx` —
|
||||
the plugin surfaces.
|
||||
|
||||
Library routes: `/specs`, `/specs/applications`, `/specs/skills`,
|
||||
`/specs/skills/$skillToken`, `/specs/skills/$skillToken/file/$fileToken`,
|
||||
`/specs/plugins`, `/plugins/$pluginId`, `/specs/library/$entryId` (see
|
||||
[`shell-and-routing.md`](shell-and-routing.md) §3).
|
||||
> Drift-note (slice-00 0.3.0-GT seam a): the plugin primitive is a **0.3.1**
|
||||
> feature (git-ancestry proven; absent at `v0.3.0`, present at `v0.3.1`). Do
|
||||
> NOT back-attribute the `/specs/plugins`, `/plugins/$pluginId` routes or
|
||||
> these plugin components to 0.3.0. `ui.md` (which predates 0.3.x) has **no
|
||||
> narrative for plugins at all** — these surfaces are authored from source +
|
||||
> the slice-00 0.3.0-GT seam, not migrated.
|
||||
|
||||
> The plugin primitive is a **0.3.1** feature (absent at `v0.3.0`, present
|
||||
> at `v0.3.1`). Do NOT back-attribute the `/specs/plugins`,
|
||||
> `/plugins/$pluginId` routes or these plugin components to 0.3.0.
|
||||
## 2. Spec review / library / live-identity flows
|
||||
|
||||
## 2. Spec review / library flows and seat details
|
||||
|
||||
These daemon-backed flows feed the Library UI:
|
||||
These daemon-backed flows feed the Library UI (`architecture.md` §6
|
||||
"Spec review and spec library flow", "Live identity / specs UI flow",
|
||||
re-confirmed accurate at HEAD):
|
||||
|
||||
- **Raw YAML preview:** UI/CLI posts YAML to `/api/specs/review/rig` or
|
||||
`/api/specs/review/agent`; `SpecReviewService` parses/validates/returns
|
||||
structured review models; UI renders them through `RigSpecDisplay` /
|
||||
`AgentSpecDisplay` (the same primitives reused for draft preview, library
|
||||
review, and live details).
|
||||
review, and live full-details).
|
||||
- **Filesystem-backed library:** `SpecLibraryService` scans builtin + user
|
||||
roots (`packages/daemon/specs`, `~/.openrig/specs`, legacy fallback
|
||||
`~/.rigged/specs`); each YAML is classified via structured review;
|
||||
service-backed rigs are marked `hasServices`. Each list request also
|
||||
merges workflow entries from the workflow-spec cache.
|
||||
`/api/specs/library` serves list, get, review and sync, plus
|
||||
`DELETE /:id`, `POST /:id/rename` and GET/POST/DELETE `/active-lens`.
|
||||
On a non-local host, list and review reads carry `?host=<id>`; the
|
||||
active lens stays local.
|
||||
- **CLI mirror:** `rig specs ls/show/preview/add/sync/remove/rename`;
|
||||
`rig specs add` installs a single YAML spec or a full spec directory;
|
||||
`rig up` / `rig bootstrap` resolve name-shaped sources through the
|
||||
library.
|
||||
- **Seat details:** graph, tree and table clicks navigate to
|
||||
`/topology/seat/$rigId/$logicalId`, which renders `LiveNodeDetails`
|
||||
(Overview and Details tabs). The shared drawer no longer has a
|
||||
seat-detail kind; its kinds are system, log, status, discovery, qitem,
|
||||
file and sub-spec. The legacy `/rigs/$rigId/nodes/$logicalId` route also
|
||||
renders `LiveNodeDetails`, but nothing in the UI links to it.
|
||||
|
||||
> Source: `packages/daemon/src/routes/spec-library.ts`;
|
||||
> `packages/ui/src/hooks/useSpecLibrary.ts`; `packages/cli/src/commands/specs.ts`
|
||||
> (`remove`, `rename`); `packages/ui/src/components/SharedDetailDrawer.tsx`
|
||||
> (viewer kinds; seat-detail retired).
|
||||
service-backed rigs are marked `hasServices`; `/api/specs/library` serves
|
||||
list/get/review/sync.
|
||||
- **CLI mirror:** `rig specs ls/show/preview/add/sync`; `rig specs add`
|
||||
installs a single YAML spec or a full spec directory; `rig up` /
|
||||
`rig bootstrap` resolve library names before other source kinds.
|
||||
- **Live identity:** Explorer/graph selection opens the shared right drawer
|
||||
(runtime-first node detail: live identity, peers, directional edges,
|
||||
transcript helpers, compact spec summary); `Open Full Details` navigates to
|
||||
`/rigs/$rigId/nodes/$logicalId` in the center workspace.
|
||||
|
||||
## 3. UI primitive inventory (reconciled against source)
|
||||
|
||||
> Drift-fix — `ui.md` "Design Primitives" (L75–107) omits `ProjectPill`.
|
||||
> `docs/DESIGN.md` L195 lists it; re-confirmed at HEAD it is a real export
|
||||
> (`packages/ui/src/components/project/ProjectMetaPrimitives.tsx:196`
|
||||
> `export function ProjectPill`). Reconciled inventory below is from source,
|
||||
> not from either doc's list.
|
||||
|
||||
- **Vellum/base** (`components/ui/`): `VellumCard`, `VellumSheet`,
|
||||
`RegistrationMarks`, `StatusPip`, `SectionHeader`, `EmptyState`,
|
||||
`Button`, `Tabs`, `Table`, form controls, plus `rig-stamp.tsx`
|
||||
(`RigStamp`).
|
||||
- **Graphics** (`components/graphics/RuntimeMark.tsx`): `RuntimeMark`,
|
||||
`RuntimeBadge`, `ToolMark`, `ToolBadge`, `ActorMark`,
|
||||
(`RigStamp`) — present at HEAD; not in ui.md's list.
|
||||
- **Graphics** (`components/graphics/RuntimeMark.tsx`, exports re-confirmed):
|
||||
`RuntimeMark`, `RuntimeBadge`, `ToolMark`, `ToolBadge`, `ActorMark`,
|
||||
`OperatorMoodMark`; normalization in `lib/runtime-brand.ts` +
|
||||
`lib/tool-brand.ts`. Runtime brands are Claude Code, Codex, Pi ("Pi"),
|
||||
OMP ("Oh My Pi", short "OMP"), terminal and unknown; `ActorMark` reuses
|
||||
the runtime marks for recognized runtimes.
|
||||
- **Project metadata** (`components/project/ProjectMetaPrimitives.tsx`):
|
||||
`ProjectPill` (`:199`), `EventBadge` (`:227`), `QueueStateBadge` (`:231`),
|
||||
`TagPill` (`:277`), `ActorChip` (`:286`), `DateChip` (`:306`),
|
||||
`FlowChips` (`:318`), `ProofThumbnailGrid` (`:337`), `ProofPacketHeader`
|
||||
(`:383`) — plus `QueueCountIcon` / `StatusDot`.
|
||||
`lib/tool-brand.ts`.
|
||||
- **Project metadata** (`components/project/ProjectMetaPrimitives.tsx`,
|
||||
exports re-confirmed): `ProjectPill` (`:196`), `EventBadge` (`:224`),
|
||||
`QueueStateBadge` (`:228`), `TagPill` (`:274`), `ActorChip` (`:283`),
|
||||
`DateChip` (`:303`), `FlowChips` (`:315`), `ProofThumbnailGrid` (`:334`),
|
||||
`ProofPacketHeader` (`:380`) — plus `QueueCountIcon` / `StatusDot` (in
|
||||
source, not in ui.md/DESIGN.md primitive lists).
|
||||
- **Viewers**: `FileViewer` (`components/drawer-viewers/FileViewer.tsx`),
|
||||
`MarkdownViewer` (`components/markdown/MarkdownViewer.tsx`),
|
||||
`ProofImageViewer` and `Lightbox` (`components/project/`),
|
||||
`SessionPreviewPane` (`components/preview/`).
|
||||
- **Themes** (`lib/theme.ts`): Vellum Light, Vellum Dark and System
|
||||
(default `system`, following the OS colour scheme), stored under the
|
||||
`openrig.theme` localStorage key. `applyTheme` toggles a `.dark` class
|
||||
on `<html>`, which switches to the `.dark` token block in `globals.css`.
|
||||
`ThemeProvider` is mounted in `main.tsx`, `ThemeSelector` in the
|
||||
AppShell top bar, and a pre-paint script in `index.html` mirrors the
|
||||
storage key.
|
||||
`ProofImageViewer`, `SessionPreviewPane` (`components/preview/`).
|
||||
|
||||
## 4. Design-system pointer (NOT a copy — Q1)
|
||||
|
||||
The canonical OpenRig visual/design system is **`docs/DESIGN.md`** (at the
|
||||
repo `docs/` root, NOT under `docs/as-built/`). Q1 is ratified: DESIGN.md
|
||||
stays at root (the as-built reorganization left it byte-identical), and this
|
||||
module **points to it rather than copying it**. DESIGN.md is the source for: Vellum-paper vs
|
||||
Black-glass surface languages, colour tokens (`packages/ui/src/globals.css`
|
||||
+ `tailwind.config.ts`), typography (`font-body` Inter / `font-headline`
|
||||
Space Grotesk / `font-mono` JetBrains Mono), layout (48px rail + Explorer +
|
||||
center + drawer + preview stack), the core-primitive list, the graphics
|
||||
system, and the interaction/motion/accessibility/do-and-do-not rules.
|
||||
stays at root, byte-identical, and this module **points to it rather than
|
||||
copying it**. DESIGN.md is the source for: Vellum-paper vs Black-glass
|
||||
surface languages, colour tokens (`packages/ui/src/globals.css` +
|
||||
`tailwind.config.ts`), typography (`font-body` Inter / `font-headline` Space
|
||||
Grotesk / `font-mono` JetBrains Mono), layout (48px rail + Explorer + center
|
||||
+ drawer + preview stack), the core-primitive list, the graphics system, and
|
||||
the interaction/motion/accessibility/do-and-do-not rules.
|
||||
|
||||
> Reconciliation note: every primitive DESIGN.md names (Vellum, Graphics,
|
||||
> Project-metadata, Topology, Preview) resolves to a real export at the
|
||||
> stamped commit. Do not duplicate its content here; read `docs/DESIGN.md`
|
||||
> directly for the visual spec.
|
||||
> Reconciliation note: DESIGN.md's primitive lists were independently
|
||||
> verified against `packages/ui/src/components/` at HEAD — every primitive
|
||||
> DESIGN.md names (Vellum, Graphics, Project-metadata, Topology, Preview)
|
||||
> resolves to a real export at HEAD. DESIGN.md is accurate and carries no
|
||||
> slice-00 numeric drift, so it is referenced as-is. Do not duplicate its
|
||||
> content here; read `docs/DESIGN.md` directly for the visual spec.
|
||||
|
||||
## See also
|
||||
|
||||
|
||||
@@ -6,375 +6,428 @@ topics: [observability, coordination]
|
||||
domains: [engineering-advisor, product-advisor, operating-advisor]
|
||||
applies-when: |
|
||||
Need to know how the operator-facing destination surfaces are built —
|
||||
the For-You attention feed (5-card classifier, attention merge, verb
|
||||
actions), the Project workspace/mission/slice scope pages (tabbed
|
||||
rollups), and the Dashboard launcher. The web UI is in maintenance mode;
|
||||
claims are sourced to file and symbol (and line where verified) at the
|
||||
stamped commit.
|
||||
the For-You attention feed (5-card classifier + verb actions), the
|
||||
Project workspace/mission/slice scope pages (tabbed rollups), and the
|
||||
Dashboard landing surface on the vellum brand system. Author-mode
|
||||
module — ui.md prose for these surfaces predates 0.3.x; every claim is
|
||||
sourced to file:line at HEAD.
|
||||
siblings: [shell-and-routing.md, ../architecture/mission-control.md]
|
||||
prerequisite-reads: [../README.md, shell-and-routing.md]
|
||||
last-verified-against-source: e8f0ab340db773392ec8be75b072d1c0f3068a50
|
||||
last-updated: 2026-10-08
|
||||
last-verified-against-source: 7eaf524c
|
||||
last-updated: 2026-07-06
|
||||
---
|
||||
|
||||
# UI Project Observability, For You, Dashboard
|
||||
|
||||
The three operator-facing destination surfaces: **For You** (`/for-you`,
|
||||
the attention feed), **Project** (`/project*`, the workspace/mission/slice
|
||||
scope pages), and the **Dashboard** (`/`, the launcher). All read live
|
||||
daemon state. For You persists two dismissal sets in localStorage; shared
|
||||
shell preferences include the theme choice (see
|
||||
[`library-specs-and-design-system.md`](library-specs-and-design-system.md))
|
||||
and the maintenance-notice dismissal (see
|
||||
[`shell-and-routing.md`](shell-and-routing.md)).
|
||||
scope pages), and the **Dashboard** (`/`, the landing surface on the
|
||||
vellum brand system). All read live daemon state; none adds UI-local
|
||||
persistence beyond per-event soft-dismiss.
|
||||
|
||||
> Paths are relative to `packages/ui/src/` unless prefixed `docs/` or
|
||||
> `packages/`. Verified at `e8f0ab34` (package version 0.6.7). The web UI
|
||||
> is in maintenance mode (`docs/reference/developing.md`); this page
|
||||
> records what ships, not a roadmap.
|
||||
> **AUTHOR-HEAVY module.** `ui.md`'s Project Observability / For You /
|
||||
> Graphics-Layer sections are thin and predate the 0.3.1 dashboard/vellum
|
||||
> brand refresh. Every load-bearing claim carries `> Source: <file:line>
|
||||
> @HEAD`; ambiguity is declared as an OPEN item, never smoothed. Paths
|
||||
> are relative to `packages/ui/src/` unless prefixed `docs/`.
|
||||
>
|
||||
> Verified at HEAD `7eaf524c` (`git describe` → `v0.3.1-6-g7eaf524c`).
|
||||
> Package version **0.3.1**; HEAD carries 6 unreleased release-0.3.2
|
||||
> commits; no `v0.3.2` tag (daemon-core.md; slice-00 §1.1).
|
||||
|
||||
## 0. Release attribution (forensic seam)
|
||||
## 0. Release attribution (forensic seam — read first)
|
||||
|
||||
Checked via `git cat-file -e <tag>:<path>`:
|
||||
Re-verified at HEAD via `git cat-file -e <tag>:<path>`:
|
||||
|
||||
| Layer | Release | Forensic proof |
|
||||
| Layer | Release | Forensic proof @HEAD |
|
||||
|---|---|---|
|
||||
| Project-observability foundation (For-You feed, feed-classifier, project scope pages, the Mission Control 7-verb vocabulary) | **0.3.0** | `v0.3.0:components/for-you/Feed.tsx`, `v0.3.0:lib/feed-classifier.ts`, `v0.3.0:components/project/ScopePages.tsx`, `v0.3.0:components/mission-control/components/VerbActions.tsx` all resolve at `v0.3.0` |
|
||||
| Vellum **brand-identity system** (`dashboard/vellum/*`: CornerBracket, VellumDestinationCard, marks, graphics, barrel) | **0.3.1, NOT 0.3.0** | `git cat-file -e v0.3.0:packages/ui/src/components/dashboard/vellum/index.ts` fails; `v0.3.1:` resolves |
|
||||
| Project-observability foundation (For-You feed, feed-classifier, project scope pages, the Mission Control 7-verb vocabulary) | **0.3.0** | `v0.3.0:components/for-you/Feed.tsx`, `v0.3.0:lib/feed-classifier.ts`, `v0.3.0:components/project/ScopePages.tsx`, `v0.3.0:components/mission-control/components/VerbActions.tsx` all resolve at `v0.3.0` (slice-00 0.3.0-GT §1.5/§1.6/§1.7) |
|
||||
| Vellum **brand-identity system** the Dashboard/For-You now render on (`dashboard/vellum/*`: CornerBracket, VellumDestinationCard, marks, graphics, single-source-of-truth barrel) | **0.3.1, NOT 0.3.0** | `git cat-file -e v0.3.0:components/dashboard/vellum/index.ts` → **ABSENT** ("exists on disk, but not in 'v0.3.0'"); `v0.3.1:` → present (slice-00 0.3.0-GT seam (b); §2 rows 1/2) |
|
||||
|
||||
Vellum surface *primitives* (`components/ui/vellum-*.tsx`) shipped 0.3.0;
|
||||
the brand system under `dashboard/vellum/` is 0.3.1. Do not back-attribute
|
||||
the brand system to 0.3.0.
|
||||
> Source: re-run at HEAD `7eaf524c` —
|
||||
> `git cat-file -e v0.3.0:packages/ui/src/components/dashboard/vellum/index.ts`
|
||||
> fails; `v0.3.0:.../for-you/Feed.tsx`, `.../lib/feed-classifier.ts`,
|
||||
> `.../project/ScopePages.tsx`, `.../mission-control/components/VerbActions.tsx`
|
||||
> all resolve at `v0.3.0`. Vellum surface *primitives*
|
||||
> (`components/ui/vellum-*.tsx`) shipped 0.3.0; the coherent vellum
|
||||
> *brand system* under `dashboard/vellum/` is 0.3.1 — slice-00 0.3.0-GT
|
||||
> seam (b) is the exact split. **Do not back-attribute the vellum brand
|
||||
> system to 0.3.0.**
|
||||
|
||||
## 1. Route reality
|
||||
## 1. Route reality (source-verified at `routes.tsx`@HEAD — BINDING)
|
||||
|
||||
Verified at `routes.tsx` (605 lines):
|
||||
Before narrating any surface, each route was verified at
|
||||
`packages/ui/src/routes.tsx`@HEAD (542 lines). The Phase-8.1 survey's
|
||||
"missing route" expectations are grep-derived and partially wrong; this
|
||||
table is authored from `routes.tsx` reality, not the survey:
|
||||
|
||||
| Path | Reality | Component | Source |
|
||||
| Path | Reality @HEAD | Component | Source |
|
||||
|---|---|---|---|
|
||||
| `/` (index) | destination route | `Dashboard` | `routes.tsx:96-100` |
|
||||
| `/for-you` | destination route | `Feed` | `routes.tsx:130-134` |
|
||||
| `/project` | destination route | `WorkspaceScopePage` | `routes.tsx:136-140` |
|
||||
| `/project/mission/$missionId` | destination route | `MissionScopePage` | `routes.tsx:142-146` |
|
||||
| `/project/slice/$sliceId` | destination route | `SliceScopePage` | `routes.tsx:148-152` |
|
||||
| `/mission-control` | redirect stub to `/for-you` | `() => <Navigate to="/for-you">` | `routes.tsx:496-500` |
|
||||
| `/slices` | redirect stub to `/project` | `() => <Navigate to="/project">` | `routes.tsx:503-507` |
|
||||
| `/slices/$name` | redirect stub to `/project/slice/$sliceId` | `useParams` → `<Navigate>` | `routes.tsx:509-516` |
|
||||
| `/progress` | redirect stub to `/project` | `() => <Navigate to="/project">` | `routes.tsx:519-523` |
|
||||
| `/steering` | redirect stub to `/project` | `() => <Navigate to="/project">` | `routes.tsx:526-530` |
|
||||
| `/markdown` | **not a route** — `MarkdownViewer` is a component | (no route) | no `path: "/markdown"` in `routes.tsx` |
|
||||
| `/for-you` | **REAL destination route** | `Feed` | `routes.tsx:122-126` |
|
||||
| `/project` | **REAL destination route** | `WorkspaceScopePage` | `routes.tsx:128-132` |
|
||||
| `/project/mission/$missionId` | **REAL destination route** | `MissionScopePage` | `routes.tsx:134-138` |
|
||||
| `/project/slice/$sliceId` | **REAL destination route** | `SliceScopePage` | `routes.tsx:140-144` |
|
||||
| `/` (index) | **REAL destination route** | `Dashboard` | `routes.tsx:88-92` |
|
||||
| `/mission-control` | **DELETED `<Navigate to="/for-you">` redirect-stub** | `() => <Navigate to="/for-you">` | `routes.tsx:440-444` |
|
||||
| `/progress` | **`<Navigate to="/project">` redirect-stub** (folds into Project tabs) | `() => <Navigate to="/project">` | `routes.tsx:463-467` |
|
||||
| `/slices` | **DELETED `<Navigate to="/project">` redirect-stub** | `() => <Navigate to="/project">` | `routes.tsx:447-451` |
|
||||
| `/slices/$name` | **`<Navigate to="/project/slice/$sliceId">` redirect-stub** | `useParams` → `<Navigate>` | `routes.tsx:453-460` |
|
||||
| `/steering` | **`<Navigate to="/project">` redirect-stub** | `() => <Navigate to="/project">` | `routes.tsx:470-474` |
|
||||
| `/markdown` | **NOT a route** — `MarkdownViewer` is a component used inside `MissionScopePage` | (no route) | grep `routes.tsx`@HEAD: zero `path: "/markdown"` |
|
||||
|
||||
> Source: component imports `routes.tsx:42-43` (`Dashboard`, `Feed`),
|
||||
> `:61-65` (`WorkspaceScopePage`/`MissionScopePage`/`SliceScopePage` from
|
||||
> `components/project/ScopePages.js`).
|
||||
> Source: `routes.tsx:88-92`,`:122-144`,`:440-474` @HEAD; component
|
||||
> imports `routes.tsx:40-41` (`Dashboard`, `Feed`), `:60-63`
|
||||
> (`WorkspaceScopePage`/`MissionScopePage`/`SliceScopePage` from
|
||||
> `components/project/ScopePages.js`) @HEAD.
|
||||
|
||||
The review altitudes `/agents` (`RigAgentsPage`) and `/fleet` (`FleetPage`)
|
||||
are listed in [`shell-and-routing.md`](shell-and-routing.md).
|
||||
|
||||
> **Route-reality contract:** the **Mission Control *system*** lives in the
|
||||
> daemon (see `../architecture/mission-control.md`); `/mission-control` is
|
||||
> a redirect stub, not a UI destination. The 7-verb *action vocabulary*
|
||||
> surfaces here via `VerbActions` in For-You cards. `/progress`, `/slices`
|
||||
> and `/steering` fold into `/project` tabs.
|
||||
> **Route-reality contract (slice-08 §10.7):** the **Mission Control
|
||||
> *system*** lives at daemon/PL-005 (see `../architecture/mission-control.md`)
|
||||
> — `/mission-control` is **NOT a UI destination**; it is a deleted
|
||||
> redirect-stub (SC-18). The 7-verb *action vocabulary* surfaces in this
|
||||
> module via `VerbActions` embedded in For-You cards, but the system
|
||||
> itself is not this module's subject. `/progress`, `/slices`,
|
||||
> `/steering` all fold into `/project` tabs — they are redirect-stubs,
|
||||
> not surfaces to narrate.
|
||||
|
||||
## 2. For You — the attention feed (`/for-you` → `Feed`)
|
||||
|
||||
`Feed` is the operator's attention surface: decision cards first, then the
|
||||
rest newest-first, subscription- and lens-filtered and soft-dismissable.
|
||||
Header reads `Attention` / `For You`; max width 720px. A plain-language
|
||||
`LevelControl` (All activity / Highlights / Needs you) sits at the top of
|
||||
the feed over the same subscription toggles.
|
||||
`Feed` is the operator's attention surface: a chronologically-sorted,
|
||||
subscription-filtered, soft-dismissable card stream over the live
|
||||
activity feed. Header reads `Attention` / `For You`; max width 720px.
|
||||
|
||||
> Source: `components/for-you/Feed.tsx` (`data-testid="for-you-feed"`,
|
||||
> max-w-720 header; `LevelControl` in `feed-level-control`; design note
|
||||
> `:3-12`); `lib/feed-levels.ts` `FEED_LEVEL_LABELS`.
|
||||
> Source: `components/for-you/Feed.tsx:364-369` (`data-testid="for-you-feed"`,
|
||||
> max-w-720 + `For You` header), feed-centerpiece design note `:3-12`
|
||||
> (PRIMARY UX = the feed; subscriptions NOT dominating — LOAD-BEARING
|
||||
> SC-16) @HEAD.
|
||||
|
||||
### 2.1 The 5-card classifier (0.3.0 spine)
|
||||
|
||||
`classifyFeed(events)` maps every `ActivityEvent` to one of five
|
||||
`classifyFeed(events)` maps every `ActivityEvent` to exactly one of five
|
||||
`FeedCardKind` values — `action-required`, `approval`, `shipped`,
|
||||
`progress`, `observation` — sorted by `receivedAt` descending. **Nothing is
|
||||
silently dropped**: an unmatched event type falls through to
|
||||
`observation`. Queue events are sub-classified by
|
||||
`queueKind(type, state, tier)`: `*.closed` → shipped;
|
||||
`qitem.closure_overdue` / `inbox.denied` → action-required; tier
|
||||
`human-gate` → **approval**; state `pending-approval` → action-required;
|
||||
`closeout-pending-ratify` → approval; `done|closed|completed|shipped` →
|
||||
shipped; otherwise progress. A human-seat destination forces
|
||||
`action-required` unless the card is already an approval.
|
||||
`progress`, `observation` — then sorts by `receivedAt` descending.
|
||||
**Nothing is silently dropped**: any unmatched event type falls through
|
||||
to `observation`. Queue-visibility events are sub-classified by
|
||||
`queueKind(type, state)` (e.g. `*.closed` → shipped; `human-gate` /
|
||||
`pending-approval` → action-required; `closeout-pending-ratify` →
|
||||
approval); a human-seat destination forces `action-required`.
|
||||
|
||||
> Source: `lib/feed-classifier.ts` — `FeedCardKind` `:10-15`, `queueKind`
|
||||
> `:105-129`, `isHumanSeat`, `classifyEvent` (approval-preserving
|
||||
> human-seat override; default-observation fallthrough), `classifyFeed`,
|
||||
> `sortFeedByDecisionBand`.
|
||||
> Source: `lib/feed-classifier.ts:9-14` (`FeedCardKind` union),
|
||||
> `classifyEvent` `:145-218` (default-observation fallthrough L216-217),
|
||||
> `queueKind` `:93-110`, `classifyFeed` `:220-223` (receivedAt-desc sort),
|
||||
> `isHumanSeat` `:141-144` @HEAD.
|
||||
|
||||
### 2.2 The feed pipeline
|
||||
The feed pipeline (`Feed.tsx`): `classifyFeed` → cap at
|
||||
`HISTORY_LIMIT = 50` → hydrate each card's kind from the live queue-item
|
||||
map + action-audit (`hydratedCardKind`: a recorded outcome on an
|
||||
action/approval card → `approval`; a `done|closed|completed` qitem →
|
||||
`shipped`) → **subscription filter** (`isCardKindSubscribed` against the
|
||||
5 `feed.subscriptions.*` config keys; `action-required` is always
|
||||
visible, `observation` only when the audit subscription is on) → the
|
||||
transient **lens-chip** filter (All / Action req / Approvals / Shipped /
|
||||
Progress / Audit; not persisted) → per-event-seq soft-dismiss filter.
|
||||
|
||||
1. **Event cards:** `classifyFeed(events)` capped at `HISTORY_LIMIT = 50`.
|
||||
2. **Attention merge:** daemon attention rows (`useAttentionItems(50, …)`:
|
||||
`GET /api/queue/list?attention=1…`, or `GET /api/queue/attention-aggregate`
|
||||
when a remote host subscription is on) and needs-input seats
|
||||
(`useNeedsInputSeats`) become cards, and `mergeAttentionIntoFeed` lets a
|
||||
queue-derived card supersede a matching event-derived **action-required
|
||||
or approval** card; shipped, progress and observation event cards for the
|
||||
same qitem remain.
|
||||
3. **Decision-band sort:** `sortFeedByDecisionBand` lifts every
|
||||
action-required and approval card above the rest, newest-first within
|
||||
each band.
|
||||
4. **Hydration:** `hydratedCardKind` re-reads each card against the live
|
||||
queue item and the action audit: a recorded outcome on an
|
||||
action/approval card → `approval`; tier `human-gate` → `approval`; a
|
||||
`done|closed|completed` item → `shipped`; a human-seat destination →
|
||||
`action-required`.
|
||||
5. **Filters, in order:** subscription (`isCardKindSubscribed`;
|
||||
`action-required` always visible, `observation` only with the audit
|
||||
subscription), the transient lens chips (All / Action req / Approvals /
|
||||
Shipped / Progress / Audit), a per-host filter, then dismissal.
|
||||
Event cards dismiss by event seq (`forYou.dismissedSeqs`); queue-derived
|
||||
cards dismiss by card id (`forYou.dismissedCardIds`); both are
|
||||
localStorage-backed.
|
||||
> Source: `components/for-you/Feed.tsx:63` (`HISTORY_LIMIT = 50`),
|
||||
> `:238` (`classifyFeed(events).slice(0, HISTORY_LIMIT)`),
|
||||
> `hydratedCardKind` `:156-180`, subscription+lens+dismiss pipeline
|
||||
> `:269-285` (subscription FIRST L280-282; lens L283; dismiss L284),
|
||||
> `LENS_CHIPS` `:54-61` @HEAD;
|
||||
> subscription forced/default rules `Feed.tsx:3-12` (action_required
|
||||
> forced ON L9; observation gated on audit_log L10) @HEAD.
|
||||
|
||||
> Source: `components/for-you/Feed.tsx` — `LENS_CHIPS` `:60-67`,
|
||||
> `HISTORY_LIMIT` `:69`, `hydratedCardKind` `:167-186`, attention merge and
|
||||
> sort `:244-276`, dismiss hooks `:285`/`:294`, filter pipeline `:334-356`;
|
||||
> `hooks/useAttentionItems.ts`, `hooks/useNeedsInputSeats.ts`,
|
||||
> `lib/attention-feed.ts` (`mergeAttentionIntoFeed`, `attentionKindFor`),
|
||||
> `hooks/useDismissedSeqs.ts`, `hooks/useDismissedCardIds.ts`.
|
||||
### 2.2 Queue-item hydration + proof previews
|
||||
|
||||
With one or more remote host subscriptions enabled, the feed shows host
|
||||
chips and status rows, cards carry a host chip, and verbs forward the
|
||||
card's `hostId` (`Feed.tsx` host filter; `hooks/useFeedSubscriptions.ts`
|
||||
key `feed.subscriptions.<hostId>.enabled`; `VerbActions.tsx`).
|
||||
For cards carrying a `qitemId` payload, `useQueueItemMap` hydrates the
|
||||
full queue-item body; for `shipped` cards `sliceForCard` matches a slice
|
||||
by tag/text and `proofPreviewForSlice` pulls the first proof packet with
|
||||
screenshots so the card renders an inline `ProofThumbnailGrid` →
|
||||
`ProofImageViewer`. This is the slice-00 §1.5 "queue cards hydrate qitem
|
||||
bodies + proof previews" foundation, live-wired.
|
||||
|
||||
### 2.3 Queue-item hydration + proof previews
|
||||
> Source: `components/for-you/Feed.tsx:263` (`useQueueItemMap`),
|
||||
> `sliceForCard` `:182-201`, `proofPreviewForSlice` `:203-213`,
|
||||
> per-card proof wiring `:421-427`; `FeedCard.tsx` proof block
|
||||
> `:453-471` (`ProofPacketHeader`+`ProofThumbnailGrid`),
|
||||
> `ProofImageViewer` `:521` @HEAD.
|
||||
|
||||
For cards carrying a `qitemId`, `useQueueItemMap` hydrates the queue item;
|
||||
for `shipped` cards `sliceForCard` matches a slice by tag/text and
|
||||
`proofPreviewForSlice` pulls the first proof packet with screenshots, so
|
||||
the card renders an inline `ProofThumbnailGrid` → `ProofImageViewer`.
|
||||
### 2.3 Verb actions on action/approval cards (the 7-verb system; OPEN-3)
|
||||
|
||||
> Source: `components/for-you/Feed.tsx` (`useQueueItemMap`,
|
||||
> `sliceForCard`, `proofPreviewForSlice`); `FeedCard.tsx` proof block and
|
||||
> `<ProofImageViewer>`.
|
||||
|
||||
### 2.4 Verb actions on action/approval cards
|
||||
|
||||
The **canonical Mission Control action vocabulary is the 7-verb system** —
|
||||
An actionable card (`action-required` or `approval`, no recorded
|
||||
outcome, non-terminal qitem) embeds `VerbActions`. The **canonical
|
||||
Mission Control action vocabulary is the 7-verb system** —
|
||||
`MISSION_CONTROL_VERBS = [approve, deny, route, annotate, hold, drop,
|
||||
handoff]`. `VerbActions` defaults to all seven
|
||||
(`enabledVerbs = [...MISSION_CONTROL_VERBS]`); route/handoff need a
|
||||
destination, annotate an annotation, hold/drop a reason.
|
||||
handoff]` — defined at the Mission Control system level (slice-00
|
||||
0.3.0-GT §1.6/seam (c): the vocabulary *originates in 0.3.0 source*).
|
||||
|
||||
> Source: `components/mission-control/hooks/useMissionControlAction.ts:5-15`;
|
||||
> `components/mission-control/components/VerbActions.tsx` (`enabledVerbs`
|
||||
> default `:108`).
|
||||
> Source: `components/mission-control/hooks/useMissionControlAction.ts:5-15`
|
||||
> (`MISSION_CONTROL_VERBS` 7-element const `:5-13` + `MissionControlVerb`
|
||||
> type `:15`), `components/mission-control/components/VerbActions.tsx:82`
|
||||
> (defaults to all 7 via `enabledVerbs = [...MISSION_CONTROL_VERBS]`),
|
||||
> per-verb input needs `:97-99` (route/handoff→destination L97;
|
||||
> annotate→annotation L98; hold/drop→reason L99) @HEAD; slice-00
|
||||
> 0.3.0-GT §1.6 + seam (c).
|
||||
|
||||
**The For-You actionable-card surface is bare one-tap APPROVE + CHAT.**
|
||||
`FeedCard` passes `bare`, `enabledVerbs={["approve"]}` and
|
||||
`oneClickVerbs={["approve"]}`, beside a CHAT button that opens the shared
|
||||
`ProgressiveTerminal` seeded via `buildChatPreamble` (human-action cards
|
||||
chat with the sender). Deny/route are not offered here, and the
|
||||
action-required empty state reads "one-tap approve and chat with the
|
||||
owning agent". The 7-verb vocabulary remains the Mission Control
|
||||
system-level vocabulary.
|
||||
|
||||
> Source: `components/for-you/FeedCard.tsx:558-570` (`bare` `:561`,
|
||||
> `enabledVerbs` `:563`, `oneClickVerbs` `:564`),
|
||||
> `resolveCardTerminalSession`; `Feed.tsx:76-82` (`EMPTY_COPY`);
|
||||
> `review/chat.ts:21` (`buildChatPreamble`); test
|
||||
> `test/foryou-bare-approve-chat.test.tsx`.
|
||||
> **OPEN-3 RESOLVED (v0.4.4 living-notes corrective, founder ruling
|
||||
> N-1, 2026-07-05).** The For-You actionable-card surface is **bare
|
||||
> one-tap APPROVE + CHAT — nothing else**. `FeedCard` passes
|
||||
> `enabledVerbs={["approve"]}` + `oneClickVerbs={["approve"]}` + the
|
||||
> v0.4.4 `bare` prop (JSX-only: skips the "Choose response" header
|
||||
> chrome; the mutation/receipt/error paths are byte-identical — pinned
|
||||
> by a raw-body test), beside a CHAT button that opens the **shared
|
||||
> `ProgressiveTerminal`** seeded via `buildChatPreamble` (terminal,
|
||||
> never a chat panel — BR-12). Deny/route are RETIRED from this
|
||||
> surface (including the action-required lens's empty-state copy:
|
||||
> "one-tap approve and chat with the owning agent"); the card-level
|
||||
> kind tag is the status label "Action required", never instruction
|
||||
> chrome. The 7-verb vocabulary above remains the MISSION-CONTROL
|
||||
> system-level vocabulary; For-You offers the two-action subset.
|
||||
>
|
||||
> Source @`bb5ad219`: `FeedCard.tsx:547-593` (bare `VerbActions`
|
||||
> `enabledVerbs=["approve"]` :561-566 + chat button + inline
|
||||
> `ProgressiveTerminal`), `:87-94` (`resolveCardTerminalSession` —
|
||||
> human-action cards chat with the SENDER), `Feed.tsx:76-82`
|
||||
> (`EMPTY_COPY["action-required"]`), `VerbActions.tsx` (`bare` prop),
|
||||
> `review/chat.ts:21` (`buildChatPreamble`); tests
|
||||
> `test/foryou-bare-approve-chat.test.tsx` (byte-identical mutation +
|
||||
> chatBtns:1/denyRoute:0 + retired-copy source-scan).
|
||||
|
||||
On mutation success `VerbActions` fires `onOptimisticOutcome`; `Feed`
|
||||
keeps an optimistic-outcome map keyed by `qitemId` so the
|
||||
`ActionOutcomePanel` receipt renders before the audit re-fetch. A terminal
|
||||
qitem with no recorded outcome derives a fallback receipt from its closure
|
||||
reason. Card footers also carry a "show context" queue-item trigger, a
|
||||
terminal drill, the evidence reference, and a "review →" link to the
|
||||
slice's Review tab.
|
||||
`ActionOutcomePanel` receipt renders instantly without waiting for the
|
||||
audit-log re-fetch (the audit re-fetch eventually surfaces the same
|
||||
shape). A terminal qitem with no recorded outcome derives a fallback
|
||||
receipt from its closure reason.
|
||||
|
||||
> Source: `Feed.tsx` (optimistic map; optimistic-first lookup);
|
||||
> `FeedCard.tsx` (`isActionableCard`, `fallbackOutcomeFromQueueItem`,
|
||||
> `ActionOutcomePanel`, `QueueItemTrigger`, `FeedCardTerminalDrill`).
|
||||
> Source: `components/for-you/Feed.tsx:224-236` (optimistic-outcome
|
||||
> map + `setOptimisticOutcome`), `:426-428` (optimistic-first, audit
|
||||
> fallback: `optimisticOutcomes.get ?? actionOutcomes.get ?? null`);
|
||||
> `FeedCard.tsx:473-500` (`isActionableCard` gate L473 + `VerbActions`
|
||||
> wiring L489-499), `isActionableCard` `:166-175`,
|
||||
> `fallbackOutcomeFromQueueItem` `:177-198`, `ActionOutcomePanel`
|
||||
> `:271-310`; `VerbActions.tsx:138-145` (`onOptimisticOutcome` on
|
||||
> mutation `onSuccess`) @HEAD.
|
||||
|
||||
### 2.5 Card surface (0.3.1 brand layer)
|
||||
### 2.4 Card surface — vellum-coherent (0.3.1 brand layer)
|
||||
|
||||
`FeedCard` renders a `bg-surface-low/45 backdrop-blur-[10px]` surface with
|
||||
a 3-stop ambient box-shadow (no border), four `CornerBracket` marks, a
|
||||
mono-uppercase kind tag with a tone-coloured icon (a dot only when a kind
|
||||
has no icon), and `ActorMark` runtime marks. Cards dismiss by keyboard
|
||||
(Backspace/Delete) or swipe, with an `UndoToast`.
|
||||
`FeedCard` renders on the **0.3.1 vellum brand system**: a
|
||||
`bg-stone-100/45 backdrop-blur` surface with a 3-stop ambient box-shadow
|
||||
(no border), four `CornerBracket` marks registering the bounds through
|
||||
the vellum, a mono-uppercase kind tag + colored dot, and runtime
|
||||
graphics marks (`ActorMark` for sessions) — the slice-00 §1.7 "shared
|
||||
graphics marks across drawers / proof rows / queue refs / story rows"
|
||||
foundation, now expressed in the matured vellum vocabulary. Cards are
|
||||
keyboard-dismissable (Backspace/Delete) and swipe-dismissable, with an
|
||||
`UndoToast`.
|
||||
|
||||
> Source: `components/for-you/FeedCard.tsx` — `CARD_SURFACE_CLASS`
|
||||
> `:108-109`, `CARD_SHADOW_STYLE`, `KIND_TOKEN`, corner brackets
|
||||
> `:452-455`, `ActorMark` `:265`; `CornerBracket` from
|
||||
> `dashboard/vellum/index.ts`.
|
||||
> Source: `components/for-you/FeedCard.tsx:72-73` (`CARD_SURFACE_CLASS`),
|
||||
> `:74-80` (`CARD_SHADOW_STYLE` 3-stop box-shadow), corner brackets
|
||||
> `:401-404` (4× `<CornerBracket position=…>`), `KIND_DOT` `:33-39`,
|
||||
> kind tag span `:410-414`, `ActorMark` import `:25` + usage `:229`;
|
||||
> `CornerBracket` from the 0.3.1 brand barrel
|
||||
> `dashboard/vellum/index.ts:17`; slice-00 0.3.0-GT seam (b) + §1.7 @HEAD.
|
||||
|
||||
The 0.3.1 storytelling preview band is **gone**: `Feed.tsx:375-380` records
|
||||
its removal. The `components/feed/cards/storytelling-cards.tsx` primitives
|
||||
remain for the `/lab/card-previews` gallery. No UI code calls
|
||||
`POST /api/missions/:id/complete` any more; the daemon route still exists
|
||||
(`packages/daemon/src/routes/missions.ts`).
|
||||
### 2.5 Storytelling preview band
|
||||
|
||||
Above the legacy card list `Feed` renders a `StorytellingFeed` preview
|
||||
built by `buildStorytellingFeedItems` from discovered missions
|
||||
(`useMissionDiscovery` → `ProgressCard`, first 2) + slices
|
||||
(`useSlices` → `ShippedCard` for shipped/done, `IncidentCard`
|
||||
otherwise, capped at 3). Mission rows carry a daemon-derived
|
||||
`status` so the "Getting Started"-style complete-and-hide filters
|
||||
durably (`status === "complete"`), with an optimistic local hide +
|
||||
best-effort `POST /api/missions/:id/complete` audit write that swallows
|
||||
network errors so a partial-air-gapped daemon does not block the hide.
|
||||
|
||||
> Source: `components/for-you/Feed.tsx:319-343` (mission/slice adapters:
|
||||
> `useMissionDiscovery` L319, `missionsWithStatus` L329-335,
|
||||
> `buildStorytellingFeedItems` L336-343; adapter comment L305-318),
|
||||
> `handleMarkMissionComplete` `:351-361` (best-effort `void fetch` L354,
|
||||
> error-swallowed L357), preview render `:399-409`;
|
||||
> `components/feed/cards/storytelling-cards.tsx:36` (`CardKind`),
|
||||
> `ShippedCard` `:184`, `IncidentCard` `:235`, `ProgressCard` `:289`
|
||||
> @HEAD.
|
||||
|
||||
## 3. Project — workspace / mission / slice scope pages (0.3.0 spine)
|
||||
|
||||
`/project*` mounts three scope pages on a shared `ScopeShell` +
|
||||
`TabNav` tabbed pattern. Tab sets:
|
||||
`/project*` mounts three scope pages, all built on a shared
|
||||
`ScopeShell` + tabbed-rollup pattern (slice-00 §1.5 project
|
||||
observability foundation). A `SHARED_TABS` set —
|
||||
`overview / story / progress / artifacts / tests / queue / topology` —
|
||||
drives `WorkspaceScopePage` and `MissionScopePage`; `SLICE_TABS`
|
||||
reorders `story` first for `SliceScopePage` but `SliceScopePage`'s
|
||||
`useState` default is `overview` (README + readiness first, not a
|
||||
metric grid).
|
||||
|
||||
| Page | Tabs | Default |
|
||||
|---|---|---|
|
||||
| `WorkspaceScopePage` | `SHARED_TABS`: Overview, Story, Progress, Artifacts, Proof, Queue, Workflow (`topology`) | `overview` |
|
||||
| `MissionScopePage` | `MISSION_TABS`: Overview, Steering, Review, Story, Progress, Artifacts, Proof, Queue, Workflow | `steering` |
|
||||
| `SliceScopePage` | `SLICE_TABS`: Review, Story, Overview, Progress, Artifacts, Proof, Queue, Workflow | `review` |
|
||||
|
||||
> Source: `components/project/ScopePages.tsx` — `SharedTab`/`SliceTab`
|
||||
> `:83-84`, `SHARED_TABS` `:86-94`, `MISSION_TABS` `:98-110`, `SLICE_TABS`
|
||||
> `:112-123`, `TabNav`, `ScopeShell`; defaults `useState` at `:698`,
|
||||
> `:798`, `:1226`.
|
||||
|
||||
Off the local host, the workspace and mission headers show an `ON <host>`
|
||||
chip (the slice header does not), the Review tab is local-only, and
|
||||
file-backed sections explain why local files are not shown.
|
||||
> Source: `components/project/ScopePages.tsx:75-76` (`SharedTab` /
|
||||
> `SliceTab` types), `SHARED_TABS` `:78-86`, `SLICE_TABS` `:88-96`,
|
||||
> `ScopeShell` `:137-166`, `TabNav` `:98-135` @HEAD.
|
||||
|
||||
### 3.1 WorkspaceScopePage (`/project`)
|
||||
|
||||
Reads the live workspace name; honest empty state (`NO WORKSPACE
|
||||
CONNECTED` with an Open-settings action) when unset. Tabs: Overview →
|
||||
`WorkspacePortfolioPanel`; Story/Progress/Artifacts/Proof/Queue → the
|
||||
scope rollups (§3.4); Workflow → `HostMultiRigGraph`.
|
||||
(`WorkspaceOverviewPanel`, the older Current Work / Archive grid, is still
|
||||
defined but not rendered.)
|
||||
Reads the live workspace name (`useWorkspaceName`); honest empty-state
|
||||
(`NO WORKSPACE CONNECTED` with an Open-settings action) when unset. The
|
||||
`overview` tab renders `WorkspaceOverviewPanel`: slices grouped into
|
||||
missions, then `partitionProjectMissions` splits them into a
|
||||
two-column **Current Work / Archive** layout (slice-00 §1.5
|
||||
"current/archive grouping"). Each mission card lists its slices as
|
||||
`Link`s to `/project/slice/$sliceId` with a `QueueCountIcon` +
|
||||
`StatusDot`. The other tabs are the scope rollups (§3.4).
|
||||
|
||||
> Source: `ScopePages.tsx` `WorkspaceScopePage` (no-workspace guard;
|
||||
> `WorkspacePortfolioPanel` `:745`; `HostMultiRigGraph` `:788`).
|
||||
> Source: `components/project/ScopePages.tsx:676-749` (`WorkspaceScopePage`;
|
||||
> no-workspace empty-state guard `:682-693`, `workspace-scope-no-workspace`
|
||||
> `:689`), `WorkspaceOverviewPanel` `:534-674` (mission bucketing
|
||||
> `:536-551`, `partitionProjectMissions` `:552`, two-column panel `:631`,
|
||||
> Current section `:632-651`, Archive section `:652-671`) @HEAD.
|
||||
|
||||
### 3.2 MissionScopePage (`/project/mission/$missionId`)
|
||||
|
||||
Lands on **Steering** (`SteeringTab`). Review → `MissionReviewTab` (§3.5).
|
||||
Overview renders the mission README (`MarkdownViewer`) above a slice rail.
|
||||
Progress renders `MissionProgressHeatmap` plus the mission `PROGRESS.md`
|
||||
(the per-slice rollup cards were removed). Artifacts → `ArtifactsNavigator`;
|
||||
Proof → `ScopeProofRollup`. Workflow renders the **projected workflow
|
||||
spec graph** via `TopologyTab` when the mission README declares a
|
||||
`workflow_spec` that is in the workflow-spec cache (the daemon returns
|
||||
`topology.specGraph`), otherwise `ScopeTopologyRollup`.
|
||||
Same `ScopeShell`/`SHARED_TABS`. `overview` renders the mission README
|
||||
(`useScopeMarkdown(missionPath, "README.md")` via `MarkdownViewer`)
|
||||
above a slice rail; `progress` renders a `MissionProgressHeatmap` + the
|
||||
mission `PROGRESS.md` + the shared `ScopeProgressRollup`. The `topology`
|
||||
tab renders the **projected workflow spec graph** via `TopologyTab`
|
||||
when the mission's README frontmatter declares a `workflow_spec` that is
|
||||
in the `WorkflowSpecCache` (daemon returns `topology.specGraph`),
|
||||
falling back to session-name aggregation otherwise.
|
||||
|
||||
> Source: `ScopePages.tsx` `MissionScopePage` (`SteeringTab` `:834`,
|
||||
> `MissionReviewTab` `:843`, `MissionProgressHeatmap` `:906`,
|
||||
> rollup-cards removal note `:979-983`, `ArtifactsNavigator` `:990`,
|
||||
> spec-graph branch `:1010-1036`).
|
||||
> Source: `components/project/ScopePages.tsx:751-895` (`MissionScopePage`;
|
||||
> `useMission` `:759`, `missionPath` `:760-761`, README/PROGRESS
|
||||
> markdown `:762-763`, overview README section `:775`, progress
|
||||
> heatmap `:832`, `mission-progress-readme` `:838`, spec-graph topology
|
||||
> branch `:875-891` — `missionTopology` `:875`, `specGraph` check
|
||||
> `:879`, session-name fallback `:890`) @HEAD.
|
||||
|
||||
### 3.3 SliceScopePage (`/project/slice/$sliceId`)
|
||||
|
||||
Lands on **Review** (`SliceReviewTab`, §3.5). Overview →
|
||||
`SliceOverviewTab` (a 4-metric summary — status, progress, qitems, last
|
||||
activity — then the README). Story → `ScopeStoryRollup` (the queue-lineage
|
||||
story graph). Progress → `AcceptanceTab`. Artifacts → `ArtifactsNavigator`;
|
||||
Proof → `SliceProofTab`; Queue → `SliceQueueTab`; Workflow → `TopologyTab`.
|
||||
Loading and error states are honest (the error names
|
||||
`rig config get workspace.slices_root` as the likely misconfiguration).
|
||||
Default tab `overview` (`SliceOverviewTab` — README + current step +
|
||||
readiness). Loading/error states are honest empty-states (the error
|
||||
state names `rig config get workspace.slices_root` as the likely
|
||||
misconfiguration). `progress` folds in `AcceptanceTab` (acceptance is
|
||||
the canonical slice-scope progress proof); `story` renders `TimelineTab`
|
||||
with curated `timeline.md` (`useSliceTimelineMarkdown`) above the
|
||||
auto-captured event feed; `topology` renders the slice's
|
||||
workflow-instance-aware `TopologyTab`; **`review` (v0.4.4) renders the
|
||||
Living Notes `SliceReviewTab`** (§3.5).
|
||||
|
||||
> Source: `ScopePages.tsx` `SliceScopePage` (`SliceReviewTab` `:1307`,
|
||||
> `ScopeStoryRollup` `:1317`, `SliceOverviewTab` `:1325`, `AcceptanceTab`
|
||||
> `:1354`, `ArtifactsNavigator` `:1363`, `SliceProofTab` `:1366`,
|
||||
> `TopologyTab` `:1379`, slices_root hint `:1276`), `SliceOverviewTab`
|
||||
> summary grid `:1157-1162`.
|
||||
> Source: `components/project/ScopePages.tsx:1187-1297` (`SliceScopePage`;
|
||||
> default `overview` `:1192`, timeline md `:1204`, loading-state
|
||||
> guard `:1206`, error-state guard `:1225` (slices_root remediation
|
||||
> hint `:1239`), story=`TimelineTab` `:1258-1265`,
|
||||
> progress=`AcceptanceTab` `:1269-1273`, topology `:1294`) @HEAD.
|
||||
|
||||
### 3.4 Shared scope rollups
|
||||
|
||||
`ScopeStoryRollup`, `ScopeProgressRollup`, `ScopeArtifactsRollup`,
|
||||
`ScopeQueueRollup` and `ScopeTopologyRollup` read from one
|
||||
`useProjectScopeRollup(missionId, loadDetails)` hook so workspace and
|
||||
mission scopes share rollup behavior; `ScopeProofRollup`
|
||||
(`project/ProofTab.tsx`) covers Proof. Detail fetching is gated on the
|
||||
active tab (`active !== "overview"` for the workspace;
|
||||
`active !== "overview" && active !== "steering"` for a mission).
|
||||
`ScopeTestsRollup`, `ScopeQueueRollup`, `ScopeTopologyRollup` (the
|
||||
non-overview tabs) all read from one `useProjectScopeRollup(missionId,
|
||||
loadDetails)` hook so workspace and mission scopes share identical
|
||||
rollup behavior over their respective slice sets — the slice-00 §1.5
|
||||
"workspace/mission rollups" foundation. Detail fetching is gated on the
|
||||
active tab (`active !== "overview"`) so the overview path stays cheap.
|
||||
|
||||
> Source: `ScopePages.tsx` `useProjectScopeRollup`, rollup components,
|
||||
> gates `:700`, `:803`.
|
||||
> Source: `components/project/ScopePages.tsx:198-217`
|
||||
> (`useProjectScopeRollup`; `rowsForScope` `:193-196`),
|
||||
> rollup components `:219-532`; gate `:679`,`:754` (`active !== "overview"`)
|
||||
> @HEAD.
|
||||
|
||||
### 3.5 Review tabs (the Living Notes surface)
|
||||
### 3.5 Review tabs (v0.4.4 — the Living Notes surface)
|
||||
|
||||
The slice tab (`review/SliceReviewTab.tsx`) renders one reviewable
|
||||
structure per slice — bands in order **NEEDS YOU → AGENTS → INTENT / PLAN
|
||||
/ DELIVERED → verify-lineage → SETTLED** — from `GET /api/review/slice/:name`
|
||||
(`hooks/useReview.ts`), with a proof-readiness status line and a defects
|
||||
box above NEEDS YOU:
|
||||
Both the slice and mission scope pages mount a `Review` tab
|
||||
(`SLICE_TABS`/mission tabs, `ScopePages.tsx:99-113`). The slice tab
|
||||
(`review/SliceReviewTab.tsx`) renders the ONE reviewable structure per
|
||||
slice — bands in order **NEEDS YOU → AGENTS → INTENT / PLAN / DELIVERED →
|
||||
verify-lineage → SETTLED** — from `GET /api/review/slice/:name`
|
||||
(`hooks/useReview.ts`):
|
||||
|
||||
- **DELIVERED** pairs each planned deliverable with its curated proof,
|
||||
media inline and expanding one at a time (`?item=` deep link). Without a
|
||||
configured readiness policy, `verified` renders as `✓ legacy QA-verified
|
||||
(item revision unbound)` · `◇ unverified — no PASSING QA comparison` ·
|
||||
`✗ missing — promised, nothing delivered`; with one, as `✓ accepted under
|
||||
selected policy` / `◇ current acceptance absent`. A note renders as
|
||||
"Judgment note:". Visible, never blocking. "See all proof" drills into
|
||||
`proof/`.
|
||||
- **Media plays**: video inline with native controls (`?seek`/`?play` deep
|
||||
links); images open `Lightbox`; evidence and the "full PRD →" door open
|
||||
`FileViewer` in the shared right-edge drawer.
|
||||
- **Two locks** render as stamps: plan-lock in PLAN, both stamps in
|
||||
SETTLED; an unaudited stamp renders as UNVERIFIED.
|
||||
- Review cards share one vellum recipe (`review/vellum.ts`); DELIVERED rows
|
||||
stack below the `sm` breakpoint.
|
||||
- **DELIVERED** pairs each planned deliverable with its curated proof down
|
||||
the column (planned mockup above delivered artifact), media inline at text
|
||||
height expanding on tap one-at-a-time (`?item=` deep link); `verified`
|
||||
renders QA's recorded comparison in plain words (✓ QA-verified · ◇
|
||||
unverified · ✗ missing + QA's note) — visible, never blocking. "See all
|
||||
proof" drills into `proof/`.
|
||||
- **Media actually plays**: video renders inline with native controls
|
||||
(`?seek`/`?play` deep links for capture verification); images open the
|
||||
shipped `Lightbox`; evidence and the "full PRD →" door open the shipped
|
||||
`FileViewer` in the shared **right-edge** drawer (the v0.4.4 corrective
|
||||
reverted the FR-11.1 left flip at its three tokens).
|
||||
- **Two locks** (§4 of the architecture module) render as deliberate stamps:
|
||||
plan-lock in PLAN, both stamps in SETTLED; an unaudited stamp renders
|
||||
loudly as UNVERIFIED.
|
||||
- Review cards ride ONE vellum recipe (`review/vellum.ts` —
|
||||
background-matched translucency + backdrop blur, token-driven for both
|
||||
themes); DELIVERED rows stack vertically below the `sm` breakpoint
|
||||
(phone-first single-column scan).
|
||||
- The mission tab (`review/MissionReviewTab.tsx`) is board-first: stage
|
||||
cells, the completion ledger, cut-complete, and a row expansion reading
|
||||
the same contract. The rig altitude (`review/RigAgentsPage.tsx`, route
|
||||
`/agents`) reads `GET /api/review/rig`.
|
||||
cells from the collapsed contract, the completion ledger, cut-complete,
|
||||
and a U5 row expansion reading the SAME contract (intent verbatim + a
|
||||
bounded per-item verified summary; the full pairing lives on the slice
|
||||
page). The rig altitude (`review/RigAgentsPage.tsx`) reads
|
||||
`GET /api/review/rig`.
|
||||
|
||||
Backend contract: see
|
||||
Backend contract + composition: see
|
||||
[`../architecture/living-notes-review.md`](../architecture/living-notes-review.md).
|
||||
|
||||
> Source: `components/review/{SliceReviewTab,MissionReviewTab,
|
||||
> Source @`bb5ad219`: `components/review/{SliceReviewTab,MissionReviewTab,
|
||||
> NeedsYouAccordion,AgentsBandView,VerifyLineageCard,EvidenceOpener,
|
||||
> RigAgentsPage}.tsx`, `review/vellum.ts`, `hooks/useReview.ts`,
|
||||
> `SharedDetailDrawer.tsx`; verified labels `SliceReviewTab.tsx:131-135`,
|
||||
> `:164`, `:194`.
|
||||
> `SharedDetailDrawer.tsx` (right-edge anchor + pre-flip z);
|
||||
> tests `test/{fileviewer-resolvable-target,drawer-primitives}.test.tsx`.
|
||||
> The rejected three-column compare and the separate item-join table are
|
||||
> DELETED files (corrective delete-not-demote; zero references remain).
|
||||
|
||||
## 4. Dashboard — the launcher (`/` → `Dashboard`)
|
||||
## 4. Dashboard — the landing surface (`/` → `Dashboard`)
|
||||
|
||||
`Dashboard` is the paper-draft launcher (OPR.0.4.1.14). It renders, in
|
||||
order: a header with the station online state; `FieldEnvironment` (live
|
||||
rows: RIGS from `useRigSummary`, AGENTS as the sum of `nodeCount` from
|
||||
`usePsEntries`, STATION from `window.location.hostname`, OPERATOR ID from
|
||||
the `agents.operator_session` setting with an `OPERATOR` fallback, and
|
||||
VERSION from `useDaemonVersion` via `/api/health-summary/version`);
|
||||
`KernelStatusCard` (from `/api/kernel/status`); `HostConfigCard`; a grid of
|
||||
six destinations (Topology, Project, For You, Library, Search & Audit,
|
||||
Settings); and `DashboardFooter`. Its glyphs come from
|
||||
`dashboard/vellum/fidelity-glyphs.js`.
|
||||
`Dashboard` is a thin composition over the **0.3.1 vellum brand
|
||||
system**: it imports `MidLayerContent`, `TopLayerContent`,
|
||||
`DestinationsLayer` from `dashboard/vellum/index.js` — the SAME barrel
|
||||
`/lab/vellum-lab` imports, so the production dashboard tracks the design
|
||||
lab exactly (single source of truth). Real-data wiring: `useRigSummary`
|
||||
→ totalRigs/totalAgents, `usePsEntries` → activeAgents, `useSpecLibrary`
|
||||
→ librarySize, `window.location.hostname` → classification eyebrow. Per
|
||||
a 2026-05-15 founder dispatch the heavy `BackLayerContent` /
|
||||
`BackVellumSheet` back-layer was removed so the dashboard sits on the
|
||||
page-level cream paper-grid; the barrel still exports them (used by the
|
||||
lab).
|
||||
|
||||
The kernel card renders `kernel_state: "skipped"` as a neutral **boot not
|
||||
tracked** state. Built-in boot can be skipped because a kernel rig is already
|
||||
managed or because automatic boot was disabled; the served reason remains
|
||||
visible. Ready-agent counts do not promote this state to healthy. An unavailable
|
||||
tracker or a malformed status envelope remains **unknown**. Recovery still uses
|
||||
the existing launch-plan and daemon restore guards.
|
||||
|
||||
The vellum barrel `dashboard/vellum/index.ts` still exports
|
||||
`BackLayerContent` and `BackVellumSheet`; `/lab/vellum-lab`
|
||||
(`lab/VellumLab.tsx`) imports from it.
|
||||
|
||||
> Source: `components/dashboard/Dashboard.tsx` (header comment `:1-24`,
|
||||
> glyph import, `DESTINATIONS`, data wiring, render order);
|
||||
> `hooks/useDaemonVersion.ts`; `components/dashboard/vellum/index.ts:5-6`;
|
||||
> `components/KernelStatusCard.tsx`; `components/RigStatusCard.tsx`.
|
||||
> Source: `components/dashboard/Dashboard.tsx:1-52` (vellum-barrel
|
||||
> import `:12-16`, single-source-of-truth note `:2-5`, real-data hooks
|
||||
> `:29-39`, back-layer-removal note `:21-27`, render `:40-50`);
|
||||
> `components/dashboard/vellum/index.ts:1-26` (barrel; `BackLayerContent`
|
||||
> `:5` / `BackVellumSheet` `:6` still exported); slice-00 0.3.0-GT
|
||||
> seam (b) + §2 rows 1/2 @HEAD.
|
||||
|
||||
## 5. Cross-cutting properties
|
||||
|
||||
- **Live daemon state** — every surface reads daemon hooks. UI-local state
|
||||
on these surfaces is the two For You dismissal sets (localStorage), the
|
||||
lens, host filter and optimistic-outcome map (transient), and each scope
|
||||
page's tab state.
|
||||
- **Honest empty/error states** — `WorkspaceScopePage` no-workspace and
|
||||
`SliceScopePage` not-available surface the cause and a remediation
|
||||
pointer, never a blank screen.
|
||||
- **Live daemon state, no UI-local persistence beyond soft-dismiss** —
|
||||
every surface reads daemon hooks; the only UI-local state is the
|
||||
per-event-seq dismiss set + transient lens chips + optimistic-outcome
|
||||
map (`Feed.tsx:217` lens, `:224` optimistic map, `:240-241` dismiss
|
||||
set; `ScopePages.tsx` `useState` tab state `:677`,`:753`,`:1192`)
|
||||
@HEAD.
|
||||
- **Honest empty/error states** — `WorkspaceScopePage` no-workspace
|
||||
(`ScopePages.tsx:682-693`), `WorkspaceOverviewPanel` index-unavailable
|
||||
(`:565-573`, label `:568`), `SliceScopePage` not-available
|
||||
(`:1225-1245`, label `:1235`) all surface the cause + a remediation
|
||||
pointer, never a blank screen @HEAD.
|
||||
- **0.3.0 observability spine on the 0.3.1 vellum brand layer** — the
|
||||
classifier / verb-action / scope-rollup logic is the 0.3.0 foundation
|
||||
(§0); the visual surface is the 0.3.1 brand layer and later refreshes.
|
||||
classifier / verb-action / scope-rollup *logic* is the 0.3.0
|
||||
foundation (§0); the *visual surface* (vellum cards, corner brackets,
|
||||
graphics marks, dashboard) is the 0.3.1 brand maturation. The split is
|
||||
slice-00 0.3.0-GT seam (b); do not collapse either direction @HEAD.
|
||||
|
||||
## OPEN items (carried, not smoothed)
|
||||
|
||||
- **OPEN — For-You verb subset (slice-00 0.3.0-GT OPEN-3).** The exact
|
||||
shipped For-You-surface verb subset is an unresolved velocity slice-01
|
||||
ruling (CHANGELOG `[0.3.1]` "all 7" vs source-material §6 "subset"
|
||||
discrepancy). This module describes the **7-verb system-level
|
||||
vocabulary only** and reports the literal current `enabledVerbs`
|
||||
prop value (§2.3) as source state, NOT as a resolution. Defer
|
||||
For-You-subset enumeration to the pending velocity ruling.
|
||||
- **OPEN — `/project` redirect-stub consolidation.** `/progress`,
|
||||
`/slices`, `/steering` are `<Navigate to="/project">` stubs and
|
||||
`/slices/$name` redirects into `/project/slice/$sliceId` (§1). Whether
|
||||
the stubs are permanent or transitional is a product decision not
|
||||
resolvable from source.
|
||||
`/slices/$name` redirects into `/project/slice/$sliceId` (§1). The
|
||||
former standalone surfaces fold into Project tabs; whether the stubs
|
||||
are permanent or transitional is a product decision not resolvable
|
||||
from source.
|
||||
- No slice-00 numeric-drift OPEN (1–5) applies — this module carries no
|
||||
migration / route-group / PL-004-event counts.
|
||||
@@ -10,8 +10,8 @@ applies-when: |
|
||||
mounts, or how the shared detail drawer and event consumption work.
|
||||
siblings: [topology.md, project-and-for-you.md, library-specs-and-design-system.md]
|
||||
prerequisite-reads: [../README.md]
|
||||
last-verified-against-source: e8f0ab340db773392ec8be75b072d1c0f3068a50
|
||||
last-updated: 2026-10-08
|
||||
last-verified-against-source: 7eaf524c
|
||||
last-updated: 2026-05-16
|
||||
---
|
||||
|
||||
# UI Shell, Routing, Drawer System
|
||||
@@ -21,18 +21,15 @@ operator surface. Brand/visual rules live in `docs/DESIGN.md` (pointer from
|
||||
`library-specs-and-design-system.md`); this module is how the shell is
|
||||
assembled and what routes it mounts.
|
||||
|
||||
> Verified against source at `e8f0ab34`; package version 0.6.7. UI
|
||||
> footprint is **304** source files (`packages/ui/src`, `.ts`+`.tsx`,
|
||||
> non-test; 235 at the previous stamp `7eaf524c`). The web UI is in
|
||||
> maintenance mode (`docs/reference/developing.md`).
|
||||
> Verified against source at HEAD `7eaf524c`; package version **0.3.1**
|
||||
> (slice-00 §1.1). UI footprint is **235** source files
|
||||
> (`packages/ui/src`, `.ts`+`.tsx`, non-test; slice-00 §1.6 / D6).
|
||||
|
||||
## 1. Package shape
|
||||
|
||||
UI package: `packages/ui`. Primary implementation areas:
|
||||
|
||||
- `src/routes.tsx` — TanStack Router route tree.
|
||||
- `src/App.tsx`, `src/main.tsx` — app root (`ThemeProvider`, the
|
||||
maintenance notice, the router).
|
||||
- `src/components/AppShell.tsx` — global shell: rail, Explorer, drawer,
|
||||
preview stack.
|
||||
- `src/components/ui/` — reusable vellum + base UI primitives.
|
||||
@@ -40,8 +37,6 @@ UI package: `packages/ui`. Primary implementation areas:
|
||||
- `src/components/topology/` — graph/table/terminal topology surfaces.
|
||||
- `src/components/project/`, `for-you/`, `dashboard/`, `feed/` —
|
||||
observability surfaces.
|
||||
- `src/components/review/`, `workflow/` — review altitudes (`/agents`,
|
||||
`/fleet`) and workflow pages.
|
||||
- `src/components/specs/` — Library / skills / plugins surfaces.
|
||||
- `src/components/{preview,markdown,drawer-viewers}/` — viewers.
|
||||
- `src/hooks/`, `src/lib/` — route data hooks, classifiers, formatters,
|
||||
@@ -49,23 +44,13 @@ UI package: `packages/ui`. Primary implementation areas:
|
||||
|
||||
## 2. Shell model
|
||||
|
||||
The root route wraps `AppShell` in `QueryClientProvider` and
|
||||
`DaemonHealthProvider` (`routes.tsx:80-90`). Above the router, `App.tsx`
|
||||
renders a dismissible `UiMaintenanceNotice` (localStorage key
|
||||
`openrig.uiMaintenanceNoticeDismissed`); `main.tsx` mounts `ThemeProvider`.
|
||||
`AppShell` wraps every route. `AppShell.tsx` lays a 48px icon rail + a
|
||||
route-aware Explorer sidebar + center workspace + shared right drawer +
|
||||
preview stack + topology overlay provider + shared drawer-selection /
|
||||
discovery-placement contexts.
|
||||
|
||||
`AppShell.tsx` lays a 48px icon rail + a route-aware Explorer sidebar +
|
||||
center workspace + shared right drawer + preview stack + topology overlay
|
||||
provider + shared drawer-selection / discovery-placement / specs-workspace
|
||||
contexts. The top bar's right slot holds `HostIndicator` and
|
||||
`ThemeSelector`. When the shared event connection is down, a "Live updates
|
||||
unavailable…" status line shows. Switching the selected host clears the
|
||||
discovery placement (`useClearPlacementOnHostSwitch`). Below the `lg`
|
||||
breakpoint a 3-slot `MobileBottomNav` (For You / Project / Topology) also
|
||||
shows.
|
||||
|
||||
The rail destinations (`AppShell.tsx` `RAIL_ICONS`) are exactly six
|
||||
destination icons plus Advisor/Operator entries:
|
||||
The rail destinations (`AppShell.tsx` `RAIL_ICONS`, re-confirmed at HEAD)
|
||||
are exactly six destination icons plus Advisor/Operator entries:
|
||||
|
||||
- Dashboard `/` (`rail-dashboard`)
|
||||
- Topology `/topology` (`rail-topology`)
|
||||
@@ -79,115 +64,95 @@ rather than acting as a generic file browser.
|
||||
|
||||
## 3. Route model
|
||||
|
||||
> The route table below is derived from `packages/ui/src/routes.tsx` at
|
||||
> `e8f0ab34` (605 lines). Each line number is the route's
|
||||
> `createRoute(` line. The exported route tree is assembled at
|
||||
> `routes.tsx:539` (`export const routeTree = rootRoute.addChildren([`);
|
||||
> it holds 54 routes.
|
||||
> Drift-fix D16 — `ui.md` "Route Model" (the L52–73 list) and
|
||||
> `architecture.md` §2 "UI architecture" predate 0.3.x. The route table
|
||||
> below is **re-derived from `packages/ui/src/routes.tsx` at HEAD** (542
|
||||
> lines). The route tree is assembled at `routes.tsx:480`
|
||||
> (`rootRoute.addChildren([...])`).
|
||||
>
|
||||
> `/mission-control` and `/progress` are **redirect stubs**, not
|
||||
> destination routes, and there is **no `/markdown` route** (markdown is
|
||||
> rendered by the `MarkdownViewer` component). There is a real `/files`
|
||||
> route.
|
||||
> Correction to the D16 expectation itself (source-verified at HEAD): the
|
||||
> survey expected `/mission-control`, `/progress`, `/markdown` as net-new
|
||||
> *real* routes. At HEAD `/mission-control` and `/progress` are **redirect
|
||||
> stubs**, not destination routes, and there is **no `/markdown` route**.
|
||||
> There IS a real `/files` route (markdown is rendered by the `MarkdownViewer`
|
||||
> component inside file/drawer surfaces, not via a `/markdown` route). The
|
||||
> route table is reported as source says, not as the survey predicted.
|
||||
|
||||
### Primary destination routes
|
||||
|
||||
| Path | Component | Notes |
|
||||
|---|---|---|
|
||||
| `/` | Dashboard (`indexRoute` `routes.tsx:96`) | rail destination |
|
||||
| `/topology` | host topology (`:106`) | + rig/pod/seat scopes (see `topology.md`) |
|
||||
| `/topology/rig/$rigId` | rig scope (`:112`) | |
|
||||
| `/topology/pod/$rigId/$podName` | pod scope (`:118`) | |
|
||||
| `/topology/seat/$rigId/$logicalId` | seat scope (`:124`) | live node details |
|
||||
| `/for-you` | attention feed (`:130`) | rail destination |
|
||||
| `/project` | workspace project scope (`:136`) | rail destination |
|
||||
| `/project/mission/$missionId` | mission scope (`:142`) | |
|
||||
| `/project/slice/$sliceId` | slice scope (`:148`) | |
|
||||
| `/specs` | Library (`:202`) | rail destination |
|
||||
| `/specs/applications` | applications section (`:208`) | |
|
||||
| `/specs/skills` | skills index (`:216`) | |
|
||||
| `/specs/skills/$skillToken` | skill viewer (`:222`) | defaults to `SKILL.md` |
|
||||
| `/specs/skills/$skillToken/file/$fileToken` | skill file viewer (`:231`) | |
|
||||
| `/specs/plugins` | plugins index (`:242`) | 0.3.1 (see `library-specs…`) |
|
||||
| `/plugins/$pluginId` | plugin detail (`:257`) | 0.3.1 |
|
||||
| `/specs/$specKind/$specName` | generic spec → library redirect (`:269`) | |
|
||||
| `/files` | Files workspace (`:248`) | |
|
||||
| `/settings` | settings center (`:278`) | rail destination |
|
||||
| `/settings/policies` | Policies (`:288`) | Claude-compaction form |
|
||||
| `/settings/log` | Log (`:293`) | 4-item Settings explorer |
|
||||
| `/settings/status` | Status (`:298`) | |
|
||||
| `/search` | audit/history view (`:304`) | |
|
||||
|
||||
### Zoom-addressed routes (no rail entry)
|
||||
|
||||
Reached from other views and deep links, deliberately not on the rail:
|
||||
|
||||
| Path | Component | Notes |
|
||||
|---|---|---|
|
||||
| `/agents` | `RigAgentsPage` (`:159`) | rig review altitude; separate from legacy `/agents/validate` |
|
||||
| `/fleet` | `FleetPage` (`:171`) | fleet attention altitude above host |
|
||||
| `/workflows` | `WorkflowsPage` (`:181`) | |
|
||||
| `/workflow/instance/$instanceId` | `WorkflowInstancePage` (`:187`) | optional `?step=<id>` anchor |
|
||||
| `/` | Dashboard (`indexRoute` `routes.tsx:88`) | rail destination |
|
||||
| `/topology` | host topology (`:98`) | + rig/pod/seat scopes (see `topology.md`) |
|
||||
| `/topology/rig/$rigId` | rig scope (`:104`) | |
|
||||
| `/topology/pod/$rigId/$podName` | pod scope (`:110`) | |
|
||||
| `/topology/seat/$rigId/$logicalId` | seat scope (`:116`) | live node details |
|
||||
| `/for-you` | attention feed (`:122`) | rail destination |
|
||||
| `/project` | workspace project scope (`:128`) | rail destination |
|
||||
| `/project/mission/$missionId` | mission scope (`:134`) | |
|
||||
| `/project/slice/$sliceId` | slice scope (`:140`) | |
|
||||
| `/specs` | Library (`:146`) | rail destination |
|
||||
| `/specs/applications` | applications section (`:152`) | |
|
||||
| `/specs/skills` | skills index (`:160`) | |
|
||||
| `/specs/skills/$skillToken` | skill viewer (`:166`) | defaults to `skill.md` |
|
||||
| `/specs/skills/$skillToken/file/$fileToken` | skill file viewer (`:175`) | |
|
||||
| `/specs/plugins` | plugins index (`:186`) | 0.3.1 (see `library-specs…`) |
|
||||
| `/plugins/$pluginId` | plugin detail (`:201`) | 0.3.1 |
|
||||
| `/specs/$specKind/$specName` | generic spec → library redirect (`:213`) | |
|
||||
| `/files` | Files workspace (`:192`) | net-new vs ui.md/D16 |
|
||||
| `/settings` | settings center (`:222`) | rail destination |
|
||||
| `/settings/policies` | Policies (`:232`) | slice 27 Claude-compaction form |
|
||||
| `/settings/log` | Log (`:237`) | slice 26 4-item Settings explorer |
|
||||
| `/settings/status` | Status (`:242`) | |
|
||||
| `/search` | audit/history view (`:248`) | |
|
||||
|
||||
### Lab routes (design experiments)
|
||||
|
||||
`/lab/project-graphics-preview` (`:310`), `/lab/card-previews` (`:318`),
|
||||
`/lab/vellum-lab` (`:328`), `/lab/vellum-bg/{a-large,b-small,c-allover}`
|
||||
(`:339`–`:349`). The vellum-lab + vellum-bg routes are the 0.3.1 vellum
|
||||
brand-system experiment surface (the `dashboard/vellum/*` system is 0.3.1).
|
||||
`/lab/project-graphics-preview` (`:254`), `/lab/card-previews` (`:262`),
|
||||
`/lab/vellum-lab` (`:272`), `/lab/vellum-bg/{a-large,b-small,c-allover}`
|
||||
(`:283`–`:293`). The vellum-lab + vellum-bg routes are the 0.3.1 vellum
|
||||
brand-system experiment surface (slice-00 0.3.0-GT seam b: vellum brand
|
||||
identity matured in 0.3.1; the `dashboard/vellum/*` system is 0.3.1).
|
||||
|
||||
### Legacy / compatibility routes
|
||||
|
||||
`/rigs/$rigId` (`:374`), `/rigs/$rigId/nodes/$logicalId` (`:380`),
|
||||
`/import` (`:389`), `/packages`, `/packages/install`, `/packages/$packageId`
|
||||
(`:395`–`:407`), `/bootstrap` (`:413`), `/agents/validate` (`:419`),
|
||||
`/specs/rig` + `/specs/agent` review (`:428`/`:434`),
|
||||
`/specs/library/$entryId` (`:440`), `/discovery` + `/discovery/inventory`
|
||||
(`:451`/`:466`), `/bundles/inspect` + `/bundles/install` (`:472`/`:478`).
|
||||
`/rigs/$rigId` (`:318`), `/rigs/$rigId/nodes/$logicalId` (`:324`),
|
||||
`/import` (`:333`), `/packages`, `/packages/install`, `/packages/$packageId`
|
||||
(`:339`–`:351`), `/bootstrap` (`:357`), `/agents/validate` (`:363`),
|
||||
`/specs/rig` + `/specs/agent` review (`:372`/`:378`),
|
||||
`/specs/library/$entryId` (`:384`), `/discovery` + `/discovery/inventory`
|
||||
(`:395`/`:410`), `/bundles/inspect` + `/bundles/install` (`:416`/`:422`).
|
||||
|
||||
### Redirect stubs (deleted routes)
|
||||
|
||||
`routes.tsx:488`–`:530` mount `<Navigate>` redirects for removed routes —
|
||||
`routes.tsx:432`–`:474` mount `<Navigate>` redirects for removed routes —
|
||||
NOT destination pages: `/context` → `/topology`; `/mission-control` →
|
||||
`/for-you` (For-You replaces it); `/slices` → `/project`; `/slices/$name` →
|
||||
`/project/slice/$sliceId` (with `sliceId` set to the name); `/progress` →
|
||||
`/project`; `/steering` → `/project`. The Mission Control *system* still
|
||||
exists in the daemon (`../architecture/mission-control.md`); only the old
|
||||
UI *route* was retired in favour of For-You.
|
||||
`/for-you` (SC-18: `/mission-control` deleted, For-You replaces it);
|
||||
`/slices` + `/slices/$name` → `/project`; `/progress` → `/project`;
|
||||
`/steering` → `/project`. The Mission Control *system* still exists at the
|
||||
daemon/PL-005 layer (`../architecture/mission-control.md`); only the old UI
|
||||
*route* was retired in favour of For-You.
|
||||
|
||||
## 4. Drawer and viewer system
|
||||
|
||||
`SharedDetailDrawer` is the shared transient detail surface for queue-item
|
||||
viewer, file viewer (`FileViewer`), subspec preview, and other detail
|
||||
selections. Drawer triggers carry root/path provenance so the viewer
|
||||
fetches and renders the correct content; the drawer supports outside-click
|
||||
dismissal.
|
||||
|
||||
Image proof viewing: For-You cards use `ProofImageViewer`
|
||||
(`components/project/ProofImageViewer.tsx`), which stays inside the shell
|
||||
layout. The Project Proof tab and the Review surfaces use the full-viewport
|
||||
`Lightbox` (`components/project/Lightbox.tsx`; mounted in
|
||||
`project/ProofTab.tsx`, `review/EvidenceOpener.tsx`,
|
||||
`review/SliceReviewTab.tsx`).
|
||||
|
||||
Skill detail (`components/specs/SkillDetailPage.tsx`) renders its own
|
||||
two-pane docs browser — a file tree beside a viewer — and draws content
|
||||
with `MarkdownViewer` (`.md`/`.mdx`) or `SyntaxHighlight` (other text). It
|
||||
does not use `FileViewer`, which only the shared drawer renders.
|
||||
viewer, file viewer, subspec preview, and other detail selections. Drawer
|
||||
triggers carry root/path provenance so the viewer fetches/render the correct
|
||||
content; the drawer supports outside-click dismissal. Image proof viewing is
|
||||
handled by `ProofImageViewer` with black-glass styling honouring the shell
|
||||
layout. Skill detail uses Library Explorer navigation + `FileViewer`
|
||||
(`components/drawer-viewers/FileViewer.tsx`) in the center workspace, not a
|
||||
nested three-column browser.
|
||||
|
||||
## 5. Event and activity consumption
|
||||
|
||||
UI event consumption is centralized through one shared `/api/events`
|
||||
connection (`lib/topology-events.ts`) so related surfaces avoid duplicate
|
||||
SSE connections. Current consumers: For You feed hydration, topology
|
||||
activity rings + hot-potato movement, the activity feed/system surfaces,
|
||||
and rig event surfaces. `useGlobalEvents` reports whether that connection
|
||||
is up and refetches review, slice and mission data on reconnect and on
|
||||
`proof.*` events. Reduced-motion preference is honoured for pulse/packet
|
||||
animation. (Daemon SSE surfaces: `/api/events`, `/api/stream/watch`,
|
||||
`/api/queue/watch` —
|
||||
[`../architecture/architecture-rules-and-event-system.md`](../architecture/architecture-rules-and-event-system.md)
|
||||
§2, "Emission and delivery".)
|
||||
UI event consumption is centralized through shared event hooks so the app
|
||||
avoids duplicate SSE connections for related surfaces. Current consumers: For
|
||||
You feed hydration, topology activity rings + hot-potato movement, the
|
||||
activity feed/system surfaces, and rig event surfaces. Reduced-motion
|
||||
preference is honoured for pulse/packet animation. (Daemon SSE surfaces:
|
||||
`/api/events`, `/api/stream/watch`, `/api/queue/watch` —
|
||||
`architecture-rules-and-event-system.md` §2.4.)
|
||||
|
||||
## See also
|
||||
|
||||
|
||||
@@ -6,13 +6,12 @@ topics: [observability, coordination]
|
||||
domains: [engineering-advisor, operating-advisor]
|
||||
applies-when: |
|
||||
Need to know how the topology surface is built — the host hybrid graph,
|
||||
the rig/pod graphs, the table/terminal views, the activity-ring /
|
||||
hot-potato visual language, terminal-preview popovers and launchers, and
|
||||
the topology navigation/overlay contracts.
|
||||
the table/terminal views, the activity-ring / hot-potato visual language,
|
||||
terminal-preview popovers, and the topology navigation/overlay contracts.
|
||||
siblings: [shell-and-routing.md, project-and-for-you.md]
|
||||
prerequisite-reads: [../README.md, shell-and-routing.md]
|
||||
last-verified-against-source: e8f0ab340db773392ec8be75b072d1c0f3068a50
|
||||
last-updated: 2026-10-08
|
||||
last-verified-against-source: 7eaf524c
|
||||
last-updated: 2026-05-16
|
||||
---
|
||||
|
||||
# UI Topology — Graph/Table/Terminal, HotPotato, ActivityRing
|
||||
@@ -21,117 +20,84 @@ Topology is a scoped workspace with graph, table, and terminal views at the
|
||||
`/topology` route family (`shell-and-routing.md` §3). It is the operator's
|
||||
live picture of host → rig → pod → seat.
|
||||
|
||||
> Verified against source at `e8f0ab34` (package version 0.6.7). The web UI
|
||||
> is in maintenance mode (`docs/reference/developing.md`). The source file
|
||||
> that defines the hybrid nodes is `HybridTopologyNodes.tsx` (DESIGN.md's
|
||||
> implementation reference).
|
||||
> Verified against source at HEAD `7eaf524c`; package version **0.3.1**
|
||||
> (slice-00 §1.1). All component names below are re-confirmed against
|
||||
> `packages/ui/src/components/topology/` at HEAD — `ui.md` and `DESIGN.md`
|
||||
> name *exported symbols*; the source file that defines the hybrid nodes is
|
||||
> `HybridTopologyNodes.tsx` (DESIGN.md L344 implementation reference).
|
||||
|
||||
## 1. Topology pieces
|
||||
|
||||
> `HybridAgentNode` and `HybridPodGroupNode` are exports inside
|
||||
> `packages/ui/src/components/topology/HybridTopologyNodes.tsx`, not
|
||||
> top-level files (`HybridPodGroupNode = memo(...)` at
|
||||
> `HybridTopologyNodes.tsx:101`; `HybridAgentNode = memo(HybridAgentNodeInner,
|
||||
> ...)` at `:321`).
|
||||
> Drift-fix — `ui.md` "Topology" (L108–137) lists `HybridAgentNode` /
|
||||
> `HybridPodGroupNode` as if top-level files. Re-confirmed at HEAD: both are
|
||||
> exports inside `packages/ui/src/components/topology/HybridTopologyNodes.tsx`
|
||||
> (`HybridPodGroupNode` is `memo(...)` at `HybridTopologyNodes.tsx:94`;
|
||||
> `HybridAgentNode` is `memo(HybridAgentNodeInner, ...)` at `:272`). The
|
||||
> component names are accurate; their file location is consolidated.
|
||||
|
||||
Components in `packages/ui/src/components/topology/`:
|
||||
Components in `packages/ui/src/components/topology/` (re-confirmed at HEAD):
|
||||
|
||||
- `HostMultiRigGraph.tsx` — host-level hybrid React Flow graph (multi-rig
|
||||
single canvas). Also mounted on the `/project` workspace Workflow tab.
|
||||
single canvas).
|
||||
- `HybridTopologyNodes.tsx` — exports `HybridAgentNode` (compact agent cards:
|
||||
runtime badges, context %, token totals, activity state, terminal preview,
|
||||
per-card CMUX open via `useCmuxLaunch`) and `HybridPodGroupNode` (soft
|
||||
dashed pod frames).
|
||||
CMUX actions) and `HybridPodGroupNode` (soft dashed pod frames).
|
||||
- `RigGroupNode.tsx` — soft rig frames with registration marks + aggregate
|
||||
activity.
|
||||
- `ActivityRing.tsx` — active / needs-input / blocked activity ring; card
|
||||
activity classes in `activity-card-visuals.ts`.
|
||||
- `HotPotatoEdge.tsx` — directional queue-movement edge animation.
|
||||
- `TopologyTableView.tsx` — dense table mirror of topology data (with
|
||||
`topology-table-shimmer.css`).
|
||||
- `TopologyTerminalView.tsx` — pinned-card terminal grid for host, rig or
|
||||
pod scope; host scope shows 12 cards by default (`SAFE_N`) with a "show
|
||||
all" toggle.
|
||||
- `TopologyTreeView.tsx` — the topology tree, rendered in the Explorer
|
||||
sidebar (`components/Explorer.tsx`), not as a center view mode.
|
||||
- `TopologyViewModeTabs.tsx` — host tabs Graph / Table / Terminal; rig and
|
||||
pod tabs add Overview. Tabs switch in place (React state), not separate
|
||||
routes. (`SEAT_SCOPE_TABS` is defined but unused; the seat scope renders
|
||||
`LiveNodeDetails`.)
|
||||
- `TerminalPreviewPopover.tsx` — smoked-glass terminal preview, portaled
|
||||
above the graph. On the graph and table it is `progressive`: a static
|
||||
mirror first, click to go live, under a page-wide live-terminal cap.
|
||||
- `TerminalLauncher.tsx` — the rig-scope tab-bar launcher: choose a
|
||||
provider (herdr or cmux) and a view (this rig, a pod, a mission's or
|
||||
slice's agents, a saved view), then open it via
|
||||
`POST /api/terminal/open`. Shown only when the selected host is local.
|
||||
- `LaunchCmuxButton.tsx` — the older rig-scope "Launch in CMUX" button.
|
||||
`TerminalLauncher` replaced it in the tab bar, and no production
|
||||
component imports it now (tests still do).
|
||||
- `TopologyTableView.tsx` — dense table mirror of topology data.
|
||||
- `TopologyTerminalView.tsx` — terminal-oriented topology state.
|
||||
- `TopologyTreeView.tsx` — tree navigation view.
|
||||
- `TopologyViewModeTabs.tsx` — graph/table/terminal/tree mode switch.
|
||||
- `TerminalPreviewPopover.tsx` — black-glass quick terminal preview, portaled
|
||||
above the graph.
|
||||
- `LaunchCmuxButton.tsx` — hover/focus CMUX launch action.
|
||||
- `ScopePages.tsx` — host/rig/pod/seat scope page wrappers.
|
||||
- `topology-overlay-context.tsx` — `TopologyOverlayProvider`: expanded-rig
|
||||
state, the rig named in the URL auto-expanded, and the Explorer mode
|
||||
(`overlay` on the graph tab, `opaque` on the others).
|
||||
- `topology-overlay-context.tsx` — `TopologyOverlayProvider` (expanded-rig
|
||||
state).
|
||||
|
||||
The rig and pod graphs are not the hybrid graph: rig and pod scopes render
|
||||
`components/RigGraph.tsx` (`RigNode` cards, `graph-layout.ts` layout),
|
||||
sharing `HotPotatoEdge` and `useTopologyActivity`. Rig scope's Overview tab
|
||||
renders `RigOverviewTab` (`RigSpecDisplay`); pod scope's is a placeholder.
|
||||
On narrow viewports the graph tab falls back to the table.
|
||||
|
||||
> Source: `topology/TopologyViewModeTabs.tsx` (`HOST_SCOPE_TABS`,
|
||||
> `RIG_POD_SCOPE_TABS`, `SEAT_SCOPE_TABS`); `topology/ScopePages.tsx`
|
||||
> (`TerminalLauncher` `:270`, `RigGraph` `:322`/`:437`, `RigOverviewTab`
|
||||
> `:342`, `useOverlayForActiveTab`); `topology/TerminalPreviewPopover.tsx`
|
||||
> (`progressive`); `topology/TopologyTerminalView.tsx` (`SAFE_N` `:35`).
|
||||
|
||||
> Note (vs `DESIGN.md` "Topology"): DESIGN.md lists the exported brand
|
||||
> primitives (`HostMultiRigGraph`, `HybridAgentNode`, `HybridPodGroupNode`,
|
||||
> `RigGroupNode`, `ActivityRing`, `HotPotatoEdge`, `TerminalPreviewPopover`,
|
||||
> `TopologyTableView`, `TopologyTerminalView`); all are present in source.
|
||||
> `TopologyTreeView`, `TopologyViewModeTabs`, `TerminalLauncher` and
|
||||
> `LaunchCmuxButton` exist in source but are not in DESIGN.md's primitive
|
||||
> list (a scope difference, not drift).
|
||||
> Note (vs `DESIGN.md` "Topology" L205–216): DESIGN.md lists the same
|
||||
> exported primitives (`HostMultiRigGraph`, `HybridAgentNode`,
|
||||
> `HybridPodGroupNode`, `RigGroupNode`, `ActivityRing`, `HotPotatoEdge`,
|
||||
> `TerminalPreviewPopover`, `TopologyTableView`, `TopologyTerminalView`) —
|
||||
> reconciled against source: all present at HEAD. `TopologyTreeView` /
|
||||
> `TopologyViewModeTabs` / `LaunchCmuxButton` exist in source but are not in
|
||||
> DESIGN.md's primitive list (DESIGN.md is the brand primitive list, not an
|
||||
> exhaustive component inventory; not a drift, a scope difference). DESIGN.md
|
||||
> stays byte-identical (Q1).
|
||||
|
||||
## 2. Topology contracts
|
||||
|
||||
Re-confirmed against source:
|
||||
From `architecture.md` §2 "Current topology UI" + `ui.md` "Important
|
||||
topology contracts", re-confirmed against source behaviour at HEAD:
|
||||
|
||||
- Graph / table / tree navigation all resolve to seat detail URLs
|
||||
(`/topology/seat/$rigId/$logicalId`).
|
||||
- The host-level graph prefixes node IDs per rig for the multi-rig single
|
||||
canvas (`lib/hybrid-layout.ts`: `PREFIX_DELIMITER = "::"`,
|
||||
`prefixedHybridNodeId`).
|
||||
- Expanded-rig state is owned by `TopologyOverlayProvider`. Rigs default to
|
||||
**expanded** (`DEFAULT_RIG_EXPANDED = true` in `HostMultiRigGraph.tsx`),
|
||||
with "Expand all" / "Collapse all" controls; graph data is fetched for
|
||||
expanded rigs only.
|
||||
- The host-level graph uses cross-rig node-ID prefixing for multi-rig single
|
||||
canvas.
|
||||
- Expanded-rig state is owned by `TopologyOverlayProvider`
|
||||
(`topology-overlay-context.tsx`); graph data is lazy-fetched for expanded
|
||||
rigs only.
|
||||
- Compact agent cards show context percentage, token totals, and activity
|
||||
card tint; `ActivityRing` + activity classes surface active / needs-input /
|
||||
blocked.
|
||||
- `HotPotatoEdge` animates directional queue movement with non-scaling
|
||||
strokes; reduced-motion preference removes pulse/travel animation and
|
||||
keeps static state signals.
|
||||
- `HotPotatoEdge` animates directional queue movement at graph zoom levels;
|
||||
reduced-motion preference removes pulse/travel animation and keeps static
|
||||
state signals.
|
||||
- Terminal-preview actions are hover/focus-visible; the
|
||||
`TerminalPreviewPopover` escapes React Flow stacking contexts (portaled
|
||||
to `document.body`) and stays within the viewport.
|
||||
- With a non-local host selected, the host graph fetch carries the host
|
||||
parameter; terminal-preview and CMUX buttons are hidden on cards and in
|
||||
the table; and the rig page shows a read-only marker instead of the
|
||||
launcher.
|
||||
`TerminalPreviewPopover` must escape React Flow stacking contexts (portaled
|
||||
above the canvas) and stay within the viewport.
|
||||
|
||||
## 3. Layout and activity helpers
|
||||
## 3. Layout helpers
|
||||
|
||||
In `src/lib/`: `hybrid-layout.ts` lays out the host graph
|
||||
(`HostMultiRigGraph`); `graph-layout.ts` (`applyTreeLayout`) lays out the
|
||||
rig/pod graph (`RigGraph`); `multi-rig-layout.ts` has no production
|
||||
importer (tests only). `topology-activity.ts` computes ring states and
|
||||
hot-potato edges, and `activity-visuals.ts` the rollups and activity dots.
|
||||
Runtime/tool identity on the cards comes from the central
|
||||
`lib/runtime-brand.ts` / `lib/tool-brand.ts` and
|
||||
`components/graphics/RuntimeMark.tsx` (runtimes: Claude Code, Codex, Pi,
|
||||
OMP, terminal, unknown). Do not duplicate brand logic (DESIGN.md "Do
|
||||
not").
|
||||
Topology layout is computed by `src/lib/` helpers (re-confirmed at HEAD):
|
||||
`graph-layout.ts`, `hybrid-layout.ts`, `multi-rig-layout.ts`,
|
||||
`topology-activity.ts`, `activity-visuals.ts`. Runtime/tool identity on the
|
||||
cards comes from the central `runtime-brand.ts` / `tool-brand.ts` +
|
||||
`RuntimeMark.tsx` (do not duplicate brand logic — DESIGN.md "Do not";
|
||||
restated here as the topology-card brand-source contract).
|
||||
|
||||
## See also
|
||||
|
||||
@@ -140,5 +106,4 @@ not").
|
||||
- `../architecture/coordination-primitive.md` — the queue movement the
|
||||
hot-potato edge visualizes.
|
||||
- Source root: `packages/ui/src/components/topology/`,
|
||||
`packages/ui/src/components/RigGraph.tsx`,
|
||||
`packages/ui/src/lib/{hybrid,graph}-layout.ts`.
|
||||
`packages/ui/src/lib/{graph,hybrid,multi-rig}-layout.ts`.
|
||||
@@ -1,355 +0,0 @@
|
||||
# Handing work between OpenRig and A2A agents
|
||||
|
||||
An OpenRig seat can give a queue row's task to an outside A2A agent. In the other direction, an A2A server can
|
||||
front a seat's queue and return its answer as an artifact. These are compositions of the
|
||||
[official Python SDK](https://github.com/a2aproject/a2a-python) and existing `rig queue` commands, not a
|
||||
`rig a2a` command or a daemon endpoint. The scripts below are examples you run and own.
|
||||
|
||||
OpenRig does not configure the outside agent's permissions, model or credentials. Choose a peer and task content
|
||||
you are authorized to share. The peer's result is its report, not acceptance of the work by your team.
|
||||
|
||||
## Before either recipe
|
||||
|
||||
Use a working OpenRig installation and an existing seat. `rig whoami --json` identifies your seat;
|
||||
`rig ps --nodes --rig <rig>` shows the receiving seat's canonical session name. If you need a team first, use
|
||||
[getting started](getting-started.md). Keep the daemon and provider environment you already use.
|
||||
|
||||
In a scratch folder, make a Python environment (Python 3.10 or newer, with `venv` and `pip` available):
|
||||
|
||||
```sh
|
||||
python3 -m venv .venv
|
||||
.venv/bin/python -m pip install 'a2a-sdk[http-server]==1.1.0' httpx uvicorn
|
||||
```
|
||||
|
||||
The examples pin the SDK version used in the pipe trials; they are not a recommendation to downgrade another
|
||||
application. The official SDK 1.1.0 paths were exercised in both directions. Other 1.x versions were not tested.
|
||||
Recheck the API and cancellation behavior when changing versions.
|
||||
|
||||
Pydantic AI 2.60.0 with FastA2A 2.1.1 did not interoperate with these SDK 1.1.0 recipes in the tested setup:
|
||||
FastA2A's inbound typed client returned `result={}` even though the SDK front, with 0.3 compatibility enabled,
|
||||
sent task, artifact and completed records in its raw SSE stream. Outbound, the official SDK raised a protobuf
|
||||
parse error at the FastA2A task's `status.timestamp`; the full wire timestamp was not retained. When mixing
|
||||
frameworks, compare the raw stream's task IDs, artifact and final status with the typed client's output.
|
||||
An HTTP 200 or an empty typed result is not proof that the task succeeded. Retain the evidence before retrying.
|
||||
|
||||
Save this helper as `queue_io.py`:
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
import json
|
||||
|
||||
async def rig(*args):
|
||||
child = await asyncio.create_subprocess_exec(
|
||||
'rig', *args, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE)
|
||||
out, err = await child.communicate()
|
||||
if child.returncode:
|
||||
raise RuntimeError(f'rig {args[:2]} exited {child.returncode}: {err.decode()} {out.decode()}')
|
||||
return json.loads(out)
|
||||
```
|
||||
|
||||
It inherits the caller's OpenRig environment. Run queue operations in the intended seat's environment; set
|
||||
`OPENRIG_URL` only when deliberately selecting another daemon. A timed-out write is uncertain: read its row and
|
||||
transitions before trying again. Do not silently send the task a second time.
|
||||
|
||||
## Outbound: a queue task goes to an A2A peer
|
||||
|
||||
You need the peer's base URL and a row assigned to your seat. For a no-model peer, the official
|
||||
[Hello World sample](https://github.com/a2aproject/a2a-samples/tree/6603ba3f2c31a7ef33e70b9d8b5b5f8be42ac9a3/samples/python/agents/helloworld)
|
||||
returns an echo artifact. Fetch that revision:
|
||||
|
||||
```sh
|
||||
git clone https://github.com/a2aproject/a2a-samples.git
|
||||
git -C a2a-samples checkout --detach 6603ba3f2c31a7ef33e70b9d8b5b5f8be42ac9a3
|
||||
```
|
||||
|
||||
Start the peer yourself in a separate terminal, following `a2a-samples/samples/python/agents/helloworld/README.md`.
|
||||
Its default URL is `http://127.0.0.1:9999`, used below; it is available only while you run the sample.
|
||||
The sample does not implement the input-required and cancellation controls described later. Use a peer that
|
||||
supports those operations when testing them.
|
||||
|
||||
Save as `a2a_client.py`. This client also works without an OpenRig row, for the inbound recipe below.
|
||||
Streaming reads have no deadline so quiet worker waits keep their stream; connection, write and pool waits are bounded to 10 seconds.
|
||||
Stop the local wait with Ctrl-C or a caller-owned overall deadline; this does not confirm cancellation, so keep the task/context IDs and cancel through the peer when it is reachable.
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
import json
|
||||
import os
|
||||
import uuid
|
||||
from pathlib import Path
|
||||
import httpx
|
||||
from a2a.client import A2ACardResolver, ClientConfig, create_client
|
||||
from a2a.helpers import new_text_message
|
||||
from a2a.types import Role, SendMessageRequest
|
||||
from google.protobuf.json_format import MessageToDict
|
||||
from queue_io import rig
|
||||
|
||||
async def main():
|
||||
row_id = os.environ.get('A2A_ROW')
|
||||
text = os.environ.get('A2A_TEXT')
|
||||
if row_id:
|
||||
row = await rig('queue', 'show', row_id, '--full', '--json')
|
||||
identity = await rig('whoami', '--json')
|
||||
if row['destinationSession'] != identity['identity']['sessionName']:
|
||||
raise RuntimeError('Choose a row assigned to this seat.')
|
||||
if row['state'] == 'pending':
|
||||
await rig('queue', 'claim', row_id, '--json')
|
||||
row = await rig('queue', 'show', row_id, '--full', '--json')
|
||||
if row['state'] != 'in-progress':
|
||||
raise RuntimeError('The row is not in progress; inspect it before sending.')
|
||||
if text is None:
|
||||
text = row['body']
|
||||
if text is None:
|
||||
raise RuntimeError('Set A2A_TEXT or A2A_ROW.')
|
||||
message = new_text_message(text, role=Role.ROLE_USER)
|
||||
if os.environ.get('A2A_CONTEXT'):
|
||||
message.context_id = os.environ['A2A_CONTEXT']
|
||||
if os.environ.get('A2A_TASK'):
|
||||
message.task_id = os.environ['A2A_TASK']
|
||||
log_path = Path(f'a2a-{uuid.uuid4()}.jsonl').resolve()
|
||||
state, bound = 'UNKNOWN', False
|
||||
with log_path.open('x') as log:
|
||||
async with httpx.AsyncClient() as http:
|
||||
card = await A2ACardResolver(httpx_client=http, base_url=os.environ['A2A_URL']).get_agent_card()
|
||||
log.write(json.dumps({'card': MessageToDict(card), 'message': MessageToDict(message)}) + '\n')
|
||||
log.flush()
|
||||
client = await create_client(agent=card, client_config=ClientConfig(
|
||||
streaming=True, httpx_client=httpx.AsyncClient(timeout=httpx.Timeout(10.0, read=None))))
|
||||
try:
|
||||
async for chunk in client.send_message(SendMessageRequest(message=message)):
|
||||
event = MessageToDict(chunk) # SDK 1.1.0 yields StreamResponse, not a tuple.
|
||||
log.write(json.dumps(event) + '\n')
|
||||
log.flush()
|
||||
print(json.dumps(event), flush=True)
|
||||
task = event.get('task')
|
||||
if task and row_id and not bound:
|
||||
await rig('queue', 'update', row_id, '--note',
|
||||
f"A2A peer={card.name} task={task['id']} context={task['contextId']} log={log_path}", '--json')
|
||||
bound = True
|
||||
status = (task or event.get('statusUpdate') or {}).get('status', {})
|
||||
state = status.get('state', state)
|
||||
finally:
|
||||
await client.close()
|
||||
if row_id:
|
||||
await rig('queue', 'update', row_id, '--note', f'A2A reported {state}; full result/events: {log_path}', '--json')
|
||||
print(f'Reported state: {state}; saved events: {log_path}')
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
When `A2A_TEXT` is unset, the row body becomes the peer's message verbatim. Write the body as the peer's input,
|
||||
or set `A2A_TEXT` to the exact text you want to send. Run it from your seat, replacing the row and peer URL:
|
||||
|
||||
```sh
|
||||
export A2A_URL=http://127.0.0.1:9999
|
||||
export A2A_ROW=<your-row-id>
|
||||
.venv/bin/python a2a_client.py
|
||||
```
|
||||
|
||||
Read the saved `artifactUpdate` parts and final status. Put the useful result on the **same** row, using a note
|
||||
while work continues or a resolution when you deliberately close it. The script leaves the row owned and open:
|
||||
|
||||
```sh
|
||||
rig queue update "$A2A_ROW" --note 'A2A result: <answer, artifact reference, and any limits>' --json
|
||||
# Only when your work on the row is actually finished:
|
||||
rig queue update "$A2A_ROW" --state done --closure-reason no-follow-on --resolution '<your assessed outcome>' --json
|
||||
```
|
||||
|
||||
If the stream fails, retain its exception and log. The peer may still be working; inspect the known task before
|
||||
resending. When the task asks for input, set `A2A_TASK` and `A2A_CONTEXT` to its recorded IDs and `A2A_TEXT` to the
|
||||
answer, then run the client again. For a new follow-up, unset `A2A_TASK` and keep `A2A_CONTEXT`: a completed task
|
||||
is not reopened. Unset `A2A_TEXT` when the next outbound task should again use its row body.
|
||||
|
||||
## Inbound: an A2A client reaches an OpenRig seat
|
||||
|
||||
Run the following server in a custodian seat's environment, with `A2A_SEAT` set to the existing worker seat's
|
||||
canonical session name. The worker is a separate participant: it watches its queue, claims the row, does the work
|
||||
and writes a resolution. A deterministic shell worker is enough to test this path; a model is optional.
|
||||
|
||||
Save as `a2a_front.py` beside `queue_io.py`:
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
import json
|
||||
import os
|
||||
import uvicorn
|
||||
from starlette.applications import Starlette
|
||||
from a2a.helpers import get_message_text, new_task_from_user_message, new_text_message, new_text_part
|
||||
from a2a.server.agent_execution import AgentExecutor
|
||||
from a2a.server.request_handlers import DefaultRequestHandler
|
||||
from a2a.server.routes import create_agent_card_routes, create_jsonrpc_routes
|
||||
from a2a.server.tasks import InMemoryTaskStore, TaskUpdater
|
||||
from a2a.types import AgentCapabilities, AgentCard, AgentInterface, AgentSkill
|
||||
from queue_io import rig
|
||||
|
||||
seat = os.environ['A2A_SEAT']
|
||||
rows, canceling, published = {}, set(), {}
|
||||
|
||||
class Front(AgentExecutor):
|
||||
async def execute(self, context, events):
|
||||
task = context.current_task or new_task_from_user_message(context.message)
|
||||
if not context.current_task:
|
||||
await events.enqueue_event(task)
|
||||
update = TaskUpdater(events, task.id, task.context_id)
|
||||
published[task.id] = asyncio.Event()
|
||||
try:
|
||||
text = get_message_text(context.message)
|
||||
if task.id not in rows:
|
||||
row_id = 'qitem-a2a-' + task.id
|
||||
body = json.dumps({'taskId': task.id, 'contextId': task.context_id, 'request': text})
|
||||
await rig('queue', 'create', '--id', row_id, '--destination', seat, '--body', body,
|
||||
'--summary', 'Inbound A2A task', '--no-nudge', '--full', '--json')
|
||||
rows[task.id] = row_id
|
||||
else:
|
||||
row_id = rows[task.id]
|
||||
await rig('queue', 'update', row_id, '--note', 'A2A answer: ' + text, '--json')
|
||||
working = False
|
||||
while True:
|
||||
row = await rig('queue', 'show', row_id, '--full', '--json')
|
||||
if task.id in canceling:
|
||||
await asyncio.Future() # cancel() owns the terminal event.
|
||||
if row['state'] == 'done':
|
||||
if not row.get('resolution'):
|
||||
await update.failed(new_text_message('Row closed without a result resolution.'))
|
||||
else:
|
||||
await update.add_artifact([new_text_part(row['resolution'])], name='seat-result')
|
||||
await update.complete(new_text_message('Seat closed row ' + row_id))
|
||||
return
|
||||
if row['state'] in ('failed', 'denied', 'handed-off'):
|
||||
await update.failed(new_text_message(row.get('resolution') or ('Row ' + row['state'])))
|
||||
return
|
||||
if row['state'] == 'canceled':
|
||||
await update.cancel(new_text_message('Queue row canceled.'))
|
||||
return
|
||||
if row['state'] == 'in-progress' and not working:
|
||||
await update.start_work(new_text_message('Seat claimed ' + row_id))
|
||||
working = True
|
||||
history = await rig('queue', 'transitions', row_id, '--full', '--json')
|
||||
notes = [t.get('transitionNote') or '' for t in history]
|
||||
conversation = [n for n in notes if n.startswith(('A2A question: ', 'A2A answer: '))]
|
||||
if conversation and conversation[-1].startswith('A2A question: '):
|
||||
await update.requires_input(new_text_message(conversation[-1][14:]))
|
||||
return
|
||||
await asyncio.sleep(1)
|
||||
except asyncio.CancelledError:
|
||||
if task.id in canceling:
|
||||
await published[task.id].wait() # See SDK 1.1.0 cancellation note below.
|
||||
raise
|
||||
except Exception as error:
|
||||
await update.failed(new_text_message(str(error)))
|
||||
|
||||
async def cancel(self, context, events):
|
||||
canceling.add(context.task_id)
|
||||
try:
|
||||
row_id = rows[context.task_id]
|
||||
await rig('queue', 'update', row_id, '--state', 'canceled', '--resolution',
|
||||
'A2A client requested cancellation; worker stop not yet confirmed.', '--json')
|
||||
await TaskUpdater(events, context.task_id, context.context_id).cancel(
|
||||
new_text_message('Queue cancellation committed; worker stop is a separate observation.'))
|
||||
finally:
|
||||
published[context.task_id].set()
|
||||
|
||||
card = AgentCard(name='OpenRig queue: ' + seat, version='example-1',
|
||||
description='A worker seat returns its queue resolution.',
|
||||
default_input_modes=['text/plain'], default_output_modes=['text/plain'],
|
||||
capabilities=AgentCapabilities(streaming=True),
|
||||
supported_interfaces=[AgentInterface(protocol_binding='JSONRPC', url='http://127.0.0.1:19092', protocol_version='1.0')],
|
||||
skills=[AgentSkill(id='queue-work', name='Queue work', description='Work assigned to ' + seat, tags=['queue'])])
|
||||
handler = DefaultRequestHandler(agent_executor=Front(), task_store=InMemoryTaskStore(), agent_card=card)
|
||||
app = Starlette(routes=[*create_agent_card_routes(card), *create_jsonrpc_routes(handler, '/')])
|
||||
uvicorn.run(app, host='127.0.0.1', port=19092)
|
||||
```
|
||||
|
||||
Start the front, then use a second terminal for the outside client:
|
||||
|
||||
```sh
|
||||
# Custodian terminal:
|
||||
export A2A_SEAT=<worker-session-from-rig-ps>
|
||||
.venv/bin/python a2a_front.py
|
||||
|
||||
# Client terminal, in the folder with the example scripts and venv:
|
||||
unset A2A_ROW A2A_TASK A2A_CONTEXT
|
||||
export A2A_URL=http://127.0.0.1:19092
|
||||
export A2A_TEXT='Return exactly these words: "hello from the receiving seat".'
|
||||
.venv/bin/python a2a_client.py
|
||||
```
|
||||
|
||||
The client waits while the worker does its part. In the **worker's own environment**, inspect and claim the row:
|
||||
|
||||
```sh
|
||||
rig queue list --owned --full --json
|
||||
export ROW=<the-new-qitem-a2a-id>
|
||||
rig queue show "$ROW" --full --json
|
||||
rig queue claim "$ROW" --json
|
||||
rig queue update "$ROW" --state done --closure-reason no-follow-on --resolution 'hello from the receiving seat' --json
|
||||
```
|
||||
|
||||
The client should receive that exact resolution as an artifact, followed by completed. Compare the artifact with
|
||||
`rig queue show "$ROW" --full --json`, including the task/context IDs in the row body. The sample uses `--no-nudge`:
|
||||
the worker must be watching its queue; merely starting the front does not start or wake an agent.
|
||||
To wake a model worker after the row appears, run `rig send <worker-session> 'Check your queue and process the new A2A task.'`
|
||||
from the custodian's environment, or remove `--no-nudge` from the front's queue-create call to request the normal queue wake.
|
||||
|
||||
For input-required, the worker instead records `--note 'A2A question: <question>'` and leaves the row in progress.
|
||||
The client reruns with the same `A2A_TASK`, `A2A_CONTEXT` and its answer as `A2A_TEXT`. The worker reads the
|
||||
`A2A answer: ` transition with `rig queue transitions "$ROW" --full --json`, then finishes that row. These prefixes
|
||||
are this example's small convention, not built-in OpenRig fields. A new follow-up omits the completed task ID and
|
||||
keeps the context ID; it produces a new row.
|
||||
|
||||
## Cancel and read the outcome honestly
|
||||
|
||||
For a protocol-1.0 JSON-RPC peer, a direct control request includes `A2A-Version: 1.0`. For example, after the task
|
||||
is bound and working (substitute its ID; use `GetTask` with the same parameters to inspect it):
|
||||
|
||||
```sh
|
||||
curl -sS "$A2A_URL" -H 'Content-Type: application/json' -H 'A2A-Version: 1.0' \
|
||||
--data '{"jsonrpc":"2.0","id":"cancel-1","method":"CancelTask","params":{"id":"<task-id>"}}'
|
||||
```
|
||||
|
||||
Read the JSON body and task state, not just HTTP status. A pipe trial received HTTP 200 carrying JSON-RPC
|
||||
`-32009 VERSION_NOT_SUPPORTED` when the version header was omitted. That was an error, not a completed task.
|
||||
The SDK handles versioned calls; raw requests must follow the peer's advertised interface and
|
||||
[protocol version rules](https://a2a-protocol.org/v1.0.0/specification/).
|
||||
|
||||
SDK 1.1.0's default V2 handler cancels the running producer **before** awaiting the executor's `cancel` callback.
|
||||
If that callback awaits a queue write, the producer can close the event channel first. The inbound trial then
|
||||
returned stale working state even though the row was canceled. The event in the example keeps that producer
|
||||
alive until the callback publishes its outcome. This is specific to the exercised ordering; see the
|
||||
[pinned SDK implementation](https://github.com/a2aproject/a2a-python/blob/v1.1.0/src/a2a/server/agent_execution/active_task.py).
|
||||
Test it again when changing SDK versions, including an awaited external write rather than an immediate callback.
|
||||
|
||||
Keep these facts separate:
|
||||
|
||||
| A2A observation | What it means for the queue or worker |
|
||||
|---|---|
|
||||
| Submitted | The A2A front accepted a task; a row may not yet be created. |
|
||||
| Working | This front observed the receiving seat's claim. |
|
||||
| Input-required | A question needs answering; this example leaves the row in-progress. |
|
||||
| Completed + artifact | The worker's stored result was returned; your assessment still belongs to you. |
|
||||
| Canceled | This inbound front committed queue cancellation; an outside peer's cancellation says nothing about your outbound row. Verify separately that the worker noticed and stopped. |
|
||||
| Failed / JSON-RPC error | Retain the actual error and any row effect; do not report success. |
|
||||
| Disconnect / timeout | The last known state remains all you know. Inspect before retrying. |
|
||||
|
||||
There is no one-to-one A2A/queue state mapping. The example does not follow handoffs to another row, so it reports
|
||||
that limit instead of pretending the successor's work completed. Stopping the front only detaches clients; it does
|
||||
not cancel its queue rows or stop their workers. Cancel or hand off outstanding work deliberately before stopping
|
||||
your server. Acknowledged cancellation does not establish that a model provider stopped spending.
|
||||
|
||||
## What was exercised, and what remains open
|
||||
|
||||
The initial trials used an OpenRig 0.7.0 candidate and SDK 1.1.0 on Linux. Outbound discovery, streamed output and
|
||||
artifacts used the official Hello World sample. Deterministic peers covered input-required, cancellation, failure
|
||||
and concurrency. Inbound used a private daemon and a separate no-model queue worker: five artifacts matched the
|
||||
stored resolutions, two tasks overlapped without crossing IDs, and completed-task reuse left the old result
|
||||
unchanged. The successful cancellation check also observed the worker stop, beyond receiving the protocol reply.
|
||||
|
||||
A later inbound check used an official SDK 1.1.0 client and front, an OpenRig queue row, and Pi 1.4.0 running
|
||||
`openai/gpt-4o-mini`. One marker answer reached the row's resolution and the client's completed artifact. A
|
||||
custodian performed the queue writes; model tools were disabled. That run used a 120-second streaming read
|
||||
timeout and prompt RPC event draining, changed together. It did not separately test the unbounded read used above.
|
||||
|
||||
These results do not establish model quality or provider billing. Other framework versions, model tool use,
|
||||
public deployment and authentication, stream reconnect, durable bridge restart, and cancellation before row
|
||||
binding were not exercised. The inbound example holds A2A tasks and their row mapping in memory: keep it running for the conversation;
|
||||
after a crash, inspect retained OpenRig rows before any replacement run. It binds loopback and supplies no public
|
||||
authentication layer. Use it on your own machine or a trusted private path, not as an unauthenticated public gateway.
|
||||
@@ -1,77 +0,0 @@
|
||||
# Handing work to an ACP agent
|
||||
|
||||
`rig acp run` gives one queue row's task to an agent that speaks the
|
||||
[Agent Client Protocol](https://agentclientprotocol.com) (ACP), such as OpenClaw's `openclaw acp`, and records what
|
||||
happened on that same row. The seat that runs it is the row's custodian; the agent is recorded as the executor.
|
||||
|
||||
```sh
|
||||
rig acp run <qitemId> --cwd <work folder> -- <the agent's ACP command> [args...]
|
||||
```
|
||||
|
||||
The row's notes get, in order:
|
||||
- **the binding:** the agent's name and version, the ACP protocol version, whether it can load sessions, and the session;
|
||||
- **progress,** about once a minute (tool calls so far, output so far); the full transcript is in the run's log file, named on the row;
|
||||
- **each permission request and its answer** (below);
|
||||
- **the outcome:** `completed`, `stopped` (for example `max_tokens`), `cancelled`, `failed` or `unknown`, with the
|
||||
agent's output;
|
||||
- **what happened to the agent's processes** after the run ended.
|
||||
|
||||
The outcome is the agent's report, not a judgment of the work. The row stays open and yours: read the result, then
|
||||
close it or hand it on with your own resolution, as you would any other.
|
||||
|
||||
## When the agent asks permission
|
||||
|
||||
OpenRig holds no permission policy of its own. The agent's own settings decide what it asks, and an owner decides
|
||||
the answer. Each request becomes a queue row to `--permissions-to` (this seat by default), listing the action, its
|
||||
target, the options the agent offered and the run, session and request it belongs to. Answer on that row with the
|
||||
option's id:
|
||||
|
||||
```sh
|
||||
rig queue update <permission row> --state done --closure-reason no-follow-on --resolution allow-once
|
||||
```
|
||||
|
||||
Answer on the permission row itself; don't hand it off, because the run waits on that row. The answer goes back to
|
||||
that one request, once. The turn waits for it; there's no deadline. An answer that isn't one
|
||||
of the offered options is noted and the question is asked again. If the turn is cancelled first, the permission row
|
||||
is closed as stale and nothing is sent. Whoever answers can follow their own written policy; that choice is theirs.
|
||||
|
||||
## Cancel, detach and stop
|
||||
|
||||
These are different things, and the row keeps them apart:
|
||||
- **Cancel** (Ctrl-C, or `rig acp cancel <runId>` from another terminal) asks the agent to stop its turn. The row
|
||||
records when it was requested and when the agent acknowledged it. Whether the model provider stopped work, and what
|
||||
it cost, stays **unknown** unless you check the provider's own usage.
|
||||
- **Detach** (a second Ctrl-C, or the run ending normally) closes the agent's connection. That doesn't stop
|
||||
the agent's runtime.
|
||||
- **Stop:** when the run ends, it reports whether any process carrying the run's environment marker remains:
|
||||
`settled` (none), `incomplete` (with their process ids) or `unknown` (the process table couldn't be read). Only
|
||||
processes that inherited the marker are seen, so one the agent started with a cleared environment, or through a
|
||||
service manager, isn't. It never touches a process it didn't launch. To stop what's left, use the runtime's
|
||||
own stop command, through `rig acp stop <runId> -- <that command>` so the result lands on the row.
|
||||
|
||||
A gateway the agent connects to but didn't start, such as OpenClaw's Gateway, isn't a process of the run. Leave a
|
||||
shared one running; stop your own with its own command.
|
||||
|
||||
## Reading the outcome
|
||||
|
||||
- `completed`: the agent ended its turn with output.
|
||||
- `unknown`: the turn ended, but nothing shows the work happened. That covers an `end_turn` with no output and no or
|
||||
zero usage (an agent can end a turn this way after its provider refused the request), an `end_turn` whose text
|
||||
reports an interruption (OpenClaw's `[OpenClaw interruption]`), and a connection that closed before the turn ended.
|
||||
Check the agent's own log before you treat it as done.
|
||||
- `failed`: the agent returned an error. The row keeps its original code, message and data.
|
||||
- `cancelled`, `stopped`: as above.
|
||||
|
||||
## Notes for specific agents
|
||||
|
||||
- **OpenClaw:** `openclaw acp` is a bridge to a running OpenClaw Gateway, so start the Gateway first, then run, for
|
||||
example, `rig acp run <row> -- openclaw acp --url ws://127.0.0.1:18789 --token-file <file>`. Its permission requests
|
||||
come from the Gateway's exec approvals.
|
||||
- **Continuing a session:** `--load-session <id>` continues an earlier session when the agent advertises loading. If it
|
||||
doesn't, or the load fails, the run reports that and starts nothing new.
|
||||
|
||||
## Limits
|
||||
|
||||
- One run is one turn for one row.
|
||||
- The client offers the agent no file-system or terminal methods; the agent works in its own environment.
|
||||
- Spend is whatever the agent's provider charges; OpenRig doesn't measure it.
|
||||
+69
-119
@@ -1,8 +1,8 @@
|
||||
# AgentSpec Reference
|
||||
|
||||
Version: 1.0
|
||||
Last validated against code: 2026-10-07, at the 0.6.6 cut `2620dea8` (whole document at `fcaf1f8e`; changes to its sources and the shipped agent specs since then checked)
|
||||
Source of truth: `packages/daemon/src/domain/agent-manifest.ts`, `packages/daemon/src/domain/types.ts`, `packages/daemon/src/domain/agent-resolver.ts`, `packages/daemon/src/domain/profile-resolver.ts`, `packages/daemon/src/domain/skill-catalog.ts`
|
||||
Last validated against code: 2026-04-11
|
||||
Source of truth: `packages/daemon/src/domain/agent-manifest.ts`, `packages/daemon/src/domain/types.ts`
|
||||
|
||||
This is the canonical reference for the AgentSpec YAML format (`agent.yaml`). Every field, validation rule, and default documented here was traced from the actual parser and validator code.
|
||||
|
||||
@@ -20,7 +20,7 @@ profiles:
|
||||
skills: []
|
||||
guidance: []
|
||||
subagents: []
|
||||
plugins: []
|
||||
hooks: []
|
||||
runtime_resources: []
|
||||
|
||||
resources: {}
|
||||
@@ -35,7 +35,7 @@ startup:
|
||||
```yaml
|
||||
name: implementer
|
||||
version: "1.0"
|
||||
description: Implementation agent — implements and verifies coherent changes
|
||||
description: Implementation agent — writes code following TDD discipline
|
||||
|
||||
defaults:
|
||||
runtime: claude-code
|
||||
@@ -46,11 +46,11 @@ imports:
|
||||
profiles:
|
||||
default:
|
||||
uses:
|
||||
skills: [development-team, systematic-debugging, verification-before-completion]
|
||||
skills: [openrig-user, development-team, test-driven-development, systematic-debugging]
|
||||
guidance: []
|
||||
subagents: []
|
||||
plugins: [shared:openrig-core]
|
||||
runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config, shared:claude-activity-hooks]
|
||||
hooks: []
|
||||
runtime_resources: []
|
||||
|
||||
resources:
|
||||
guidance:
|
||||
@@ -75,7 +75,6 @@ description: Vault specialist agent — manages HashiCorp Vault for this managed
|
||||
defaults:
|
||||
runtime: claude-code
|
||||
model: claude-opus-4-6
|
||||
effort: high
|
||||
lifecycle:
|
||||
execution_mode: interactive_resident
|
||||
compaction_strategy: default-compaction
|
||||
@@ -92,11 +91,11 @@ profiles:
|
||||
preferences:
|
||||
runtime: claude-code
|
||||
uses:
|
||||
skills: [systematic-debugging, vault-user]
|
||||
skills: [openrig-user, systematic-debugging, vault-user]
|
||||
guidance: []
|
||||
subagents: []
|
||||
plugins: [shared:openrig-core, vault-tools]
|
||||
runtime_resources: [claude-settings]
|
||||
hooks: []
|
||||
runtime_resources: []
|
||||
startup:
|
||||
files:
|
||||
- path: guidance/profile-specific.md
|
||||
@@ -112,11 +111,10 @@ resources:
|
||||
guidance:
|
||||
- id: role
|
||||
path: guidance/role.md
|
||||
plugins:
|
||||
- id: vault-tools
|
||||
source:
|
||||
kind: local
|
||||
path: plugins/vault-tools
|
||||
hooks:
|
||||
- id: pre-commit
|
||||
path: hooks/pre-commit.sh
|
||||
runtimes: [claude-code]
|
||||
runtime_resources:
|
||||
- id: claude-settings
|
||||
path: runtime/claude-settings.fragment.json
|
||||
@@ -149,12 +147,12 @@ startup:
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `name` | string | yes | — | Agent name. Used in spec library identification and validation messages. |
|
||||
| `version` | string | yes | — | Spec version. Quote it (`"1.0"`): an unquoted number fails as a non-string. An importing spec that pins `imports[].version` must match it exactly. |
|
||||
| `version` | string | yes | — | Spec version. Informational — not used for compatibility gating. |
|
||||
| `description` | string | no | — | Human-readable description. Shown in spec library and review surfaces. |
|
||||
| `defaults` | Defaults | no | — | Default runtime, model, and lifecycle settings. Applied when not overridden by the rig spec or profile. |
|
||||
| `imports` | Import[] | no | `[]` | Other AgentSpecs to import. Resources from imported specs become available for profile `uses` references. |
|
||||
| `profiles` | map<string, Profile> | no | `{}` | Named profiles. Each profile selects resources and can override startup/lifecycle. The rig spec member's `profile` field selects which profile to use. |
|
||||
| `resources` | Resources | no | all empty | Declared resources (skills, guidance, subagents, plugins, runtime resources). These are the available pool that profiles select from via `uses`. |
|
||||
| `resources` | Resources | no | all empty | Declared resources (skills, guidance, subagents, hooks, runtime resources). These are the available pool that profiles select from via `uses`. |
|
||||
| `startup` | StartupBlock | no | `{ files: [], actions: [] }` | Agent-level startup files and actions. Applied to all profiles via the startup layering model. |
|
||||
|
||||
---
|
||||
@@ -165,7 +163,6 @@ startup:
|
||||
defaults:
|
||||
runtime: claude-code
|
||||
model: claude-opus-4-6
|
||||
effort: high
|
||||
lifecycle:
|
||||
execution_mode: interactive_resident
|
||||
compaction_strategy: default-compaction
|
||||
@@ -174,10 +171,8 @@ defaults:
|
||||
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `runtime` | string | no | — | Default runtime for this agent. Precedence: the rig spec member's `runtime`, then the profile's `preferences.runtime`, then this, then `claude-code`. |
|
||||
| `model` | string | no | — | Default model, with the same precedence. |
|
||||
| `effort` | string | no | — | Default reasoning effort, with the same precedence. Claude gets `--effort`, Codex `-c model_reasoning_effort=…`, Pi `--thinking <level>` (Pi's levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`; passed as written). A blank or non-string value is ignored with an advisory. |
|
||||
| `advisor` | string | no | — | Default Claude Advisor model, with the same precedence. Passed as the session-scoped `--advisor` flag, independently of the primary model; never written to shared Claude settings. Blank or non-string values are ignored with an advisory. Other runtimes ignore it. |
|
||||
| `runtime` | string | no | — | Default runtime for this agent. Can be overridden by the rig spec member's `runtime` field. |
|
||||
| `model` | string | no | — | Default model. Can be overridden by the rig spec member's `model` field. |
|
||||
| `lifecycle` | Lifecycle | no | see below | Lifecycle behavior defaults. |
|
||||
|
||||
### Lifecycle Defaults
|
||||
@@ -185,9 +180,8 @@ defaults:
|
||||
| Field | Type | Default | Allowed Values |
|
||||
|-------|------|---------|----------------|
|
||||
| `execution_mode` | string | `interactive_resident` | `interactive_resident` (only value in v1; `wake_on_demand` is explicitly rejected) |
|
||||
| `compaction_strategy` | string | `default-compaction` | `default-compaction`, `managed-compaction`, `handover`, `apprentice-handover`; deprecated aliases accepted with a validation advisory: `harness_native` → `default-compaction`, `pod_continuity` → `handover` (`custom_prompt` is explicitly rejected in v1). `managed-compaction` and `apprentice-handover` create their jobs only for `claude-code` seats; see [Codex compaction and sizing](agent-startup-guide.md#codex-compaction-and-sizing) |
|
||||
| `compaction_strategy` | string | `default-compaction` | `default-compaction`, `managed-compaction`, `handover`, `apprentice-handover`; deprecated aliases accepted with a validation advisory: `harness_native` → `default-compaction`, `pod_continuity` → `handover` (`custom_prompt` is explicitly rejected in v1) |
|
||||
| `restore_policy` | string | `resume_if_possible` | `resume_if_possible`, `relaunch_fresh`, `checkpoint_only` |
|
||||
| `mechanic` | string | — | A canonical `seat@rig` session address; needed by `apprentice-handover` |
|
||||
|
||||
---
|
||||
|
||||
@@ -203,18 +197,15 @@ imports:
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `ref` | string | yes | Reference to another AgentSpec directory. Must start with `local:` (relative) or `path:` (absolute). The referenced directory must contain an `agent.yaml`. |
|
||||
| `version` | string | no | Optional version constraint. Must be an exact version — no ranges (`~`, `^`, `>=`, etc.). When set, the imported spec's `version` must equal it, or resolution fails with `version_mismatch`. |
|
||||
| `version` | string | no | Optional version constraint. Must be an exact version — no ranges (`~`, `^`, `>=`, etc.). |
|
||||
|
||||
### Import Resolution
|
||||
|
||||
- `local:` paths resolve relative to the importing spec's directory
|
||||
- `path:` paths are absolute filesystem paths
|
||||
- Imported resources become available for `uses` references in profiles
|
||||
- A qualified reference `namespace:id` (e.g., `shared:openrig-core`) names the imported spec by its `name` field
|
||||
- An unqualified reference (just `id`) resolves against the spec's own resources first, then against the one import that
|
||||
declares it. If two imports declare it, the reference is ambiguous and fails: qualify it
|
||||
- An imported spec may not have imports of its own, and its `name` may not contain `:`. Two imports that resolve to the
|
||||
same spec name are refused, and import cycles are detected
|
||||
- When referencing imported resources in `uses`, use qualified `namespace:id` format (e.g., `shared:openrig-user`)
|
||||
- Unqualified references (just `id`) resolve against the spec's own local resources first
|
||||
|
||||
### The Shared Import Pattern
|
||||
|
||||
@@ -225,13 +216,7 @@ imports:
|
||||
- ref: local:../../shared
|
||||
```
|
||||
|
||||
This gives access to the shared pool: skills such as `systematic-debugging`, `verification-before-completion`,
|
||||
`development-team` and `test-driven-development`; the `openrig-core` plugin, which carries `openrig-user` and OpenRig's
|
||||
other skills; and runtime resources such as `claude-default-settings`, `claude-default-mcp`, `codex-default-config` and
|
||||
`claude-activity-hooks`. Agents select the ones they need via profile `uses`, for example
|
||||
`plugins: [shared:openrig-core]`. That selection projects the plugin's skills into the seat. For a Claude seat it also loads
|
||||
the plugin's hooks, through a `CLAUDE_CODE_PLUGIN_DIRS` the daemon sets for a seat that selected `openrig-core` (see
|
||||
`refocus-channel.md`); a seat that didn't select it gets neither.
|
||||
This gives access to the full pool of shared skills (openrig-user, systematic-debugging, development-team, etc.) and agents select the ones they need via profile `uses`.
|
||||
|
||||
---
|
||||
|
||||
@@ -245,10 +230,10 @@ profiles:
|
||||
runtime: claude-code
|
||||
model: claude-opus-4-6
|
||||
uses:
|
||||
skills: [systematic-debugging, vault-user]
|
||||
skills: [openrig-user, systematic-debugging, vault-user]
|
||||
guidance: [role]
|
||||
subagents: []
|
||||
plugins: [shared:openrig-core]
|
||||
hooks: []
|
||||
runtime_resources: []
|
||||
startup:
|
||||
files: []
|
||||
@@ -259,15 +244,13 @@ profiles:
|
||||
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `summary` | string | no | — | Profile description. Spec review surfaces read a profile `description` instead. |
|
||||
| `preferences` | object | no | — | Runtime/model/effort/Advisor preferences for this profile. |
|
||||
| `summary` | string | no | — | Profile description. |
|
||||
| `preferences` | object | no | — | Runtime/model preferences for this profile. |
|
||||
| `preferences.runtime` | string | no | — | Preferred runtime. |
|
||||
| `preferences.model` | string | no | — | Preferred model. |
|
||||
| `preferences.effort` | string | no | — | Preferred reasoning effort. |
|
||||
| `preferences.advisor` | string | no | — | Preferred Claude Advisor model; overrides `defaults.advisor` and can be overridden by the member. |
|
||||
| `uses` | Uses | no | all empty | Selects which declared resources are active for this profile. |
|
||||
| `startup` | StartupBlock | no | — | Profile-level startup files and actions. Merged with agent-level startup via layering. |
|
||||
| `lifecycle` | Lifecycle | no | — | Profile-level lifecycle overrides. `restore_policy` can only narrow (`resume_if_possible` → `relaunch_fresh` → `checkpoint_only`); `compaction_strategy` and `mechanic` take the most specific value (defaults, then profile, then member). |
|
||||
| `lifecycle` | Lifecycle | no | — | Profile-level lifecycle overrides. |
|
||||
|
||||
### Uses
|
||||
|
||||
@@ -275,28 +258,18 @@ The `uses` block selects which resources from the `resources` pool (including im
|
||||
|
||||
```yaml
|
||||
uses:
|
||||
skills: [systematic-debugging, vault-user]
|
||||
skills: [openrig-user, systematic-debugging, vault-user]
|
||||
guidance: [role]
|
||||
subagents: []
|
||||
plugins: [shared:openrig-core]
|
||||
hooks: [pre-commit]
|
||||
runtime_resources: [claude-settings]
|
||||
```
|
||||
|
||||
Each array contains resource IDs. These can be:
|
||||
- **Unqualified** (`vault-user`) — resolves against the spec's own `resources` first, then imported specs
|
||||
- **Qualified** (`shared:systematic-debugging`) — resolves against a specific imported spec's resources
|
||||
- **Qualified** (`shared:openrig-user`) — resolves against a specific imported spec's resources
|
||||
|
||||
The `uses` categories are: `skills`, `guidance`, `subagents`, `plugins`, `runtime_resources`. A `uses.hooks` key, even an
|
||||
empty list, is refused: hooks ship inside plugins.
|
||||
|
||||
**Skills resolve more widely than other resources.** For Claude Code and Codex seats, a skill ID that no declared
|
||||
resource provides is looked up at launch in the project's runtime skill folder in the seat's cwd (`<cwd>/.claude/skills` or
|
||||
`<cwd>/.agents/skills`), then the `skills/` folder beside the RigSpec, then the home skill folder, then the managed
|
||||
skills root. Pi looks only in the `skills/` folder beside the RigSpec. OMP does no filesystem discovery, so its
|
||||
`uses.skills` references need declared resources. A discovered skill's ID is its `SKILL.md` frontmatter `name`, and a declared resource wins over a discovered skill with the
|
||||
same ID. When a profile selects a skill from inside the spec's own folder and the managed catalog holds a different
|
||||
copy, the spec's copy is used and launch warns `skill_bundle_precedence`. Any other differing copy fails launch with
|
||||
`skill_identity_conflict`.
|
||||
The `uses` categories are: `skills`, `guidance`, `subagents`, `plugins`, `hooks`, `runtime_resources`.
|
||||
|
||||
---
|
||||
|
||||
@@ -313,12 +286,10 @@ resources:
|
||||
subagents:
|
||||
- id: helper
|
||||
path: subagents/helper
|
||||
plugins:
|
||||
- id: vault-tools
|
||||
source:
|
||||
kind: local
|
||||
path: plugins/vault-tools
|
||||
plugin_type: auto
|
||||
hooks:
|
||||
- id: pre-commit
|
||||
path: hooks/pre-commit.sh
|
||||
runtimes: [claude-code]
|
||||
runtime_resources:
|
||||
- id: claude-settings
|
||||
path: runtime/claude-settings.fragment.json
|
||||
@@ -326,11 +297,7 @@ resources:
|
||||
type: claude_settings_fragment
|
||||
```
|
||||
|
||||
Resources are the available pool. They are NOT automatically delivered to agents — profiles select them via `uses`.
|
||||
The only declared resources delivered are those that the active profile's `uses` block references. Two sources add
|
||||
skills outside `uses`: the managed skill catalog's system selection and a project's `install.skills`.
|
||||
|
||||
`resources.hooks` is refused at validation: hooks now ship inside plugins, declared under `resources.plugins`.
|
||||
Resources are the available pool. They are NOT automatically delivered to agents — profiles select them via `uses`. The only resources delivered are those that the active profile's `uses` block references.
|
||||
|
||||
### Plugin paths
|
||||
|
||||
@@ -363,28 +330,28 @@ profiles:
|
||||
not shell interpolation and does not consult a seat's shell startup files. Its
|
||||
suffix must be relative. Existing absolute, tilde and spec-relative paths keep
|
||||
their meaning; `~user` is still a literal relative segment, not a user lookup.
|
||||
This form needs OpenRig 0.6.5 or later; keep bundles using it pinned to such a
|
||||
version.
|
||||
This form requires a daemon version that supports it; keep bundles using it
|
||||
pinned to such a version.
|
||||
|
||||
### Resource Categories
|
||||
|
||||
| Category | Fields | Description |
|
||||
|----------|--------|-------------|
|
||||
| `skills` | `id`, `path` | Skill directories containing a SKILL.md. Projected by the runtime adapter. Claude and Codex seats get them in the seat's own storage, `<OpenRig home>/state/seats/<rig id>/<logical seat>/<runtime>/`, outside the project: Claude to `plugin/skills/<id>` in the seat's generated plugin, where they show as `openrig:<id>`, and Codex to `skills/<id>` beside the seat's skill catalog. A Claude or Codex seat without that storage gets `<cwd>/.claude/skills/<id>` or `<cwd>/.agents/skills/<id>`. Pi and OMP project to the seat's own agent directory under OpenRig's state. |
|
||||
| `guidance` | `id`, `path`, `target`*, `merge`* | Guidance files, merged as a managed block (see "Guidance Resources"). |
|
||||
| `subagents` | `id`, `path` | Subagent definitions. Claude copies them to `<cwd>/.claude/agents/`, Codex to `<cwd>/.agents/`; Pi and OMP don't project them. |
|
||||
| `plugins` | `id`, `source`, `plugin_type`* | Local plugin directories; selected with `uses.plugins`. `source.kind` must be `local`. `plugin_type` is `claude`, `codex` or `auto` (default): Claude projects a plugin to `<cwd>/.claude/plugins/<id>` when it is `claude`, or `auto` with a `.claude-plugin/plugin.json`; Codex projects to `<cwd>/.codex/plugins/<id>` when it is `codex`, or `auto` with a `.codex-plugin/plugin.json`. Pi and OMP don't project plugins. Neither Claude Code nor Codex reads skills from that plugin folder, so when a seat is instantiated a selected plugin's skills are also projected into the seat's skill folder under their plain names: the seat's own storage (see `skills`), or `.claude/skills/<name>` or `.agents/skills/<name>` for a seat without it. A folder already there with the same name, ignoring letter case, that OpenRig doesn't own is left alone; unless it already holds the same bytes, launch warns `plugin_skill_kept`. A skill the seat already selects by that name (from its profile, the System World or the project) keeps that source, an edited OpenRig-owned copy is kept with `plugin_skill_kept`, a retained plugin copy whose remembered source can no longer be projected is also kept with `plugin_skill_kept` (a seat selecting that plugin refreshes it at its next launch), and if the plugin skills can't be projected the seat launches without them and warns `plugin_skills_not_projected`. Hooks ship inside plugins. |
|
||||
| `runtime_resources` | `id`, `path`, `runtime`, `type` | Runtime-specific resources. `runtime` and `type` are required. An entry whose `runtime` isn't the seat's runtime is skipped. Pi and OMP project none. |
|
||||
| `skills` | `id`, `path` | Skill directories containing a SKILL.md. Delivered via `skill_install`. |
|
||||
| `guidance` | `id`, `path`, `target`*, `merge`* | Guidance files. Delivered via `guidance_merge` into CLAUDE.md/AGENTS.md. |
|
||||
| `subagents` | `id`, `path` | Subagent definitions. |
|
||||
| `plugins` | `id`, `source` | Local plugin directories; selected with `uses.plugins`. |
|
||||
| `hooks` | `id`, `path`, `runtimes`* | Hook scripts. Optional `runtimes` array restricts to specific runtimes. |
|
||||
| `runtime_resources` | `id`, `path`, `runtime`, `type` | Runtime-specific resources. `runtime` and `type` are required. |
|
||||
|
||||
*Fields marked with `*` are optional.
|
||||
|
||||
Recognized runtime resource types:
|
||||
- `claude_settings_fragment` — merge a JSON object into `<cwd>/.claude/settings.local.json`.
|
||||
- `claude_mcp_fragment` — merge a JSON object into `<cwd>/.mcp.json`.
|
||||
- `claude_activity_hooks` — reconcile OpenRig's activity hooks into `<cwd>/.claude/settings.local.json`.
|
||||
- `codex_config_fragment` — upsert a TOML fragment into `$CODEX_HOME/config.toml` (default `~/.codex/config.toml`) inside an OpenRig-managed block.
|
||||
- `codex_config_fragment` — upsert a TOML fragment into `~/.codex/config.toml` inside an OpenRig-managed block.
|
||||
|
||||
Unknown runtime resource types are still copied to the Claude or Codex runtime extension directory for agent-visible context.
|
||||
Unknown runtime resource types are still copied to the runtime extension directory for agent-visible context.
|
||||
|
||||
#### Writing a `codex_config_fragment`
|
||||
|
||||
@@ -421,8 +388,7 @@ overwritten, and the rest of the fragment still applies.
|
||||
|
||||
### Resource Path Rules
|
||||
|
||||
- All resource paths must be safe relative paths (no `..` traversal, no absolute paths), except a plugin's
|
||||
`source.path`, which takes the forms under "Plugin paths"
|
||||
- All resource paths must be safe relative paths (no `..` traversal, no absolute paths)
|
||||
- Paths resolve relative to the agent spec's directory
|
||||
- Resource IDs must be unique within their category
|
||||
- Resource IDs are the identifiers used in `uses` references
|
||||
@@ -433,15 +399,16 @@ overwritten, and the rest of the fragment still applies.
|
||||
guidance:
|
||||
- id: role
|
||||
path: guidance/role.md
|
||||
merge: managed_block # optional — the only strategy applied
|
||||
target: CLAUDE.md # optional — where to merge
|
||||
merge: managed_block # optional — how to merge (default: managed_block)
|
||||
```
|
||||
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `id` | string | yes | — | Resource identifier. A `rig-role` guidance resource is never merged; deliver a role with a `send_text` startup file. |
|
||||
| `id` | string | yes | — | Resource identifier. |
|
||||
| `path` | string | yes | — | Relative path to the guidance file. |
|
||||
| `target` | string | no | — | Parsed but not used: the runtime decides the file. Claude merges into the rig's `managed_blocks` file (`CLAUDE.md` by default, or `CLAUDE.local.md`); Codex, Pi and OMP merge into `<cwd>/AGENTS.md`. |
|
||||
| `merge` | string | no | `managed_block` | Only `managed_block` is applied. Any other value, such as `append`, merges nothing. |
|
||||
| `target` | string | no | — | Target file for merging (e.g., `CLAUDE.md`). |
|
||||
| `merge` | string | no | `managed_block` | Merge strategy. One of: `managed_block`, `append`. |
|
||||
|
||||
---
|
||||
|
||||
@@ -461,7 +428,7 @@ restore behavior, and the distinction between readiness and verified proof.
|
||||
|
||||
| Hint | When Delivered | Mechanism |
|
||||
|------|---------------|-----------|
|
||||
| `auto` | Depends on the file | A seat's own role (a file marked `orientation: role`, or at a `guidance/role.md` path) is `send_text`, so pod-mates never overwrite each other's role in the shared file. A seat launched before this rule keeps the hint saved at its launch, which restore (`rig up <rig>`), `rig seat launch --fresh` and handover replay, until the rig is instantiated from its spec again: `rig down <rig>`, then `rig up <spec file>`, which starts a new generation with fresh conversations. Otherwise a path ending in `SKILL.md`, or content beginning with `# SKILL`, is `skill_install`; a `.md` file is `guidance_merge`; and any other file is `send_text` |
|
||||
| `auto` | Before harness boot | System chooses based on file type |
|
||||
| `guidance_merge` | Before harness boot | Merged into CLAUDE.md/AGENTS.md as managed block |
|
||||
| `skill_install` | Before harness boot | Installed to runtime skill directory |
|
||||
| `send_text` | After harness is ready | Sent as text to agent terminal via tmux |
|
||||
@@ -475,26 +442,17 @@ restore behavior, and the distinction between readiness and verified proof.
|
||||
3. Import `ref` must start with `local:` (relative) or `path:` (absolute).
|
||||
4. Import `version` must be an exact version (no ranges).
|
||||
5. `profiles` must be a map (object), not an array.
|
||||
6. Profile `uses` references other than skills must resolve to declared resources (local or imported). Skill
|
||||
references are checked at launch, not at validation (see "Uses").
|
||||
6. Profile `uses` references must resolve to declared resources (local or imported).
|
||||
7. Unqualified `uses` references that don't resolve to local resources require imports to be present.
|
||||
8. Qualified `uses` references must be in `namespace:id` format.
|
||||
9. All resource paths must be safe relative paths (a plugin's `source.path` excepted).
|
||||
10. Resource IDs must be unique within their category, and each `resources.<category>` must be an array.
|
||||
11. `runtime_resources` entries require `runtime` and `type` fields.
|
||||
12a. `resources.hooks` and `profiles.<name>.uses.hooks` are refused: "removed in plugin-primitive (Phase 3a)". Declare
|
||||
a plugin instead.
|
||||
12b. A plugin needs a unique non-empty `id`, a `source` object with `kind: local` and a non-empty `path`, and a
|
||||
`plugin_type` of `claude`, `codex` or `auto` when given.
|
||||
12c. Lifecycle `mechanic` must be a canonical `seat@rig` session address.
|
||||
9. All resource paths must be safe relative paths.
|
||||
10. Resource IDs must be unique within their category.
|
||||
11. `runtime_resources` entries require `runtime` field.
|
||||
12. Lifecycle `execution_mode` must be `interactive_resident`.
|
||||
13. Lifecycle `compaction_strategy` must be one of `default-compaction`, `managed-compaction`, `handover`, `apprentice-handover` — or a deprecated alias (`harness_native`, `pod_continuity`), which validates with a deprecation advisory and normalizes to its canonical value (OPR.0.5.6.20).
|
||||
14. Lifecycle `restore_policy` must be `resume_if_possible`, `relaunch_fresh`, or `checkpoint_only`.
|
||||
15. Startup files and actions follow the same validation rules as in RigSpec.
|
||||
|
||||
Unknown keys are ignored, not refused. `rig agent validate <path> [--json]` runs these syntax checks through the running
|
||||
daemon; it doesn't resolve imports, find skills or check that files exist, so a missing skill shows up only at launch.
|
||||
|
||||
---
|
||||
|
||||
## File System Layout
|
||||
@@ -511,8 +469,8 @@ my-agent/
|
||||
skills/
|
||||
my-skill/
|
||||
SKILL.md # skill content
|
||||
plugins/
|
||||
my-plugin/ # plugin (skills, hooks) with .claude-plugin/ and/or .codex-plugin/
|
||||
hooks/
|
||||
pre-commit.sh # hook script
|
||||
runtime/
|
||||
claude-settings.fragment.json # runtime-specific resource
|
||||
```
|
||||
@@ -523,20 +481,12 @@ The only required file is `agent.yaml`. Everything else is referenced by paths i
|
||||
|
||||
## Shipped Examples
|
||||
|
||||
Every agent below except `shared` imports `shared` and selects `plugins: [shared:openrig-core]`, which carries
|
||||
`openrig-user`. Paths are under `packages/daemon/specs/agents/`; the kernel's own agents are under
|
||||
`packages/daemon/specs/rigs/launch/kernel/agents/`.
|
||||
|
||||
| Agent | Location | Default runtime | Profile skills | Purpose |
|
||||
|-------|----------|-----------------|----------------|---------|
|
||||
| `shared` | `shared/` | — | — (resource pool only) | Shared skills, the `openrig-core` plugin and runtime resources |
|
||||
| `implementer` | `development/implementer/` | claude-code | development-team, systematic-debugging, verification-before-completion | Implementation agent |
|
||||
| `qa` | `development/qa/` | codex | development-team, systematic-debugging, verification-before-completion, agent-browser, dogfood | Quality assurance agent |
|
||||
| `orchestrator` | `orchestration/orchestrator/` | claude-code | orchestration-team, systematic-debugging, verification-before-completion | Rig orchestration lead |
|
||||
| `independent-reviewer` | `review/independent-reviewer/` | claude-code | review-team, systematic-debugging, verification-before-completion | Independent code reviewer |
|
||||
| `vault-specialist` | `apps/vault-specialist/` | claude-code | systematic-debugging, verification-before-completion, vault-user | Vault domain specialist |
|
||||
| `product-designer` | `design/product-designer/` | claude-code | development-team, frontend-design, verification-before-completion | Product designer |
|
||||
| `pm` | `product-management/pm/` | claude-code | office-hours, context-builder, requirements-writer, ui-mockup, plan-review, exec-summary, backlog-capture; `advisor` profile: orchestration-team | Product manager; its `advisor` profile is the factory's advisor |
|
||||
| `analyst`, `synthesizer` | `research/analyst/`, `research/synthesizer/` | claude-code, codex | — | Research team |
|
||||
| `conveyor-lead`, `-planner`, `-builder`, `-reviewer` | `conveyor/` | claude-code, codex, claude-code, codex | per role | Kept for the `factory-rsi` world bundle (its planner); no built-in team uses them |
|
||||
| `factory-rsi-release-manager`, `factory-rsi-dogfood` | `factory-rsi/` | claude-code | per role | Used by the `factory-rsi` world bundle (not a built-in team) |
|
||||
| Agent | Location | Imports | Profile Skills | Purpose |
|
||||
|-------|----------|---------|---------------|---------|
|
||||
| `shared` | `specs/agents/shared/` | none | — (resource pool only) | Shared skill pool for all built-in agents |
|
||||
| `implementer` | `specs/agents/development/implementer/` | `shared` | openrig-user, development-team, test-driven-development, systematic-debugging, etc. | TDD implementation agent |
|
||||
| `qa` | `specs/agents/development/qa/` | `shared` | openrig-user, development-team, etc. | Quality assurance agent |
|
||||
| `orchestrator` | `specs/agents/orchestration/orchestrator/` | `shared` | openrig-user, orchestration-team, etc. | Rig orchestration lead |
|
||||
| `independent-reviewer` | `specs/agents/review/independent-reviewer/` | `shared` | review-team, systematic-debugging, verification-before-completion | Independent code reviewer |
|
||||
| `vault-specialist` | `specs/agents/apps/vault-specialist/` | `shared` | openrig-user, systematic-debugging, vault-user | Vault domain specialist |
|
||||
| `design` | `specs/agents/design/` | none | — | Product designer |
|
||||
@@ -1,7 +1,7 @@
|
||||
# Agent Startup Guide
|
||||
|
||||
Last validated: 2026-10-05, against main `9b88b118`
|
||||
Applies to: OpenRig 0.6.8
|
||||
Applies to: OpenRig 0.6.6
|
||||
|
||||
This guide teaches you how to think about what goes into an agent's startup experience — what files to write, where to put them, and how the layering model delivers them. It is an authoring guide, not a schema reference. For field-level details, see `rig-spec.md` and `agent-spec.md`.
|
||||
|
||||
@@ -38,31 +38,6 @@ The attention codes that stop startup this way are `trust_gate`,
|
||||
`bypass_consent_gate`, `codex_auth_refusal` and `codex_client_incompatible`.
|
||||
They are recognized from each harness's English prompt text.
|
||||
|
||||
## Continue a Codex fork whose child ID arrived late
|
||||
|
||||
For a member with `session_source.mode: fork`, OpenRig waits for Codex's new
|
||||
child thread ID before sending its role and other startup prompts. It saves the
|
||||
ID and sends the role only for a verified child: the bound pane's foreground
|
||||
process forks the requested parent, and its own native record, matched to its
|
||||
start time, supplies the ID. This capture uses `runtime.readiness_timeout_seconds`
|
||||
(30 seconds by default, configurable from 1 to 600 seconds), as does the later
|
||||
readiness check. The two waits have separate budgets. A seat handover with
|
||||
`--source fork:<seat>` is different: its fork carries the conversation itself,
|
||||
and a missed ID capture leaves the ID pending rather than stopping the handover.
|
||||
|
||||
If the ID is still unavailable, the seat reports `attention_required` and keeps
|
||||
its startup context pending. Wait for the child to finish starting, resolve any
|
||||
native prompt, then run `rig seat continue <seat>`. The continuation verifies
|
||||
that the bound pane is running a fork of the requested parent and reads the
|
||||
child's own native identity before delivering the saved context. It does not
|
||||
launch another fork or resume the parent. The parent ID is never saved as the
|
||||
child's resume token.
|
||||
|
||||
An unavailable or conflicting identity leaves the context pending. Once prompt
|
||||
delivery has been attempted, it cannot be replayed by `continue`, including
|
||||
after a daemon restart: inspect `rig seat status <seat>` and the native pane
|
||||
before deciding how to recover an uncertain delivery.
|
||||
|
||||
## Two Categories of Startup
|
||||
|
||||
Everything an agent receives at boot time falls into one of two categories:
|
||||
@@ -240,161 +215,32 @@ seconds), for up to 30 seconds by default. Change the window with
|
||||
`rig config set runtime.readiness_timeout_seconds <1-600>` (or `OPENRIG_RUNTIME_READINESS_TIMEOUT_SECONDS`); it
|
||||
applies to the next launch. A recognized prompt (the attention codes above) ends the wait at once as
|
||||
`attention_required`. A timeout ends startup as `failed` ("Readiness timeout after Ns — harness did not become
|
||||
interactive"), and the post-launch files aren't sent. A Codex fork that the rig launches (a member with
|
||||
`session_source.mode: fork`, or an agent image's fork) is the exception: its timeout ends as `attention_required`,
|
||||
with its startup context kept for `rig seat continue` (see below). A seat handover's fork has its own readiness check.
|
||||
interactive"), and the post-launch files aren't sent.
|
||||
|
||||
**Fresh Claude handovers.** `rig handover --source fresh` keeps the previous agent's scrollback. Before sending the
|
||||
handover context, OpenRig waits for the latest prompt inside Claude's complete input frame, and confirms that the
|
||||
process in the pane belongs to the new launch. A shell's `❯` prompt or echoed launch command is not enough, even
|
||||
with an old Claude header or input frame above it and Claude already running. A header alone or a partially drawn
|
||||
input frame also keeps the check pending. If the current screen or process cannot be read, or the process identity is unconfirmed, the handover keeps
|
||||
waiting within the readiness window and fails if that window expires. Old screen text or the `claude` process label
|
||||
alone cannot complete this check. A healthy agent can therefore remain unconfirmed while those observations are
|
||||
unavailable; inspect its pane before deciding how to recover.
|
||||
|
||||
**Claude submission check.** For each startup message to a Claude seat, OpenRig makes a bounded check that the prompt
|
||||
was submitted. When the capture can't tell, it records the submission as unverified and carries on. When it sees the
|
||||
same prompt still sitting in the input, it presses Enter once more; if it's still there, it warns "Startup prompt still
|
||||
staged in <session>; press Enter in that pane." The seat can still end `ready` with its submission `unverified` or
|
||||
`staged`, so `ready` doesn't prove the prompt was submitted. After all files and actions are delivered, readiness is
|
||||
checked once more, so a prompt that appears by then gives `attention_required`.
|
||||
**Claude submission check.** For every startup message to a Claude seat, OpenRig confirms the prompt was submitted. If
|
||||
the text is still sitting in the input, it presses Enter once more; if it's still there, it warns "Startup prompt still
|
||||
staged in <session>; press Enter in that pane." The seat still ends `ready`. After each send, readiness is checked
|
||||
again, so a prompt that appears at that point gives `attention_required`.
|
||||
|
||||
**Startup proof.** A `startup_proof` action selects `authenticated` or `none` (the default is none; the last applicable
|
||||
one wins, and it needs `idempotent: true`). With `authenticated`, a fresh launch of an agent seat includes a challenge,
|
||||
and the seat answers it with `rig startup-proof submit --challenge-id <id> --answer <answer>`. `rig ps --nodes --full`
|
||||
shows the result in the ORIENTED column: `verified`, `missing`, `rejected` or `n-a`. A missing proof doesn't block startup.
|
||||
and the seat answers it with `rig startup-proof submit --challenge-id <id> --answer <answer>`. `rig ps --nodes` shows
|
||||
the result in the ORIENTED column: `verified`, `missing`, `rejected` or `n-a`. A missing proof doesn't block startup.
|
||||
|
||||
**After a failure.** Delivery, launch and action failures, and readiness timeouts other than a Codex fork's, give
|
||||
`failed`. Every 30 seconds the context monitor marks a `failed` or `attention_required` seat `ready` once its pane reads
|
||||
ready, unless its fresh or Codex fork context is still pending for `rig seat continue`. A seat that timed out can therefore read `ready` without having received its
|
||||
post-launch files. If it needs them, first look at what that occupant has done; then
|
||||
`rig seat launch <seat> --fresh --reason <text>` starts a blank conversation for the seat. If the occupant is still
|
||||
live, the command refuses with `session_live` unless you also pass `--stop`, which replaces that occupant deliberately.
|
||||
|
||||
**Preview before replacing a seat.** `rig seat launch <seat> --fresh --plan` inspects the selected
|
||||
seat without starting tmux, stopping or launching a process, projecting startup files, or changing
|
||||
lifecycle/queue records. Add `--json` for structured output. `--fresh` is still required;
|
||||
`--reason` is optional for the preview and required when executing. Pass `--stop` to preview the
|
||||
intended replacement of a live managed occupant. Adopted and unmanaged occupants remain blocked.
|
||||
|
||||
The plan identifies the target, current occupant, stop requirements, blockers, startup counts,
|
||||
and each sibling seat's unchanged effect. Siblings stay attached and untouched. Launch composes
|
||||
a new command through the runtime adapter using current settings; it does not replay a stored
|
||||
wrapper command. The seat's launch environment and managed executable selection still apply.
|
||||
The plan does not construct or display the launch command.
|
||||
|
||||
A preview is a snapshot, not a reservation or a native-readiness check. Unreadable tmux produces
|
||||
`complete: false` and `launchable: null` (unknown), unless a known blocker already proves
|
||||
`launchable: false`. A successful preview exits 0, including blocked or incomplete plans; scripts
|
||||
must inspect `launchable === true` before deciding to execute. Request failures still exit nonzero.
|
||||
Execution always resolves and checks the current state again. An older daemon without the preview
|
||||
endpoint refuses the request; the CLI never falls back to executing a launch.
|
||||
|
||||
### Change an existing seat's working directory
|
||||
|
||||
Editing `cwd` in an already applied RigSpec doesn't update an existing seat's saved launch directory. Use `set-cwd` to
|
||||
save a new one for the seat's next launch:
|
||||
|
||||
```sh
|
||||
rig seat set-cwd planning-lead@project \
|
||||
--cwd /work/project/seats/planning-lead --reason "isolate planning"
|
||||
rig seat status planning-lead@project
|
||||
```
|
||||
|
||||
**The path:** it must be absolute **on the daemon's host**. OpenRig creates a missing directory, resolves symlinks to
|
||||
its real path, and refuses a filesystem root.
|
||||
|
||||
**What it saves:** the directory and a `node.cwd_changed` audit event (from, to, reason, operator), together, in one
|
||||
transaction. The seat's node, canonical address, queue, session history and skill selection stay as they are.
|
||||
`rig seat status` shows **Working directory for future launches** (`launch_cwd` in JSON). That's saved configuration,
|
||||
not where the running process is.
|
||||
|
||||
**What it writes:** it creates the folder if it's missing, and writes nothing else there. The seat's next fresh launch or
|
||||
rebuild handover writes its startup files there, as launch does today.
|
||||
|
||||
**`set-cwd`'s preflight policy:** before saving, it reads, without writing, the enumerated resource copies (including
|
||||
nested plugin files) and startup skills that launch would place in the new directory, at their actual destinations,
|
||||
as they are at that moment. It's a point-in-time check, not a global overwrite guarantee or protection against later
|
||||
changes; at adoption, launch applies its own policy. (The commit's re-check covers the saved startup configuration,
|
||||
not the destination's file contents.)
|
||||
- **Refused, with the protected paths named (`cwd_destination_conflict`):** a file there that an operator edited, an
|
||||
unrecorded file with different content, or two sources for one destination. That's stricter than launch, which
|
||||
overwrites an unrecorded differing file with a warning; the refusal is deliberate, while the occupant still runs.
|
||||
- **What to do:** use a clean destination, or move or merge those files, then retry.
|
||||
- **Not checked:** managed guidance blocks and native configuration merges keep the adapter's policy at launch, and
|
||||
launch-owned files such as `.openrig/context-collector.cjs` are written by launch as always.
|
||||
- **A community harness** takes no startup files, so none are checked for it.
|
||||
|
||||
**The running occupant keeps its current directory.** Adopt the new one with:
|
||||
- `rig seat launch <seat> --fresh --stop --reason <text>`, which starts a blank conversation; or
|
||||
- `rig handover <seat> --source rebuild --reason <text>`, which carries durable context.
|
||||
|
||||
For Codex rebuilds, OpenRig also carries a complete supported native permission policy read from the live
|
||||
predecessor's own conversation and process, without adding fresh-launch grants. A later recorded seat permission
|
||||
or policy choice, or a differing declared successor profile, takes precedence. Missing, stale or unsupported observations keep the existing launch
|
||||
behaviour and are reported as unverified in the handover result; requested modes and profiles alone don't prove
|
||||
preservation. The result reports what was emitted, not native successor equivalence.
|
||||
|
||||
**Adopt it promptly.** The saved directory doesn't move the running process, but background work can use it before
|
||||
adoption. Saved configuration isn't the live process's directory, and these examples aren't the only consumers. For a
|
||||
running Claude seat:
|
||||
- **Collector provisioning** writes `.openrig/context-collector.cjs` and merges `.claude/settings.local.json` in the
|
||||
saved directory, under its existing preservation rules.
|
||||
- **Managed compaction,** manual (`POST /api/compaction/trigger`) or automatic, asks the seat to write its restore map
|
||||
under it. That may be outside the seat's current workspace, so a seat without bypass permissions may meet a write
|
||||
prompt.
|
||||
|
||||
Adopting promptly is guidance. It doesn't protect against a poll or a compaction that runs before your next command.
|
||||
|
||||
**Before adopting,** don't `rig down`/`rig up` or hand over by fork. Those resume the existing conversation in the
|
||||
saved directory, and Claude keeps conversations per project directory, so a resume there may not find it.
|
||||
Cross-directory resume hasn't been run natively; this is the order to follow. `rig seat restart --keep-conversation`
|
||||
(Codex) isn't adoption: it respawns in the directory it observes from the running process.
|
||||
|
||||
**Failures:** a refusal, missing or malformed saved startup context, or an audit-write failure leaves the prior
|
||||
directory saved, and changes no seat, custody or startup file (a refusal may leave the new folder created). A concurrent configuration change is reported, not overwritten. A CLI timeout means the outcome is
|
||||
unknown; check `rig seat status` before retrying. Choosing the same directory again records no second event.
|
||||
|
||||
**The old directory:** files there are left as they are, since other seats may still use them. The source RigSpec
|
||||
declaration isn't changed either; update it separately if a future recreation should use the new directory.
|
||||
**After a failure.** Delivery, launch and action failures, and readiness timeouts, give `failed`. Every 30 seconds the
|
||||
context monitor marks a `failed` or `attention_required` seat `ready` once its pane reads ready, unless fresh context
|
||||
is still pending for `rig seat continue`. A seat that timed out can therefore read `ready` without having received its
|
||||
post-launch files; relaunch it with `rig seat launch <seat> --fresh` if it needs them.
|
||||
|
||||
### The `applies_on` Field
|
||||
|
||||
Each startup file and action specifies when it applies:
|
||||
- `fresh_start` — delivered when a new conversation starts: the first launch, `rig seat launch --fresh`,
|
||||
`rig seat continue`, and seats restored with `--fresh`
|
||||
- `restore` — delivered when a seat is restored without its earlier conversation: a restore whose resume falls back to a fresh conversation, or a retried start
|
||||
- `restore` — delivered when a seat is restored, including a restore whose resume falls back to a fresh conversation
|
||||
- Default: `[fresh_start, restore]` (both)
|
||||
|
||||
**An exact resume delivers neither.** When a restore reopens the seat's saved conversation (`rig up <rig> --existing` with a resume token), OpenRig types no startup actions and delivers no startup files, `restore` ones included: the conversation already has them, and typing them again would add turns to it. The one exception: a managed guidance block missing from the guidance file is put back before the harness starts.
|
||||
|
||||
Use this to avoid re-sending context that a fresh conversation doesn't need twice. For example, a one-time project briefing might only apply on `fresh_start`, while identity grounding should apply on both, so a seat that comes back fresh gets it again.
|
||||
|
||||
---
|
||||
|
||||
## What a seat is set to, and what it's running
|
||||
|
||||
A seat's settings can disagree with its running agent: what's saved for the next launch, what the running process
|
||||
actually uses, and what its conversation has already read are three separate things. OpenRig reports each one
|
||||
separately. Without live evidence it says unknown (or not verified), never the saved value. A saved change reaches the
|
||||
running seat only through the action in the last column.
|
||||
|
||||
| What | Saved for the next launch | What the running seat has | How the running seat gets it |
|
||||
|---|---|---|---|
|
||||
| Model | `rig seat set-model` | `rig ps --nodes` shows the configured model beside the last observed one, or `UNKNOWN (<reason>)` | The next managed resume or successor launch |
|
||||
| Reasoning effort | `rig seat set-effort` | `rig seat effort <seat>`: requested, saved, sent at launch, and what the session recorded, which is not verified until it takes a turn | Its next managed continuation; nothing restarts |
|
||||
| Permissions | `rig seat set-permissions` (`--mode`, `--rules`, or for Codex `--codex-permissions` or `--codex-profile`), shown by `rig seat status` | What it launched with; a status read doesn't prove the running process enforces the selection | Its next managed launch or resume ([per-seat permission mode](getting-started.md#per-seat-permission-mode)) |
|
||||
| Working directory | `rig seat set-cwd`, shown by `rig seat status` as **Working directory for future launches** | The directory it started in | `rig seat launch --fresh --stop` (a blank conversation) or `rig handover --source rebuild` (durable context); [details](#change-an-existing-seats-working-directory) |
|
||||
| Startup files and skills | The spec's startup files, skills and actions | What its conversation read when it started; editing a file afterwards doesn't reach it | A fresh launch or a handover delivers them again; for the running seat, send or walk the change (`rig walk <seat> --through <files>`) |
|
||||
| Tools (MCP servers, plugins) | Selected fragments, merged into the harness's own config (`.mcp.json` for Claude, `config.toml` for Codex) | Unknown to OpenRig: registered isn't active, Claude asks before it uses a new server, and no OpenRig command reports which tools a running harness loaded | Check in the harness itself (Claude Code's `/mcp`); a running session may need a restart to pick up newly written config ([runtime config disclosure](#runtime-config-disclosure)) |
|
||||
|
||||
Per harness: Claude Code's and Codex's permission choices are in the setup reference
|
||||
([Claude Code](getting-started.md#claude-code-a-different-launch-flag),
|
||||
[Codex](getting-started.md#codex-select-sandbox-and-approvals-together)), Codex homes are
|
||||
[below](#separate-codex-homes-for-separate-installations), community harnesses' limits are in
|
||||
[their presets](community-harness-presets.md), and moving a live seat to the other runtime is in the
|
||||
[setup reference](getting-started.md#move-a-seat-to-the-other-runtime).
|
||||
Use this to avoid re-sending context that the agent already has from its resumed conversation. For example, a one-time project briefing might only apply on `fresh_start`, while identity grounding should apply on both.
|
||||
|
||||
---
|
||||
|
||||
@@ -405,9 +251,7 @@ The AgentSpec and RigSpec allow declaring deterministic environment configuratio
|
||||
### What the Spec Supports
|
||||
|
||||
**Hooks** ship inside plugins: declare the plugin under `resources.plugins[]`. AgentSpec validation refuses
|
||||
`resources.hooks`. OpenRig loads one plugin's hooks into a seat itself: the shipped `openrig-core` plugin, for a Claude seat
|
||||
that selects it (see [the refocus channel](refocus-channel.md#the-mechanism)). The folder a declared plugin is projected into
|
||||
is not one Claude Code or Codex loads, so a plugin of your own does not get its hooks run by that projection.
|
||||
`resources.hooks`.
|
||||
|
||||
**Runtime resources** (in `resources.runtime_resources`):
|
||||
```yaml
|
||||
@@ -434,11 +278,6 @@ Types are `send_text`, `slash_command` and `startup_proof` (see "Startup proof"
|
||||
`idempotent` is required, and an action that isn't idempotent must not list `restore` in `applies_on`. Both phases
|
||||
run after the harness is ready: `after_files` (the default) after the post-launch files, then `after_ready`.
|
||||
|
||||
**Don't rename a managed Claude seat.** OpenRig starts every Claude seat with `--name <session>`, on a fresh start and on
|
||||
every resume, and its own reads of the seat use that name: context usage and managed compaction read the status-line
|
||||
record Claude saves under it, and the input box is recognized by the name on its border. A startup `/rename` to another
|
||||
name breaks those reads until the next resume puts the session name back.
|
||||
|
||||
### Current Support Matrix
|
||||
|
||||
| Capability | Status | Notes |
|
||||
@@ -446,9 +285,9 @@ name breaks those reads until the next resume puts the session name back.
|
||||
| Guidance file projection (`guidance_merge`) | **Supported** | Reliable. Primary delivery mechanism. |
|
||||
| Skill projection (`skill_install`) | **Supported** | Reliable. Skills are copied to workspace. |
|
||||
| `send_text` delivery after ready | **Supported** | Reliable. Requires harness to be ready. |
|
||||
| Hooks | **Through plugins, limited** | `resources.hooks` is refused. OpenRig loads the shipped `openrig-core` plugin's hooks into a Claude seat that selects it (Claude Code v2.1.280 or later); a plugin you declare under `resources.plugins[]` is projected, but its hooks are not loaded. |
|
||||
| Hooks | **Through plugins** | Declare a plugin under `resources.plugins[]`; `resources.hooks` is refused. |
|
||||
| Runtime resource projection | **Supported for recognized fragments** | `claude_settings_fragment`, `claude_mcp_fragment`, and `codex_config_fragment` are applied to provider config. Unknown types are copied to runtime extension directories. |
|
||||
| Permission configuration | **Native settings plus managed launch flags** | OpenRig launches Claude with `acceptEdits` and Codex with `workspace-write` unless an explicit supported selection changes them; a seat with no policy, selection or named Codex profile also gets the per-launch [team default](rig-spec.md#team-launch-defaults), and the `kernel` rig's seats get a wider operational default ([rig spec, "At launch"](rig-spec.md)). Neither is written to a settings file. Use [the first-user permission guide](getting-started.md#opt-in-permissive-operation) for opt-in and custom choices. |
|
||||
| Permission configuration | **Native settings plus managed launch flags** | OpenRig launches Claude with `acceptEdits` and Codex with `workspace-write` unless an explicit supported selection changes them. It does not add a global Claude `Bash(rig:*)` allowance. Use [the first-user permission guide](getting-started.md#opt-in-permissive-operation) for opt-in and custom choices. |
|
||||
| MCP installation | **Supported for Claude fragments** | A selected `claude_mcp_fragment` is merged into the project's `.mcp.json`. Claude asks to approve new servers found there; that prompt stops startup as `mcp_gate` until someone answers it and runs `rig seat continue`. Otherwise use `/mcp` or `claude mcp add`, or describe the servers in startup files for the agent to configure. |
|
||||
| System dependency installation | **Not deterministic** | Describe in startup files; agent handles via shell commands. |
|
||||
| Recurring tasks / wake timers | **Runtime-dependent** | Claude Code supports recurring tasks via the `/loop` command. Codex does not have a confirmed equivalent. Orchestrators should include `/loop` instructions in startup for Claude Code agents. |
|
||||
@@ -482,9 +321,6 @@ OpenRig performs best-effort deterministic runtime configuration for managed ses
|
||||
Purpose: apply selected `claude_mcp_fragment` resources for Claude in that project.
|
||||
- Codex global config: `$CODEX_HOME/config.toml`, or `~/.codex/config.toml` when unset
|
||||
Purpose: pre-trust managed workspaces and apply selected `codex_config_fragment` resources. Codex currently has no equivalent project-local MCP config path for global profile settings.
|
||||
- Global skill folders: `~/.claude/skills` and `~/.agents/skills`
|
||||
Purpose: daemon startup seeds the `openrig-skills` and `refocusing` skills and the person-facing `rigs` skill. Each
|
||||
upgrade refreshes the `rigs` skill; a copy installed another way is left as it is.
|
||||
|
||||
Two important caveats:
|
||||
- these writes are best-effort and should still be paired with startup guidance so the local agent can verify and repair them if needed
|
||||
@@ -553,8 +389,6 @@ remain shared.
|
||||
timeout, error or unrecognized answer adds nothing. Named profiles and full
|
||||
bypass are not read. The read may write Codex's own state files in
|
||||
`CODEX_HOME`, read its login and fetch managed policy, as a Codex start does.
|
||||
- Managed launches pass `-c check_for_update_on_startup=false`, so Codex skips its startup update check; your Codex
|
||||
config is not changed.
|
||||
- Can self-install dependencies from instructions but timer/recurring behavior is not reliably available
|
||||
|
||||
**Pi and OMP:**
|
||||
@@ -564,106 +398,6 @@ remain shared.
|
||||
|
||||
**Terminal seats** (`builtin:terminal`) get no agent or profile layers and no startup proof.
|
||||
|
||||
### Claude compaction preparation directory
|
||||
|
||||
Managed Claude compaction asks the seat to write a restore map before `/compact`. By default,
|
||||
OpenRig uses `<cwd>/.openrig/compaction/preparation/`, falling back to its instance home when
|
||||
that directory cannot be prepared. A filesystem write check cannot establish whether Claude's
|
||||
file-edit permissions allow the seat to write there.
|
||||
|
||||
If the launch workspace is denied by Claude's permissions, select an absolute preparation root:
|
||||
|
||||
```sh
|
||||
rig config set policies.claude_compaction.preparation_root /absolute/path/to/restore-maps
|
||||
```
|
||||
|
||||
Grant the seat file-edit access to that root in its Claude configuration. OpenRig does not change
|
||||
Claude permissions; choose a directory outside any matching deny rule. The corresponding environment
|
||||
variable is `OPENRIG_POLICIES_CLAUDE_COMPACTION_PREPARATION_ROOT`.
|
||||
|
||||
New manual and automatic attempts use `<root>/<session>/<attempt-id>/RESTORE-MAP.md`; an in-flight
|
||||
attempt keeps its original path through the post-compaction restore request. The root gets an
|
||||
exclusive `.gitignore` containing `*`, and the daemon publishes the marked `.tmp` file with an
|
||||
atomic rename. Use a dedicated root: a conflicting
|
||||
ignore file or an unwritable configured directory stops preparation with
|
||||
`preparation_directory_unavailable`, visible in `rig compact <session> --state`, without choosing
|
||||
another location. Fix the directory and explicitly retry. `--skip-map` still skips the map once.
|
||||
|
||||
Reset with `rig config reset policies.claude_compaction.preparation_root` to restore the default.
|
||||
The setting applies to new attempts without restarting the daemon.
|
||||
|
||||
The managed `/compact` command keeps its 600-character budget. When the selected map path or
|
||||
the attempt's compaction instruction does not fit, the existing restore request carries it;
|
||||
it never substitutes a newer preparation root or instruction. An explicitly selected root's
|
||||
published map is also named in that request when the path fit in `/compact`. The default root
|
||||
keeps the existing command/restore handoff. Under `--skip-map`, restore still recognizes an
|
||||
optional map completed at that attempt's path, or says that no map was required.
|
||||
|
||||
The compaction preparation and command-submission tests cover manual and automatic attempts,
|
||||
long paths and instructions, settings changed during preparation, directory failures and
|
||||
late maps after cancellation or expiry. They use synthetic delivery and filesystem fixtures;
|
||||
they do not prove a live Claude session's permission choices or compaction behavior.
|
||||
|
||||
### Codex compaction and sizing
|
||||
|
||||
OpenRig's managed compaction is for Claude Code seats only, by design. That covers `rig compact`, the
|
||||
`policies.claude_compaction.*` automatic policy, and the watchdog jobs that the `managed-compaction` and
|
||||
`apprentice-handover` strategies create. A Codex seat compacts with Codex's own automatic compaction, and OpenRig
|
||||
leaves that to Codex.
|
||||
|
||||
- `rig compact <session>` refuses a Codex seat: "not a Claude (claude-code) seat".
|
||||
- `rig compact-plan` lists a Codex seat as skipped (`codex_not_managed_by_claude_compact_in_place`).
|
||||
- The automatic policy never acts on a Codex seat.
|
||||
- A Codex member with `compaction_strategy: managed-compaction` or `apprentice-handover` gets no watchdog jobs.
|
||||
|
||||
**What Codex compacts at.** Codex describes `model_auto_compact_token_limit` as the "token threshold that triggers
|
||||
automatic history compaction (unset uses model defaults)". Its configuration reference does not say what those
|
||||
defaults are, and the model catalog's `auto_compact_token_limit` is null for the models we checked in Codex 0.162.1.
|
||||
Measure a seat's own compactions before relying on an unset limit.
|
||||
|
||||
**What window the model has.** `codex debug models` prints the catalog. Each model carries `context_window`,
|
||||
`max_context_window` and `effective_context_window_percent`. In Codex 0.162.1, `gpt-5.6-sol` has a `context_window`
|
||||
of 272000 at 95%, which is 258400. That is the `model_context_window` its rollout `token_count` events report.
|
||||
A limit only matters when it is below that effective window. Leave `model_context_window` alone: don't raise it toward
|
||||
`max_context_window` to avoid compaction. Set the limit instead.
|
||||
|
||||
**Setting the limit for seats only.** Put `model_auto_compact_token_limit` in a Codex profile file,
|
||||
`$CODEX_HOME/<name>.config.toml` (`~/.codex/<name>.config.toml` when `CODEX_HOME` is unset), and name it on each
|
||||
Codex member that should use it:
|
||||
|
||||
```toml
|
||||
# ~/.codex/seat-compaction.config.toml
|
||||
model_auto_compact_token_limit = 150000 # choose your own value
|
||||
```
|
||||
|
||||
```yaml
|
||||
codex_config_profile: seat-compaction
|
||||
```
|
||||
|
||||
OpenRig passes `-p seat-compaction` on that seat's fresh, fork and resume launches. Codex layers the profile file on
|
||||
top of the base user config, so only seats that name the profile see the lower limit. A Codex session started without
|
||||
that profile keeps the base `config.toml` in the same Codex home (`$CODEX_HOME/config.toml`, or `~/.codex/config.toml`
|
||||
when `CODEX_HOME` is unset). The `150000` is an example, not a recommendation.
|
||||
|
||||
With the normal launch mode, `codex_config_profile` replaces OpenRig's explicit workspace-write sandbox flag, so the
|
||||
profile must set the sandbox and approvals you want. See
|
||||
[permission precedence and limits](getting-started.md#custom-settings-and-precedence), which also gives Codex's order
|
||||
of precedence between a profile, project settings and CLI overrides.
|
||||
|
||||
**The trade-off.** Every model call carries the whole context so far, so a smaller context makes each call cheaper. The
|
||||
cost is that Codex compacts sooner and more often, so more of the conversation is carried as a summary instead of
|
||||
verbatim. A higher limit keeps more detail and makes each call larger.
|
||||
|
||||
**Related keys.** These also shape compaction. This guide doesn't recommend values for them. See Codex's
|
||||
[configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference):
|
||||
|
||||
| Key | What Codex says it does |
|
||||
|---|---|
|
||||
| `model_auto_compact_token_limit_scope` | `total` (the default) counts the full active context; `body_after_prefix` counts only growth after the carried compaction-window prefix. |
|
||||
| `compact_prompt` | Inline override for the history compaction prompt. |
|
||||
| `experimental_compact_prompt_file` | Loads the compaction prompt override from a file (experimental). |
|
||||
| `tool_output_token_limit` | Token budget for storing individual tool or function outputs in history. |
|
||||
|
||||
When authoring startup content, note which instructions are runtime-specific. For example, an orchestrator that needs a monitoring loop should include instructions like: "If running Claude Code, use `/loop 3m` to periodically check rig health. If running Codex, check rig health at the start of each task cycle instead."
|
||||
|
||||
---
|
||||
@@ -715,28 +449,6 @@ Existing user files and legacy role blocks are left intact; this is not a cleanu
|
||||
of already-installed shared blocks. General user-authored guidance projection is
|
||||
unchanged.
|
||||
|
||||
The other shipped agent specs that start a seat with `guidance/role.md` mark that
|
||||
file `orientation: role` too, so `rig queue whoami --json` reports their role and
|
||||
refocus names it. They never projected a role into shared guidance; their startup
|
||||
delivery is unchanged.
|
||||
|
||||
**Removing a leftover shared role block by hand.** A kernel installed before 0.6.5
|
||||
may still hold one seat's old role in its working directory's `CLAUDE.md` (or the
|
||||
rig's configured `managed_blocks` file) or `AGENTS.md`. Upgrading doesn't remove it.
|
||||
`rig down` removes OpenRig's managed blocks from that file when no other running
|
||||
rig uses it, so it stays until then. To remove it sooner, by hand:
|
||||
|
||||
1. Find the exact block: the lines from `<!-- BEGIN OpenRig MANAGED BLOCK: role -->`
|
||||
through `<!-- END OpenRig MANAGED BLOCK: role -->` (in older files, `RIGGED`
|
||||
instead of `OpenRig`). Only the block whose id is exactly `role`; leave
|
||||
`rig-role`, other ids and everything outside the markers alone.
|
||||
2. Confirm each seat that shares that directory has its per-seat replacement:
|
||||
`rig queue whoami --json` run in the seat reports `role.state` as `present`.
|
||||
A seat started before it was upgraded still has the old content in its
|
||||
conversation; restart it fresh if you want it to start from the per-seat role.
|
||||
3. Keep a copy of the file, remove only those lines, and compare the result with
|
||||
the copy: nothing else in the file should differ.
|
||||
|
||||
**Separate project context from role**
|
||||
|
||||
Don't put project documentation inside the role guidance. The role is about the agent's function; project context is about what the agent is working on. Use rig-level or pod-level startup files for project context.
|
||||
|
||||
@@ -1,11 +1,8 @@
|
||||
# Agent state taxonomy
|
||||
|
||||
The formal activity language OpenRig's surfaces render from — the TUI and the `rig ps`
|
||||
ACTIVITY column. One oracle computes it; surfaces render it. Two exceptions remain: the web
|
||||
UI's graph node still derives its own running/needs-input/idle/unknown from the legacy
|
||||
`agentActivity`, and `rig ps --active` / `--filter agentActivity.state` filter on that legacy
|
||||
field. Startup, orientation, restore and attention states are separate vocabularies, listed
|
||||
under "Other state on the same surfaces" below.
|
||||
The formal state language every OpenRig surface renders from — TUI, `rig ps`, the node
|
||||
inventory, and any future consumer. One oracle computes it; surfaces render it; no
|
||||
surface keeps a private vocabulary.
|
||||
|
||||
**This document is the canonical text for the shipped taxonomy** and adds the
|
||||
engineering reconciliation; it never forks a second vocabulary. Its typed source of
|
||||
@@ -19,12 +16,6 @@ truth is `packages/daemon/src/domain/activity-taxonomy.ts`.
|
||||
| activity | `working` · `idle-at-prompt` · `unknown` (+ needs-input as count+reason, below) | what a present agent is doing |
|
||||
| resumability | `live` · `resumable` · `context-walled` | what a non-present agent can come back as |
|
||||
|
||||
Only the activity axis is served today. The session and resumability values are declared in
|
||||
`activity-taxonomy.ts` but no surface reads them: `rig ps --nodes --full` shows the raw session
|
||||
STATUS, both node views show a LIFECYCLE of `running`, `detached`, `recoverable` or `attention_required` (`run`, `det`, `rec`,
|
||||
`att`), and node inventory serves `occupantLifecycle` (`active`, `retiring`, `retired`,
|
||||
`context_walled`, `compacted`, `crashed`, `unknown`).
|
||||
|
||||
The axes never blend. Reachability is strict; revival optimism is a different field
|
||||
(omnigent's strict-liveness split). `unknown` is a first-class honest value — the oracle
|
||||
saying it cannot tell. Unknown beats a confident wrong answer.
|
||||
@@ -41,46 +32,18 @@ state. Attention/alarm values likewise stay in their own machinery (`attentionCo
|
||||
Both herdr and omnigent converged on this exclusion, with warning comments on the
|
||||
collision in both codebases.
|
||||
|
||||
The legacy `agentActivity` field distinguishes a typed provider interruption from
|
||||
a request for a person: fresh Codex `at_limit` and Claude `StopFailure/rate_limit`
|
||||
events carry `state: unknown` and `reason: usage_limit`, never a `needs_input`
|
||||
hook. A permission prompt can independently supply human-input evidence. See
|
||||
[Claude usage-limit detection](claude-status-line.md#claude-usage-limit-detection)
|
||||
for the separate provider signal and queue timer.
|
||||
|
||||
### Per-seat attention in the node inventory
|
||||
|
||||
`rig ps --nodes` carries the daemon's `needsAttention` result, using the same predicate
|
||||
as the rig's `attentionCount`. It also serves `arbitratedNeedsInput`: `true` for observed
|
||||
input, `false` for an observed clear, and `null` when no authoritative needs-input source
|
||||
answered. `needsInputEvidence` retains that source's rung and observation time, or `null`.
|
||||
A zero prompt count alone is not an observed clear. Absent arbitration evidence leaves
|
||||
the existing live-hook fallback in effect; lifecycle, startup, held and error signals
|
||||
can independently raise attention. A false attention flag means no known trigger, not
|
||||
proof that an unobserved input box is clear.
|
||||
|
||||
The compact human table's ATTN column renders `yes`, `no`, or `?` when the flag is
|
||||
unavailable. Compact JSON retains `needsAttention`; use `--full` or
|
||||
`--fields needsAttention,arbitratedNeedsInput,needsInputEvidence` with `--json` for the
|
||||
provenance. The TUI uses the served flag for attention glyphs and totals, and shows the
|
||||
needs-input evidence in seat detail, including a hook-only prompt. With an older daemon,
|
||||
attention stays unknown while its existing prompt, startup and error hints remain visible.
|
||||
|
||||
## Derived diagnoses — computed at read time, never stored
|
||||
|
||||
- **PARKED** — the disease: `(activity = idle-at-prompt OR needs-input pending) ×
|
||||
(open obligations OR unhealthy HELD rows)`. A dropped baton or an unanswered block. When
|
||||
activity is `unknown` the verdict is `indeterminate`, never parked or not-parked. Queryable
|
||||
at rig and seat level with `rig parked [seat] [--rig <name>] [--json]`; the join lives in the
|
||||
parked query, never inside the oracle (the oracle's non-inference contract: it never reads
|
||||
queue state).
|
||||
(open obligations exist)`. A dropped baton or an unanswered block. Queryable at rig and
|
||||
seat level; the join lives in the parked query surface, never inside the oracle
|
||||
(the oracle's non-inference contract: it never reads queue state).
|
||||
- **HELD** — the deliberate counterpart: a queue-level hold with a named owner and an
|
||||
armed wake (`rig view show held`). Stopping on purpose is HELD; stopping by accident is
|
||||
PARKED. A HELD row is healthy only while its wake is live, and not fired-but-unconsumed
|
||||
unless the stuck sweep owns its recovery; an unhealthy HELD row on a stopped seat makes
|
||||
the seat parked.
|
||||
PARKED. A HELD row is **not** parked.
|
||||
- **DONE-UNSEEN** — finished work whose completion nobody consumed (herdr derives it as
|
||||
idle ∧ unseen). Declared as a concept only; no surface computes it yet.
|
||||
idle ∧ unseen). Declared here and computed at read time from claims/transitions,
|
||||
outside the activity oracle, preserving its non-inference boundary.
|
||||
|
||||
## Reconciliation with prior art
|
||||
|
||||
@@ -102,10 +65,8 @@ time-bounded evidence. Rungs, top down, with each rung's retirement condition:
|
||||
- **r3 — Claude `sessions/<pid>.json` self-report** (busy/shell/idle/waiting, since
|
||||
v2.1.139): standing, above hooks for working/idle. Undocumented internal — unreadable
|
||||
means fall down the ladder, never error.
|
||||
- **r2 — lifecycle hooks** (Claude SessionStart/UserPromptSubmit/PostToolBatch/Stop/StopFailure/Notification;
|
||||
Codex SessionStart/UserPromptSubmit/Stop/PermissionRequest): standing for Claude; Codex's
|
||||
hook rung starts at trial and is promoted after 50 agreeing observations over at least an
|
||||
hour. Exactly-once turn boundaries; SubagentStop filtered (it
|
||||
- **r2 — lifecycle hooks** (Claude Stop/StopFailure; Codex UserPromptSubmit/Stop/
|
||||
PermissionRequest): standing. Exactly-once turn boundaries; SubagentStop filtered (it
|
||||
can fire post-turn and must never revive an idle seat). Hook-rung authority is
|
||||
TIME-BOUNDED: the hook rung is the only rung that does not self-date its evidence, so
|
||||
persistent cross-rung contradiction degrades it to identity-only, visibly, with a
|
||||
@@ -115,53 +76,11 @@ time-bounded evidence. Rungs, top down, with each rung's retirement condition:
|
||||
- **r1 — window-activity sampling** (today's oracle): the fallback tier. Retires
|
||||
PER-HARNESS when that harness's hook rung earns trust through a measured agreement
|
||||
window in production — never by fixture pass alone (symmetric admission: a fixture
|
||||
pass admits a rung to TRIAL, where it is measured but not consulted; production agreement
|
||||
promotes it). Undeclared and partial-coverage rungs are identity-only, which is also where
|
||||
a degraded rung goes, with one declared exception: for a pi or omp seat or a community
|
||||
harness, sampling is positive-only: a changing pane reads working, and a quiet one never reads idle on its
|
||||
own, since the pane can be quiet mid-turn.
|
||||
- **pi and omp runner hooks**: OpenRig's runner reads the child's RPC event stream and posts
|
||||
each turn boundary (`agent_start`, `turn_start`, tool calls, `agent_end`; attention). These
|
||||
decide working, idle and needs-input. Unlike Claude and Codex hooks, an idle or attention
|
||||
boundary holds until the next one instead of expiring after 15 s; a working boundary still
|
||||
expires, so a turn whose end was lost reads unknown, not working forever. Posts are taken
|
||||
in the runner's own order (time, then its sequence), so an older boundary arriving late
|
||||
doesn't win. The runner's report that its child
|
||||
exited reads unknown, not idle. A boundary the runner didn't see (if a runtime ended a turn
|
||||
without `agent_end`) leaves the seat working up to the 15 s window, then unknown, never idle. After a
|
||||
daemon restart, a runner seat takes its last recorded boundary from the hook store, for its
|
||||
current session and occupant generation only, so an idle seat still reads idle before it
|
||||
posts again, provided that report is fresh: a pi runner's idle boundary states an interval
|
||||
(below) and lapses to unknown once it is older than two of them.
|
||||
A pi runner also posts an idle `Stop` (`idle_heartbeat`) every three minutes while it waits, and states that
|
||||
interval as `livenessSeconds` on every `Stop`: a newly ready runner reads idle at once, and an idle boundary that
|
||||
carries an interval holds for two of them, then lapses to unknown, so a runner killed without saying so stops reading
|
||||
idle. Silence never clears a pending attention prompt, and a runner that states no interval (omp, an older pi
|
||||
runner) keeps the hold-until-the-next-boundary behaviour.
|
||||
|
||||
Claude permission notifications raise needs-input immediately. A visible permission can clear
|
||||
after it has been observed and then disappears. A notification whose dialog was never observed
|
||||
can also clear when Claude reports `PostToolBatch`: every tool in that actor's batch has resolved,
|
||||
so its earlier permission requests are no longer pending. The relay carries the native actor
|
||||
identity; a subagent or in-process teammate finishing its batch cannot clear the main session's
|
||||
request, and overlapping actors remain separate. An individual `PostToolUse` is insufficient
|
||||
because another tool in the batch may still be waiting for permission.
|
||||
|
||||
Batch completion must come from the current occupant and have a later source timestamp than
|
||||
the matching notification. Missing actor attribution from an older relay, equal or older
|
||||
timestamps, and another actor's completion retain attention. An unrecognized or missing screen
|
||||
does not expire attention by age. `Stop` and `UserPromptSubmit` remain the turn-boundary fallback.
|
||||
The oracle remembers each actor's latest completed batch for the current occupant, so a strictly
|
||||
earlier notification arriving late cannot restore the mark, even if the completion arrived first.
|
||||
A notification with an equal or later timestamp remains eligible; swapping or retiring the
|
||||
occupant discards its remembered completions.
|
||||
Completing a batch changes the needs-input signal without inferring that the seat is idle or
|
||||
overwriting a later elicitation. The hook contract is documented in
|
||||
[Claude's hooks reference](https://code.claude.com/docs/en/hooks#posttoolbatch).
|
||||
pass admits a rung to TRIAL; production agreement promotes it; identity-only until
|
||||
promoted).
|
||||
|
||||
Partial-coverage honesty: a source with partial lifecycle coverage gets identity-only
|
||||
trust, unless its inventory declares it positive-only. A positive-only source can report
|
||||
working and nothing else; its silence reads unknown, never idle. The ladder is also the migration path — new oracles slot in above existing
|
||||
trust. The ladder is also the migration path — new oracles slot in above existing
|
||||
heuristics, lower rungs retire a release at a time, consumers never see a flag day.
|
||||
|
||||
Seat-keyed: state attaches to the durable seat nodeId, never the occupant. A handover or
|
||||
@@ -169,23 +88,6 @@ generation swap is its own visible event — never an activity transition — an
|
||||
rung-inventory re-declaration: a successor never inherits its predecessor's rung
|
||||
authority (hooks live in occupant config while the pane is seat-persistent).
|
||||
|
||||
## Other state on the same surfaces
|
||||
|
||||
These are separate vocabularies, not activity values. `rig ps --nodes --full` shows them in
|
||||
its STARTUP, ORIENTED, LIFECYCLE and RESTORE columns (the default compact view shows only
|
||||
LIFECYCLE); see the
|
||||
[startup guide](agent-startup-guide.md) for how each arises.
|
||||
|
||||
- **Startup status:** `pending`, `ready`, `attention_required`, `failed`. `ready` means
|
||||
startup finished, never that the seat is oriented, and a seat isn't marked `ready` while
|
||||
its startup context is still pending for `rig seat continue`.
|
||||
- **Oriented:** `verified`, `missing`, `rejected`, `n-a`, from the startup proof.
|
||||
- **Attention codes:** `trust_gate`, `hook_trust_gate`, `update_gate`, `login_required`,
|
||||
`mcp_gate`, `bypass_consent_gate`, `codex_auth_refusal`, `codex_client_incompatible`.
|
||||
- **Restore outcome:** `resumed`, `fresh-primed`, `awaiting-decision`, `attention_required`,
|
||||
`failed` (plus `rebuilt`, `operator_recovered` and the legacy `fresh`). A seat joined with
|
||||
`rig attach` as an external CLI reads `left_attached`: restore leaves it as it is.
|
||||
|
||||
## Rejected oracles — dated receipts (2026-08-26), so nobody re-derives them expensively
|
||||
|
||||
- **transcript-quiescence as an activity oracle: REJECTED.** omnigent's 1-second version
|
||||
|
||||
@@ -12,9 +12,10 @@ comes from a web page, only when that page is the OpenRig UI or a page you allow
|
||||
its own Tailscale name (for example `my-machine.your-tailnet.ts.net`, or the short `my-machine`).
|
||||
The daemon learns its own Tailscale name automatically from Tailscale on this machine.
|
||||
- The web UI, when it is turned on (`rig config set ui.enabled true`, then restart the daemon) and
|
||||
opened over `http` on the daemon's own port at any address the daemon accepts, including its
|
||||
Tailscale name. A UI page served any other way, such as over `https` through your own domain,
|
||||
also needs its exact origin in `OPENRIG_ALLOWED_ORIGINS`, then a daemon restart.
|
||||
opened at the daemon's own address and port. To open it at a non-loopback name or address, such
|
||||
as its Tailscale name, also list that page's exact origin in `OPENRIG_ALLOWED_ORIGINS` (for
|
||||
example `http://my-machine.your-tailnet.ts.net:7433`), then restart the daemon. Without it, the
|
||||
UI's terminal is refused there, and at a non-loopback IPv6 address its API requests are too.
|
||||
|
||||
### When you see a refusal
|
||||
|
||||
@@ -34,16 +35,14 @@ The daemon answers `403` with a sentence that says what to do. There are two kin
|
||||
|
||||
`OPENRIG_ALLOWED_HOSTS` lists names you use to reach the daemon. `OPENRIG_ALLOWED_ORIGINS` lists
|
||||
web pages allowed to call it. They are separate: a UI served through your own domain usually needs
|
||||
both. Separate several entries with commas. Pages on other origins cannot read the refusal; the
|
||||
message is for you, the CLI and agents.
|
||||
both. Pages on other origins cannot read the refusal; the message is for you, the CLI and agents.
|
||||
|
||||
### Limits
|
||||
|
||||
- If you rename the machine in Tailscale, the daemon keeps accepting its previous name until it
|
||||
restarts or until it next looks its name up after seeing an unrecognized one.
|
||||
- If the daemon has not reached Tailscale's resolver since it started, its Tailscale name is
|
||||
refused until a lookup succeeds. A later failed lookup keeps the name it already learned.
|
||||
`localhost` and IP addresses keep working.
|
||||
- If the daemon cannot reach Tailscale's resolver, its Tailscale name is refused until a later
|
||||
lookup succeeds. `localhost` and IP addresses keep working.
|
||||
- This protects against unknown web pages and unknown names. It is not complete browser isolation:
|
||||
a page on another site can still cause a simple read request to an address the daemon accepts,
|
||||
although it cannot read the answer. Keep the daemon on loopback or your tailnet.
|
||||
@@ -40,7 +40,7 @@ Every member's `pod.member=runtime`, sorted by `pod.member` in UTF-16 code-unit
|
||||
whitespace, and runtimes are spelled as in `rig.yaml`. For example:
|
||||
|
||||
```text
|
||||
dev.build=claude-code,dev.qa=claude-code,dev.review=codex,orch.lead=codex
|
||||
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.
|
||||
@@ -77,8 +77,8 @@ Shared test vectors are in `schemas/fixtures/identity-vectors.json`.
|
||||
| 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-registry` status, generated | the status generator only |
|
||||
| Registry entry | `registry-entry.v1` | `openrig-registry/registry/<slug>.yaml` | maintainers, through review |
|
||||
| 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
|
||||
|
||||
@@ -121,9 +121,7 @@ carries no tested status.
|
||||
`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. Optional `posture[].nonInterruptiveDefault` (boolean) carries the rig's authored
|
||||
`non_interruptive` for those seats; an explicit launch choice overrides it. When it is `true`, `firstRunWarnings`
|
||||
is omitted. Pi has no additional warning-suppression flag. `nativeEffect` stays `unknown`.
|
||||
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
|
||||
|
||||
@@ -50,25 +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.
|
||||
- `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`.
|
||||
- `CULTURE.md` — norms layered into members at startup.
|
||||
|
||||
### 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`. The walkers also
|
||||
read `NOTES.md` (or `MISSION_NOTES.md`), and fall back to `README.md` for a node
|
||||
without a `SPEC.md`.
|
||||
specification is a leaf property), `PROOF.md`, `PROGRESS.md`.
|
||||
|
||||
**Project-tree context cannot ship.** It describes what *you* are building —
|
||||
mission intent, slice specifications, proof contracts. No vendor can author it
|
||||
in advance, and shipping a default would install someone else's project as
|
||||
your context. Real projects author their own; `rig scope mission create` and
|
||||
`rig scope slice create` start the tree. (Topology-tree context is the opposite: how a team
|
||||
your context. The demo project carries a worked example to copy from; real
|
||||
projects author their own. (Topology-tree context is the opposite: how a team
|
||||
of agents runs well is largely general, which is why included rigs ship
|
||||
defaults.)
|
||||
|
||||
@@ -76,11 +70,8 @@ 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 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
|
||||
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
|
||||
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
|
||||
@@ -102,9 +93,9 @@ reproduces the drift it was meant to catch. Run it; do not recall it.
|
||||
|
||||
## Shipped defaults and the curation path
|
||||
|
||||
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.
|
||||
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.
|
||||
A shipped default is a **starting point** the occupying team appends to — it
|
||||
is never overwritten by a later rig-up (existing files win).
|
||||
|
||||
|
||||
@@ -1,11 +0,0 @@
|
||||
# Checked seat stop (HTTP)
|
||||
|
||||
Read `GET /api/seat/stop-precondition/:seatRef` immediately before an operator-confirmed stop. A successful response has this shape:
|
||||
|
||||
```json
|
||||
{"contract":"seat-stop.v1","expected":{"nodeId":"<node ID>","sessionId":"<latest session ID or null>"}}
|
||||
```
|
||||
|
||||
Pass `expected` unchanged in the body of the existing `POST /api/seat/stop/:seatRef`, alongside `reason` and optional `operator`. The contract marker lets clients detect support. `expected` is optional; a request without it retains the existing stop behavior. A malformed explicit value returns HTTP 400. A null session ID can describe an empty seat, but stopping it returns `no_session`.
|
||||
|
||||
Checked stop requires the delivery guard. It refuses a changed node, latest session, binding or occupant before a terminal effect with HTTP 409 `selection_changed`. If the selection changes after client detach, the response reports `partialEffect: true` and no kill is sent. A kill failure or a failure to save stop state after a kill reports `stop_uncertain`; inspect the seat before retrying. Success retains the usual `seat`, `sessionName` and `sessionId` fields.
|
||||
@@ -1,111 +0,0 @@
|
||||
# Custom Claude status line
|
||||
|
||||
OpenRig installs a silent context collector as `statusLine.command` in the seat
|
||||
working directory's `.claude/settings.local.json`. Claude's project-local setting
|
||||
overrides your user-level status line, so a renderer configured only in
|
||||
`~/.claude/settings.json` can disappear in that directory. Other Claude sessions
|
||||
using the same directory also read that setting.
|
||||
|
||||
Since 0.6.5, OpenRig preserves a custom, nonempty project-local status line command,
|
||||
including a wrapper or a command composed with shell operators. It still refreshes
|
||||
its own collector script. If your command does not run the collector, context and
|
||||
provider usage stop updating, and Claude resume-token capture at adoption or
|
||||
handover loses its current session evidence. An earlier sidecar can remain and
|
||||
contain an older session ID; without one, context and capture report
|
||||
`missing_sidecar`, and provider usage reports `no_statusline_cache_yet` unless an
|
||||
earlier cache remains.
|
||||
|
||||
## Feed both commands the same input
|
||||
|
||||
On macOS, Linux or WSL2, save a wrapper such as this, replacing the three
|
||||
placeholder paths and `my-statusline` with your actual commands:
|
||||
|
||||
```sh
|
||||
#!/bin/sh
|
||||
input=$(cat)
|
||||
printf '%s' "$input" |
|
||||
node '/seat/cwd/.openrig/context-collector.cjs' \
|
||||
'/instance/home/state/context-usage' \
|
||||
'/instance/home/state/provider-usage' >/dev/null 2>&1
|
||||
printf '%s' "$input" | my-statusline
|
||||
```
|
||||
|
||||
Take the collector path and both directory arguments from the existing generated
|
||||
`statusLine.command` in that seat's `.claude/settings.local.json`; the instance
|
||||
home is the selected `OPENRIG_HOME`. Keep paths quoted, including paths with
|
||||
spaces. Each command needs the same status line JSON on stdin: simply running
|
||||
the collector and renderer in sequence against a single stdin lets the first
|
||||
consume the input.
|
||||
|
||||
In that same settings file, merge this field while preserving your other settings:
|
||||
|
||||
```json
|
||||
{
|
||||
"statusLine": {
|
||||
"type": "command",
|
||||
"command": "sh '/absolute/path/to/openrig-status-line.sh'"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Use the renderer command from your user-level configuration in the wrapper. The
|
||||
collector stays silent and the renderer supplies the visible status line. This
|
||||
POSIX-shell example applies to WSL2's Linux installation; it does not establish
|
||||
native Windows support.
|
||||
|
||||
## Check after an upgrade or instance change
|
||||
|
||||
The collector command's paths and arguments are implementation details. OpenRig
|
||||
preserves your wrapper, so it cannot refresh those arguments for you. Recheck
|
||||
them after an upgrade, a seat-directory move or an `OPENRIG_HOME` change.
|
||||
|
||||
After Claude next updates its status line, inspect context usage in `rig ps` or
|
||||
`rig whoami --full` from the seat. Unknown or stale context is a reason to check
|
||||
the wrapper; it does not prove the collector is running. For a direct check,
|
||||
inspect the current session's JSON under the configured `state/context-usage`
|
||||
directory: its timestamp should advance and its `session_id` should match the
|
||||
current Claude session. A visible custom status line alone does not verify
|
||||
collection or end-to-end adoption/handover recovery. The wrapper above suppresses
|
||||
collector errors; remove its stderr redirection temporarily when diagnosing it.
|
||||
|
||||
## Claude usage-limit detection
|
||||
|
||||
The status line supplies subscription usage windows and their reset timestamps.
|
||||
OpenRig also registers Claude's [`StopFailure` hook](https://code.claude.com/docs/en/hooks#stopfailure),
|
||||
available since Claude Code 2.1.78. Its exact `error: "rate_limit"` value reports a
|
||||
provider interruption even when no status line window is available. This path
|
||||
requires the updated OpenRig hook configuration and the current seat's runtime
|
||||
and occupant generation. Unknown identity or an expired event cannot trigger a
|
||||
usage-limit pause; a hook with a newer source timestamp supersedes the event,
|
||||
regardless of arrival order. The event expires after five minutes in any case.
|
||||
|
||||
A helper Claude started from a seat's shell inherits that seat's environment,
|
||||
so its rate-limit hook is attributed to that seat too. This is appropriate when
|
||||
the helper uses the same login, since the quota belongs to the account. A
|
||||
helper on a different login is attributed the same way, so its rate limit can
|
||||
hold pending handoffs to every seat in that seat's Claude pool for one retry
|
||||
interval, even when the seat's own login still has room. This attribution does
|
||||
not bind the hook to Claude's own native session.
|
||||
|
||||
The event carries no usage percentage, account identity or reset timestamp.
|
||||
It marks the Claude provider pool as limited and preserves a current
|
||||
`agentActivity.reason` of `usage_limit` over a cached idle reading. It does not
|
||||
count as a request for human input; a newer permission prompt still takes
|
||||
precedence in the seat's activity display. Conflicting seat windows retain the
|
||||
existing `explicit_unknown` host diagnosis.
|
||||
|
||||
Pending work handled by the wake ladder uses the existing local Claude pool
|
||||
(the one-account-per-host assumption), with separate pools for seats that
|
||||
declare different Claude config directories. If reset windows conflict within
|
||||
a proposed shared pool, only the seats reporting exhaustion are held; another
|
||||
seat's pending handoffs can still retry. An exhausted status line window with
|
||||
a known reset supplies the timer. Otherwise a typed failure uses
|
||||
`queue.wake_retry_interval_seconds` (default 300) from the event time, plus the
|
||||
existing wake jitter, and records `config-fallback`. That is a retry time, not a
|
||||
claim that the provider's quota will reset then. The timer releases the shared
|
||||
blocker once and retains the existing durable wake delivery behavior.
|
||||
|
||||
Authentication, billing and overloaded errors are not classified as usage
|
||||
limits. Claude limit banners are not scraped, and older runtimes or failures
|
||||
that do not emit this hook still depend on status line data. Without either
|
||||
source, provider usage remains unknown.
|
||||
@@ -1,13 +0,0 @@
|
||||
# Install as $OPENRIG_HOME/community-harnesses/cursor.yaml, with openrig-cursor-launch on the seat's PATH.
|
||||
format: 1
|
||||
name: cursor
|
||||
command: openrig-cursor-launch
|
||||
maintainer: Your name or team
|
||||
limits:
|
||||
- resume reads a chat as missing unless its store is in the seat's Cursor config folder, under the seat's working directory
|
||||
- no guidance, skills or startup files are placed
|
||||
- needs-input and approval prompts are read from the screen only
|
||||
launch_result: true
|
||||
resume: true
|
||||
startup_assisted: false
|
||||
first_input: true
|
||||
@@ -1,68 +0,0 @@
|
||||
#!/bin/sh
|
||||
# A reference launcher for Cursor's CLI as an OpenRig community harness. Copy it, own it, and change it: OpenRig
|
||||
# doesn't ship or run it. It follows docs/reference/community-harness-presets.md:
|
||||
# - a new launch: `cursor-agent create-chat` prints a new chat id; the launcher reports it, then reopens that chat;
|
||||
# - a resume (OPENRIG_RESUME_REF set): it reopens the chat it was asked for and reports that id, or, when Cursor holds
|
||||
# no such chat, reports it missing and starts nothing.
|
||||
# Cursor's chat-id facts come from the probe in OpenRig issue #352, and the chat store's location from Cursor's own CLI
|
||||
# (2026.10.22).
|
||||
set -eu
|
||||
|
||||
producer="openrig-cursor-launch 2"
|
||||
cursor="${OPENRIG_CURSOR_AGENT:-cursor-agent}"
|
||||
|
||||
# Each seat gets its own Cursor config folder unless CURSOR_CONFIG_DIR is already set. Cursor keeps cli-config.json
|
||||
# (`--model`, approval settings) and the chats there, so a seat doesn't rewrite the person's own ~/.cursor. Cursor's
|
||||
# login isn't in it: Cursor keeps that in ~/.config/cursor/auth.json on Linux and in the Keychain on macOS.
|
||||
CURSOR_CONFIG_DIR="${CURSOR_CONFIG_DIR:-${OPENRIG_HOME:-$HOME/.openrig}/state/cursor/${OPENRIG_NODE_ID:-${OPENRIG_SESSION_NAME:-default}}}"
|
||||
export CURSOR_CONFIG_DIR
|
||||
mkdir -p "$CURSOR_CONFIG_DIR"
|
||||
|
||||
# Write this attempt's record, all at once, where OpenRig asked for it (nothing when it didn't ask).
|
||||
report() {
|
||||
[ -n "${OPENRIG_LAUNCH_RESULT:-}" ] || return 0
|
||||
tmp="$OPENRIG_LAUNCH_RESULT.$$.tmp"
|
||||
printf '%s\n' "$1" > "$tmp"
|
||||
mv "$tmp" "$OPENRIG_LAUNCH_RESULT"
|
||||
}
|
||||
plain_id() { case "$1" in ''|*[!A-Za-z0-9._:-]*) return 1 ;; *) return 0 ;; esac; }
|
||||
# Where Cursor keeps a chat: <config folder>/chats/<md5 of the working directory>/<chat id>/store.db. Cursor hashes
|
||||
# its process's working directory, which is the physical path, so this hashes `pwd -P`.
|
||||
chat_store() {
|
||||
if command -v md5sum >/dev/null 2>&1; then sum=$(pwd -P | tr -d '\n' | md5sum | cut -d' ' -f1)
|
||||
else sum=$(pwd -P | tr -d '\n' | md5 -q); fi
|
||||
printf '%s/chats/%s/%s/store.db' "$CURSOR_CONFIG_DIR" "$sum" "$1"
|
||||
}
|
||||
|
||||
# Preserve the file's exact bytes, including trailing newlines. A read error stops before the harness starts.
|
||||
if [ -n "${OPENRIG_FIRST_INPUT:-}" ]; then
|
||||
first_input=$(cat "$OPENRIG_FIRST_INPUT" && printf '.')
|
||||
first_input=${first_input%.}
|
||||
set -- "$@" "$first_input"
|
||||
fi
|
||||
|
||||
if [ -n "${OPENRIG_RESUME_REF:-}" ]; then
|
||||
id="$OPENRIG_RESUME_REF"
|
||||
plain_id "$id" || { echo "openrig-cursor-launch: refusing an unusual chat id" >&2; exit 2; }
|
||||
# Cursor's `--resume` with an id it doesn't hold exits 0 on a new, empty chat, so check first. Gone: say so, start nothing.
|
||||
if [ ! -f "$(chat_store "$id")" ]; then
|
||||
report "{\"format\":1,\"attempt\":\"${OPENRIG_LAUNCH_ATTEMPT:-}\",\"harness\":\"cursor\",\"error\":\"missing\",\"producer\":\"$producer\"}"
|
||||
echo "openrig-cursor-launch: Cursor has no chat $id in $CURSOR_CONFIG_DIR for $(pwd -P); starting nothing" >&2
|
||||
exit 1
|
||||
fi
|
||||
else
|
||||
# create-chat prints the id but doesn't exit (see #352): read the first line, then stop it.
|
||||
out=$(mktemp)
|
||||
"$cursor" create-chat > "$out" 2>/dev/null &
|
||||
pid=$!
|
||||
i=0
|
||||
while [ "$i" -lt 100 ] && [ ! -s "$out" ]; do sleep 0.1; i=$((i + 1)); done
|
||||
kill "$pid" 2>/dev/null || true
|
||||
id=$(head -n 1 "$out" | tr -d '\r\n\t ')
|
||||
rm -f "$out"
|
||||
# No usable id: report nothing, so OpenRig shows the identity as unavailable, and start Cursor on its own chat.
|
||||
plain_id "$id" || exec "$cursor" --trust "$@"
|
||||
fi
|
||||
|
||||
report "{\"format\":1,\"attempt\":\"${OPENRIG_LAUNCH_ATTEMPT:-}\",\"harness\":\"cursor\",\"nativeRef\":\"$id\",\"producer\":\"$producer\"}"
|
||||
exec "$cursor" --resume "$id" --trust "$@"
|
||||
@@ -1,19 +0,0 @@
|
||||
# Merge this into each Hermes seat's config.yaml, in that seat's Hermes home ($OPENRIG_HOME/state/hermes/<node id> with
|
||||
# the example launcher), before the seat's first start.
|
||||
#
|
||||
# Hermes runs every tool command in its gateway (one per Hermes home, so one per seat with the example launcher), with
|
||||
# the gateway's environment. For each session it swaps
|
||||
# in the client's own values only for its toolchain names and the names listed here. Without this list, `rig` inside
|
||||
# Hermes runs as whichever seat started the gateway, or as no seat. With it, each seat runs `rig` as itself.
|
||||
# These are the seat's own OpenRig variables; none is a secret, and Hermes refuses credential-like names anyway.
|
||||
terminal:
|
||||
client_env_passthrough:
|
||||
- OPENRIG_SESSION_NAME
|
||||
- OPENRIG_NODE_ID
|
||||
- OPENRIG_HOME
|
||||
- OPENRIG_URL
|
||||
- OPENRIG_HOST
|
||||
- OPENRIG_PORT
|
||||
- OPENRIG_DB
|
||||
|
||||
# Your own settings go beside it (the guide says which): the model and provider, and agent.max_turns if you want a cap.
|
||||
@@ -1,12 +0,0 @@
|
||||
# Install as $OPENRIG_HOME/community-harnesses/hermes.yaml, with openrig-hermes-launch on the seat's PATH.
|
||||
format: 1
|
||||
name: hermes
|
||||
command: openrig-hermes-launch # no model, provider or --max-turns here: they go in the seat's Hermes config.yaml
|
||||
maintainer: Your name or team
|
||||
limits:
|
||||
- resume not declared until reopening a named session, and a missing one, have been checked with a real Hermes
|
||||
- closing a seat's pane detaches it; Hermes finishes any accepted turn; whether its gateway exits when idle is unchecked
|
||||
- creation settings (model, provider, max turns) come from the seat's Hermes config.yaml, not from flags
|
||||
- no guidance, skills or startup files are placed
|
||||
- needs-input and approval prompts are read from the screen only
|
||||
names_conversation: true
|
||||
@@ -1,34 +0,0 @@
|
||||
#!/bin/sh
|
||||
# A reference launcher for Hermes Agent's CLI as an OpenRig community harness. Copy it, own it, and change it: OpenRig
|
||||
# doesn't ship or run it. It follows docs/reference/community-harness-presets.md (`names_conversation`):
|
||||
# - a new launch (OPENRIG_CONVERSATION set): Hermes creates the session titled with that name;
|
||||
# - a resume (OPENRIG_RESUME_REF set): Hermes reopens that session, and never creates one. A name that matches nothing
|
||||
# ends with Hermes's own "No session found" error, so a gone conversation isn't replaced by a new one.
|
||||
# Put the model, provider and max turns in the seat's Hermes config.yaml, not on the command line. Hermes v0.22.4's CLI
|
||||
# creates a `-c <name> --create-if-missing` session with no launch flags, then reopens it and refuses any creation flag
|
||||
# that differs, so such flags fail even on a new name. Other arguments go only to a new session, never to a resume.
|
||||
set -eu
|
||||
|
||||
hermes="${OPENRIG_HERMES:-hermes}"
|
||||
|
||||
# Each seat gets its own Hermes home, so seats don't share sessions or a gateway, and a seat's stop concerns only its own.
|
||||
# Its settings (model, provider, agent.max_turns) come from that home's config.yaml, and its key from the environment
|
||||
# (an OpenRouter key, say), not from the person's ~/.hermes.
|
||||
HERMES_HOME="${OPENRIG_HOME:-$HOME/.openrig}/state/hermes/${OPENRIG_NODE_ID:-${OPENRIG_SESSION_NAME:-default}}"
|
||||
export HERMES_HOME
|
||||
mkdir -p "$HERMES_HOME"
|
||||
|
||||
# Hermes's tools see its shared gateway's environment except for the names a profile passes through, so a seat whose
|
||||
# config.yaml doesn't pass OPENRIG_SESSION_NAME would run `rig` as another seat, or as none (see config.yaml.example).
|
||||
if ! grep -qs OPENRIG_SESSION_NAME "$HERMES_HOME/config.yaml"; then
|
||||
echo "openrig-hermes-launch: $HERMES_HOME/config.yaml doesn't pass OPENRIG_SESSION_NAME to Hermes's tools, so rig run from Hermes won't act as this seat; see config.yaml.example" >&2
|
||||
fi
|
||||
|
||||
if [ -n "${OPENRIG_RESUME_REF:-}" ]; then
|
||||
exec "$hermes" chat -c "$OPENRIG_RESUME_REF"
|
||||
fi
|
||||
if [ -n "${OPENRIG_CONVERSATION:-}" ]; then
|
||||
exec "$hermes" chat -c "$OPENRIG_CONVERSATION" --create-if-missing "$@"
|
||||
fi
|
||||
echo "openrig-hermes-launch: OpenRig passed no conversation name; is names_conversation set in the preset?" >&2
|
||||
exit 2
|
||||
@@ -1,15 +0,0 @@
|
||||
# The Gateway must already run. Configure its route and authentication in this seat's OPENCLAW_CONFIG_PATH.
|
||||
format: 1
|
||||
name: openclaw-gateway
|
||||
command: openrig-openclaw-launch --gateway
|
||||
maintainer: Your name or team
|
||||
limits:
|
||||
- connects to an existing Gateway; this launcher never starts or stops that service
|
||||
- stopping the TUI closes its client; an accepted turn may keep running on the Gateway
|
||||
- uses only agent main; automatic session resets must stay off
|
||||
- typing /new changes the native key while the seat keeps the name OpenRig gave it
|
||||
- no guidance, skills or startup files are placed
|
||||
- needs-input and approval prompts are read from the screen only
|
||||
names_conversation: true
|
||||
resume: true
|
||||
first_input: true
|
||||
@@ -1,16 +0,0 @@
|
||||
# Install as $OPENRIG_HOME/community-harnesses/openclaw.yaml, with openrig-openclaw-launch on the seat's PATH.
|
||||
format: 1
|
||||
name: openclaw
|
||||
command: openrig-openclaw-launch
|
||||
maintainer: Your name or team
|
||||
limits:
|
||||
- runs locally in the pane (openclaw tui --local), using only agent main, with no Gateway; Gateway-attached use isn't covered
|
||||
- Finish the current local turn before stopping; an interrupted local turn may retain native recovery work and refuse the next request. This launcher does not repair or retry it.
|
||||
- local resume may run a native database integrity check; check that the TUI has finished startup before sending work
|
||||
- automatic session resets (session.reset) must stay off, or a key can start a new conversation
|
||||
- typing /new in the pane moves the chat to a fresh session key; the seat still holds the name OpenRig gave it
|
||||
- no guidance, skills or startup files are placed
|
||||
- needs-input and approval prompts are read from the screen only
|
||||
names_conversation: true
|
||||
resume: true
|
||||
first_input: true
|
||||
@@ -1,70 +0,0 @@
|
||||
#!/bin/sh
|
||||
# Reference launcher for OpenClaw 2026.10.6 (fe06181), not installed by OpenRig.
|
||||
# Each seat owns its client state and uses the main agent. OpenRig's opaque name maps to its full native key.
|
||||
# --gateway selects an existing Gateway configured for this client; the default is an embedded local agent.
|
||||
# Resume checks that exact key at its owner; an unavailable lookup is not a missing conversation.
|
||||
set -eu
|
||||
|
||||
openclaw="${OPENRIG_OPENCLAW:-openclaw}"
|
||||
mode=local
|
||||
if [ "${1:-}" = --gateway ]; then mode=gateway; shift; fi
|
||||
OPENCLAW_STATE_DIR="${OPENRIG_HOME:-$HOME/.openrig}/state/openclaw/${OPENRIG_NODE_ID:-${OPENRIG_SESSION_NAME:-default}}"
|
||||
export OPENCLAW_STATE_DIR
|
||||
mkdir -p "$OPENCLAW_STATE_DIR"
|
||||
|
||||
name="${OPENRIG_RESUME_REF:-${OPENRIG_CONVERSATION:-}}"
|
||||
if [ -z "$name" ]; then
|
||||
echo "openrig-openclaw-launch: OpenRig passed no conversation name; is names_conversation set in the preset?" >&2
|
||||
exit 2
|
||||
fi
|
||||
case "$name" in
|
||||
agent:main:*) key="$name" ;;
|
||||
agent:*) echo "openrig-openclaw-launch: this example supports only the main OpenClaw agent" >&2; exit 2 ;;
|
||||
*) key="agent:main:$name" ;;
|
||||
esac
|
||||
|
||||
# Preserve the file's exact bytes, including trailing newlines. A read error stops before the harness starts.
|
||||
if [ -n "${OPENRIG_FIRST_INPUT:-}" ]; then
|
||||
first_input=$(cat "$OPENRIG_FIRST_INPUT" && printf '.')
|
||||
first_input=${first_input%.}
|
||||
set -- "$@" --message "$first_input"
|
||||
fi
|
||||
|
||||
if [ -n "${OPENRIG_RESUME_REF:-}" ]; then
|
||||
if [ "$mode" = gateway ]; then
|
||||
params=$(KEY="$key" node -e 'process.stdout.write(JSON.stringify({ key: process.env.KEY, agentId: "main" }))')
|
||||
if listing=$("$openclaw" gateway call sessions.describe --params "$params" --json); then listed=true; else listed=false; fi
|
||||
else
|
||||
if listing=$("$openclaw" sessions --agent main --json --limit all); then listed=true; else listed=false; fi
|
||||
fi
|
||||
if [ "$listed" = false ]; then
|
||||
echo "openrig-openclaw-launch: this seat's OpenClaw sessions couldn't be listed; not starting" >&2
|
||||
exit 4
|
||||
fi
|
||||
if printf '%s' "$listing" | KEY="$key" MODE="$mode" node -e '
|
||||
let raw = ""; process.stdin.on("data", (chunk) => { raw += chunk; });
|
||||
process.stdin.on("end", () => {
|
||||
try {
|
||||
const data = JSON.parse(raw);
|
||||
if (process.env.MODE === "gateway") {
|
||||
if (data.session === null) process.exit(3);
|
||||
process.exit(data.session?.key === process.env.KEY ? 0 : 4);
|
||||
}
|
||||
const { sessions } = data;
|
||||
if (!Array.isArray(sessions)) process.exit(4);
|
||||
process.exit(sessions.some((s) => s?.agentId === "main" && s.key === process.env.KEY) ? 0 : 3);
|
||||
} catch { process.exit(4); }
|
||||
});'; then
|
||||
:
|
||||
else
|
||||
result=$?
|
||||
if [ "$result" -eq 3 ]; then
|
||||
echo "openrig-openclaw-launch: this seat's OpenClaw sessions don't list \"$key\"; not starting a new one under that key" >&2
|
||||
else
|
||||
echo "openrig-openclaw-launch: this seat's OpenClaw sessions couldn't be listed; not starting" >&2
|
||||
fi
|
||||
exit "$result"
|
||||
fi
|
||||
fi
|
||||
if [ "$mode" = gateway ]; then exec "$openclaw" tui --session "$key" "$@"; fi
|
||||
exec "$openclaw" tui --local --session "$key" "$@"
|
||||
@@ -1,100 +0,0 @@
|
||||
#!/bin/sh
|
||||
# A reference launcher for Pi's own terminal UI (interactive `pi`) as an OpenRig community harness. Copy it, own it, and
|
||||
# change it: OpenRig doesn't ship or run it. It's written for Pi 1.4.0 from its source and not yet checked with a real Pi.
|
||||
# It follows docs/reference/community-harness-presets.md (`names_conversation`, `first_input`):
|
||||
# - a new launch (OPENRIG_CONVERSATION set): Pi creates the session whose id is that name, in the seat's own session
|
||||
# folder, and takes the first input as its first prompt;
|
||||
# - a resume (OPENRIG_RESUME_REF set): the launcher opens the one session file whose id is that name, and starts nothing
|
||||
# when there isn't exactly one. Pi's --session-id creates a new session for an id it doesn't find, and --session with
|
||||
# an id can open another session whose id starts the same way, so neither is used to resume.
|
||||
set -eu
|
||||
|
||||
pi="${OPENRIG_PI:-pi}"
|
||||
state="${OPENRIG_HOME:-$HOME/.openrig}/state/pi-tui/${OPENRIG_NODE_ID:-${OPENRIG_SESSION_NAME:-default}}"
|
||||
sessions="$state/sessions"
|
||||
|
||||
# Each seat gets its own Pi agent folder (settings, logins, skills) unless PI_CODING_AGENT_DIR is already set, so seats
|
||||
# don't share settings and a person's ~/.pi/agent isn't touched. Give the seat its provider key in its environment, or its
|
||||
# login and settings in this folder, before its first start.
|
||||
PI_CODING_AGENT_DIR="${PI_CODING_AGENT_DIR:-$state/agent}"
|
||||
# Pi expands a leading ~ in this folder; do the same, so the skills land where Pi looks.
|
||||
case "$PI_CODING_AGENT_DIR" in
|
||||
"~") PI_CODING_AGENT_DIR="$HOME" ;;
|
||||
"~/"*) PI_CODING_AGENT_DIR="$HOME/${PI_CODING_AGENT_DIR#"~/"}" ;;
|
||||
esac
|
||||
export PI_CODING_AGENT_DIR
|
||||
mkdir -p "$PI_CODING_AGENT_DIR/skills" "$sessions"
|
||||
|
||||
# Copy the installed OpenRig's coordination skills in at each launch, so an upgrade reaches the seat. Pi lists the skills
|
||||
# in <agent folder>/skills/ by itself; the seat's first input should still name queue-handoff (see the recipe).
|
||||
skills_from="${OPENRIG_PI_SKILLS_FROM:-${OPENRIG_HOME:-$HOME/.openrig}/plugins/openrig-core/skills}"
|
||||
set -f
|
||||
for skill in ${OPENRIG_PI_SKILLS:-queue-handoff}; do
|
||||
case "$skill" in
|
||||
*[!a-z0-9-]*|-*) echo "openrig-pi-tui-launch: skipping '$skill': not a skill name" >&2; continue ;;
|
||||
esac
|
||||
if [ -d "$skills_from/$skill" ]; then
|
||||
rm -rf "$PI_CODING_AGENT_DIR/skills/$skill"
|
||||
cp -Rp "$skills_from/$skill" "$PI_CODING_AGENT_DIR/skills/"
|
||||
else
|
||||
echo "openrig-pi-tui-launch: no $skill skill in $skills_from; starting without it" >&2
|
||||
fi
|
||||
done
|
||||
set +f
|
||||
|
||||
# Pi's session ids: letters, digits, '.', '_' and '-', starting and ending with a letter or digit.
|
||||
valid_id() {
|
||||
case "$1" in
|
||||
"" | *[!A-Za-z0-9._-]* | [!A-Za-z0-9]* | *[!A-Za-z0-9]) return 1 ;;
|
||||
esac
|
||||
}
|
||||
|
||||
# The first input goes over as Pi's first prompt, byte for byte, after `--`. OpenRig's starts with its identity-context
|
||||
# line; Pi would read one starting with @ as a file even after `--`, and may run one starting with / as a command.
|
||||
set --
|
||||
if [ -n "${OPENRIG_FIRST_INPUT:-}" ]; then
|
||||
first_input=$(cat "$OPENRIG_FIRST_INPUT" && printf '.')
|
||||
first_input="${first_input%.}"
|
||||
if [ -n "$first_input" ]; then set -- -- "$first_input"; fi
|
||||
fi
|
||||
|
||||
if [ -n "${OPENRIG_RESUME_REF:-}" ]; then
|
||||
id="$OPENRIG_RESUME_REF"
|
||||
if ! valid_id "$id"; then
|
||||
echo "openrig-pi-tui-launch: '$id' isn't a Pi session id; starting nothing" >&2
|
||||
exit 2
|
||||
fi
|
||||
# Pi names a session file <time>_<id>.jsonl, but the file's first line, its header, is what says which session it is:
|
||||
# its top-level type and id, read as JSON as Pi reads it. Pi writes the file only once the conversation has a message, so
|
||||
# a session that never got one can't be reopened. Pi runs on Node, so node reads the header.
|
||||
node="${OPENRIG_PI_NODE:-node}"
|
||||
if ! command -v "$node" >/dev/null 2>&1; then
|
||||
echo "openrig-pi-tui-launch: $node isn't on PATH to read Pi's session headers; starting nothing" >&2
|
||||
exit 1
|
||||
fi
|
||||
found="" count=0
|
||||
for file in "$sessions"/*_"$id".jsonl; do
|
||||
[ -s "$file" ] || continue
|
||||
if head -n 1 "$file" | "$node" -e '
|
||||
let text = ""; process.stdin.on("data", c => { text += c; }).on("end", () => {
|
||||
try { const h = JSON.parse(text); process.exit(h && h.type === "session" && h.id === process.argv[1] ? 0 : 1); }
|
||||
catch { process.exit(1); }
|
||||
});' "$id"; then
|
||||
found="$file" count=$((count + 1))
|
||||
fi
|
||||
done
|
||||
if [ "$count" -ne 1 ]; then
|
||||
echo "openrig-pi-tui-launch: expected one Pi session $id in $sessions, found $count; starting nothing" >&2
|
||||
exit 1
|
||||
fi
|
||||
exec "$pi" --session-dir "$sessions" --session "$found" "$@"
|
||||
fi
|
||||
if [ -n "${OPENRIG_CONVERSATION:-}" ]; then
|
||||
if ! valid_id "$OPENRIG_CONVERSATION"; then
|
||||
echo "openrig-pi-tui-launch: '$OPENRIG_CONVERSATION' isn't a Pi session id; starting nothing" >&2
|
||||
exit 2
|
||||
fi
|
||||
exec "$pi" --session-dir "$sessions" --session-id "$OPENRIG_CONVERSATION" "$@"
|
||||
fi
|
||||
echo "openrig-pi-tui-launch: OpenRig passed no conversation name; is names_conversation set in the preset?" >&2
|
||||
exit 2
|
||||
@@ -1,15 +0,0 @@
|
||||
# Install as $OPENRIG_HOME/community-harnesses/pi-tui.yaml, with openrig-pi-tui-launch on the seat's PATH.
|
||||
# "pi" itself is the built-in managed Pi runtime, so this preset for Pi's own terminal UI takes another name.
|
||||
format: 1
|
||||
name: pi-tui
|
||||
command: openrig-pi-tui-launch # no model or provider here: they go in the seat's Pi settings or environment
|
||||
maintainer: Your name or team
|
||||
limits:
|
||||
- checked once with Pi 1.4.0 and OpenRig 0.7.4 (one run, one model); other Pi versions aren't checked
|
||||
- resume not declared until reopening a named session, and a missing one, have been checked with a real Pi
|
||||
- with the default typing guard, a wake submits a person's half-typed draft in Pi's editor together with the wake; run the seat unattended, not where a person also types
|
||||
- a send while a Pi dialog OpenRig doesn't recognize is open, such as /settings, types into the dialog
|
||||
- how Pi takes a wake that arrives while it's busy isn't shown
|
||||
- only the listed openrig-core skills are copied into the seat's Pi agent folder; no guidance or startup files are placed
|
||||
names_conversation: true
|
||||
first_input: true
|
||||
@@ -1,351 +0,0 @@
|
||||
# Community harness presets
|
||||
|
||||
A community harness is a coding harness an outside contributor maintains. You install it as one small data file, and a
|
||||
rig member runs it by naming it as its `runtime`. OpenRig doesn't test these harnesses. It shows them as community
|
||||
harnesses, and it reads their activity only from what the screen shows.
|
||||
|
||||
## What a community harness gets
|
||||
|
||||
What OpenRig does for a community-harness seat, capability by capability. **Partly** and **no** mean OpenRig shows that it doesn't know;
|
||||
it never reads an unsupported capability as idle, working, ready or verified.
|
||||
|
||||
| Capability | Supported | How it works, or what you see instead |
|
||||
|---|---|---|
|
||||
| Launch | yes | OpenRig types the preset's `command` into the seat's pane, with its variables passed through `/usr/bin/env`. The seat reads as ready once something other than a shell runs in the pane; that's a process check, not proof of which conversation it runs. With `startup_assisted`, the seat reports attention required until a person checks it. |
|
||||
| Delivery | yes | `rig send` and queue wakes paste the text into the pane and press Enter, as for any seat. A pane that's back at a shell is refused (`target_runtime_unverified`) and nothing is typed. OpenRig doesn't confirm the harness took the message; `rig send --verify` checks the pane afterwards. |
|
||||
| Identity | when declared | With `launch_result`, the conversation is shown as reported by its launcher; with `names_conversation`, as named by OpenRig. Neither is observed by OpenRig. Without either, the identity is unavailable. |
|
||||
| Resume | when declared | `resume: true` with one of the two above (see [Reopening a conversation](#reopening-a-conversation-resume-true)). Without it, a resume says `Resume is unsupported: community harness "<name>" is launch-only`, and a restore stops and asks. |
|
||||
| Activity | partly | Read from the screen only; there are no activity hooks. Work and attention the screen shows are kept, but a screen that looks idle reads `unknown`, never idle, because a quiet prompt can be an approval or a pause. |
|
||||
| Attention | partly | Read from the screen: a permission question or numbered choice that OpenRig recognizes reads as needing attention, and `rig send` won't type into it. A prompt it doesn't recognize reads `unknown`. |
|
||||
| Approval | no | Approvals stay in the harness's own pane. OpenRig relays none, so a person answers them there. |
|
||||
| Cancel | no | OpenRig has no verb that cancels a running turn. `rig seat stop` and `rig down` end the seat's tmux session; anything the harness runs outside its pane, such as a gateway, is its own, and the preset's `limits` should say what keeps running. Restarting in place and switching harness are refused. |
|
||||
| Transport | yes | The seat is a tmux pane like any other, so `rig capture`, `rig send` and `--host` work as they do for any seat. |
|
||||
|
||||
**Not placed:** guidance, skills and startup files (a launch warns that they weren't delivered), and the model: set it in the harness's own
|
||||
configuration.
|
||||
|
||||
**Check that the harness answers on its own first.** Before writing a preset, start the harness in a terminal outside OpenRig, with the
|
||||
same configuration and credentials your launcher will give it, and send it one prompt. Use the folder your launcher gives the seat, not
|
||||
the harness's default one: the example launchers keep one per seat under `$OPENRIG_HOME/state/<harness>/` (`HERMES_HOME`,
|
||||
`OPENCLAW_STATE_DIR` or `CURSOR_CONFIG_DIR`), so a check with your own defaults can pass while the seat's setup fails. If no answer comes
|
||||
back, the problem is in the harness's own setup, such as its model, provider or login, and relaunching an OpenRig seat won't fix it. Fix
|
||||
it in the harness, then connect it.
|
||||
|
||||
## The preset
|
||||
|
||||
One YAML file per harness: `$OPENRIG_HOME/community-harnesses/<name>.yaml`. `rig community-harness list` shows what's
|
||||
installed.
|
||||
|
||||
```yaml
|
||||
format: 1
|
||||
name: example-harness # must match the file name: lowercase letters, digits and hyphens
|
||||
command: example-launch # one program and its arguments, typed into the seat's pane
|
||||
maintainer: Example Maintainer
|
||||
limits: # what the maintainer says doesn't work
|
||||
- fork unsupported
|
||||
launch_result: true # optional: the launcher reports the conversation it created (below)
|
||||
# names_conversation: true # optional, instead of launch_result: OpenRig names the conversation (below)
|
||||
resume: true # optional, needs one of those two; declare it only once your harness's resume is checked
|
||||
startup_assisted: true # optional: startup submission needs a person's check (below)
|
||||
first_input: true # optional: launcher takes the first turn from OPENRIG_FIRST_INPUT (below)
|
||||
```
|
||||
|
||||
- **`command`** is a single program and its arguments. Shell syntax such as `|`, `&&`, `;`, redirections or `$(…)`
|
||||
is refused: put it in a script and name the script.
|
||||
- **Built-in runtime names are reserved.** A preset can't replace `claude-code`, `codex` or the other built-ins.
|
||||
- **Unknown fields are refused,** so a preset written for a newer OpenRig says so instead of half-working.
|
||||
- **Fork isn't supported, and resume only as described below.** Neither is placing skills, guidance or startup files. Except
|
||||
for assisted startup below, the seat is called ready while something other than a shell runs in its pane, which says
|
||||
nothing about which conversation it is.
|
||||
|
||||
### Assisted startup
|
||||
|
||||
Set `startup_assisted: true` when startup submission needs a person's check. The seat may start its first turn
|
||||
automatically, including from input passed at launch with `first_input: true`. This declaration requires a check after
|
||||
the submission attempt; it does not hold the agent back. Without `first_input`, OpenRig pastes the startup text and
|
||||
presses Enter once.
|
||||
|
||||
After attempting startup input, OpenRig reports **attention required**: check the pane and submit any text still in the
|
||||
composer. OpenRig does not resend the identity prompt. Once the seat responds, use the reported
|
||||
`rig seat clear-attention <session> --reason "Startup submission checked; seat responded"` command to acknowledge the
|
||||
check. A launch with no startup text needs no such check. Other presets keep their existing behavior.
|
||||
|
||||
## Reporting the conversation a launch created (`launch_result: true`)
|
||||
|
||||
Some harnesses create their own conversation id before they start. Cursor's `cursor-agent create-chat` is one. With
|
||||
`launch_result: true`, the harness's launcher tells OpenRig that id for each launch.
|
||||
|
||||
1. **OpenRig names one file per launch attempt.** It starts `command` with two variables:
|
||||
- `OPENRIG_LAUNCH_RESULT`, a new file path inside `$OPENRIG_HOME/state/launch-results/`;
|
||||
- `OPENRIG_LAUNCH_ATTEMPT`, this attempt's id.
|
||||
2. **The launcher writes one JSON record to that path,** then starts the harness:
|
||||
```json
|
||||
{ "format": 1, "attempt": "<OPENRIG_LAUNCH_ATTEMPT>", "harness": "cursor", "nativeRef": "<the conversation id>", "producer": "openrig-cursor-launch 1.0" }
|
||||
```
|
||||
3. **OpenRig reads that attempt's record once,** waiting up to 20 seconds for it. It records `nativeRef` on the session,
|
||||
and the seat shows its identity as **reported by its launcher, not observed**. That's what the launcher says, not
|
||||
proof that the harness used it.
|
||||
|
||||
The seat still starts, with its identity **unavailable** and the reason named, when the record:
|
||||
- wasn't written;
|
||||
- belongs to another attempt or another harness;
|
||||
- isn't JSON, isn't format 1, or is larger than 64 KiB;
|
||||
- has an unusable `nativeRef` (empty, too long, or containing spaces or control characters);
|
||||
- names no producer;
|
||||
- or is reached through a link.
|
||||
|
||||
None of these means the conversation is gone.
|
||||
|
||||
A reported id doesn't make the harness resumable on its own. Without `resume: true`, nothing resumes it: a restore
|
||||
stops and asks, as it did before (re-run it with `--fresh <seat>` only if you want a new conversation), and elsewhere a
|
||||
resume says it's unsupported, and a new conversation starts only where the caller allows a fresh start.
|
||||
|
||||
**Good to know:**
|
||||
- **The variables are passed with `/usr/bin/env`,** so `launch_result` needs a POSIX system.
|
||||
- **A launcher that never writes its record** adds up to 20 seconds to each launch, while OpenRig waits for it.
|
||||
- **Records are kept,** one small file per attempt, under `$OPENRIG_HOME/state/launch-results/<session>/`. A record
|
||||
larger than 64 KiB isn't read.
|
||||
|
||||
## Letting OpenRig name the conversation (`names_conversation: true`)
|
||||
|
||||
Some harnesses take a conversation name from the caller and create that conversation, or reopen it. Hermes's
|
||||
`hermes chat -c <name> --create-if-missing` is one. With `names_conversation: true`, OpenRig names each new conversation
|
||||
and the harness uses that name, so no record is needed.
|
||||
- **A new launch:** OpenRig starts `command` with `OPENRIG_CONVERSATION` set to a new name, `openrig-<seat>-<8 hex digits>`
|
||||
(at most 100 characters). Each launch gets its own name, so two seats never share a conversation.
|
||||
- **What the seat shows:** OpenRig records that name on the session, and the seat shows its identity as **named by
|
||||
OpenRig, not observed**. That's the name OpenRig passed, not proof that the harness used it.
|
||||
- **Not with `launch_result`:** a preset declares one or the other. Either the launcher reports the conversation, or
|
||||
OpenRig names it.
|
||||
|
||||
## Reopening a conversation (`resume: true`)
|
||||
|
||||
**A named conversation:** with `names_conversation`, a resume starts `command` with `OPENRIG_RESUME_REF` set to the saved
|
||||
name. The harness reopens it and must never create one under that name. Nothing reports back, so:
|
||||
- **readiness is process-only:** the seat reads as ready while something other than a shell runs in its pane. That
|
||||
doesn't show the named conversation exists: a harness (or a launcher's own check) that hasn't yet found it gone reads
|
||||
as ready, and the saved name stays unverified until something observes it;
|
||||
- **never creating one is the launcher's job:** a resume must not create a conversation under the saved name. When it's
|
||||
gone, the harness or launcher ends with its error and the pane is back at a shell; the seat keeps its saved name, and
|
||||
OpenRig starts nothing new, though the seat may already have read as ready;
|
||||
- **a former runtime's id** isn't passed to the harness, as below.
|
||||
|
||||
**A reported conversation:** with `launch_result`, a resume (a restore included) starts the launcher with `OPENRIG_RESUME_REF` set to the
|
||||
conversation to reopen. The launcher reports what happened in the same attempt's file:
|
||||
- **Reopened:** the usual record, with that conversation as `nativeRef`.
|
||||
- **Gone:** `{ "format": 1, "attempt": "…", "harness": "cursor", "error": "missing", "producer": "…" }`. The launcher
|
||||
starts nothing. OpenRig reports the conversation missing and starts nothing either: it never replaces it with a new one.
|
||||
|
||||
For a reported conversation, OpenRig also says so plainly when:
|
||||
- **no usable record is written:** the resume isn't confirmed. The seat needs attention and keeps the conversation it
|
||||
asked for; nothing is restarted;
|
||||
- **the record names a different conversation:** the seat needs attention and keeps the conversation it asked for.
|
||||
OpenRig doesn't switch it to the reported one;
|
||||
- **the saved conversation isn't this harness's own** (a former runtime's id, say): it isn't passed to the launcher. A restore stops and asks, and elsewhere the resume says it isn't possible;
|
||||
- **the record's folder can't be made:** the launcher couldn't be told what to reopen, so nothing starts.
|
||||
|
||||
## An example: Hermes
|
||||
|
||||
[`community-harness-examples/hermes/`](community-harness-examples/hermes/) has a preset and a small launcher for Hermes
|
||||
Agent's CLI.
|
||||
- **The launcher:** it creates the session OpenRig named (`-c <name> --create-if-missing`), and on a resume reopens it
|
||||
without `--create-if-missing`, with its own Hermes home per seat. A name that matches nothing ends with Hermes's own
|
||||
"No session found" error.
|
||||
- **Settings go in the seat's Hermes `config.yaml`, not in flags:** Hermes's CLI creates a named session with no launch
|
||||
flags and then reopens it, refusing any creation flag (model, provider, `--max-turns`) that differs. So the preset's
|
||||
command carries none, and each seat's `config.yaml`, in its Hermes home, sets them before the seat's first start:
|
||||
the model and provider, and `agent.max_turns` if you want a cap (nothing else sets it once the flag is gone).
|
||||
- **Let Hermes run `rig` as the seat:** Hermes runs every tool command in its gateway, one per Hermes home, so with
|
||||
this launcher one per seat (a two-seat run showed separate gateways, homes and sockets, and stopping one seat left
|
||||
the other's running). It runs them with that gateway's
|
||||
environment, and swaps in a session's own values only for its toolchain names and the names its profile lists in
|
||||
`terminal.client_env_passthrough`. So put the seat's OpenRig variables in that list, in each seat's `config.yaml`
|
||||
([`config.yaml.example`](community-harness-examples/hermes/config.yaml.example)). Without it, `rig` inside Hermes
|
||||
runs as whichever seat started the gateway, or as no seat; with it, each seat runs `rig` as itself. To check, ask the
|
||||
seat's Hermes to run `rig whoami --json`. The launcher warns when a seat's `config.yaml` doesn't pass
|
||||
`OPENRIG_SESSION_NAME`. This covers Hermes's CLI and TUI, whose clients pass their environment; its ACP clients pass
|
||||
none.
|
||||
- **The preset:** it declares `names_conversation` but not `resume`, until reopening a named session, and a missing one,
|
||||
have been checked with a real Hermes.
|
||||
- **Stopping:** Hermes's CLI is a client of a gateway, so closing a seat's pane detaches it. Hermes finishes any turn it
|
||||
accepted. Whether the seat's gateway then exits once idle hasn't been checked: check with `ps` that a stopped seat's
|
||||
gateway has gone before relying on it. The preset says so in its limits.
|
||||
|
||||
Copy them and maintain them as your own.
|
||||
|
||||
## An example: OpenClaw
|
||||
|
||||
[`community-harness-examples/openclaw/`](community-harness-examples/openclaw/) has a preset and a small launcher for
|
||||
OpenClaw's CLI.
|
||||
- **Choose the mode:** `openclaw.yaml` runs an embedded agent with `tui --local`. `openclaw-gateway.yaml` runs a TUI client of an existing Gateway. Configure that client's Gateway route and authentication through `OPENCLAW_CONFIG_PATH`; the launcher never starts or stops the Gateway.
|
||||
- **The conversation:** both examples use only agent `main`, mapping OpenRig's name to the full native key `agent:main:<OpenRig name>`. Each seat has its own client state folder.
|
||||
- **Its resume check:** local mode checks `sessions --agent main --json --limit all`; Gateway mode calls the selected Gateway's `sessions.describe`. Both require the exact canonical key. An unavailable lookup stops the launch; a confirmed missing key is never recreated. A client's local cache cannot authorize Gateway resume.
|
||||
- **Stopping:** a Gateway client's pane closing detaches it. The Gateway and an accepted turn can keep running; stopping that service is separate. Local mode runs its embedded agent in the pane.
|
||||
- **Unattended seats:** prefer Gateway mode within the capabilities qualified for your installed version. Local interrupted-turn recovery is not supported by these launchers.
|
||||
- **Local interruption:** Finish the current local turn before stopping; an interrupted local turn may retain native recovery work and refuse the next request. This launcher does not repair or retry it. OpenRig recognizes the recorded local “changed while starting work” error frame as needing attention: “OpenClaw turn not recovered; inspect the pane before retrying”. Use `rig capture <session>` to inspect the native conversation. An ordinary send still submits a new turn, with an advisory that the last local turn was not recovered; it is not an automatic replay of that turn. It does not clear native recovery records, repeat the request or start a fresh conversation; a successful process launch is not proof that the turn recovered.
|
||||
- **Local startup after resume:** OpenClaw may run its database integrity check during startup. A reported resumed process does not confirm readiness for the next request; check that the TUI has finished starting before sending work.
|
||||
- **Resets must stay off:** automatic session resets can create a new conversation under the same key. Typing `/new` also moves to a fresh key while the seat keeps the name OpenRig gave it.
|
||||
- **The presets:** both declare `names_conversation`, `resume` and `first_input`. The launcher passes the generated first startup text through OpenClaw's `--message` option. OpenRig labels the saved name as passed, not observed by its adapter.
|
||||
|
||||
Copy the launcher and the preset for your mode, and maintain them as your own.
|
||||
|
||||
**Stopping a community seat stops its pane.** `rig down` names those seats ("Pane stopped: …"), since a harness's own
|
||||
processes, a gateway say, may keep running after it. OpenRig doesn't stop them, and whether they survive isn't exercised
|
||||
by OpenRig's tests, so check the harness's own processes after `rig down`. Each preset's limits say what to expect.
|
||||
|
||||
**Not supported for community harnesses:** restarting a seat in place (`rig seat restart` is for Codex seats) and
|
||||
switching harness on a running seat. Each says so before anything changes.
|
||||
|
||||
## An example: Cursor
|
||||
|
||||
[`community-harness-examples/cursor/`](community-harness-examples/cursor/) has a preset and a small launcher for Cursor's
|
||||
CLI.
|
||||
- **The launcher:** it reports the chat `cursor-agent create-chat` makes, then reopens it. Each seat gets its own Cursor
|
||||
config folder unless `CURSOR_CONFIG_DIR` is already set. Cursor keeps its chats and `cli-config.json` there, and its
|
||||
login elsewhere.
|
||||
- **The preset:** it declares `launch_result` and `resume`. Cursor's `--resume` with an id it doesn't hold starts a new,
|
||||
empty chat without saying so, so on a resume the launcher first checks that the chat's store exists. When it doesn't, the
|
||||
launcher reports `error: "missing"` and starts nothing.
|
||||
- **First input at launch:** the preset declares `first_input: true` and `startup_assisted: false`. The launcher passes
|
||||
the generated startup text as Cursor's positional first prompt. This route and same-chat resume were checked with
|
||||
Cursor Agent 2026.10.22-27dcf5f. Later tool approvals use Cursor's native prompts; startup submission does not answer them.
|
||||
- **Sender names come from the sending session.** A command run from an unattached operator shell can arrive as
|
||||
`<unknown sender>`; that doesn't mean the receiving Cursor seat lost its identity.
|
||||
|
||||
Copy both and maintain them as your own.
|
||||
|
||||
## An example: Pi's terminal UI
|
||||
|
||||
[`community-harness-examples/pi-tui/`](community-harness-examples/pi-tui/) has a preset and a small launcher that run Pi's
|
||||
own terminal UI as a community harness. `pi` is the built-in managed Pi runtime, so the preset is named `pi-tui`. OpenRig
|
||||
delivers to this seat as to any community seat (the Delivery row above), not as to a plain `runtime: terminal` seat, which
|
||||
queue wakes don't reach. Checked once, on Pi 1.4.0 with OpenRig 0.7.4 and one model: a parked row's wake reached Pi in
|
||||
the same session (the same session file) and Pi resumed the work, and a handoff reached a second `pi-tui` seat, which
|
||||
picked it up unattended. The first seat's task named the commands to use, so this shows a wake reaching Pi and Pi acting
|
||||
on it, not Pi choosing by itself to park or hand work on.
|
||||
- **The launcher:** each seat gets its own Pi agent folder (`$OPENRIG_HOME/state/pi-tui/<node>/agent`, unless
|
||||
`PI_CODING_AGENT_DIR` is set) and its own session folder. At each launch it copies the installed `openrig-core` skills
|
||||
it's given (`queue-handoff` by default) into that agent folder. A new launch starts `pi --session-id <the name OpenRig
|
||||
gave>` and passes the first input as Pi's first prompt, byte for byte.
|
||||
- **Resume isn't declared.** The launcher can reopen a named session: it opens the one session file whose header has that
|
||||
id, and starts nothing when there isn't exactly one, because Pi's own `--session-id` creates a session for an id it
|
||||
doesn't find. Declare `resume: true` only after a real Pi has reopened a named session and refused a missing one.
|
||||
- **Its limits:** run a `pi-tui` seat unattended, not where a person also types into it.
|
||||
- With the seat's [typing guard](seat-delivery.md) at its default, a wake submits a person's half-typed draft in Pi's
|
||||
editor together with the wake. The guard's draft-aware mode isn't a known fix for this.
|
||||
- A send while a Pi dialog OpenRig doesn't recognize is open, such as `/settings`, types into the dialog.
|
||||
- Not shown: how Pi takes a wake that arrives while it's busy (a message sent during a busy turn was answered after
|
||||
it), and other Pi versions.
|
||||
- **Give the seat a model** before its first start: its provider key in its environment, or its login and settings in its
|
||||
agent folder.
|
||||
|
||||
Copy both and maintain them as your own.
|
||||
|
||||
The launcher is the contributor's code, in the contributor's package. OpenRig runs no code from a preset and loads no
|
||||
module into its daemon. A preset that sets `launch_result`, `names_conversation`, `startup_assisted` or `first_input` is refused by an older
|
||||
OpenRig that doesn't know the field.
|
||||
|
||||
## Pass the first startup input at launch
|
||||
|
||||
A format-1 preset may set `first_input: true` (a boolean, default false). OpenRig composes the same initial identity turn it would otherwise paste, including the first merged text file, durable-obligation guidance and any selected orientation challenge. Before launch it writes that text to a per-attempt 0600 file under its own `state/first-input/` folder and passes the path as `OPENRIG_FIRST_INPUT`. The typed launch command carries the path, not the text; an argument-based launcher still puts the text in the native harness’s argv.
|
||||
|
||||
The contributor-owned launcher reads the file and uses its harness’s supported initial-prompt route: the Cursor example passes one positional prompt; OpenClaw uses `--message`. Core knows neither flag. If no initial identity turn is due (an ordinary resume, for example), the variable is absent and the launcher starts without a first message. Later startup files and actions use their existing delivery paths; they are not folded into the launch file.
|
||||
|
||||
OpenRig records `node.startup_first_input_passed` with the path and `submission: unconfirmed`. This says the input was passed at launch, not that the native harness submitted or read it. An uncertain launch is not permission to replay it. Readiness remains process-only. `startup_assisted` is independent: when declared, startup still requires a person’s acknowledgement, including when the first input was passed at launch.
|
||||
|
||||
Presets without `first_input` and built-in runtimes keep their existing behavior. Older OpenRig versions reject this new field as unknown. The private input file remains for diagnostics; it can contain private startup context. A launcher that turns its contents into one argument is subject to the platform’s argument-size limit; the launcher must report a launch error rather than silently truncate the turn. The examples’ argument transport is covered with stand-ins; native unattended startup still requires qualification with the installed harness.
|
||||
|
||||
## Interactive Pi in a terminal seat: the coordination skills
|
||||
|
||||
This is for a seat that runs interactive `pi` from a `runtime: terminal` member's startup, or from a community preset's
|
||||
launcher. It isn't for a managed `runtime: pi` seat, which already copies its selected skill directories into the seat's own
|
||||
Pi agent directory (`$OPENRIG_HOME/state/pi/<session>/agent/skills/`), or for Workshop, whose Pi profiles carry pinned skill
|
||||
copies (openrig-world's `PI-SKILLS.md`). The [`pi-tui` example](#an-example-pis-terminal-ui) above does step 1 for its
|
||||
seats in its launcher.
|
||||
|
||||
OpenRig installs no skills for a terminal or community seat: it skips their resources and startup files, and `rig skill
|
||||
loadout` covers Claude Code and Codex only. Without the coordination skills, the agent there doesn't know the queue's habits,
|
||||
such as parking a row that waits on CI instead of leaving it in progress, or handing work on so the next row names its
|
||||
source. The seat's setup does two things.
|
||||
|
||||
1. **Make the released skills readable.** The installed OpenRig's own plugin carries them, matching the installed release:
|
||||
`rig plugin list` shows `openrig-core` and its path (usually `$OPENRIG_HOME/plugins/openrig-core`), and the skills are in
|
||||
its `skills/` folder. Copy whole skill directories, keeping their helper files and modes, into the `skills/` folder of the
|
||||
Pi agent directory that seat uses (`PI_CODING_AGENT_DIR`, or `~/.pi/agent` by default). At least `queue-handoff`:
|
||||
|
||||
```bash
|
||||
CORE="$(rig plugin list | awk '$1 == "openrig-core" {print $NF}')"
|
||||
PI_AGENT_DIR="${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}"
|
||||
mkdir -p "$PI_AGENT_DIR/skills"
|
||||
cp -Rp "$CORE/skills/queue-handoff" "$PI_AGENT_DIR/skills/"
|
||||
```
|
||||
|
||||
Copy again after each OpenRig upgrade: a copy doesn't follow the plugin.
|
||||
2. **Point the agent at it when it starts.** Don't count on Pi finding the skill by itself; name it in the seat's first turn.
|
||||
For example:
|
||||
|
||||
> Before you work your queue, read `<Pi agent directory>/skills/queue-handoff/SKILL.md` in full: it's how this team hands
|
||||
> work on, parks it and waits. When you wait on CI or a long job, park the row with `rig queue block <id> --on
|
||||
> external:<what> --wake-after <duration> --continuation "<what resumes>"`.
|
||||
|
||||
- A community preset with `first_input: true` carries it in the seat's first input when the file is declared with
|
||||
`delivery_hint: send_text` (see "Pass the first startup input at launch" above). A `.md` file left at the `auto` hint
|
||||
counts as guidance, which a community seat doesn't take.
|
||||
- A plain terminal seat can pass it as Pi's initial message in the command its startup runs. Check `pi --help` for that
|
||||
argument in your Pi version.
|
||||
- `first_input` carries text, not files: it doesn't install the skills.
|
||||
|
||||
**In a plain terminal seat, a queue wake doesn't reach Pi.** OpenRig doesn't treat a `runtime: terminal` seat as an agent
|
||||
seat. When a parked row's wake fires, OpenRig doesn't type it into Pi, and a handoff to that seat records a failed wake
|
||||
(`failed:terminal-seat`). Parking still records the wait, but `--wake-after` won't bring Pi back. Check the seat's parked
|
||||
rows yourself (`rig queue whoami --session <seat>`, or `rig queue show <id>`), or tell Pi to continue the named row.
|
||||
|
||||
**What this shows, and what it doesn't.** A copied folder and a startup line put the text in front of the agent. They don't
|
||||
show that Pi discovered the skill by itself, or that the agent follows it. Check those separately: that the agent read the
|
||||
whole file (its tool trace), and what its rows record, such as a CI wait parked on `external:` with a wake, and a handoff
|
||||
made with `handoff-and-complete`, whose next row names it as its source.
|
||||
|
||||
## Write your own
|
||||
|
||||
Start from the example closest to your harness, and change it. First check that the harness answers a prompt on its own
|
||||
([above](#what-a-community-harness-gets)).
|
||||
|
||||
1. **Choose how the conversation is named.**
|
||||
- **Your harness creates an id you can read before it starts,** as Cursor's `create-chat` does: declare `launch_result: true`, and the
|
||||
launcher writes the record.
|
||||
- **Your harness takes a name from its caller and creates or reopens it,** as Hermes's `-c <name>` and OpenClaw's session key do: declare
|
||||
`names_conversation: true`, and the launcher passes `OPENRIG_CONVERSATION` on.
|
||||
- **Neither:** leave both out. The seat starts and works, its identity shows as unavailable, and it can't be resumed.
|
||||
2. **Write the launcher:** a small script your package installs on the seat's `PATH`. It reads OpenRig's variables, starts the harness with
|
||||
`exec`, and does nothing else.
|
||||
- `OPENRIG_CONVERSATION` with `names_conversation`, or `OPENRIG_LAUNCH_RESULT` and `OPENRIG_LAUNCH_ATTEMPT` with `launch_result`.
|
||||
- **On a resume,** `OPENRIG_RESUME_REF`: reopen exactly that conversation. Check that it exists first, and when it doesn't, end with an
|
||||
error (or report `error: "missing"`) instead of creating one.
|
||||
- **With `first_input: true`,** `OPENRIG_FIRST_INPUT`: pass the file's exact bytes through your harness's own first-prompt route.
|
||||
- **Keep each seat's harness state apart** (Cursor's config folder, Hermes's home, OpenClaw's state folder), so two seats never share a
|
||||
conversation.
|
||||
3. **Write the preset** at `$OPENRIG_HOME/community-harnesses/<name>.yaml`, and check it with `rig community-harness list`.
|
||||
- Declare `resume` only after checking, with the real harness, that a reopen works and that a missing conversation is refused.
|
||||
- List what doesn't work under `limits`.
|
||||
4. **Try it in a rig:** give a member `runtime: <name>`, then go through the checks in the promotion test below.
|
||||
5. **Publish the preset and the launcher in your own package,** and maintain them. OpenRig runs no code from a preset, so the launcher is
|
||||
yours.
|
||||
|
||||
## The promotion test
|
||||
|
||||
A community harness stays a community harness: you maintain it, and OpenRig shows it as one. **Promotion** means OpenRig takes a harness on
|
||||
as a built-in runtime that it maintains and tests itself. **Promotion is decided by the OpenRig maintainers, on evidence from OpenRig's own
|
||||
testing.** Passing these checks isn't automatic promotion, and it isn't a promise of upstream support.
|
||||
|
||||
What the maintainers look at:
|
||||
1. **Everything the preset declares works on a real install,** end to end through OpenRig:
|
||||
- a seat starts and takes its first turn (`rig up`);
|
||||
- a message arrives (`rig send`), and the reply can be read (`rig capture`);
|
||||
- the seat stops (`rig down`) without leaving work running that the person can't see, or the preset's `limits` say what keeps running;
|
||||
- with `resume`, `rig up <rig> --existing` reopens the same conversation, and a missing one is refused, never replaced.
|
||||
2. **What it doesn't support reads as not known,** never as idle, working, ready or verified.
|
||||
3. **Its `limits` are true,** and name anything a person would otherwise be surprised by.
|
||||
4. **The built-in runtimes are unchanged.**
|
||||
5. **It's maintained:** a named maintainer, and a launcher that keeps working with the harness's current release.
|
||||
|
||||
There's no score or threshold. The maintainers weigh the evidence.
|
||||
@@ -9,9 +9,8 @@ external network, and an installed-package scenario (`scripts/run-pr-scenarios.s
|
||||
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)).
|
||||
**In a fresh clone or worktree, run `npm ci`, then `npm run build`,** as CI does in every job and
|
||||
before each package suite (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)
|
||||
@@ -20,7 +19,7 @@ Locally, `npm test` builds only the daemon, and `test:workspaces` and `test:ui`
|
||||
|---|---|---|
|
||||
| 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` | daemon build, script self-tests, first-run reference check, docs guard, skill mirror check, context-pack generation 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://…` |
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# Edge Types Reference
|
||||
|
||||
Historical whole-document validation: 2026-10-07, at the 0.6.6 cut `2620dea8` (whole document at `fcaf1f8e`).
|
||||
The fallback escalation section and deferred-target exceptions below describe #605.
|
||||
Source of truth: `packages/daemon/src/domain/rigspec-schema.ts`, `packages/daemon/src/domain/rigspec-instantiator.ts`, `packages/daemon/src/domain/queue-owner.ts`, `packages/daemon/src/domain/escalation-owner.ts`
|
||||
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`
|
||||
|
||||
---
|
||||
|
||||
@@ -17,83 +17,46 @@ See `docs/reference/rig-spec.md` for the YAML syntax.
|
||||
|
||||
## Edge Kinds
|
||||
|
||||
Five edge kinds are accepted by both the pod-aware and legacy flat-node validators:
|
||||
Five edge kinds are accepted by the validator:
|
||||
|
||||
| Kind | Accepted | Has Runtime Behavior | Description |
|
||||
|------|----------|---------------------|-------------|
|
||||
| `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 |
|
||||
| `delegates_to` | yes | **yes — affects launch order** | Source delegates work to target |
|
||||
| `spawned_by` | yes | **yes — affects launch order** | Target was spawned by source |
|
||||
| `can_observe` | yes | no | Source can observe target's output |
|
||||
| `collaborates_with` | yes | no | Peer collaboration |
|
||||
| `escalates_to` | yes | **yes — fallback queue escalation** | Source escalates to target |
|
||||
| `escalates_to` | yes | no | Source escalates to target |
|
||||
|
||||
## What Edges Actually Do Today
|
||||
## What Edges Actually Do Today (OpenRig 0.1.x)
|
||||
|
||||
### Launch ordering
|
||||
|
||||
Only `delegates_to` and `spawned_by` constrain the order in which nodes are launched:
|
||||
Only `delegates_to` and `spawned_by` affect runtime behavior. They constrain the order in which nodes are launched:
|
||||
|
||||
- **`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 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.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
### Fallback escalation across rigs
|
||||
|
||||
A seat with **no declared `delegates_to` parent** may declare one `escalates_to` destination. The wake ladder and
|
||||
stuck sweep use it for new recovery rows; they do not move the original obligation or reassign an already-open recovery. A stopped or unbound declared
|
||||
parent still takes precedence, preserving the existing parent route and its fallback.
|
||||
|
||||
```yaml
|
||||
edges:
|
||||
- kind: escalates_to
|
||||
from: work.lead
|
||||
to: review-advisor@coord
|
||||
```
|
||||
|
||||
The target is a canonical same-daemon seat address (`pod-member@rig`), or an existing local member using the usual
|
||||
edge syntax. Named targets are stored without requiring the other rig to exist and resolved when needed. A matching
|
||||
physical session name takes precedence over a derived canonical address. Deferred declarations survive export and
|
||||
snapshots; they don't constrain launch order or make the rigs depend on each other's lifecycle.
|
||||
|
||||
Delivery is one hop. Recovery rows carry `escalation-route:one-hop`, so a destination's own `escalates_to` declaration
|
||||
does not forward the recovery again. A missing or stopped destination, multiple matches or declarations, self route,
|
||||
or declared cycle preserves the existing fallback: the wake ladder proceeds to its operator rung; the sweep retains
|
||||
its existing owner fallback. The recovery body/transition explains the result. Cycle inspection includes stopped
|
||||
seats and delegation parents; an unresolved downstream endpoint is reported as unknown, never as proof of no cycle.
|
||||
Queue address admission is unchanged. Cross-host and synthetic destinations are not supported.
|
||||
|
||||
On an existing rig, use `rig edge add <rig> work.lead review-advisor@coord --kind escalates_to`; `--plan` writes nothing.
|
||||
The receipt's target node ID is null for a deferred address. Remove it with the exact edge ID returned by add.
|
||||
A rig-local graph omits deferred targets, since those seats are outside that graph; the raw topology and export retain them.
|
||||
|
||||
### Graph visualization
|
||||
|
||||
Local-node edges are rendered in the UI topology graph; deferred cross-rig targets are omitted. 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.
|
||||
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.
|
||||
|
||||
### Identity projection
|
||||
|
||||
Local-node edges appear in `rig whoami --json` output under `edges.outgoing` and `edges.incoming`, with their kind and the connected peer's identity. This lets an agent know its relationship to other members — but the agent interprets this information, it's not enforced by the runtime.
|
||||
All edges appear in `rig whoami --json` output under `edges.outgoing` and `edges.incoming`, with their kind and the connected peer's identity. This lets an agent know its relationship to other members — but the agent interprets this information, it's not enforced by the runtime.
|
||||
|
||||
### Attach hint heuristic
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
## What Edges Do NOT Do Today
|
||||
|
||||
Edges do NOT currently:
|
||||
|
||||
- **Route messages** — `rig send` can target any session, regardless of edges (queue escalation, above, is the one
|
||||
daemon path that follows `delegates_to` or fallback `escalates_to`)
|
||||
- **Route messages** — `rig send` can target any session, regardless of edges
|
||||
- **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
|
||||
@@ -157,7 +120,7 @@ If none fit, `can_observe` is the safest default — it documents the relationsh
|
||||
## Validation Rules
|
||||
|
||||
1. Edge kinds must be one of: `delegates_to`, `spawned_by`, `can_observe`, `collaborates_with`, `escalates_to`
|
||||
2. Pod-local edges use unqualified member IDs — both endpoints must exist in the same pod, except a named `escalates_to` target as above.
|
||||
3. Cross-pod edges use `pod.member` format — both endpoints must resolve to actual members, except a named `escalates_to` target as above.
|
||||
2. Pod-local edges use unqualified member IDs — both `from` and `to` must exist in the same pod
|
||||
3. Cross-pod edges use `pod.member` format — both endpoints must resolve to actual members
|
||||
4. Cross-pod edges must reference different pods (same-pod edges should use the pod-local syntax)
|
||||
5. Self-edges are not validated at the schema level but are not meaningful
|
||||
@@ -1,165 +0,0 @@
|
||||
# Gateway participants: several people, shared channels, organizations and policy
|
||||
|
||||
OpenRig's gateway can register **several people** and **shared channels**, group them into **organizations** and
|
||||
**groups**, give each readable **policy** text, and name a **default person**. Agents read the policy and apply it;
|
||||
OpenRig doesn't enforce it. This page covers the commands, what the default is for, and what upgrading and rolling back
|
||||
do.
|
||||
|
||||
## Participants
|
||||
|
||||
A participant is either:
|
||||
- **a person**, registered with `rig gateway human add` as before, with their own Slack binding; or
|
||||
- **a shared channel**: one vetted Slack channel registered as one participant, `<id>@external`, not a person per
|
||||
sender.
|
||||
|
||||
People and channels share one address space: a channel can't take a person's id.
|
||||
|
||||
```bash
|
||||
# An organization and a group inside it (one command each, create or update)
|
||||
rig gateway org set acme --name "Acme" --policy "Answer Acme's customers within a working day. Never promise a date."
|
||||
rig gateway group set support --organization acme --name "Support" --policy-file ./support-policy.md
|
||||
|
||||
# People: the second and later ones are allowed now
|
||||
rig gateway human add sarah --display-name "Sarah" \
|
||||
--binding "slack:main:file:/etc/openrig/slack.env:primary:handle=U0SARAH" --delivery-class B \
|
||||
--organization acme --group support --policy "Sarah approves refunds up to 500." --default
|
||||
|
||||
# A shared channel
|
||||
rig gateway channel add acme-customers --display-name "Acme customers" \
|
||||
--binding "slack:main:file:/etc/openrig/slack.env:C0ACME" --organization acme
|
||||
|
||||
# See everyone, with organization, groups, the default and each participant's policy
|
||||
rig gateway participants
|
||||
rig gateway participants --organization acme --json
|
||||
rig gateway human show sarah
|
||||
```
|
||||
|
||||
Change a person's placement with `rig gateway human set <id> organization|groups|policy <value>` (`unset` clears it;
|
||||
for policy, `@<path>` reads a file). Remove a channel with `rig gateway channel remove <id>`, which refuses while
|
||||
non-terminal rows are addressed to it unless you pass `--force`.
|
||||
|
||||
## Policy is context, not enforcement
|
||||
|
||||
A participant's **effective policy** is its organization's text, then each of its groups', then its own, each labelled
|
||||
with where it came from. Agents read it (`rig gateway participants --json`, `rig gateway human show --json`) and apply
|
||||
it with judgment. It doesn't grant or block anything by itself, and a participant's name never implies a policy.
|
||||
|
||||
## The default person
|
||||
|
||||
Some things need a person without naming one: an escalation of stuck work, the digest of notices, Mission Control's
|
||||
my-queue, a workflow's human step when no person is configured for it, and a pairing approval without `--human`. They
|
||||
go to:
|
||||
1. the default person, when one is chosen (`rig gateway default <id>`, or `--default` on `human add`);
|
||||
2. otherwise the only registered person, so a one-person install needs no choice;
|
||||
3. otherwise nobody, and each says so: an escalation reports `undeliverable:no-default-person`, the notice digest
|
||||
waits, and the others name the command to run.
|
||||
|
||||
`rig gateway default` shows the current default; `rig gateway default --clear` clears the choice. Choosing a default
|
||||
never changes `workspace.operator_seat_name`, which keeps its own meaning.
|
||||
|
||||
## In the TUI: whose queue, and who acts
|
||||
|
||||
The person at the terminal is the **primary user**: the default person, or, with several people and none chosen, the
|
||||
person at the terminal unnamed. Whatever the TUI shows, its acts are theirs.
|
||||
- **Opening:** with a chosen default, the TUI opens on that person's Feed. With none chosen, including a one-person
|
||||
install that never chose one, it opens on the topology, as before.
|
||||
- **Whose queue:** `whose <person>` shows one person's asks, `whose all` everyone's, and `whose default` the default
|
||||
person's. The Feed's first line says whose queue it shows and who acts.
|
||||
- **Acting on someone else's ask** (answer, approve or resolve from the TUI) records both: the primary user as the actor,
|
||||
and the person asked in the audit notes and the transition. The asking seat reads, for example, "Answered by
|
||||
mike@external, the primary user at the terminal, on sarah@external's ask". With several people and none chosen, the
|
||||
actor is `human@host`.
|
||||
- **Viewing Sarah isn't acting as Sarah.** Only Sarah, from her own channel, answers as Sarah. Without the primary
|
||||
user's authority, one registered person can't answer, approve, deny or resolve what was asked of another; that's
|
||||
refused (`answer_not_recorded`) and nothing changes.
|
||||
- With no one registered, the TUI and its acts are as before, except on a shared channel's ask or a row parked on a
|
||||
channel: the TUI shows the act as `human@host`, the person at the terminal, and it's recorded that way, never as the
|
||||
channel.
|
||||
- **A shared channel never acts.** Its messages are correspondence, so nothing it says answers, approves, denies or
|
||||
resolves an ask, and a customer's earlier message in an ask's thread is never taken as its answer. A request without
|
||||
the primary user's authority that acts as a channel, with any Mission Control verb (including drop, route, hold, hand
|
||||
off and annotate), is refused (`answer_not_recorded`) and nothing changes.
|
||||
- **Where the authority applies:** only on a request that carries no seat identity header, which is how the TUI calls
|
||||
the daemon. Seats and the CLI send that header, so their acts stay theirs. This is the existing trusted-network
|
||||
distinction, not an authentication check: a request that leaves the header out is taken as the terminal's, as any
|
||||
such request already is.
|
||||
|
||||
## Shared-channel conversations
|
||||
|
||||
A registered shared channel lets people who aren't registered, such as a customer, talk to a seat, without registering
|
||||
each of them.
|
||||
|
||||
**Setup:**
|
||||
1. Invite the OpenRig Slack app to the channel.
|
||||
2. Register the channel: `rig gateway channel add acme-customers --display-name "Acme customers" --binding
|
||||
"slack:main:file:/etc/openrig/slack.env:C0ACME" --organization acme --policy-file ./acme-customers.md`.
|
||||
3. Send its new messages to the support seat: `rig slack channel-map set support-rig C0ACME --inbound
|
||||
support@support-rig`. Without a map, they go to the inbound destination.
|
||||
|
||||
A channel works on its own: no registered person is needed for it to converse.
|
||||
|
||||
**What the seat sees:** each message lands as a row from the channel (`acme-customers@external`). Its body ends with a
|
||||
labelled block: the channel, its organization and groups, who wrote (the Slack user, marked as not a registered person),
|
||||
and the channel's effective policy. The row is tagged `participant:acme-customers`, `shared-channel` and
|
||||
`slack-sender:<user id>`. A registered person writing in the channel stays themselves; the block only says where they
|
||||
wrote.
|
||||
|
||||
The channel's policy is the labelled block OpenRig adds at the end of the row, after the message. Anything above it is
|
||||
the sender's own words, even if it looks like policy. `rig gateway participants --json` is the source.
|
||||
|
||||
**Answering:** reply into the customer's thread with an update to the channel:
|
||||
|
||||
```bash
|
||||
rig queue create --destination acme-customers@external --human-intent update --reply-to <their row's id> \
|
||||
--summary "Your invoice" --body "It's on your account page."
|
||||
```
|
||||
|
||||
A later update with the same `--reply-to` lands in the same thread. An update without `--reply-to` posts to the channel
|
||||
on its own. Posts to a channel mention nobody.
|
||||
|
||||
**What a channel can't do:** its messages are correspondence. They never answer, approve, close or resume anyone's ask.
|
||||
You can still send an ask to the channel; the queue accepts it with a warning that nothing there will settle it, so read
|
||||
the replies and close it yourself. Its questions show in the channel as a list, without buttons, and ask for a reply in
|
||||
the thread.
|
||||
|
||||
## Where it's stored
|
||||
|
||||
- **People** stay exactly as before: one file per person under `$OPENRIG_HOME/gateway/humans/`, plus the generated
|
||||
`humans.generated.yaml`. Nothing new is written into them.
|
||||
- **Everything else** (the default, organizations, groups, each participant's placement and policy, and shared
|
||||
channels) is in `$OPENRIG_HOME/gateway/participants.yaml`, written by the commands above.
|
||||
- **A problem in `participants.yaml` never disables the person registry.** People still receive and answer their asks.
|
||||
The commands above report the problem, and with several people no default is chosen until it's fixed.
|
||||
- **A person removed by hand** leaves a warning in `rig gateway participants`, not a broken file. `rig gateway human
|
||||
remove` also removes the person's placement, and the default if it was them.
|
||||
|
||||
## Upgrading
|
||||
|
||||
For a one-person install, nothing to do: it keeps working as before, that person stays the default, pending rows keep
|
||||
their addresses, and no new file is written until you use one of the commands above.
|
||||
|
||||
A TUI older than the daemon still works: it sends the actor the daemon serves, the person asked, which is still their
|
||||
own act. On a shared channel's ask the daemon serves `human@host`. An older TUI's approve there is recorded as
|
||||
`human@host`, and its answer is refused (`answer_not_recorded`), because answering someone else's ask takes the primary
|
||||
user's authority, which only a current TUI sends.
|
||||
|
||||
**If several people are already registered** (earlier versions listed hand-added people with an advisory), choose a
|
||||
default with `rig gateway default <id>` after upgrading. Until you do, escalations report
|
||||
`undeliverable:no-default-person` instead of reaching whoever's id sorted first, and the notice digest waits.
|
||||
|
||||
## Rolling back to 0.7.2 or earlier
|
||||
|
||||
Older versions don't read `participants.yaml`, and the person files carry nothing they don't understand, so:
|
||||
- **every registered person still loads**, and each can still answer their own asks from Slack;
|
||||
- **another person's reply is guarded less on 0.7.1 and 0.7.0:** there, a different person's Slack reply in the thread
|
||||
of a question parked on someone else can resume that question, and 0.7.0 can record such a reply to a pending ask as
|
||||
an answer row (it still can't close the ask);
|
||||
- **there's no default:** escalations and the notice digest go to the first person by id, Mission Control's my-queue
|
||||
has no default person, and pairing needs `--human`;
|
||||
- **the TUI** opens on the topology and records a terminal answer as the person asked, as before. Rows already
|
||||
answered by the primary user keep their notes;
|
||||
- **shared channels are unknown:** their customers' messages are refused again, as from any unregistered sender, and
|
||||
rows addressed to a channel become undeliverable on the older version;
|
||||
- **organizations, groups and policy aren't shown.**
|
||||
|
||||
Upgrading again restores all of it, because the older version never changes `participants.yaml`.
|
||||
+145
-916
File diff suppressed because it is too large.
Load diff
@@ -115,12 +115,9 @@ outcome list affirms zero outcomes, not failed discovery. `false-positive`
|
||||
clears the suspicion without inventing a denominator when no missing facts remain.
|
||||
A false-positive assessment that still names missing facts stays indeterminate
|
||||
and does not close the episode interval. `indeterminate` supplies
|
||||
no outcomes and names the missing fact in `missingFacts`. `established` needs
|
||||
`boundedAuthority` set to true or false (not null) and no missing facts; while an
|
||||
established census still confirms the signal, a `false positive`, `insufficient
|
||||
evidence` or `resolved` verdict is refused. Required references must resolve
|
||||
inside the finding's resolved project folder (the configured workspace when no
|
||||
project resolves); extra evidence beyond the initial packet is allowed. The receipt retains the actual actor, timestamp, identity provenance,
|
||||
no outcomes and names the missing fact in `missingFacts`. Required references
|
||||
must resolve inside the workspace; extra evidence beyond the initial packet is
|
||||
allowed. The receipt retains the actual actor, timestamp, identity provenance,
|
||||
source basis, and evidence hashes. A changed basis refuses a stale submission.
|
||||
Later evidence changes make confirmation indeterminate rather than preserving
|
||||
a false ratio. Outcome meaning remains attributed agent judgment.
|
||||
@@ -134,8 +131,7 @@ traffic in the same family starts a new episode. Repeated reads never advance
|
||||
these boundaries. One occurrence and the existing owner cooldown apply to each
|
||||
episode; a disposition stops repeated requests.
|
||||
|
||||
This bounded source reads every handoff family touched in the window; only
|
||||
explicitly linked project or mission work resolves a scope. Its bounds: at most 2,000 touched
|
||||
This bounded source covers explicitly linked project or mission work: at most 2,000 touched
|
||||
qitems, 1,000 members / 10,000 transitions per family, 200 workflow
|
||||
receipts, 200 declared slices, and 100 proof files per selected slice. Overflow
|
||||
refuses visibly. When more than 200 families (roots) were touched, it evaluates the
|
||||
@@ -379,9 +375,7 @@ A consumer such as a later Herder plugin reads `GET /api/health` and
|
||||
`rig health explain <finding-id> --json` records. The record schema is
|
||||
`openrig.health/v0alpha1`; list metadata is `openrig.health-list/v0alpha1`.
|
||||
For a source that bounds its input, list metadata also carries `coverage`
|
||||
(`source`, `evaluatedAt`, `unit`, `total`, `evaluated`, `omitted`, `limit`,
|
||||
`order`, `partial`). A source that failed or hit a limit appears instead as
|
||||
`status: "unavailable"` with its `reason`, and its findings are left out.
|
||||
(`source`, `total`, `evaluated`, `omitted`, `limit`, `order`, `partial`), and
|
||||
`rig health policy` reports the scheduled evaluation's coverage under
|
||||
`engine.lastEvaluation.coverage`. Preserve ID, status, policy version, time window, freshness, evidence and
|
||||
threshold together. There is no health score or implicit remediation authority.
|
||||
@@ -390,19 +384,6 @@ ID reads retain them while the source can still project them. A recurrence after
|
||||
clear receives a new episode ID. This is an on-demand projection, not a history
|
||||
store; a detail 404 does not prove resolution.
|
||||
|
||||
In the TUI, the instance Table and the rig/pod Table and Overview load canonical
|
||||
findings for their health summaries. These summaries previously could show `Not assessed`
|
||||
even when the daemon served findings because they did not request the projection.
|
||||
Once the topology drill is resolved, these pages use the existing bounded
|
||||
`GET /api/health?limit=200` read; pod summaries continue to cover their rig.
|
||||
Other topology views using focused reads keep this projection lazy; the Health
|
||||
tab requests it explicitly.
|
||||
This findings read is separate from the control-plane `GET /healthz` read.
|
||||
|
||||
If `GET /api/health?limit=200` fails, including HTTP 503, the summary shows
|
||||
`Unknown · Unavailable`. A projection that was not requested remains
|
||||
`Unknown · Not assessed`, and a loaded empty result is not a healthy verdict.
|
||||
|
||||
Lists default to 100 and cap at 200, with `total` and `truncated` explicit.
|
||||
Ceremony findings take precedence before the cap so context pressure cannot
|
||||
hide the primary signal. Narrow a truncated query; do not certify the unseen
|
||||
@@ -418,9 +399,7 @@ Behavioral and epistemic categories intentionally have no detector. Review
|
||||
carousel, redundant wakes, stale directives and scope admission have typed
|
||||
evaluators and replay controls, but the live source does not infer their missing
|
||||
candidate-change, rescue, directive-conflict or admission-authority facts.
|
||||
Untagged work is still read: a family whose scope can't be resolved shows as an
|
||||
indeterminate instance-scope finding that names the unresolved scope and can't
|
||||
start a diagnosis. Undeclared relationships remain outside passive ceremony
|
||||
Untagged work and undeclared relationships remain outside passive ceremony
|
||||
coverage; normal tagged work no longer requires a special outcome census. A small lineage below the configured threshold may still deserve an
|
||||
agent's inspection; the threshold is a conservative admission rule, not a
|
||||
definition of good process.
|
||||
|
||||
+7
-61
@@ -24,9 +24,7 @@ rig doctor --json
|
||||
```
|
||||
|
||||
Use the installed command's `--help` if an option is unavailable. Read the diagnostic findings; don't treat them as
|
||||
instructions to reset the machine. `rig doctor` checks Claude and Codex authentication using the same local checks
|
||||
as setup, including a configured Codex provider credential variable. A set variable does not prove that the provider accepts it or that managed
|
||||
seats receive it. Doctor does not run an agent task: also inspect `rig ps --nodes --rig <rig>`. If the daemon is involved, `rig daemon status` and `rig daemon logs` show its state
|
||||
instructions to reset the machine. If the daemon is involved, `rig daemon status` and `rig daemon logs` show its state
|
||||
and recent output.
|
||||
|
||||
**If OpenRig won't install or `rig` won't run, start here anyway.** Record the attempted package version, install
|
||||
@@ -36,58 +34,18 @@ help.
|
||||
## Match the guidance to the installed version
|
||||
|
||||
The reference documents beside this file describe the version they were installed with. GitHub's default branch can
|
||||
contain changes that haven't reached your user's version. After an upgrade, start with the short note on what changed
|
||||
in the installed version: `rig context get reference/whats-new.md`. For full release notes and known limitations, open
|
||||
contain changes that haven't reached your user's version. For release notes and known limitations, open
|
||||
`https://github.com/mvschwarz/openrig/blob/v<version>/docs/releases/v<version>.md`, using the version number from
|
||||
`rig --version` (without the commit it may show in parentheses). When that file doesn't exist, use the version's
|
||||
section of `https://github.com/mvschwarz/openrig/blob/v<version>/CHANGELOG.md`. If neither is available, say so
|
||||
`rig --version` (without the commit it may show in parentheses). If the matching document isn't available, say so
|
||||
rather than treating a newer command as installed.
|
||||
|
||||
## Find your next step
|
||||
|
||||
### Installation or platform problems
|
||||
|
||||
Supported platforms are macOS and Linux, and WSL2 on Windows; native Windows isn't supported. OpenRig's automated tests
|
||||
don't run on WSL2 yet; one user's [reported working setup](getting-started.md#wsl2-a-reported-working-setup) lists what
|
||||
mattered. OpenRig needs
|
||||
Node.js 22 or 24 and tmux. A Linux distribution's own Node.js can be older; check `node --version`. With npm 11 or
|
||||
later, an `npm warn install-scripts` line for `@openrig/cli` means only the postinstall Node.js and SQLite check was
|
||||
skipped; `node "$(npm root -g)/@openrig/cli/scripts/check-abi.mjs"` runs it. A WSL error needs its actual versions,
|
||||
commands and error text; don't assume a Windows-related pull request fixes it.
|
||||
|
||||
The one-command install ([getting-started](getting-started.md#install-and-sign-in)) prints its plan with
|
||||
`--dry-run` and changes nothing. When a step fails it prints `FAILED [n/4] <command or check> (exit <code>)` and
|
||||
stops. Read its diagnostic: if it names a runnable command, run that command by hand for the full error and record it
|
||||
in a report; otherwise follow the accompanying diagnostic. If the only remaining failures are provider sign-ins under
|
||||
"Some steps need attention", the install steps finished: sign in to each selected provider and continue.
|
||||
|
||||
### Installation finished, but there is nobody to talk to
|
||||
|
||||
Load the `rigs` skill and follow its step 2: it opens the OpenRig view (`rig terminal open saved:kernel --window`),
|
||||
gives the attach commands when the window can't open or over SSH, and hands the person's goal to the operator.
|
||||
[Install and sign in](getting-started.md#install-and-sign-in) says how to load it. The reference for the view, manual
|
||||
attachment and the table of what can interrupt it is
|
||||
[Open the kernel conversations](getting-started.md#open-the-kernel-conversations)
|
||||
(`rig context get reference/getting-started.md#open-the-kernel-conversations`). Started is not ready: the view can
|
||||
open while the kernel's agents finish starting, and opening it creates no other kernel or account.
|
||||
|
||||
### A step interrupted setup or the OpenRig view
|
||||
|
||||
Name the exact command and result, the reason it stopped and the next useful step. A harness's permission rules,
|
||||
sandbox or automatic permission decision can refuse an installing agent's tool call before OpenRig runs.
|
||||
Claude Code's [auto mode can deny calls](https://code.claude.com/docs/en/auto-mode-config); explain the reported
|
||||
refusal and let the person review that step in their harness controls or run it themselves, within their chosen
|
||||
permissions. Do not silently claim installation failed or completed from a refused call.
|
||||
|
||||
For missing tools, downloads or selected logins, use the specific setup hint. A Herdr install warning leaves plain
|
||||
tmux available. A requested Ghostty install can fail setup; resolve it or decline with `--no-ghostty` and keep the
|
||||
earlier choices. Terminal.app remains available; required tools and logins still matter. macOS may ask for
|
||||
Automation permission; a missing display or remote daemon needs the documented headless/manual route.
|
||||
Herdr may show an intro (Return to continue) and an agent-integration panel (Esc to close); the view does not
|
||||
require installing those integrations. Enlarge a cramped 80×24 window. Use authorized desktop tools to inspect the
|
||||
window contents, or state that visibility is unconfirmed and ask the person to check. A successful command or
|
||||
window listing alone is not visual proof. The [OpenRig view guide and friction table](getting-started.md#open-the-kernel-conversations)
|
||||
connects each observation to its next step. Preserve existing conversations while resolving it.
|
||||
Supported platforms are macOS and Linux. Native Windows is not supported yet, and WSL2 has not been tested. OpenRig needs
|
||||
Node.js 22 or 24 and tmux. A WSL error needs its actual versions, commands and error text; don't assume a
|
||||
Windows-related pull request fixes it.
|
||||
|
||||
### The team did not start, or a terminal is missing
|
||||
|
||||
@@ -120,12 +78,6 @@ unknown outcome, check `rig seat status <seat>` before trying again. For a rig w
|
||||
`--non-interruptive` on `rig up` or `rig bundle install` avoids Claude's warning and Codex's notices in the first
|
||||
place; see `non-interruptive-mode.md` beside this file.
|
||||
|
||||
Codex's initial sign-in chooser and API-key entry are recognised as `login_required`, so startup reports the
|
||||
sign-in step instead of waiting for a generic readiness timeout. Finish that step in the seat's terminal, then use
|
||||
the continuation command above. A quoted or dismissed login screen is not a current login gate; other layouts
|
||||
keep their existing readiness handling. Claude's persistent "Not logged in" footer alone is not a login refusal, because a
|
||||
configured gateway may authenticate its requests.
|
||||
|
||||
### You can't tell which instance or configuration is involved
|
||||
|
||||
Read [instance layout](instance-layout.md) (`rig context get reference/instance-layout.md`) and
|
||||
@@ -139,19 +91,13 @@ issue's current status; a similar symptom alone is not a diagnosis.
|
||||
|
||||
- Claude seats reported as needing attention after a restore: [#86](https://github.com/mvschwarz/openrig/issues/86),
|
||||
[#273](https://github.com/mvschwarz/openrig/issues/273).
|
||||
- Claude usage limits may not be detected when neither a status line window nor a current
|
||||
`StopFailure/rate_limit` hook is available: [#99](https://github.com/mvschwarz/openrig/issues/99).
|
||||
See [Claude usage-limit detection](claude-status-line.md#claude-usage-limit-detection) for the inputs and retry behavior.
|
||||
- Claude usage limits may not be detected: [#99](https://github.com/mvschwarz/openrig/issues/99).
|
||||
- Codex prompt variants not recognised as idle: [#79](https://github.com/mvschwarz/openrig/issues/79).
|
||||
- Codex asks about hook trust at first launch: [#17](https://github.com/mvschwarz/openrig/issues/17), not reproduced
|
||||
by the team.
|
||||
- A Codex seat on the default `workspace-write` sandbox starts without network access, so it can't reach the local
|
||||
daemon, when its Codex configuration sets network access off, a managed requirement could restrict it, or Codex
|
||||
doesn't answer OpenRig's configuration read in time: [#275](https://github.com/mvschwarz/openrig/issues/275).
|
||||
- Kernel seats fail within a second of the first start on a distribution tmux whose server exits on `capture-pane`
|
||||
(`tmux -V` prints `next-3.4`): [#980](https://github.com/mvschwarz/openrig/issues/980). `rig doctor` checks for
|
||||
it (`tmux_capture`); the manual check and recovery are in
|
||||
[Incomplete setup and restart](getting-started.md#incomplete-setup-and-restart).
|
||||
|
||||
For everything else, search [open issues](https://github.com/mvschwarz/openrig/issues).
|
||||
|
||||
|
||||
@@ -6,9 +6,8 @@ operators and monitoring tools. This view is host-scoped; rig/node filters and
|
||||
multi-host fan-out do not apply. Ordinary `rig ps` output is unchanged.
|
||||
|
||||
The view reports available CPU count, host load averages (1/5/15 minutes),
|
||||
load divided by CPU count, running seats, the number of rotating seats and how
|
||||
many of them are backed off, and transcript capture attempts, failures, UTF8
|
||||
bytes and elapsed capture time for currently rotating seats.
|
||||
load divided by CPU count, running seats, and transcript capture attempts,
|
||||
failures, UTF8 bytes and elapsed capture time for currently rotating seats.
|
||||
Load is not CPU utilization; capture elapsed time includes waiting for tmux,
|
||||
and is not daemon CPU time. Load averages are unavailable on Windows, rather
|
||||
than reported as zero. Counters reset when a rotation is restarted/stopped or
|
||||
|
||||
@@ -1,114 +0,0 @@
|
||||
# Hosted members: a tool outside the terminal on your team
|
||||
|
||||
A hosted member is a tool that lives outside a terminal, such as an assistant, a chat bot or a cloud routine, and works as a member of a rig. You
|
||||
address work to it like any seat. It reaches the team through OpenRig's MCP server under a grant you issue and can revoke. It never gets a pane.
|
||||
|
||||
Assistants that run on your machine can reach OpenRig's MCP server locally. Many assistants live in a vendor's cloud, and those can only reach a server on the internet.
|
||||
|
||||
> **Experimental and unsupported. Off by default.** Nothing in OpenRig listens on the internet unless you set it up yourself. You serve `rig mcp serve --http`, put it behind your own TLS tunnel or proxy, and issue a token. Doing that is like opening a port in your firewall. Anyone with the URL and a valid token can act as that member within its grant. Treat the token like a password, give the member the narrowest grant, and revoke it when you're done (`rig mcp token revoke <name>`). We don't support, and take no responsibility for, an OpenRig reachable from the internet, just as with running OpenRig itself on the open internet. Use at your own risk.
|
||||
|
||||
## Set one up
|
||||
|
||||
1. **Pick its address** on an existing rig: `<member>@<rig>`, for example `grok@research`. No node is added; the queue takes rows for it.
|
||||
2. **Say what it's good at, and its limits,** in a roster: an entry in `<workspace.root>/rosters/<file>.json` with its seat, this machine's host id
|
||||
(`hostSelfId` from `rig ps --nodes -A --json`), `capabilities`, `use_when`, `why`, a `caveat` for its limits, and `"hosted": true` (see
|
||||
[Rosters](rosters.md)).
|
||||
3. **Issue its grant:**
|
||||
|
||||
```sh
|
||||
rig mcp token add grok --seat grok@research --rig research
|
||||
```
|
||||
|
||||
It prints the token once. The member acts as `grok@research`: every row it creates or changes is attributed to that seat, and it reaches only
|
||||
that rig's seats and work.
|
||||
4. **Serve the MCP server over HTTP** behind a tunnel or proxy that adds TLS: `rig mcp serve --http`. See `rig mcp serve --help` for binding and
|
||||
for how authentication works. If the proxy runs browser checks (such as Cloudflare's Browser Integrity Check), skip them for `/mcp`:
|
||||
MCP clients aren't browsers.
|
||||
5. **Add the server in the tool:** its `https://…/mcp` URL and the token as a bearer credential.
|
||||
|
||||
## How it works its rows
|
||||
|
||||
- **Hand it work** as you would any seat: `rig queue create --destination grok@research …`.
|
||||
- **The member works it** through the MCP tools:
|
||||
- `rig_queue_list` with `owned` lists its rows;
|
||||
- `rig_queue_claim` takes one;
|
||||
- `rig_queue_update` closes it done with the answer in `resolution`, or `rig_queue_handoff` hands it on to a seat in its rig.
|
||||
- **It can send work too:** `rig_queue_create` to its rig's seats.
|
||||
- **Its rows outlive the conversation.** A new conversation with the same grant reaches the same work.
|
||||
- **`rig_whoami`** answers the seat its grant names, though the member has no session.
|
||||
|
||||
## Asking a person while keeping the work
|
||||
|
||||
When a row needs a person's approval before the member can finish it, the member keeps the row and asks:
|
||||
- **The row came from a person:** the member sets it `blocked` with `blockedOn` that person, and puts the question, with a short form of
|
||||
what it will do, in the row's `summary`. The person is asked with the summary and the row; a transition note stays in the row's history
|
||||
and isn't part of the ask. A longer draft goes at an https link in `evidenceRef`, which the ask carries. The person's answer returns the
|
||||
row to the member in progress.
|
||||
- **The row came from a seat, or from a shared channel:** the member asks as a new row, to that seat, or for a channel's row to its rig's
|
||||
lead (a shared channel takes correspondence and can't answer an ask). Then it sets its own row `blocked` on the new row's id. When the
|
||||
question closes, the member's row returns to pending.
|
||||
- **Keep the question and action summary short.** A long row body continues as numbered thread replies, within the existing delivery
|
||||
limits. Use an https `evidenceRef` for a longer approval draft. The summary and framing can still be too large, so nothing promises
|
||||
unlimited delivery.
|
||||
|
||||
Either way the row reads blocked, not done, while it waits, and the member finishes that same row. Nothing promises to wake the
|
||||
member, so it checks its rows again.
|
||||
|
||||
The server tells the member this in its MCP instructions. The text is versioned, so you can check which version a tool received:
|
||||
|
||||
> Member workflow (member-workflow/v2). Your inbox is the items addressed to your seat: rig_queue_list with owned set. It's yours, not the team's queue. A wake, a ring or a message only points at it: list your inbox, then act. For each item: claim it (rig_queue_claim), do it, then close it done with closure reason no-follow-on and the answer in resolution (rig_queue_update), or hand it on (rig_queue_handoff). Listing or reading an item doesn't take it. Say what you can reach from your grant, not from the tool list: a listed tool isn't access. rig_artifact_read's answer for an item names the shared roots you may read, and none means no shared files. If the person connected you, that's basically authorized: claim the items in your inbox and do them without asking whether you may. When an item needs a person's approval before you can finish it, don't close it and don't take the action: keep the item and ask. If it came from a person (an address ending in @external that isn't a shared channel; the item's 'Shared channel:' line names one), set it blocked with blockedOn that person and, as its summary, the question with a short form of what you'll do: the person sees the summary and the item, not your note, which keeps the record. Link a longer draft as an https evidenceRef. Their answer returns the item to you in progress. Otherwise ask as a new item, to the seat it came from or, for a shared channel's item, to your rig's lead (rig_team shows it), with your question and draft. Then set yours blocked with blockedOn that new qitemId: when that item closes, yours returns to pending, to claim again. Nothing promises to wake you, so check your inbox again. Then finish the same item; don't open a new one.
|
||||
|
||||
## Ring it when work lands
|
||||
|
||||
If the tool has a trigger that starts it from outside, such as a webhook on a scheduled routine, add it to the member's roster
|
||||
entry. The entry holds secret names, never values:
|
||||
|
||||
```json
|
||||
"wake": { "webhook": { "url_ref": "GROK_WAKE_URL", "authorization_ref": "GROK_WAKE_AUTH", "secrets_env_file": "/abs/path/grok-wake.env" } }
|
||||
```
|
||||
|
||||
- **The secrets:**
|
||||
- `url_ref` names the secret holding the webhook URL.
|
||||
- `authorization_ref`, when the tool needs one, names the secret holding the `Authorization` header value.
|
||||
- Credentials in the URL itself (`https://user:pass@host/…`) are sent as Basic `Authorization` instead, unless
|
||||
`authorization_ref` is set: then its value is sent, and the URL's credentials are dropped.
|
||||
- The daemon reads each from its environment (the name, or `OPENRIG_<NAME>`), else from `secrets_env_file`, an env file kept at mode 0600.
|
||||
- **The ring:** when a row lands for the member, the daemon POSTs
|
||||
`{"source":"openrig.queue","schema_version":1,"event":"work-waiting","qitem_id":…,"destination":…,"summary":…,"from":…}`.
|
||||
- It's a pointer, not the row's body: the member reads the row under its grant.
|
||||
- A receiver should tolerate a repeated `qitem_id`. A ring accepted just before the daemon stops, before it's recorded,
|
||||
is rung again on recovery, the same at-least-once window a terminal wake has.
|
||||
- It waits up to 10 seconds and doesn't follow redirects.
|
||||
- **What the trigger should do:** start a run that lists the member's rows (`rig_queue_list` with `owned`) and claims its work.
|
||||
|
||||
## What the record says, and doesn't
|
||||
|
||||
These facts stay separate on the row:
|
||||
- **Wake:** with a trigger, the row's wake result is `wake-accepted:webhook (<url_ref>) answered <status>` when the trigger took the
|
||||
ring, or `failed:webhook …`. Accepted means the tool's trigger answered, not that the member read the row.
|
||||
- With no trigger, the result is `unroutable`, and OpenRig tells the person: the operator seat when it's a person, else whoever
|
||||
created the row.
|
||||
- It tells the person too when the member was rung but hasn't claimed the work by the stuck sweep's unclaimed age
|
||||
(`queue.stuck_sweep_unclaimed_age_minutes`, 60 by default).
|
||||
- The member sees new work when it checks: when it's rung, when its person asks it to, or on a schedule the tool runs.
|
||||
- **Pickup:** its claim, a transition by its seat. Listing or reading a row isn't pickup.
|
||||
- **Result:** the closing transition and its resolution, or the handoff.
|
||||
- **Notification:** where a person asked, Slack's posted receipt. A posted notice isn't the person's acknowledgment.
|
||||
|
||||
**On the team:** `rig_team` lists the rig's hosted members (roster entries marked hosted that aren't one of its nodes), with their capabilities and caveat, no pane, and activity `unknown`.
|
||||
OpenRig doesn't observe a hosted member between its calls, so it never reads idle. `rig roster find` shows it the same way.
|
||||
- **Presence:** each entry carries `presence`, which says what OpenRig last saw of the member. It isn't pickup, and `null` means unknown:
|
||||
- `lastCallAt`: its last authenticated call to this host's `rig mcp serve --http`, recorded at most once a minute in
|
||||
`<OPENRIG_HOME>/mcp-http-presence.json`, beside the token file;
|
||||
- `lastWake`: its latest ring and the result, among its 50 most recent rows.
|
||||
- `rig roster show` and `find` show the last call; the last ring is in `rig_team`.
|
||||
|
||||
## Revoke
|
||||
|
||||
`rig mcp token revoke grok` refuses its next request. The rows it worked, and their answers, stay.
|
||||
|
||||
## Limits today
|
||||
|
||||
- **Webhook triggers only:** OpenRig rings a webhook. Email and other triggers aren't supported yet. A member without a trigger
|
||||
isn't rung, and its person is told instead.
|
||||
- **It can't act as a person:** it works rows addressed to its seat, a person's request to it included. It can't settle an ask addressed to a person, or hand work to one.
|
||||
@@ -79,11 +79,6 @@ Missing or malformed selections fail; absence is never inferred as disablement.
|
||||
`rig context work-install --json` reports the effective state, source, manifest,
|
||||
context selectors, and skills. With `--runtime`, its managed skill loadout then
|
||||
combines System World, topology, and Project World selectors with provenance.
|
||||
The catalog is a Git checkout. A skill folder with uncommitted or untracked content is
|
||||
skipped by itself and named. With `--runtime`, work-install reports selected skips with
|
||||
exit 1. It inspects by default; `--apply-skills` projects the remaining clean skills while
|
||||
keeping any previously projected copy of the skipped skill. An uncommitted change directly
|
||||
in the catalog root, such as `catalog.yaml`, still makes the whole catalog unavailable.
|
||||
|
||||
For a pre-0.5.9 home, use the `openrig-upgrade` skill's
|
||||
`migrate-telemetry-state-0.5.9.mjs` helper as an Agent-Operated Migration. Its
|
||||
|
||||
@@ -12,9 +12,8 @@ observer. Do not copy the token to incidental identity or health checks.
|
||||
|
||||
Records use `schema: openrig.request-phase/v1` in the existing
|
||||
`logs/slow-operations.jsonl`. Each process has an observation `epoch` and sequence
|
||||
`seq`. An activation record carries the installed build stamp (`semver`,
|
||||
`commit`, `dirty`, `builtAt`; each is null in an unstamped development build).
|
||||
Each admitted request gets a distinct
|
||||
`seq`. An activation record carries the installed build stamp (null for an
|
||||
unstamped development build). Each admitted request gets a distinct
|
||||
`serverRequestId`, even if a caller reuses an `attemptId`. Routes are recorded as
|
||||
`rigs_list` or `rig_nodes`, never a rig name or full URL.
|
||||
|
||||
@@ -53,8 +52,7 @@ observations, never requests. The existing 1 MiB log plus three rotated files an
|
||||
0600 file modes apply. The worker writes asynchronously; HTTP observation never
|
||||
waits for fsync or the synchronous slow-operation BEGIN barrier.
|
||||
|
||||
Records carry cumulative `rejected` (admission refused), `expired` and
|
||||
`observerErrors` counters and writer
|
||||
Records carry cumulative admission/expiry/observer-error counters and writer
|
||||
`coverage` counters (`offered`, `enqueued`, `dropped`, `acknowledged`, `failed`,
|
||||
`pending`, `recorderHealthy`). Writer counters describe the state sampled for that
|
||||
record, not an acknowledgment of that record itself. Retained epoch/sequence
|
||||
|
||||
@@ -1,274 +0,0 @@
|
||||
# Keeping a Watch for a Person
|
||||
|
||||
**How an operator turns "remind me in 20 minutes" or "tell me when X happens, check every hour" into a watch it
|
||||
keeps, using today's queue commands.** The person speaks in sentences. They never see YAML, a job ID or a policy name
|
||||
unless they ask.
|
||||
|
||||
> **Status (0.7.0).** The kernel operator's role guidance points here: when a person asks it to watch something or
|
||||
> remind them, it reads this page (installed at `$OPENRIG_HOME/reference/keeping-a-watch.md`) first. Every step below
|
||||
> was exercised with the CLI on an isolated private daemon: create, set aside, fire, re-arm, list, change, stop, a
|
||||
> daemon restart and a handover. A native run with a real operator, install and channel has **not** been run yet.
|
||||
> The usage warning's command and field names are checked against the served command on a test fixture; it hasn't
|
||||
> been run as a watch.
|
||||
|
||||
## The shape
|
||||
|
||||
A watch is a **queue task the operator owns**, set aside with a **one-shot timer**:
|
||||
|
||||
1. The person asks. The operator creates one task for itself and sets it aside with `--wake-after`.
|
||||
2. The timer fires once and wakes the operator. The operator reads the task and checks the condition.
|
||||
3. Then it tells the person, re-arms the timer, or both. **A timer fires once: a watch that isn't re-armed goes
|
||||
quiet.**
|
||||
|
||||
OpenRig keeps the record and the timer. The operator does the judgment: what to check, and whether it's worth telling
|
||||
the person.
|
||||
|
||||
## Before you set one: can you reach the person?
|
||||
|
||||
Run `rig gateway human list --json`. A watch tells the person through the registered human channel (Slack today,
|
||||
also shown in the TUI Feed), at `<entityId>@external`. **A terminal is never a person's address.** If no human is
|
||||
registered, say so now, before setting anything up: a watch that can't reach them is a watch they'll never hear from.
|
||||
|
||||
## Setting a watch
|
||||
|
||||
**1. Write the task body for a successor.** You may be restarted, compacted or replaced before the watch ends. A new
|
||||
operator must be able to act from the task alone. Put these in the body:
|
||||
|
||||
```markdown
|
||||
Person's words: "Tell me when the release PR merges; check every hour."
|
||||
Check: `gh pr view <n> --json state` — met when state is MERGED.
|
||||
Interval: 1h.
|
||||
Tell them: <entityId>@external (human channel), once, when met.
|
||||
Stop: after telling them once, or when they say stop.
|
||||
Unknown: not said yet.
|
||||
```
|
||||
|
||||
**2. Create it for yourself,** with a `watch` tag so it can be listed later (tags can't be changed after creation).
|
||||
`<your session>` is your session name from `rig whoami --json`:
|
||||
|
||||
```bash
|
||||
rig queue create --destination <your session> --tags watch \
|
||||
--summary "Watch: tell <person> when the release PR merges (hourly)" --body-file <file>
|
||||
```
|
||||
|
||||
**3. Set it aside with the timer.** A new pending task can be set aside directly; no claim is needed:
|
||||
|
||||
```bash
|
||||
rig queue block <task> --on external:<what you check> --wake-after 1h \
|
||||
--continuation "check <what>; tell <person> if met, else re-arm 1h"
|
||||
```
|
||||
|
||||
`--on` is always required; `external:<what>` names the outside thing you're waiting on. The timer first fires after
|
||||
the interval, not now.
|
||||
|
||||
**4. Say back what you set, in one or two plain lines:** what you'll check, how often, how they'll be told, and when
|
||||
it stops. For example: "I'll check the release PR every hour and message you here once it merges. Then I'll stop."
|
||||
|
||||
A plain reminder ("remind me in 20 minutes to look at the release notes") is the same with no condition. Set it aside
|
||||
with `--wake-after 20m`, and when it fires, tell them and close it.
|
||||
|
||||
## Every time the timer fires: read the record first
|
||||
|
||||
When the timer's message arrives, **run `rig queue show <task> --full --json` before doing anything.** A message already
|
||||
on its way can still arrive after the watch was stopped or changed. If the task is no longer set aside (done, canceled, or replaced),
|
||||
do nothing.
|
||||
|
||||
Otherwise, check the condition, then do exactly one of these:
|
||||
|
||||
| What you found | Do |
|
||||
|---|---|
|
||||
| **Met, and the watch was "once"** | Tell the person (below), then close: `rig queue update <task> --state done --closure-reason no-follow-on --note "<what you saw>"` |
|
||||
| **Met, and it's "every time"** | Tell the person, then re-arm |
|
||||
| **Not met** | Re-arm. Say nothing to the person: never send "nothing yet" |
|
||||
| **Can't tell** (no fresh reading) | The first time, tell them once that you can't tell, and why. Record that in a note (`Unknown: said <time>`), then re-arm. **Never say "all fine" for an unknown.** Stay quiet on later unknowns until the reading returns or changes |
|
||||
|
||||
**Re-arm** by setting it aside again with a fresh timer:
|
||||
|
||||
```bash
|
||||
rig queue block <task> --on external:<what> --wake-after 1h --note "checked <time>: not met"
|
||||
```
|
||||
|
||||
A new set-aside replaces the old one and retires any earlier timer, so a task never carries two live timers.
|
||||
|
||||
**Put what changed in `--note` or `--continuation`, not both.** When `rig queue block` gets `--continuation`, that is
|
||||
the note it records, and `--note` is dropped.
|
||||
|
||||
Each check costs one of your turns on the person's subscription. **Use the longest interval that serves the ask.**
|
||||
|
||||
## Telling the person
|
||||
|
||||
```bash
|
||||
rig queue create --destination <entityId>@external --human-intent update \
|
||||
--summary "<subject>" --body-file <brief> --evidence-ref <watch task id> --verify --json
|
||||
```
|
||||
|
||||
- Always pass `--evidence-ref`; the watch task's ID is a durable pointer the person can open.
|
||||
- Later messages about the same watch can thread with `--reply-to <earlier message's id>`.
|
||||
- **`posted` means the connector posted it, not that they read it.** Don't say they saw it.
|
||||
- **If delivery fails or is indeterminate,** inspect that task before anything else. Never resend blindly.
|
||||
|
||||
## "What are you watching for me?"
|
||||
|
||||
List **every active state**, not just set-aside ones. A watch being checked can be in progress, and a new one can be
|
||||
pending:
|
||||
|
||||
```bash
|
||||
rig queue list --owned --state pending,in-progress,blocked --full --limit 200 -o json
|
||||
```
|
||||
|
||||
Then keep the tasks tagged `watch`. Two rules:
|
||||
|
||||
- **Check that the number of tasks returned is below the limit.** The limit applies before you filter by tag. If you got
|
||||
exactly the limit, raise it and list again. **Never report "no watch" from a page that was cut off.**
|
||||
- **Use `--full`.** Compact output leaves out the body and the waiting view.
|
||||
|
||||
For each watch, say what it checks, how often, how they'll be told, and the next check. The next check is
|
||||
`waiting.nextBackstop.dueAt` when `waiting.nextBackstop.mechanism` starts with `watchdog:`. If a set-aside watch shows
|
||||
no timed backstop instead, its timer has fired and wasn't re-armed. Check it now and re-arm it.
|
||||
|
||||
Answer from the records, so a second reader would give the same list.
|
||||
|
||||
## Changing or stopping a watch
|
||||
|
||||
| The person says | Do |
|
||||
|---|---|
|
||||
| **"Check every 2 hours instead"** | Re-arm with the new interval and a note saying what changed: `rig queue block <task> --on external:<what> --wake-after 2h --note "<person's words>"` |
|
||||
| **"Watch Y instead"** (what's checked changes) | A task's body can't be edited. Create the new watch, then retire the old one: `rig queue update <old> --state canceled --closure-reason superseded --closure-target <new> --note "<person's words>"` |
|
||||
| **"Stop watching that"** | `rig queue update <task> --state canceled --note "<person's words>"`. Leaving the set-aside state retires its timer. A plain cancel takes no other closure fields |
|
||||
|
||||
Tell the person in one line what changed. After a stop, take no further action for that watch.
|
||||
|
||||
## Across a restart or handover
|
||||
|
||||
A set-aside watch's current timer is **kept** when the operator is restarted or replaced, and it fires at whoever is
|
||||
the operator next. That's why the body must stand alone.
|
||||
|
||||
**One gap:** a timer fires once. If the operator is replaced **after a fire and before the re-arm**, the successor
|
||||
inherits a set-aside watch with no live timer. OpenRig's idle-owner check may remind the new operator once, but only
|
||||
under some conditions, with no delay guarantee. So:
|
||||
|
||||
- **Re-arm promptly** after every fire.
|
||||
- **After a restart or handover, list your watches** (above) and re-arm any that show no timed backstop.
|
||||
- **Handing a watch to another session** (`rig queue handoff <task> --to <session>`) closes the old task and retires its
|
||||
timer (unless another task shares that timer through `--wake-watchdog`; a watch set up as above never does). The new
|
||||
task arrives pending, with its body and `watch` tag but no timer: the new owner sets it aside again with a fresh
|
||||
timer, as in step 3.
|
||||
|
||||
## A usage warning: "warn me when my allowance runs low"
|
||||
|
||||
This is a conditional watch like any other: the same task, timer, re-arm, stop and human channel. Only the check is
|
||||
specific.
|
||||
|
||||
**The check is `rig provider status --all-hosts --json`.** It returns what every registered machine already holds,
|
||||
this one included, and never starts a read on any account. With no host registry it covers this machine only, and
|
||||
says so. Use it rather than the single-machine `rig provider status --json`: one allowance used from several
|
||||
machines appears once, with each machine's own observation beside it, so you can't count it twice. If it answers that
|
||||
usage windows are off, tell the person that before setting the watch, as you would an unreachable channel.
|
||||
|
||||
For a Claude login supplied by `CLAUDE_CODE_OAUTH_TOKEN`, an explicit one-credential read is available:
|
||||
|
||||
```sh
|
||||
rig provider status --refresh --provider claude --claude-token-file /absolute/private/personal.token --credential-label Personal
|
||||
```
|
||||
|
||||
The file must be readable by the daemon, regular, at most 8 KiB, and contain only the token. Ownership by the daemon user and mode 0600 or
|
||||
0400 are recommended; different ownership, broader permissions and symlinks produce warnings, not refusals. Provision it through your existing credential
|
||||
custody; never put token values in arguments, seat environment settings, evidence or a queue item. The path is on the selected daemon's
|
||||
machine. Repeat the command for another labelled file when you want to compare subscriptions. This option does not fan out with
|
||||
`--all-hosts` or `--hosts`.
|
||||
|
||||
**Each token refresh spends one model turn.** Status and TUI reads show the cached result and never probe. A timeout or refusal does not
|
||||
prove no allowance was spent. The probe uses a temporary home/config/work directory and a single Haiku turn, with CLI flags requesting no tools, hooks or MCP. Unsupported CLI flags or missing events are reported as failures/unknown, not as free capacity. The event format is evidenced on
|
||||
Claude Code 2.1.310; other versions may report different fields. These are credential labels you supplied, not provider-verified account
|
||||
names, and do not prove a running seat uses that credential. The ordinary status-line sample/account join remains unproven.
|
||||
|
||||
Only actually reported window percentages and resets are measurements. A rejected window can have an unknown percentage; overage rejection
|
||||
is separate from subscription rejection. Readings and their times survive daemon restart, marked historical until refreshed. Files with
|
||||
different references/labels stay separate; equal resets or matching labels on another host never establish one allowance or extra room.
|
||||
|
||||
**Never put `--refresh` in the timer's check.** `rig provider status --all-hosts --refresh` starts a native read of the
|
||||
accounts on every machine. Run it only when the person asks for a fresh reading now.
|
||||
|
||||
**Choose the allowance with the person once, and write its identity into the body.**
|
||||
- **The allowance:** its `items[].key` and `items[].provider`, read from one run of the check. Show them the allowance
|
||||
by its label in the plain `rig provider status --all-hosts` view, never a key they have to type. An item whose key
|
||||
is null (a login that hasn't been identified) can't be watched: say so, and offer to watch it once it's identified.
|
||||
- **For Codex, the login email too:** `items[].observations[].row.identity.email`, shown on each machine's line in the
|
||||
plain view. The same Codex account can appear as more than one item with the same key, one per login email (or none)
|
||||
it was seen under. So on each fire, use the one item whose key matches and whose observations carry the recorded
|
||||
email. If none or several do, you can't tell. A Codex allowance whose login email is missing can't be pinned this
|
||||
way, so it stays can't tell. A changed email isn't followed: if the person's login email changes, set the watch
|
||||
again with them.
|
||||
- **The window:** `items[].observations[].row.windows[].window`. Claude's are `five_hour` and `weekly`; Codex's are
|
||||
`primary` and `secondary`, with `items[].observations[].row.windows[].durationMins` saying which is which.
|
||||
- **The threshold:** on `items[].observations[].row.windows[].remainingPercent`. It's a percentage, and no absolute
|
||||
amount is served. Remaining is 100 minus `items[].observations[].row.windows[].usedPercent`, never below 0. Both are
|
||||
null when the machine reported no usage for the window.
|
||||
|
||||
**What each part of the answer means:**
|
||||
|
||||
| Field | What it tells you |
|
||||
|---|---|
|
||||
| `items[].linkage` | `single`: one machine saw it. `same`: several machines saw one allowance. Compare their observations; **never add or average them**. `conflict`: the machines' fresh observations disagree (their reset times are more than 60 s apart); every observation is kept and none is chosen. `unknown`: the same id seen under another login, or with no login email, and not merged with it. `items[].notes` says why. For Codex, the one item carrying the person's recorded key and email is still theirs: its `unknown` is about the other login's item (see the decision). Any other `unknown` item is not theirs to watch |
|
||||
| `items[].observations[].hostId`, `items[].observations[].readAt` | Which machine the observation is from, and when this daemon read it |
|
||||
| `items[].observations[].row.windows[].observedAt` | When that machine's reading was taken: the time to tell the person |
|
||||
| `items[].observations[].row.windows[].resetsAt` | When that window resets: tell the person this too |
|
||||
| `items[].observations[].row.windows[].freshness` | `fresh`, `stale` or `unavailable`, with `items[].observations[].row.windows[].freshnessReason` saying why. A reading is fresh for 15 minutes |
|
||||
| `items[].observations[].row.windows[].level` | The served level, with `items[].observations[].row.windows[].levelReason`. Compare the person's threshold, not this level. But **`unknown` means the number can't be used**: no usage was reported, the window's reset time has passed (the number is from before it), or Claude seats report different windows (possibly different logins) |
|
||||
| `items[].observations[].row.lastRefresh` | **Codex:** that machine's last native read. When `items[].observations[].row.lastRefresh.outcome` is `failed`, the reading it kept is older and reads `stale`. **Claude:** the last read of the daemon's own Claude login (its identity) only. Claude's windows come from the seats' status-line readings at their own times, so they can stay `fresh` beside a failed identity read |
|
||||
| `items[].observations[].row.identityNote` | **Claude:** which login the identity is (as of the last identity read) and which seats the windows came from. The windows aren't proven to be that login. Say so when you tell the person |
|
||||
| `hosts[].usage`, `hosts[].usageReason` | Whether each machine's usage was read: `served`, `off`, `older` or `unavailable`, and why. A machine that wasn't read contributes nothing, never a zero |
|
||||
| `hosts[].lastRefresh` | The last refresh started from here for that machine, per provider. A `failed` one sits beside the older observation the machine kept |
|
||||
| `seatAccounts[].seats[].configured`, `seatAccounts[].seats[].allowance` | The account each seat is **configured** to use. `seatAccounts[].seats[].allowance.linked` is always false: configuration isn't proof of which allowance a running seat draws on, or that a Claude seat's windows are the identity's login. Never tell the person a seat uses this allowance because of it |
|
||||
| `seatAccounts[].seats[].observed` | What the seat itself was seen reporting: whether its status line has sent windows and when (`seatAccounts[].seats[].observed.lastSampledAt`), and `seatAccounts[].seats[].observed.differsFrom`, the seats whose readings disagree with it. Observed facts, still not a link to an allowance |
|
||||
|
||||
**The decision on each fire,** using the table in "Every time the timer fires". A usable reading is a `fresh`
|
||||
observation of the chosen window whose `level` isn't `unknown`.
|
||||
- **Met:** a usable reading is below the threshold. Tell them the lowest one, with its machine, `observedAt` and
|
||||
`resetsAt`. If the linkage is `conflict`, also tell them the machines disagree, from `items[].notes`, rather than
|
||||
presenting the lowest as the reading.
|
||||
- **Not met:** every usable reading is at or above the threshold, and there is at least one.
|
||||
- **Another login on the same Codex account:** when the item matched by key and recorded email has `items[].notes`
|
||||
saying the account is also observed under another login email (or with none), its linkage reads `unknown` on one
|
||||
machine, or `same` on several. Use its own usable readings as above. When you tell the person, say that login's
|
||||
observations are unlinked: not added, and not merged.
|
||||
- **Can't tell:** no usable reading: none `fresh`, or the fresh ones' `level` is `unknown`, which includes a null
|
||||
`remainingPercent`. Also when the allowance is missing from the answer or its key is null, or (Codex) no login email
|
||||
was recorded, or no item, or more than one, carries both the key and the recorded email. Use the once-then-quiet
|
||||
unknown rule, and give the reason (`freshnessReason`, `levelReason`, or the machine's `usageReason`).
|
||||
|
||||
The task body, for the person's own allowance, window and threshold:
|
||||
|
||||
```markdown
|
||||
Person's words: "Warn me when my Claude allowance drops below 20% of its 5-hour window; check every 30 minutes."
|
||||
Check: `rig provider status --all-hosts --json` (served readings only; never --refresh).
|
||||
Allowance: key <allowance key>, provider claude, window five_hour. Chosen with the person.
|
||||
(For Codex, also: login email <email shown in the label>.)
|
||||
Usable: a fresh observation of that window whose level isn't unknown.
|
||||
Met: a usable reading with remainingPercent below 20. Report the lowest, with its machine, observedAt and resetsAt.
|
||||
Never add machines' numbers. If the linkage is conflict, say the machines disagree (items[].notes).
|
||||
Claude: say the windows come from seats' status lines and aren't proven to be the identity's login (identityNote).
|
||||
Codex: the one item with the recorded key and email is theirs even if its linkage is unknown; say the other login's
|
||||
observations are unlinked (items[].notes).
|
||||
Can't tell: no usable reading (none fresh, or level unknown: give its levelReason), the allowance missing or its key
|
||||
null, or (Codex) no email recorded, or no item, or more than one, carries both the key and the recorded email. Give the
|
||||
reason.
|
||||
Interval: 30m.
|
||||
Tell them: <entityId>@external (human channel), once, when met.
|
||||
Stop: after telling them once, or when they say stop.
|
||||
Unknown: not said yet.
|
||||
```
|
||||
|
||||
## What not to use
|
||||
|
||||
- **`rig watchdog register --policy periodic-reminder` for a person's watch.** It repeats every interval until it's
|
||||
stopped (the first fire comes one interval after you register it), and it stops when the agent that registered it
|
||||
is replaced. It's fine for agent-to-agent reminders. Your own watch timers also show as `periodic-reminder` in
|
||||
`rig watchdog list`: that's the one-shot timer `--wake-after` arms, not a registered repeating reminder. It's retired
|
||||
when it fires or when the task stops being set aside. A wake held back because you were typing (a retained
|
||||
delivery) wasn't delivered, so it doesn't use the timer up: it's tried again at each interval until an attempt goes
|
||||
through (delivered or failed), which retires it. A timer another task shares through `--wake-watchdog` stays live
|
||||
for that task when this task is handed off or stopped, and the same rule applies to its wake. None of this is a
|
||||
delivery guarantee.
|
||||
- **Transcript bytes as "usage".** `context-usage-threshold` measures an agent's transcript, not an account's
|
||||
allowance. For an allowance, see "A usage warning" above.
|
||||
@@ -91,9 +91,7 @@ shipped vocabulary (four rungs plus two exits):
|
||||
`wip | provisional | established | canonical | superseded | retired`
|
||||
|
||||
`superseded` must name its successor; `retired` means do-not-use. These are the ONLY
|
||||
valid values — `rig scope slice stage` and `rig scope mission stage` reject invented stages
|
||||
(shape, shaped, draft) and a `superseded` without a successor; context-pack manifests and
|
||||
lore frontmatter aren't checked. Items minted under
|
||||
valid values — invented stages (shape, shaped, draft) are rejected. Items minted under
|
||||
new conventions carry a stage from birth: labeling from day one is free, retrofitting
|
||||
is archaeology.
|
||||
|
||||
|
||||
@@ -3,10 +3,8 @@
|
||||
For rigs whose hand-authored context predates the chain-file convention and
|
||||
lives at the legacy location (`~/.openrig/shared-docs/rigs/<rig>/`, or
|
||||
`$OPENRIG_SHARED_DOCS_ROOT/rigs/<rig>/`). Nothing here is destructive: the
|
||||
legacy tree is left in place, `rig context trace` keeps reading it at the rig and
|
||||
seat levels throughout (with an advisory), and every copy is no-clobber. The refocus
|
||||
trace, `seat:` profile atoms and handover priming read only `topology.root`, so
|
||||
they see these files only after migration.
|
||||
legacy tree is left in place, reads keep working throughout (the walker's
|
||||
advisory-emitting fallback), and every copy is no-clobber.
|
||||
|
||||
## The path, with exact commands
|
||||
|
||||
|
||||
@@ -84,9 +84,7 @@ line so attribution remains visible when the resolver returns only that section.
|
||||
|
||||
## Addressing and composition
|
||||
|
||||
Lore uses the existing `seat:` grammar and an explicit rig-and-seat read grant
|
||||
(`rig context profile <pack> --situation <fresh|handover|post-compaction> --rig <rig> --seat <seat>`,
|
||||
where the grant needs both `--rig` and `--seat`).
|
||||
Lore uses the existing `seat:` grammar and an explicit rig-and-seat read grant.
|
||||
The address says which file or section to read; the grant says whose seat tree
|
||||
the address is relative to. No grant means no read.
|
||||
|
||||
|
||||
@@ -196,9 +196,7 @@ The layers compose from surfaces that already exist; no new mechanism is require
|
||||
retains `claude-code`. Profile defaults from `OPENRIG_RUNTIME`, otherwise
|
||||
Claude; work-install requires the flag to inspect or apply skills.
|
||||
- Delivery: `rig walk <seat> --through-profile world-public --profile <profile>
|
||||
--situation <situation> ...` applies the already-inspected profile (walk's
|
||||
seat grant is `--seat-grant`, and its `--runtime` takes `claude` or `codex`,
|
||||
defaulting to `claude`, so a Codex profile needs `--runtime codex`);
|
||||
--situation <situation> ...` applies the already-inspected profile;
|
||||
`--through <files> --pace <interval>` remains the raw byte-walk path. Paced
|
||||
sends naming addressed reads serve pointer-walks.
|
||||
- The delta: a dated markdown file beside the seat's recap; verified by reading it.
|
||||
|
||||
@@ -6,8 +6,7 @@ This does not sign in to a provider or change any seat's permission policy.
|
||||
|
||||
The option applies only to seats whose resolved launch posture is `full_bypass`.
|
||||
This must be declared through `builtin:yolo`, a `full_bypass` flag policy, or an explicit `full_bypass` selection;
|
||||
ambient `OPENRIG_YOLO` alone without an attached policy is not covered. One exception: kernel Codex seats on the
|
||||
kernel's operational default always get the Codex notice overrides below, without this option.
|
||||
ambient `OPENRIG_YOLO` alone without an attached policy is not covered.
|
||||
|
||||
- Claude Code receives `--settings '{"skipDangerousModePermissionPrompt":true}'`, accepting its bypass-permissions warning.
|
||||
A seat with an explicitly selected native permission mode other than `bypassPermissions` doesn't get it.
|
||||
@@ -25,8 +24,7 @@ Turning it on for an existing rig works the same way: `rig down <rig-name>`, the
|
||||
|
||||
For an operator default on **new rigs**, use `rig config set launch.non_interruptive true`, or set
|
||||
`OPENRIG_LAUNCH_NON_INTERRUPTIVE` in the daemon's environment (it overrides the config file).
|
||||
The default is false; a rig spec's `non_interruptive` overrides it (see below), and an explicit positive or
|
||||
negative command-line flag overrides both. Existing rigs
|
||||
The default is false; an explicit positive or negative command-line flag overrides it. Existing rigs
|
||||
keep their saved choice when the operator default changes. On a remote install the receiving daemon's
|
||||
default applies.
|
||||
|
||||
@@ -36,28 +34,10 @@ and, for each affected seat, "Non-interruptive: OpenRig accepted Claude's bypass
|
||||
Codex's full-access and GPT-5.1 migration notices… no warning-acceptance settings were written."
|
||||
|
||||
A bundle's before-install view (`rig bundle inspect`) says when this option is available for its full-bypass
|
||||
Claude and Codex seats, and that Claude Code asks once to accept its warning otherwise. When the bundle's `rig.yaml`
|
||||
declares `non_interruptive: true`, it says instead that the bundle's launches are non-interruptive by default, and
|
||||
leaves out the asks-once note. See [bundle formats](bundle-formats.md).
|
||||
Claude and Codex seats, and that Claude Code asks once to accept its warning otherwise. See
|
||||
[bundle formats](bundle-formats.md).
|
||||
|
||||
This feature writes no warning-acceptance settings to Claude or Codex files. It uses the launch-flag
|
||||
surfaces checked in Claude Code 2.1.282 and Codex 0.153.4. Other notices introduced by later harness
|
||||
versions, sign-in, and harness preconditions can still require attention. Ordinary launches without
|
||||
an opt-in keep their existing behaviour.
|
||||
|
||||
## Bundle or rig default
|
||||
|
||||
A pod-aware `rig.yaml` may declare `non_interruptive: true` alongside its
|
||||
permission policy. This saves the choice on the installed rig without requiring
|
||||
a CLI flag. Explicit `--non-interruptive` or `--no-non-interruptive` wins over
|
||||
the spec; a declared boolean wins over the machine's `launch.non_interruptive`
|
||||
default. A declaration of `false` is distinct from omission. Exports include
|
||||
`non_interruptive: true` when enabled; disabled or unset choices omit the key
|
||||
because saved state does not distinguish their origin. Restores of the existing
|
||||
rig retain its saved choice.
|
||||
|
||||
The before-install view reports this declaration as
|
||||
`posture[].nonInterruptiveDefault` for full-bypass Claude/Codex seats, separately
|
||||
from `nonInterruptive: available`. It leaves `nativeEffect: unknown`: explicit
|
||||
launch choices, sign-in and unsupported harness notices still apply. This field
|
||||
does not broaden the rig's permission policy or add warning flags to Pi.
|
||||
@@ -1,9 +0,0 @@
|
||||
# HTTP operation correlation
|
||||
|
||||
`GET /api/operations/capabilities` advertises `operation-correlation.v1` and the supported kinds: `rig.create`, `rig.import`, and `member.add`. A client should check this marker before relying on correlation; an older daemon may ignore an unfamiliar request header.
|
||||
|
||||
For `POST /api/rigs`, `POST /api/rigs/import`, and `POST /api/rigs/:rigId/pods/:podNamespace/members`, send a UUID in `X-OpenRig-Operation-Id`. Keep the same daemon, route targets, original request text, and behavior-changing headers for a retry. IDs are case-normalized. An ID that isn't an RFC UUID receives HTTP 400 `Invalid X-OpenRig-Operation-Id` before the route does anything else. Once a request passes the route's own validation, a different request using the same ID receives HTTP 409 `operation_id_conflict`. Matching compares the exact request text, so a change in whitespace or key order is a different request, not an equivalent one; an exact replay receives HTTP 200 with `replayed: true` and current database state. A first request retains its usual status and response fields and adds `operation`.
|
||||
|
||||
The operation contains the rig and node IDs committed by that request. Its `current` field reads the database at response time, including whether recorded resources still exist and the latest recorded session for each node. It does not inspect tmux or prove a launch finished. A reservation with no IDs can mean that execution is still underway or that it failed before creating resources. Replaying an exact request that failed before creating resources returns HTTP 200 with `operation.rigId: null` and `operation.nodeIds: []`; inspect those fields to distinguish it from a replay that recorded resources. Replays never execute the mutation again, retry a launch, or recreate deleted resources. Use a new UUID only when deliberately starting a new execution.
|
||||
|
||||
This contract stores neither the original response nor a recovery verdict. An HTTP response can be lost after a database commit. External launch effects are outside the database transaction, so the contract is correlation rather than exactly-once execution of external effects.
|
||||
@@ -50,5 +50,4 @@ Scope research to the unknown that could change the plan; scope an adversarial
|
||||
pass to the failure modes the author may miss. Record the questions resolved and
|
||||
the resulting design changes so the owner can judge the value of the selected
|
||||
rung. Run planned research before build dispatch, while its answers can still
|
||||
shape the spec. Record the chosen rung in the slice's frontmatter as
|
||||
`approved-spec-dial:`; `rig view show execution` shows it as `planning_dial`.
|
||||
shape the spec.
|
||||
@@ -1,8 +1,8 @@
|
||||
# Product-journey SDLC components
|
||||
|
||||
This is a reusable menu for building the smallest complete user outcome. A
|
||||
mission or slice selects only the components its work needs and records them,
|
||||
with any explicit edges between them, in mission/slice YAML. This is **not a mode, pipeline, topology, rig
|
||||
mission or slice selects only the components its work needs and records their
|
||||
order in mission/slice YAML. This is **not a mode, pipeline, topology, rig
|
||||
shape, or mandatory gate set**. If no composition is present, use the light
|
||||
Part A flow in `sdlc-conventions.md`.
|
||||
|
||||
@@ -215,8 +215,7 @@ possible explanation.
|
||||
## Composition rules
|
||||
|
||||
1. `project.yaml` may declare project defaults; `mission.yaml` may select the
|
||||
catalog and override those defaults for the mission. Some file in that chain
|
||||
must name the catalog: there is no default catalog.
|
||||
catalog and override those defaults for the mission.
|
||||
2. `slice.yaml` selects or overrides the components for that slice.
|
||||
3. Edges are explicit data. Array order is presentation, not dependency.
|
||||
4. Select the fewest components that honestly fit the work.
|
||||
@@ -306,19 +305,15 @@ On a fresh start, restore, or new assignment:
|
||||
Do not choose a mission from an old onboarding packet or a folder's recency.
|
||||
3. Resolve SDLC selection in order: project defaults, mission defaults, then the
|
||||
active slice's explicit selection/override. A narrower explicit selection
|
||||
replaces the broader component list and its edges; it does not append every
|
||||
ancestor's gates. Follow an addressed wave map for its membership, review model and
|
||||
replaces the broader component list; it does not append every ancestor's
|
||||
gates. Follow an addressed wave map for its membership, review model and
|
||||
boundary; an explicit named-slice exception applies only to that slice.
|
||||
4. Read only the selected components and additional addressed context. Repository
|
||||
references resolve from the Git root of the repository that holds the YAML
|
||||
declaring the catalog, which may not be the code checkout; installed references from
|
||||
references resolve from the code repository root; installed references from
|
||||
`$OPENRIG_HOME/reference`; context-pack refs use `rig context get`. For a
|
||||
Markdown `#section` address, use `loading-addressable-markdown` rather than
|
||||
loading an entire unrelated manual. Expand the investigation when the task's
|
||||
evidence requires it: the address map is a starting point, not a search limit.
|
||||
For work running as a workflow instance, `rig workflow guidance <instance>`
|
||||
reads the effective selection, the selected catalog sections and the original
|
||||
intent; add `--component <id>` or `--full` to expand.
|
||||
5. State briefly the user outcome, current role, candidate, selected path and
|
||||
next completion boundary. No composition means the light Part A flow in
|
||||
`sdlc-conventions.md#a1-the-flow-in-one-pass`. Do not author a
|
||||
|
||||
@@ -31,9 +31,7 @@ measuring stick:
|
||||
3. **PRESENT DECISIONS DECISION-READY.** One at a time, lettered, recommendation
|
||||
first, records cited. The owner's ruling gates everything downstream —
|
||||
mechanically where possible (a blocked-on anchor), never by memory.
|
||||
4. **MINT SLICES AT PLAN TIME** with real one-paragraph intents
|
||||
(`rig scope slice create <mission> <slug> --intent "..."`; without `--intent`
|
||||
the SPEC.md intent defaults to the title).
|
||||
4. **MINT SLICES AT PLAN TIME** with real one-paragraph intents.
|
||||
5. **DEPOSIT THE DESIGN — the fidelity law.** Every design-bearing slice's SPEC.md
|
||||
carries the full design contract INLINE: the owner's words verbatim, the settled
|
||||
do-not-reopen decisions, the live evidence, the shape of done, the anti-goals. A
|
||||
|
||||
@@ -41,12 +41,8 @@ Reinstalling changes nothing. If the file's shape doesn't allow that (for
|
||||
example a flow-style list), if the id is already taken by another root, if the
|
||||
folder is registered under a different id, or if the rig is already listed
|
||||
under another project, install writes nothing to the catalog and prints what to
|
||||
change, and the folder isn't copied either. An existing folder at
|
||||
`<workspace.projects_root>/<id>/` is never overwritten: if its files differ from
|
||||
the bundle's, install keeps it and says so. Without a catalog, the one it writes
|
||||
keeps an entry for the workspace root beside the bundle's, under the id from the
|
||||
workspace's own `project.yaml` (`default` when it declares none); if that id is the
|
||||
bundle's project id, install reports a conflict and writes no catalog.
|
||||
change. Without a catalog, the one it writes keeps a `default` entry for the
|
||||
workspace root beside the bundle's.
|
||||
|
||||
## Project-world install
|
||||
|
||||
@@ -108,33 +104,10 @@ ownership receipt. A later seat start with no project-world input preserves it;
|
||||
an explicit install whose `install.skills` is empty clears it. This keeps
|
||||
"project not supplied" distinct from "project deliberately selects no skills."
|
||||
|
||||
Before refreshing a skill copy, don't take `rig skill audit` as the answer. The
|
||||
audit reports declared provenance, date freshness (its `stale` is a verified date
|
||||
past 90 days or one with no evidence source) and copy hashes. It doesn't say
|
||||
whether a copy is safe to refresh, and two copies with different hashes aren't
|
||||
evidence of a deliberate fork. For a managed copy in a working folder, the
|
||||
read-only check is `rig skill loadout --runtime <claude-code|codex> --cwd
|
||||
<target> --project-root <project> --json`, without `--apply`. It reports
|
||||
`current`; `stale`, still OpenRig's last projection, so `--apply` can refresh it;
|
||||
`conflicting`; `shadowed`; or `missing`. Read the detail of `conflicting` and
|
||||
`shadowed`: `conflicting` can mean the bytes differ or that the target couldn't
|
||||
be inspected, which leaves any difference unknown, and a confirmed difference
|
||||
doesn't prove a deliberate local edit. A seat's own skills, kept outside the
|
||||
project (0.7.1 and later), are listed with where they're stored by
|
||||
`rig skill loadout --seat <session|self> --json`; that read doesn't classify
|
||||
them. A global or untracked copy has no install
|
||||
record, so its origin stays unknown: ask the skill's owner, and don't move global
|
||||
skills into a project just to get one.
|
||||
|
||||
## Work-install project selection
|
||||
|
||||
`rig context work-install` picks one project from the catalog at
|
||||
`workspace.catalog_path` (default `workspace.yaml`), in the order below. Without a
|
||||
catalog, the workspace root itself is the project (`selectedBy: workspace`, or
|
||||
`explicit` with a matching `--project`), and `--project` must match its
|
||||
`project.yaml` id. Operating posture uses steps 3-5
|
||||
the same way when a task names no project (see
|
||||
[scoped operating posture](scoped-operating-posture.md)).
|
||||
`rig context work-install` picks one project from `workspace.yaml`, in this
|
||||
order:
|
||||
|
||||
1. `--project <id>`;
|
||||
2. the only declared project;
|
||||
@@ -156,9 +129,8 @@ projects:
|
||||
rigs: [openrig-dev]
|
||||
```
|
||||
|
||||
`rigs` is optional. A `rigs` value that isn't a list of rig names is ignored
|
||||
with a warning; the entry can still be chosen by `--project`, as the only entry
|
||||
or by working directory, but never counts as unclaimed in step 5. A rig listed under two projects, or two projects sharing the
|
||||
`rigs` is optional. An entry whose `rigs` isn't a list of rig names is ignored
|
||||
with a warning. A rig listed under two projects, or two projects sharing the
|
||||
deepest root, leave the choice to `--project`. Step 3 reads the seat's
|
||||
`OPENRIG_SESSION_NAME`, so a plain shell skips it. `--json` reports the step
|
||||
that chose the project as `position.selectedBy`.
|
||||
@@ -178,7 +150,7 @@ existing file-reader allowlist. Catalog membership does not grant file-read or
|
||||
execution permission. These views only read; they do not select a lifecycle
|
||||
operation or activate a mission. Execution and slice queue membership require
|
||||
an exact `project:<id>` tag; lifecycle instances use their authored project
|
||||
identity. Unscoped historical tasks and global review artifacts without
|
||||
identity. Unscoped historical queue rows and global review artifacts without
|
||||
project binding are excluded from project-specific claims.
|
||||
|
||||
The read API adds `GET /api/scopes/projects` and optional `project` and
|
||||
@@ -186,12 +158,6 @@ The read API adds `GET /api/scopes/projects` and optional `project` and
|
||||
detail also requires the selected mission directory. Existing reads without a
|
||||
project parameter keep their legacy contract.
|
||||
|
||||
`GET /api/scopes?counts=1` is the light list: each mission's slices with only
|
||||
their `dirName`, `id`, `displayName`, `status`, `stage` and `locks` (and
|
||||
`sourcePath` for a selected project), read from each slice's node file alone. It
|
||||
leaves out readiness and proof pairing, which are most of the work and bytes of
|
||||
the default list. `detail=1` takes precedence when both are given.
|
||||
|
||||
## UI Mapping
|
||||
|
||||
- `workspace.root` maps to the Project workspace.
|
||||
@@ -212,23 +178,14 @@ ambiguity.
|
||||
|
||||
## Queue Mapping
|
||||
|
||||
A `slice:<id>` tag is the authoritative way to attach a queue item to a slice;
|
||||
with a project selected, typed rows also need the `project:<id>` tag. The tag
|
||||
value is either the slice's frontmatter `id` (a dot-ID such as `CUS.9775.1.1`)
|
||||
or its directory name (`01-custody-funds`); both resolve to the same slice on
|
||||
the Queue tab, the ownership lanes and the agents band. A row that carries both
|
||||
forms counts once. As a
|
||||
fallback, for slices with no typed rows, items attach when their body or tags
|
||||
mention one of:
|
||||
Queue items attach to a slice when their body or tags mention one of:
|
||||
|
||||
- the slice id;
|
||||
- the mission id;
|
||||
- the legacy `rail-item` value in slice frontmatter.
|
||||
|
||||
Once any slice in a mission has typed rows, the fallback stops matching on the
|
||||
mission id (and on a `rail-item` defaulted from it) for that mission's other
|
||||
slices too. For new work, tag rows with `slice:<id>` (and `project:<id>`), and
|
||||
include the mission and slice ids in the body as well. Example:
|
||||
For new work, include both mission and slice ids in the queue item body or
|
||||
tags. Example:
|
||||
|
||||
```text
|
||||
Mission: idea-ledger
|
||||
@@ -238,71 +195,6 @@ Slice: capture-product-ideas
|
||||
This makes Story, Queue, Tests, and Topology tabs line up with the filesystem
|
||||
slice without adding a separate project database schema.
|
||||
|
||||
### Workflow packets
|
||||
|
||||
Packets that `rig workflow` projects carry the scope of their instance. Pass the
|
||||
scope when the instance is created and every packet it creates (the entry, each
|
||||
hand-off and gate, exception items, and resume packets) is tagged, so they show
|
||||
on the slice's Queue tab:
|
||||
|
||||
```bash
|
||||
rig workflow instantiate ./spec.workflow.md \
|
||||
--root-objective "Build the capture flow" --created-by orch@my-rig \
|
||||
--project my-project --mission idea-ledger --slice capture-product-ideas \
|
||||
--tags ticket-7
|
||||
```
|
||||
|
||||
- `--project` should name a project in the workspace catalog. `--mission` and
|
||||
`--slice` take the same ids as the slice routes. `rig workflow run` takes the
|
||||
same flags. The CLI refuses what it can check itself (an id of the wrong shape,
|
||||
a reserved tag, a tag that contradicts a flag) as a usage error, before
|
||||
anything is sent. Only the daemon knows the catalog, so a mistyped `--project`
|
||||
is **not refused**: the daemon creates the instance unscoped, its packets carry
|
||||
no scope tags, and the CLI prints a warning on stderr (also with `--json`)
|
||||
that names the instance and says the scope was not applied. The CLI does not
|
||||
retry; instantiating again creates a second instance.
|
||||
- Packets carry `project:<id>`, `mission:<id>` and `slice:<id>` for the parts
|
||||
you set, then your `--tags`, after the tags the workflow system writes. Tags
|
||||
compose as in `rig queue create`: duplicates collapse, so `--slice S --tags
|
||||
slice:S` is one tag.
|
||||
- `--tags` is refused locally when it carries what the workflow runtime reads
|
||||
back to route packets: `workflow`, `handoff`, `gate`, `entry`, `resume`,
|
||||
`re-route`, `workflow-exception`, and the `workflow:`, `instance:`, `step:`,
|
||||
`exception:`, `occurrence:` and `recovery-for:` prefixes, a `project:`,
|
||||
`mission:` or `slice:` tag that contradicts its flag, or a second value of
|
||||
the same key.
|
||||
- `rig workflow instantiate-lifecycle` needs no flags: it takes the project and
|
||||
mission from the lifecycle identity it compiles. A compiled step's packets
|
||||
carry the `slice:<directory>` of the slice that step was compiled from, even
|
||||
when another slice's directory has the same name as its `metadata.id`. A step
|
||||
an authored graph names carries `slice:<directory>` when it names an active
|
||||
slice: by its exact directory name, else by a `metadata.id` that exactly one
|
||||
active slice claims (an id two slices claim maps to nothing, with a compile
|
||||
advisory). A step that names no slice, such as an authored closing step,
|
||||
carries only `project:` and `mission:`, so it appears on no slice's Queue tab.
|
||||
A project id or mission name the compiler reads from the manifests that cannot
|
||||
be a tag (a space, a `:`, a leading `.`, `_` or `-`, or too long) is left off
|
||||
the packets with a compile advisory; the lifecycle still instantiates. Slice
|
||||
metadata the lifecycle does not run is read only leniently, for step names, and
|
||||
never fails compile or instantiate.
|
||||
- Over HTTP, `POST /api/workflow/instantiate` reads the scope from a `scope`
|
||||
object (`{ project, mission, slice, tags }`). A scope that is valid and names
|
||||
a catalogued project is applied as above. A scope the route cannot apply (a
|
||||
project the catalog does not declare, a conflicting, reserved or malformed tag
|
||||
or id, or a `scope` that is not an object) is ignored: the route does what it
|
||||
did before the field existed and creates one unscoped instance, records
|
||||
nothing the scope named, and never lets a rejected tag reach a packet. The
|
||||
response `advisories` then carry a `Scope not applied (...)` note that names
|
||||
the instance (`scopeIgnored` repeats it); `rig workflow run` prints
|
||||
`advisories`. Bare `project`, `mission`, `slice` or `tags` fields in the body
|
||||
are ignored the same way, with a note. A failure unrelated to the scope still
|
||||
fails the request.
|
||||
- A Projects view scoped to a project lists a slice's packets only when they
|
||||
carry `project:<id>` as well as `slice:<id>`, so pass `--project` with
|
||||
`--slice`.
|
||||
- The scope is stored on the instance when it is created and does not change.
|
||||
Instances created without it behave as before.
|
||||
|
||||
## Compatibility
|
||||
|
||||
The default discovery root is `workspace.slices_root=<workspace.root>/missions`.
|
||||
|
||||
@@ -11,9 +11,7 @@ For every flag, see the [rig bundle reference](rig-bundle.md); for the file form
|
||||
## 1. Lay out the folder
|
||||
|
||||
A shareable bundle is one folder, kept on GitHub: in its own repository, or as a subfolder of one you already have.
|
||||
The folder holds the rig spec (`rig.yaml`), the agents it uses, and a README. Choose
|
||||
[names that describe the team, domains and roles](topology-naming.md) before wiring its references.
|
||||
The rules are the bundle standard
|
||||
The folder holds the rig spec (`rig.yaml`), the agents it uses, and a README. The rules are the bundle standard
|
||||
(`openrig.bundle-standard/v1`), summarized under "Advisory author check" in the
|
||||
[rig bundle reference](rig-bundle.md#advisory-author-check).
|
||||
|
||||
@@ -21,23 +19,7 @@ Two rules matter most for strangers:
|
||||
- **Keep everything inside the folder.** Every `agent_ref` should be `local:` and point inside it. A path that exists on
|
||||
your machine won't exist on anyone else's.
|
||||
- **Never put credentials in it.** No tokens, keys or `.env` files. `rig bundle create` refuses well-known sensitive
|
||||
file names (such as `.env`, `.pem` and `.key`) anyway. It also refuses contained `.claude/.credentials.json`,
|
||||
`.codex/auth.json` and `.pi/agent/auth.json`, including nested copies in agents or a carried project. Remove them
|
||||
and rebuild. Only if recipients should have these logins (for example, your own internal test bundle) and their
|
||||
owner agrees, `rig bundle create --include-login-files` records the exact included login-file paths in the
|
||||
manifest and consumers show a notice; anyone with the bundle could read those files.
|
||||
Unrecorded login files and other sensitive paths still fail. See [harness login files](rig-bundle.md#harness-login-files).
|
||||
|
||||
To start from a running team, use `rig export <team> -o ./my-team/rig.yaml` after creating `my-team`.
|
||||
Export keeps the rig's name, including an old `starter` name; choose a descriptive `name` in `rig.yaml`
|
||||
before sharing. `rig bundle create --name` names the archive, not the installed rig.
|
||||
For a local daemon, export copies the declared culture file from its recorded rig root and keeps any
|
||||
existing destination file. Check that file before sharing. A missing, inaccessible or remote source is
|
||||
reported for manual copying. If the daemon is reached through a localhost tunnel, copy the culture from
|
||||
that host and check it yourself. Agent refs outside the folder are reported as nonportable: copy those agents and their
|
||||
imports into the folder and use `local:` refs, or let `rig bundle create --rig-root <original-root>` vendor
|
||||
agents into an archive. To include an existing README, declare `docs: [{ path: README.md }]` in `rig.yaml`;
|
||||
export does not invent a README or its contents. Check the folder after these edits.
|
||||
file names (such as `.env`, `.pem` and `.key`) anyway.
|
||||
|
||||
Two optional files sit beside `rig.yaml`:
|
||||
- **`bundle.yaml`** declares what people need before installing: setup steps (`preconditions`, shown before install
|
||||
@@ -53,9 +35,9 @@ Two optional files sit beside `rig.yaml`:
|
||||
rig bundle check ./my-team # checks the folder against the standard; launches nothing
|
||||
```
|
||||
|
||||
Fix what it reports, or say in your README why a finding doesn't apply. Any finding exits 1, and the output names the
|
||||
file a finding is about when there is one. It checks the folder on disk, including files you haven't committed, so
|
||||
check again at the commit you share. README completeness and embedded secrets always read `not_checked`: those are yours to review.
|
||||
Fix what it reports, or say in your README why a finding doesn't apply. Any finding exits 1, and `--json` names the file
|
||||
each finding is about. It checks the folder on disk, including files you haven't committed, so check again at the
|
||||
commit you share. README completeness and embedded secrets always read `not_checked`: those are yours to review.
|
||||
|
||||
You can also build and look inside the archive:
|
||||
|
||||
@@ -95,21 +77,18 @@ ask.
|
||||
|
||||
Links need `git`, a running local OpenRig daemon, and a public GitHub link without credentials; they don't work with
|
||||
`--host`. If the team uses `permission_policy: builtin:yolo` (no permission prompts), `--non-interruptive` lets OpenRig accept the harnesses'
|
||||
first-launch warnings for you (see [non-interruptive mode](non-interruptive-mode.md)). As the author, you can make that
|
||||
the install default by declaring `non_interruptive: true` in `rig.yaml`; `--no-non-interruptive` overrides it.
|
||||
first-launch warnings for you (see [non-interruptive mode](non-interruptive-mode.md)).
|
||||
|
||||
Installing writes the bundle's files into the install target (`--target`, the current directory if you leave it
|
||||
out) and launches the team from there, with the seats working in `--cwd`. If the target already
|
||||
has a different file at the same path, install refuses and writes nothing, so use an empty or dedicated directory.
|
||||
Installing again over a stopped team of the same name replaces it, and in its own install folder the changed files are
|
||||
backed up first under `~/.openrig/bundle-backups/`. A running team of the same name is refused, so stop it with
|
||||
`rig down` first. The reference's "Install a bundle" section has the details.
|
||||
has a different file at the same path, install refuses and writes nothing, so use an empty or dedicated directory. The
|
||||
reference's "Install a bundle" section has the details.
|
||||
|
||||
## 5. Choose your harnesses (when a bundle offers configurations)
|
||||
|
||||
```sh
|
||||
rig up <link> --preset all-claude
|
||||
rig up <link> --seat orch.lead=pi --seat dev.qa=codex
|
||||
rig up <link> --seat build.lead=pi --seat check.qa=codex
|
||||
```
|
||||
|
||||
On openrig.dev/rigs, pick a configuration and the page gives you one command to paste, which fetches exactly that
|
||||
@@ -120,24 +99,13 @@ or **"Not tested by OpenRig"**, which means exactly that. You're welcome to run
|
||||
|
||||
## 6. Submit it to openrig.dev/rigs
|
||||
|
||||
Before you submit, run `rig bundle check` on the folder at the commit you'll submit. openrig-registry's registry check
|
||||
runs the same check, with the latest published OpenRig, on the folder at your `ref`, and any finding fails it. A team
|
||||
made with `rig export` has no README of its own: add one and declare it in `rig.yaml` as `docs: [{ path: README.md }]`
|
||||
(see [section 1](#1-lay-out-the-folder)).
|
||||
|
||||
Open a pull request to [mvschwarz/openrig-registry](https://github.com/mvschwarz/openrig-registry) that adds one file,
|
||||
Open a pull request to [mvschwarz/openrig-world](https://github.com/mvschwarz/openrig-world) that adds one file,
|
||||
`registry/submissions/<your-team>.yaml`, with three fields: `repository` (your GitHub repository URL), `folder` (the
|
||||
folder holding `rig.yaml`, or `.` for the repository root) and `ref` (a branch, tag or commit). No pull requests? Open
|
||||
an issue there with the same three things. A maintainer then writes the full entry, in the `registry-entry.v1` format
|
||||
defined in the [bundle formats reference](bundle-formats.md), with the parts only a review can produce, such as the
|
||||
pinned commit and each configuration's package digest.
|
||||
|
||||
Rig names are unique on the site. If `registry/<your-team>.yaml` already exists, openrig-registry's registry check
|
||||
still replies that your submission was received, and says the name is taken; choose a distinct one, for example
|
||||
`<taken-name>-<your-name>`. A team whose `rig.yaml` name matches a listed team's, such as an unchanged copy of one,
|
||||
passes the checks with a notice for the maintainer about the shared name. Whether it's listed is the maintainer's
|
||||
review decision, not the checks'.
|
||||
|
||||
What happens next:
|
||||
- a maintainer pins your link to an exact commit, runs the same check, and reads everything your bundle gives to an
|
||||
agent;
|
||||
|
||||
@@ -1,212 +0,0 @@
|
||||
# Getting started
|
||||
|
||||
OpenRig runs a team of coding agents (Claude Code, Codex and others) on your project, each in its own terminal. You
|
||||
talk to one agent, and it hands work to the others. The team keeps its tasks and messages between sessions.
|
||||
|
||||
Most people let their coding agent set it up. This page explains what happens either way, so nothing is a black
|
||||
box, and shows how to do each step by hand if you'd rather.
|
||||
|
||||
## The quick way: let your coding agent do it
|
||||
|
||||
In your project folder, add OpenRig's `rigs` skill to the agent you use:
|
||||
|
||||
```sh
|
||||
# Claude Code
|
||||
npx skills add https://github.com/mvschwarz/openrig/tree/<release-tag>/skills/rigs --skill rigs --agent claude-code
|
||||
# Codex
|
||||
npx skills add https://github.com/mvschwarz/openrig/tree/<release-tag>/skills/rigs --skill rigs --agent codex
|
||||
```
|
||||
|
||||
For a new install, use the latest release's tag, for example `v0.7.4`. If OpenRig is already installed, use the tag
|
||||
that matches `rig --version`, or upgrade first. If the command fails with `npx: command not found`, Node.js isn't
|
||||
installed or isn't on your PATH yet (see [What you need](#what-you-need)). Then type `/rigs` in Claude Code, or `$rigs` in Codex, and say what
|
||||
you want built.
|
||||
|
||||
The skill has your agent work through the steps below in order. It says what it will run and change before it runs
|
||||
it, and it asks before installing anything on your system. It finishes when you're talking to the operator.
|
||||
|
||||
## How the pieces fit
|
||||
|
||||
- **`rig`** is the command you and your agents use. It comes from the npm package `@openrig/cli`.
|
||||
- **The daemon** is a small background service on your machine. It keeps tasks, messages and state in a local
|
||||
database. `rig daemon start` starts it.
|
||||
- **tmux** runs each agent in its own terminal session. Agents keep running when you close a window, and one agent
|
||||
can type into another's terminal.
|
||||
- **The kernel** is OpenRig's own small team, which starts with the daemon. You talk to its **operator**, which
|
||||
starts and runs teams for you. Its **advisor** helps you think through what you want.
|
||||
- **Your team** (a *rig*) is the set of agents that work on your project, such as `starter`.
|
||||
- **The OpenRig view** is a terminal window with the operator and, beside it or on another page, a dashboard of your
|
||||
agents.
|
||||
|
||||
## What you need
|
||||
|
||||
- macOS or Linux. On Windows, use WSL2 ([one person's working setup](getting-started.md#wsl2-a-reported-working-setup)).
|
||||
- Node.js 22 or 24 (on Apple silicon, Node.js 22) and tmux.
|
||||
- Claude Code or Codex, signed in. One is enough to start.
|
||||
|
||||
If `node --version` does not show a supported version, first check your existing Node installation and PATH.
|
||||
Ask your coding agent to help use the toolchain already on your machine. On a Mac, a shared Homebrew installation
|
||||
may belong to another user; do not change its ownership to complete this setup. After correcting PATH or installing
|
||||
Node, open a new terminal and check `node --version` and `npx --version` before continuing.
|
||||
|
||||
On a Mac where you aren't an administrator, or where another account owns Homebrew, install Node.js in your own home
|
||||
folder with [nvm](https://github.com/nvm-sh/nvm); nvm itself needs no administrator password. A new Mac account has no
|
||||
`~/.zshrc`, and nvm's installer only adds itself to a profile file that already exists, so create one first:
|
||||
|
||||
```sh
|
||||
touch ~/.zshrc
|
||||
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash
|
||||
```
|
||||
|
||||
Then open a new terminal and run `nvm install 22`. If nvm's installer says you need Apple's command line tools, run
|
||||
`xcode-select --install`, then its install command again. That's nvm v0.40.8's install command; [nvm's
|
||||
page](https://github.com/nvm-sh/nvm#install--update-script) has the newest.
|
||||
|
||||
## What happens, step by step
|
||||
|
||||
Each step shows the command, so you can run it yourself.
|
||||
|
||||
### 1. Install the `rig` command
|
||||
|
||||
```sh
|
||||
npm install -g @openrig/cli
|
||||
rig --version
|
||||
```
|
||||
|
||||
This installs the CLI globally under your npm prefix. `rig --version` prints the version and a commit, such as
|
||||
`0.6.12 (9e5382dd)`. With npm 11 or later, an `npm warn install-scripts` line is expected: it means only the
|
||||
Node.js and SQLite check was skipped.
|
||||
|
||||
### 2. Set up the tools around it
|
||||
|
||||
```sh
|
||||
rig setup --providers claude
|
||||
```
|
||||
|
||||
Use `codex` or `both` in place of `claude` to match the coding agents you use. Add `--dry-run` first to see the plan without changing anything. Setup does four things:
|
||||
- it checks Node.js, tmux and your sign-in;
|
||||
- it installs a missing tmux (with Homebrew on macOS, if you have it) or the coding agent you chose;
|
||||
- it installs Herdr, a terminal workspace app the OpenRig view can use, unless you add `--no-herdr`;
|
||||
- it adds an OpenRig block to `~/.tmux.conf` (mouse support and longer scrollback).
|
||||
|
||||
It doesn't start anything. It ends with a summary of what's done and what still needs you. A missing sign-in shows
|
||||
there: run `claude auth login` or `codex login`, then carry on.
|
||||
|
||||
### 3. Start OpenRig
|
||||
|
||||
```sh
|
||||
rig daemon start
|
||||
rig status
|
||||
rig ps --nodes --rig kernel
|
||||
```
|
||||
|
||||
The daemon starts and boots the kernel with the coding agents you're signed in to, or both if you're signed in to both.
|
||||
|
||||
**What starting OpenRig changes, for the coding agents you use** (paths are the usual defaults):
|
||||
- **For Codex:** hooks and trust in `~/.codex/config.toml`, when OpenRig or a Codex agent starts.
|
||||
- **For Claude Code:** workspace trust in `~/.claude.json`, and activity hooks in the project's
|
||||
`.claude/settings.local.json`, plus a status line unless you already have your own.
|
||||
- **For both:** small discovery skills in `~/.claude/skills` and `~/.agents/skills`.
|
||||
- **Kernel access:** by default the kernel gets broader permissions than a project team gets by default. On Codex
|
||||
that's full access with no approval prompts. On Claude Code, its file tools, web fetches and operational commands,
|
||||
including reads under your home folder, run without asking. A permission policy, per-agent choice or Codex profile
|
||||
changes that.
|
||||
|
||||
OpenRig doesn't guarantee it can preserve or roll back these files, so back them up first. [Everything OpenRig writes, and why](../../README.md#what-openrig-changes-on-your-machine).
|
||||
|
||||
Started isn't the same as ready. `rig status` shows a `Kernel:` line, and `rig ps --nodes --rig kernel` shows each
|
||||
kernel agent's state. They can take a moment after the daemon is up.
|
||||
|
||||
### 4. Open the OpenRig view
|
||||
|
||||
```sh
|
||||
rig terminal open saved:kernel --window
|
||||
```
|
||||
|
||||
**What you'll see:**
|
||||
- **Where it opens:** a new terminal window or tab. If your agent is already running inside Herdr, it opens a new
|
||||
Herdr space instead. It uses Herdr when installed, plain tmux otherwise.
|
||||
- **Layout:** in a narrow window, or when the width can't be measured, the operator fills the first page. From 120
|
||||
columns, the dashboard and the operator share it. The advisor has its own tab.
|
||||
- **On a Mac:** you may be asked to let your terminal app be controlled. Allowing it is fine.
|
||||
- **Over SSH or with no display:** the window can't open. The command says why and, where it can, prints a command
|
||||
to run in a new terminal. Otherwise your agent works out the exact command to join the operator.
|
||||
|
||||
You're installed when you're talking to the operator.
|
||||
|
||||
### 5. Start your first team
|
||||
|
||||
Tell the operator what you want built, and in which folder. It recommends one of three teams:
|
||||
- `starter`: a builder and a reviewer, for one bounded change;
|
||||
- `workshop`: a lead, a builder, QA and a reviewer, for ongoing work in one repository;
|
||||
- `factory`: seven agents, for sustained product work.
|
||||
|
||||
Before it starts one, it tells you what starting a team in your folder changes: managed guidance in `AGENTS.md` or
|
||||
`CLAUDE.md`, plus the team's skills. Then it waits for your yes. As shipped, `starter` uses both Claude Code and
|
||||
Codex. With only one of them, ask the operator to adapt it.
|
||||
|
||||
By hand, from your repository (the first command shows what it would start, and starts nothing):
|
||||
|
||||
```sh
|
||||
rig up starter --cwd . --plan
|
||||
rig up starter --cwd .
|
||||
rig ps --nodes --rig starter
|
||||
```
|
||||
|
||||
If an agent stops at a sign-in, trust or permission prompt, `rig up` reports `Status: partial` and names the prompt.
|
||||
Answer it in that agent's terminal, then run the `rig seat continue <seat>` command it prints. The team is ready
|
||||
for work once its agents show as ready in `rig ps --nodes --rig starter`.
|
||||
|
||||
### 6. Give the team work, and stop it
|
||||
|
||||
```sh
|
||||
rig send dev-build@starter 'Fix <one useful thing>. Ask dev-review to check it, and record the result and how I can try it.'
|
||||
rig queue list --destination dev-build@starter
|
||||
```
|
||||
|
||||
The builder records the work as a task, so you can follow it with `rig queue`. When you're done, `rig down starter`
|
||||
stops that team. `rig daemon stop` stops the background service and leaves agent sessions running.
|
||||
|
||||
## The one-command install
|
||||
|
||||
Instead of steps 1 and 2 (the first line shows the plan and changes nothing):
|
||||
|
||||
```sh
|
||||
curl -fsSL https://openrig.dev/install.sh | sh -s -- --dry-run
|
||||
curl -fsSL https://openrig.dev/install.sh | sh
|
||||
```
|
||||
|
||||
It checks Node.js and npm, installs the latest `@openrig/cli`, then runs `rig setup`. It doesn't know which coding agent
|
||||
you use, so it checks and may install both. For just one, use steps 1 and 2. If a sign-in is missing, setup reports
|
||||
it as the step to finish: sign in, then continue at step 3.
|
||||
|
||||
## What these words mean
|
||||
|
||||
- **Rig:** a team of agents, started with one command. Your first one is usually `starter`.
|
||||
- **Seat:** one agent's role and address in a team, such as `dev-build@starter`.
|
||||
- **Harness:** the software around the model that an agent runs in: Claude Code, Codex or Pi.
|
||||
- **Kernel:** OpenRig's own small team, which starts with OpenRig. It isn't your project's team.
|
||||
- **Operator:** the kernel's agent you talk to first. It recommends a team for your goal and starts it when you say
|
||||
yes.
|
||||
- **Advisor:** the kernel's agent for thinking through what you want before a team starts. It has its own tab.
|
||||
- **OpenRig view:** the terminal view that opens on the operator. In a wide window the dashboard sits beside it;
|
||||
otherwise, or when the width can't be measured, the dashboard is on its own page. `saved:kernel` in
|
||||
`rig terminal open saved:kernel` is the name of this saved view.
|
||||
|
||||
## Learn it in this order
|
||||
|
||||
1. **How OpenRig works:** [the world and its purpose](../../packages/daemon/assets/onboarding/01-world-and-purpose.md),
|
||||
the first page a new agent in a team gets. It's written to agents, and it's the shortest account of rigs, seats and
|
||||
queued work. Your install has the same page under `$(npm root -g)/@openrig/cli/daemon/assets/onboarding/`.
|
||||
2. **First use:** this page, and [what these words mean](#what-these-words-mean).
|
||||
3. **One command:** `rig <command> --help` is the exact answer for the version you have installed, and `rig --help`
|
||||
lists every command.
|
||||
4. **Every command and flag:** the [CLI reference](../as-built/cli-reference.md).
|
||||
It describes the source commit it names, so where it and your installed `--help` disagree, `--help` is right for
|
||||
your version.
|
||||
|
||||
## More
|
||||
|
||||
- **Every detail of setup:** troubleshooting, permissions, headless and SSH use, and what can stop the view from
|
||||
opening. See the [setup reference](getting-started.md).
|
||||
- **Stuck?** Run `rig context get help`, or read [Help](help.md).
|
||||
@@ -14,39 +14,7 @@ it is the mechanism that makes shipped chain files (see
|
||||
|---|---|---|---|
|
||||
| UserPromptSubmit | ✓ | ✓ | deliver due or on-demand context at a model-visible boundary |
|
||||
| Stop | ✓ | — | catch a long Claude turn crossing the growth threshold |
|
||||
| PostCompact | ✓ | ✓ | retain exact compaction due-state; deliver on the next actionable prompt |
|
||||
|
||||
**How the hooks reach a seat.** A Claude seat whose resolved plugin selection includes the shipped `openrig-core` plugin
|
||||
(for example `plugins: [shared:openrig-core]`, or the same plugin under another name) starts with `CLAUDE_CODE_PLUGIN_DIRS`
|
||||
set to the vendored plugin (`$OPENRIG_HOME/plugins/openrig-core`), so Claude loads `hooks/claude.json` with no setup step, on a
|
||||
fresh launch, a restore, a handover successor and a launch with a permission mode. A seat that didn't select the plugin is
|
||||
launched as before and doesn't load these hooks. The folder a spec's plugin selection projects into the seat's workspace is
|
||||
not what Claude loads. A list the seat declares itself in `CLAUDE_CODE_PLUGIN_DIRS` keeps working, with the vendored plugin
|
||||
added after it.
|
||||
Claude Code reads this variable from v2.1.280. OpenRig doesn't check the Claude version at launch: an older Claude ignores the
|
||||
variable, starts normally, and doesn't load these hooks. The behaviour was checked on Claude Code 2.1.296 and not on
|
||||
earlier versions.
|
||||
A Claude started from inside a seat (its shell or Bash tool) inherits the seat's environment and so loads the plugin as well.
|
||||
A seat that loads the plugin is also given `OPENRIG_SEAT_PROJECT_DIR`, its launch project, and the plugin's seat effects (the
|
||||
activity and session-identity posts, the compaction hooks, refocus, and the first-launch marker) run only when that Claude's
|
||||
`CLAUDE_PROJECT_DIR` names the same folder (compared by real path, so a trailing slash or symlink doesn't matter). A nested
|
||||
Claude in another project, or in a subfolder of the seat's project, therefore changes nothing for the seat, and a `cd` inside
|
||||
the seat's own session keeps working because `CLAUDE_PROJECT_DIR` is fixed when Claude starts. A nested Claude in the seat's
|
||||
own project folder is the same project and still acts as the seat, as before this change. Without either variable (a seat
|
||||
launched before this change, a manual run) the hooks do what they always did. The plugin's activity relay stays quiet next to
|
||||
the seat's own `settings.local.json` copy only when that entry is exactly OpenRig's and the script it names is the same
|
||||
script; an entry from an older install doesn't match, so both report until the seat's next launch refreshes it.
|
||||
OpenRig automatically installs its Codex plugin for seats that select it. On its first installation, the six exact shipped
|
||||
hook definitions and bundle content are trusted before launch, after checking the entire installed plugin against this daemon's shipped copy.
|
||||
On upgrade, OpenRig renews content approval only for a previously approved OpenRig-owned bundle with unchanged approved hook definitions.
|
||||
It keeps explicit disables, refusals, unknown config layers and other plugins' state. An installation without a proven prior approval stays under native review.
|
||||
Codex's "continue without trusting" leaves no record: a skip of an otherwise eligible OpenRig-owned update may therefore be superseded on retry.
|
||||
OpenRig records its approved bundle in `CODEX_HOME/.openrig-core-hook-trust.json` and leaves Codex's immutable `.hook-trust` baseline untouched.
|
||||
Codex 0.164 checks bundle contents when hooks run; a later edit requires native approval again. Older Codex versions enforce their own trust rules.
|
||||
The Codex
|
||||
column above then applies only to a Codex seat whose plugin selection includes openrig-core: every Codex hook command
|
||||
exits 0 before running anything unless OpenRig gave that seat `OPENRIG_SEAT_PROJECT_DIR` and an explicit
|
||||
`OPENRIG_NODE`.
|
||||
| PostCompact | ✓ | ✓ | retain exact compaction due-state; deliver on the next prompt |
|
||||
|
||||
Claude's additional firing signal is **transcript growth** — not turns (one turn
|
||||
can burn 200k tokens across fifty tool calls) and not wall-clock (the failure is
|
||||
@@ -57,38 +25,11 @@ redundant double-fire around Codex's own compaction cadence. Set
|
||||
`OPENRIG_REFOCUS_NOW=1` for an on-demand refocus and
|
||||
`OPENRIG_REFOCUS_ENABLED=0` to disable the feature. Fresh `SessionStart` is
|
||||
always a no-op: the default onboarding pack owns fresh orientation. Both
|
||||
runtimes retain `PostCompact` due-state for the next prompt. After a managed Claude
|
||||
compaction, the acknowledgement-only boundary and other prompts (for up to 10 minutes)
|
||||
are skipped without consuming that state, so the hook delivers on the restore request
|
||||
(after 10 minutes, on the next prompt);
|
||||
that request asks the seat to read the refocusing skill and consume the delivered
|
||||
traces rather than rerun them, and the read-depth audit accounts for them. Otherwise the hook
|
||||
is a no-op (it writes a stderr advisory when the transcript shrinks or the
|
||||
session has no identity), and it degrades to silence on unrelated hook errors.
|
||||
**Time budget.** By default each lookup (the trace, the content REF, `rig queue whoami`, `rig config`) gets 2 seconds,
|
||||
as before, and a slow one ends as a reported gap (`TRACE GAP`, `REFOCUS CONTENT REF FAILED`, or a role marked
|
||||
unknown). Set `OPENRIG_REFOCUS_BUDGET_MS` in a seat's environment to give a slow trace more time, up to 52000 (52 s).
|
||||
Each lookup's cap then grows in proportion (at 45000 the trace may take 20 seconds; at 52000, about 23), and every lookup
|
||||
is also cut to what is left of that budget, so the attempt delivers what it has and counts as failed. After a failed
|
||||
attempt, the issue report gets its own 1.5 seconds once the lookups are done. Both registrations allow `refocus.cjs` 60
|
||||
seconds, where they used to stop it at 5; the other OpenRig hooks keep theirs. So a default fire whose lookups together
|
||||
pass 5 seconds now completes instead of being stopped with nothing delivered, and a hook that hangs outside its lookups
|
||||
can hold a prompt for up to those 60 seconds.
|
||||
|
||||
A configured REF resolution failure degrades loudly in the delivered payload while still completing the hook — a
|
||||
refocus must never break a seat's turn.
|
||||
|
||||
**Overlapping events (unresolved).** Two hook runs for the same seat and occupant are not serialized. If they overlap,
|
||||
a `PostCompact` recorded while a prompt is delivering can be lost, and one refocus can be delivered twice. This is
|
||||
reproduced between hook processes; whether a harness overlaps these events for one session is not established, so it is
|
||||
an open gap, not one shown to be safe.
|
||||
|
||||
Failed trace or configured-content resolution keeps refocus due. After three
|
||||
consecutive failed attempts for the same seat and occupant, the hook emits one
|
||||
idempotent issue-stream item tagged `issue,refocus`, visible through `rig stream
|
||||
list --tag refocus`. A successful delivery resets that failure episode. An
|
||||
unconfirmed stream write keeps the same item ID for the next failed attempt; it
|
||||
does not send a wake, change seat status, or prove the agent read the content.
|
||||
runtimes retain `PostCompact` due-state for the next prompt. Otherwise the hook
|
||||
is a silent no-op, and it degrades to silence on unrelated hook errors. A
|
||||
configured REF resolution failure instead degrades
|
||||
loudly in the delivered payload while still completing the hook — a refocus
|
||||
must never break a seat's turn.
|
||||
|
||||
Because the hook runs at the seat's own turn boundaries, delivery to a
|
||||
RUNNING seat needs no relaunch, no operator action, and no message traffic:
|
||||
@@ -103,9 +44,8 @@ Resolution order:
|
||||
1. `OPENRIG_REFOCUS_CONTENT_REF` — a path-like context-library ref resolved
|
||||
through `rig context get`, so refocus receives the same assembled bytes as
|
||||
on-demand pull. This wins when REF and FILE are both set.
|
||||
2. `OPENRIG_REFOCUS_CONTENT_FILE` — an operator-authored file, set in the
|
||||
environment the seat's harness runs in (rig and agent specs have no `env`
|
||||
key).
|
||||
2. `OPENRIG_REFOCUS_CONTENT_FILE` — an operator-authored file (per-seat or
|
||||
per-rig via spec env).
|
||||
3. `$OPENRIG_HOME/refocus/REFOCUS.md` — the instance's standing content.
|
||||
4. The generic default at
|
||||
`skills/refocusing/references/refocus.md`: three project-neutral orientation
|
||||
@@ -133,60 +73,12 @@ reports broken links as gaps rather than following pointers.
|
||||
This automatic hook path is additive to one-shot manual injection through
|
||||
`rig send --context`; neither mode substitutes for the other.
|
||||
|
||||
## The work packet (off by default on every runtime, for now)
|
||||
|
||||
Set `OPENRIG_REFOCUS_WORK_PACKET=1` in a seat's harness environment so its
|
||||
refocus carries the work it is actually doing as text rather than as pointers.
|
||||
`=0` (or `off`, `false`, `no`) turns it off. Unset, each runtime's default
|
||||
applies. A runtime's default becomes on only after a native run shows the
|
||||
packet reaching the agent and leading to the right next action. No runtime has
|
||||
been shown that yet, so today both Claude Code and Codex default to off.
|
||||
With the switch on:
|
||||
|
||||
- The hook asks `rig queue whoami --work-candidates` for labelled evidence.
|
||||
That is each in-progress row's own `mission:` tag (a slice tag is optional),
|
||||
or for an untagged row the nearest local handoff ancestor's mission, plus
|
||||
blocked rows as held work and pending rows as possible next work. The
|
||||
strict `currentWork` derivation is unchanged.
|
||||
- One direct, resolved tag is shown as the work, labelled with its source so
|
||||
the agent can correct a stale tag. Anything less certain lists every
|
||||
candidate's one-line intent and asks the agent to name its mission (or to say
|
||||
it has no current work), giving the `--work-start` route that then shows
|
||||
that mission's intent as text. The project-level chain appears only as
|
||||
labelled orientation.
|
||||
- A tag that does not resolve on this host is named, never replaced. A
|
||||
retargeted handoff or a remote ancestor gives no assumed mission. A mission
|
||||
named only in body text is not evidence.
|
||||
- The seat's `LEARNED.md` contributes its `MY JOB HERE` and `STANDING DUTIES`
|
||||
sections, and notes and each node's `PROGRESS.md` contribute their
|
||||
`Current state` section. When a file has
|
||||
no such heading, the packet says so and shows a bounded excerpt. No heading
|
||||
is required.
|
||||
- A notes or `LEARNED.md` file older than
|
||||
`OPENRIG_REFOCUS_NOTES_MAX_AGE_DAYS` (default 14) is named with its age, the
|
||||
age's source (`updated:` frontmatter, else mtime) and the threshold: a cue
|
||||
for judgment, not a staleness verdict.
|
||||
- Each field is bounded on its own, with no total cap. A held or next row's
|
||||
summary and continuation are one line each (about 160 characters), with
|
||||
`rig queue show <id>` named when one was shortened. At most 20 held and 10
|
||||
next rows are shown, with how many there are and the `rig queue list` command
|
||||
for the rest. A matched section's body is cut at about 1,500 characters,
|
||||
pointing to `--depth full`.
|
||||
|
||||
`trace-to-root.py --packet --work-candidates <path|->` renders the same packet
|
||||
by hand.
|
||||
|
||||
## Relation to chain files
|
||||
|
||||
The chain files are the durable, altitude-addressed home of orientation
|
||||
content; the refocus channel is its delivery schedule. A practice added to a
|
||||
rig's `LEARNED.md` today reaches running seats through their next refocus
|
||||
trace, which reads `LEARNED.md` at each topology level. The default light trace
|
||||
shows only about the first 800 characters of each `LEARNED.md` body, so a
|
||||
practice appended to a longer file reaches seats only with
|
||||
`OPENRIG_REFOCUS_DEPTH=full` or through the configured refocus content. A `CRAFT.md` practice
|
||||
reaches them only through the configured refocus content (REF or FILE), and future
|
||||
installs through the shipped defaults
|
||||
rig's `CRAFT.md` today reaches running seats through their next refocus
|
||||
pointer, and future installs through the shipped defaults
|
||||
(discovery → curation → ship, per the convention doc).
|
||||
|
||||
## What a refocus is NOT
|
||||
|
||||
@@ -88,11 +88,7 @@ naming that exact delta AND a distinct successor delta file existing. A header a
|
||||
does not expire it; missing or unreadable inputs remain unknown/live. At the actual
|
||||
boundary, verify the event before recording expiry, then stop citing the expired
|
||||
delta. Do not create a successor merely to make the condition true. Candidate
|
||||
absorption is not proof of publication or served production adoption. The delta is
|
||||
`CAPABILITY-DELTA-v<version>.md` in the release mission folder (scaffolded by
|
||||
`rig scope mission create release-X.Y.Z`); its `expiry.canon_path` and
|
||||
`expiry.successor_path` name the two inputs, and `rig scope audit --mission <name>`
|
||||
reports `expired_capability_delta` once both hold.
|
||||
absorption is not proof of publication or served production adoption.
|
||||
|
||||
Private project topology, host practice, and release ownership go to the versioned
|
||||
project world instead of leaking into the public package. The new release's delta
|
||||
@@ -111,8 +107,8 @@ obligations start at ITS cut.
|
||||
packaged result, repairs any missed absorption as explicit debt, absorbs private
|
||||
project truth, re-primes, and observes whether a clean world-installed agent
|
||||
reaches the capability from its situation without being told its name.
|
||||
- A missing route is a release finding. Repair the smallest existing seam or record
|
||||
the evidenced gap as scoped follow-up work in the project; do not create a second
|
||||
- A missing route is a release finding. Repair the smallest existing seam or deposit
|
||||
the evidenced gap into the derivable-context mission; do not create a second
|
||||
capability registry, search service, or world store at the boundary.
|
||||
|
||||
## 8. What deliberately does NOT happen at the boundary
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# RigBundle Reference
|
||||
|
||||
Version: 2 (pod-aware)
|
||||
Last validated against code: 2026-10-07, at the 0.6.6 cut `2620dea8` (whole document at `a350c59b`; changes to its sources since then checked)
|
||||
Source of truth: `packages/daemon/src/domain/bundle-types.ts`, `packages/daemon/src/domain/bundle-archive.ts`, `packages/daemon/src/domain/pod-bundle-assembler.ts`, `packages/daemon/src/routes/bundles.ts`, `packages/cli/src/commands/bundle.ts`, `packages/daemon/src/domain/bundle-install-context.ts`, `packages/daemon/src/domain/bundle-source-resolver.ts`, `packages/daemon/src/domain/bootstrap-orchestrator.ts`
|
||||
Last validated against code: 2026-10-05, whole document, at main `a350c59b`
|
||||
Source of truth: `packages/daemon/src/domain/bundle-types.ts`, `packages/daemon/src/domain/bundle-archive.ts`, `packages/daemon/src/domain/pod-bundle-assembler.ts`, `packages/daemon/src/routes/bundles.ts`, `packages/cli/src/commands/bundle.ts`
|
||||
|
||||
A `.rigbundle` is a self-contained distributable archive that packages a rig spec, all referenced agent specs, their resources (skills, guidance, startup files), culture file, documentation, and an integrity manifest into a single file. The recipient can install and launch the rig without needing the original source tree.
|
||||
|
||||
@@ -20,8 +20,8 @@ Replace `COMMIT` with a full commit ID. Branches and tags are also accepted, inc
|
||||
resolve once to a full commit before fetching. Each result names the resolved source, configuration ID, package digest
|
||||
and assembler. Save the printed commit-pinned URL to repeat the same source selection. Only a full 40-character commit
|
||||
ID counts as a commit; a shorter one is looked up as a branch or tag name. `--preset` and repeatable
|
||||
`--seat pod.member=runtime` select only configurations the folder declares. A link build takes the rig's `name` from
|
||||
its `rig.yaml` unless `--name` says otherwise, and is named `github-bundle` when `rig.yaml` has no readable name.
|
||||
`--seat pod.member=runtime` select only configurations the folder declares. A link build is named `github-bundle`
|
||||
unless `--name` says otherwise.
|
||||
|
||||
Link import needs a running, verified local daemon and a credential-free, publicly readable GitHub URL. It does not
|
||||
upload files to remote daemons. For a remote target, run the link command on that host, or create an archive, transfer
|
||||
@@ -59,8 +59,7 @@ checks pod-aware rig validity, README inclusion in `docs`, readable declared fil
|
||||
minimum-version shape, declared preset consistency and known sensitive filenames. It does not contact a daemon,
|
||||
build an archive, run preflight or launch anything. Findings give exit status 1; they are never an install gate. It
|
||||
reads the folder on disk, not a link or a commit, so files that aren't committed are checked too. Human output gives
|
||||
each rule's status, ID and reason, then the file it's about in parentheses when there is one; `--json` carries the
|
||||
same as a `path` field.
|
||||
each rule's status, ID and reason; `--json` also names the files a finding is about.
|
||||
|
||||
README completeness and arbitrary embedded secrets need human review and are reported as `not_checked`. A bounded
|
||||
or unreadable scan is also `not_checked`, never a clean scan. The check is advice for authors, not a security audit or
|
||||
@@ -191,7 +190,6 @@ integrity:
|
||||
| `rig_spec` | string | yes | Relative path to the rig spec within the archive. Safe relative path. |
|
||||
| `agents` | AgentEntry[] | yes | Array of vendored agent entries. |
|
||||
| `culture_file` | string | no | Relative path to the culture file if present. |
|
||||
| `included_login_files` | string[] | no | Exact archive-relative harness login files deliberately included by the producer. Only these paths are exempt from the login-file refusal; this unsigned declaration is not authentication or receiver approval. |
|
||||
| `integrity` | Integrity | no | Per-file SHA-256 checksums for content verification. Validation doesn't require it, but install refuses an archive without it and inspect reports integrity FAIL. |
|
||||
| `provenance` | object | no | Stated, not verified: `created_at`, `daemon_version`, `cli_version`, `source_host`, `author_session`, `source_rig_id`, `source_rig_name`, `notes`, and `source` for a GitHub link build. |
|
||||
| `assembler` | object | no | `openrigVersion` of the OpenRig that built the archive. |
|
||||
@@ -222,28 +220,6 @@ integrity:
|
||||
| `original_ref` | string | yes | The original import ref before rewriting. |
|
||||
| `hash` | string | yes | SHA-256 hash of the imported agent.yaml. |
|
||||
|
||||
### Harness login files
|
||||
|
||||
By default, create refuses `.claude/.credentials.json`, `.codex/auth.json` and `.pi/agent/auth.json`
|
||||
at the root or nested anywhere in selected bundle content, including agents and an explicitly carried project.
|
||||
The author check reports them too. Messages name paths, never contents, and explain both remedies:
|
||||
remove the file from the agent folder or carried project and build again; or, only if recipients should have this
|
||||
login (for example, your own internal test bundle) and its owner agrees, recreate with
|
||||
`rig bundle create <spec> -o <archive.rigbundle> --include-login-files`.
|
||||
Anyone with that archive could read the included login files.
|
||||
|
||||
The flag applies to this create only. The generated `included_login_files` manifest list names only the actual,
|
||||
exact archive-relative login files included. Inspect, unpack, install and bootstrap honour those paths without
|
||||
another flag and show a credential-bearing notice. An additional unrecorded login file still fails, as do malformed
|
||||
records, directory or wildcard exemptions, and unrelated sensitive files. There is no machine setting or `--force`
|
||||
bypass. The unsigned record states the producer's choice; it does not authenticate the producer, establish trust,
|
||||
or constitute a fresh recipient approval. Review the source and files before using a bundle.
|
||||
|
||||
Compatibility change: previously accepted bundles containing these files now fail default creation and downstream
|
||||
verification/install unless deliberately rebuilt with the record. Inspection remains diagnostic: it reports failed
|
||||
integrity. Ordinary `auth.json` elsewhere and non-login harness files are unchanged. Filename checks do not scan
|
||||
arbitrary contents for secrets.
|
||||
|
||||
### Integrity Section
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
@@ -295,7 +271,7 @@ where the daemon runs.
|
||||
### Create a bundle
|
||||
|
||||
```bash
|
||||
rig bundle create <spec-path-or-github-link> -o <output.rigbundle> [--rig-root <dir>] [--preset <name>] [--seat <pod.member=runtime>]... [--context-pack <dir>]... [--project-dir <dir>] [--name <name>] [--bundle-version <ver>] [--min-cli-version <ver>] [--min-daemon-version <ver>] [--notes <text>] [--include-packages <refs...>] [--allow-drift] [--include-login-files] [--json]
|
||||
rig bundle create <spec-path-or-github-link> -o <output.rigbundle> [--rig-root <dir>] [--preset <name>] [--seat <pod.member=runtime>]... [--context-pack <dir>]... [--project-dir <dir>] [--name <name>] [--bundle-version <ver>] [--min-cli-version <ver>] [--min-daemon-version <ver>] [--notes <text>] [--include-packages <refs...>] [--allow-drift] [--json]
|
||||
```
|
||||
|
||||
| Flag | Required | Default | Description |
|
||||
@@ -307,12 +283,11 @@ rig bundle create <spec-path-or-github-link> -o <output.rigbundle> [--rig-root <
|
||||
| `--seat <pod.member=runtime>` | no | — | Use this runtime for one seat, within what `configurations.yaml` allows. Repeatable; applied after `--preset`. An undeclared choice is refused with the allowed set, and nothing is built. |
|
||||
| `--context-pack <dir>` | no | — | Carry the context pack in `<dir>`. Repeatable. The directory may be outside the rig folder, for example a world pack whose `manifest.yaml` is at its repository root. Only `manifest.yaml` and the files it declares are carried, the same set `rig context add --git` installs, and the pack lands in the bundle at `context-packs/<manifest name>/`. Needs a pod-aware spec. |
|
||||
| `--project-dir <dir>` | no | — | Carry the project the rig works in: the folder holding its `project.yaml` (which must declare an `id`) and files beside it, such as `SPEC.md`. On install the project is registered in the workspace catalog and the rig is associated with it, before any seat launches (see [project-workspace.md](project-workspace.md)). Needs a pod-aware spec. |
|
||||
| `--name` | no | the rig's `name` in `rig.yaml`; `my-bundle` (`github-bundle` for a link) when it has no readable name | Bundle name in the manifest. |
|
||||
| `--name` | no | `my-bundle` (`github-bundle` for a link) | Bundle name in the manifest. |
|
||||
| `--bundle-version` | no | `0.1.0` | Bundle version in the manifest. |
|
||||
| `--min-cli-version`, `--min-daemon-version` | no | — | The oldest OpenRig CLI or daemon that may install the bundle, checked on install. For a link they override the author's `bundle.yaml` minimums. |
|
||||
| `--notes <text>` | no | — | Notes stored in the manifest's provenance. |
|
||||
| `--include-packages <refs...>` | no | all from the spec | Legacy (schema 1) specs only: the package refs to include. |
|
||||
| `--include-login-files` | no | off | Only if recipients should have these logins and their owner agrees (for example, an internal test bundle), include them and record their exact archive-relative paths. Create and consumers show a credential-bearing notice. Does not exempt other sensitive files. |
|
||||
| `--allow-drift` | no | off | Build a spec that differs from the running rig of the same name. Without it, create refuses; with it, the difference is written into the manifest's provenance notes. |
|
||||
| `--json` | no | off | Machine-readable output. |
|
||||
|
||||
@@ -359,9 +334,7 @@ Under "Needs (not checked)" the view lists the author's setup preconditions, wit
|
||||
shell, in order". For a declared full-bypass Claude seat it notes that Claude Code asks once to accept its bypass
|
||||
warning, and when any Claude or Codex seat is full bypass it says that `--non-interruptive` is available (see
|
||||
[non-interruptive mode](non-interruptive-mode.md)). It doesn't select the mode or check whether you've already
|
||||
accepted the warning. When the bundle's `rig.yaml` declares `non_interruptive: true`, the view instead says that the
|
||||
bundle declares non-interruptive launches for those seats, with broad file, command and network access, and that
|
||||
`--no-non-interruptive` overrides it; the asks-once note is left out.
|
||||
accepted the warning.
|
||||
|
||||
`rig bundle install` and bundle-form `rig up` print this same view to stderr before the existing action, including
|
||||
`--plan`. With `--json`, stdout remains one result; its optional `behaviour` field carries the structured view.
|
||||
@@ -394,9 +367,9 @@ rig bundle install <bundle-path-or-github-link> [--plan] [--yes] [--target <root
|
||||
| `--target <root>` | yes in apply mode, for an archive path | the current directory for a link | Directory the bundle is installed into and launched from. Required for an archive path unless `--plan` is used. |
|
||||
| `--cwd <dir>` | no | — | Working directory for every launched member, for this install only (for example, the repository the rig works on). Does not change the install target. |
|
||||
| `--preset <name>`, `--seat <pod.member=runtime>` | no | — | For a GitHub link, the declared configuration to build and install. |
|
||||
| `--non-interruptive` | no | the bundle `rig.yaml`'s `non_interruptive`, else the operator setting `launch.non_interruptive`, else off | Accept the harnesses' first-launch warnings for this rig's full-bypass Claude and Codex seats with launch flags, writing nothing to your settings. The choice is saved on the rig. `--no-non-interruptive` turns a saved choice off; stop a running rig with `rig down` first. See [non-interruptive mode](non-interruptive-mode.md). |
|
||||
| `--non-interruptive` | no | off, or the operator setting `launch.non_interruptive` | Accept the harnesses' first-launch warnings for this rig's full-bypass Claude and Codex seats with launch flags, writing nothing to your settings. The choice is saved on the rig. `--no-non-interruptive` turns a saved choice off; stop a running rig with `rig down` first. See [non-interruptive mode](non-interruptive-mode.md). |
|
||||
| `--skip-version-check` | no | off | Skip the compatibility check below. Not for routine use. |
|
||||
| `--force` | no | off | Skip the running-team check below. Not for routine use. A pod-aware bundle is still refused before target files are written when a team with the same name is running; a legacy (schema 1) bundle can be left partly installed. |
|
||||
| `--force` | no | off | Skip the rig-name conflict check below. Not for routine use: a conflict can leave a partial install. |
|
||||
| `--json` | no | `false` | Emit machine-readable JSON. |
|
||||
|
||||
Install **launches the rig**; it does not just unpack it. It extracts the bundle to a temporary directory, validates integrity, and bootstraps the rig. In apply mode, the daemon requires `targetRoot`, so `rig bundle install` must be given `--target <root>` for an archive path unless you are running with `--plan`.
|
||||
@@ -404,32 +377,20 @@ Install **launches the rig**; it does not just unpack it. It extracts the bundle
|
||||
Before it plans or applies, install runs two checks on the archive, both also under `--plan`:
|
||||
- **compatibility:** the manifest's `min_daemon_version` and `min_cli_version` against this daemon and CLI. A failure
|
||||
reports "Bundle compatibility check failed" with the versions involved.
|
||||
- **running team:** a running team with the bundle's rig name refuses the install with "Bundle install conflict check
|
||||
failed". The error names the installed and the offered team and lists three choices: use the existing team, stop it
|
||||
with `rig down` and retry to replace it, or cancel. This check does not refuse a stopped team with that name.
|
||||
- **rig-name conflict:** the bundle's rig name against every rig this daemon knows, running or not. A match reports
|
||||
"Bundle install conflict check failed".
|
||||
|
||||
Each error lists its fixes; the compatibility error also names `--skip-version-check`. `--skip-version-check` and
|
||||
`--force` skip only these two checks: the manifest safety check of its `rig_spec` and `project` entries always runs.
|
||||
|
||||
For a pod-aware (schema version 2) bundle, installing a team whose rig name matches a stopped team replaces it: the
|
||||
earlier team is archived when the new one is created, and the result gives the `rig unarchive <id>` command that
|
||||
restores it. If OpenRig cannot confirm the earlier team is stopped, install refuses with `generation_unconfirmed` and
|
||||
creates no replacement team. For an install into that team's own install folder, OpenRig makes this check before
|
||||
writing any files; for any other target, bundle files already copied there stay.
|
||||
|
||||
A legacy (schema version 1) bundle does not replace a stopped team. Its approved external and package install steps run
|
||||
first, and then its rig-name check fails preflight with "Rig name '<name>' already exists".
|
||||
Each error lists its fixes, including the override flag.
|
||||
|
||||
For a pod-aware (schema version 2) bundle, apply copies every extracted file (`bundle.yaml`, `rig.yaml`, `agents/`, culture and docs files, and any carried `project/`, `context-packs/` and author-declared contents) into the target and launches from there, then removes the temporary extraction. So:
|
||||
|
||||
- the target becomes the rig root: `agent_ref` paths resolve inside it, and a member with `cwd: "."` starts in the target (every pod-aware member must declare a `cwd`);
|
||||
- an absolute member `cwd` stays as authored, and `--cwd <dir>` (on `rig bundle install` or `rig up`) still overrides every member's cwd;
|
||||
- if the target already has a file with **different** content at any bundle path (for example its own `rig.yaml`), install refuses with `target_conflict` and writes nothing. Identical target files don't cause a target-content conflict; the other installation checks above, including the running-team check, still apply. Use an empty or dedicated directory as the target.
|
||||
- exception: reinstalling over a stopped team into that team's own install folder (the target's `bundle.yaml` is schema version 2 with the same bundle name, or with `my-bundle` or `github-bundle`, the default names before 0.6.7) replaces its files there. Each differing path is first copied under `<OpenRig home>/bundle-backups/reinstall-*/files/`, with a `RESTORE.json` beside it; other files in the folder are kept. The files stay installed even if a later launch fails.
|
||||
- if the target already has a file with **different** content at any bundle path (for example its own `rig.yaml`), install refuses with `target_conflict` and writes nothing. Identical files are accepted, so reinstalling the same bundle into the same target works. Use an empty or dedicated directory as the target.
|
||||
|
||||
The bundle's declared skills, plugins, workflow specs, context packs and agent images are routed into your libraries **before any member launches**, and the context-pack library is rescanned, so a member's first turn can already read a pack the bundle carried. A routing failure does not stop the install: it is printed as a warning, returned in `routingFailures`, and recorded in the install audit. The human output lists what each declared kind routed and any entry that was not routed.
|
||||
|
||||
A carried pack is routed into `context.root` under its folder name in the archive: for a pack carried with `--context-pack`, that is its manifest name (`context-packs/<name>/`); for a pack the author's `bundle.yaml` declares, it is the basename of the declared folder, whatever the manifest says. If a pack of that name is already installed, install never merges into it: an identical pack is reported as `already_installed`, and a different one (for example a `rig context add --git` install at another revision) is kept unchanged and reported as `kept_existing`, with the `rig context rm <name>` command to use the bundle's copy instead.
|
||||
A carried pack is routed into `context.root` under its manifest name. If a pack of that name is already installed, install never merges into it: an identical pack is reported as `already_installed`, and a different one (for example a `rig context add --git` install at another revision) is kept unchanged and reported as `kept_existing`, with the `rig context rm <name>` command to use the bundle's copy instead.
|
||||
|
||||
A carried project is registered as `registered` (a new catalog entry), `associated` (the rig added to an existing entry), `already_registered` or `conflict`. A conflict writes nothing to the catalog and is reported as a routing failure; the install continues. A project folder that already exists with different files is kept unchanged.
|
||||
|
||||
@@ -476,20 +437,17 @@ rig up <bundle-path-or-github-link> [--target <root>] [--cwd <dir>] [--plan] [--
|
||||
take different routes:
|
||||
- **A GitHub link** builds the archive and installs it through the `rig bundle install` path, with its compatibility
|
||||
and rig-name checks and the install audit.
|
||||
- **A local `.rigbundle` path** goes through the bundle bootstrap path directly. It skips the compatibility check,
|
||||
isn't recorded in the install audit (so `rig bundle history` doesn't list it), and doesn't print the routing summary.
|
||||
For a pod-aware archive, a running team with the same name is still refused before target files are written, and a
|
||||
stopped one is replaced as described under "Install a bundle". A legacy (schema 1) archive runs its approved install
|
||||
steps before its rig-name check, which then refuses a running team and fails preflight for a stopped one; it also
|
||||
gets no post-install routing this way. To get the checks and the audit for a local archive, use `rig bundle install`
|
||||
or `rig bootstrap`.
|
||||
- **A local `.rigbundle` path** goes through the bundle bootstrap path directly. It skips the compatibility and
|
||||
rig-name checks, isn't recorded in the install audit (so `rig bundle history` doesn't list it), and doesn't print the
|
||||
routing summary. A legacy (schema 1) archive gets no post-install routing this way. To get the checks and the audit
|
||||
for a local archive, use `rig bundle install` or `rig bootstrap`.
|
||||
|
||||
`rig bootstrap <bundle-path>` also accepts archives and uses the ordinary bundle
|
||||
install path, including compatibility checks and the install audit. Use `--plan`
|
||||
to preview, or `--target <root>` to choose the persistent install directory. Its
|
||||
default target is the caller's current directory; `--cwd` only changes the agents'
|
||||
working directory. YAML files and library spec names keep the spec bootstrap path.
|
||||
It prints no behaviour view and has no `--non-interruptive` option; a bundle's declared `non_interruptive` still applies.
|
||||
It prints no behaviour view and has no `--non-interruptive` option.
|
||||
|
||||
- `--target <root>` is the install target described above (for a schema-version-2 bundle, the directory the bundle is copied into and launched from)
|
||||
- if `--target` is omitted for a `.rigbundle` or a link, the CLI defaults the install target to the current working directory, so the bundle's files are written there
|
||||
@@ -561,7 +519,7 @@ When an agent spec has `imports`, each import is resolved, vendored into the bun
|
||||
7. Each agent must have `name`, `path` (safe relative), and `hash`
|
||||
8. Optional blocks, when present, must be well formed: `provenance`, `compatibility`, `skills`, `plugins`,
|
||||
`workflow_specs`, `context_packs`, `agent_images`, and `project` (an `id` made of letters, digits, `.`, `_` and `-`,
|
||||
and a safe relative `path`), plus `included_login_files` (unique safe relative paths)
|
||||
and a safe relative `path`)
|
||||
|
||||
The manifest validator doesn't check `integrity`; unpack does (below).
|
||||
|
||||
@@ -651,6 +609,4 @@ Equivalent explicit form:
|
||||
rig up /path/to/my-team.rigbundle --target ~/projects/my-project
|
||||
```
|
||||
|
||||
The bundle is extracted to a temporary directory and its integrity is verified. A schema-version-2 bundle is then copied into the target root and the rig is launched from there, with all agents and resources from the bundle. If you also want agents to launch with a different working directory for that run, pass `--cwd <dir>` separately.
|
||||
|
||||
A running team must be stopped before reinstalling. Reinstalling into a stopped team's recorded install folder preserves conflicting files in the instance's `bundle-backups` directory; the result names the backup. The folder must still contain that bundle's installed manifest. A copied same-name manifest in another folder does not authorize replacing its conflicting files. Other targets retain first-install behavior: different files at the same paths are refused before writing. New installations record the canonical target folder for each generation, independently of `--cwd`. Older generations and new generations created directly from `rig.yaml` have no recorded folder and retain the manifest-only check until their next successful bundle installation, so a copied same-name manifest can still qualify for those generations.
|
||||
The bundle is extracted to a temporary directory and its integrity is verified. A schema-version-2 bundle is then copied into the target root (refused if the target holds different files at the same paths) and the rig is launched from there, with all agents and resources from the bundle. If you also want agents to launch with a different working directory for that run, pass `--cwd <dir>` separately.
|
||||
+45
-462
@@ -1,16 +1,13 @@
|
||||
# RigSpec Reference
|
||||
|
||||
Version: 0.2 (pod-aware)
|
||||
Last validated against code: 2026-10-07, at the 0.6.6 cut `2620dea8` (whole document at `fcaf1f8e`; changes to its sources since then checked)
|
||||
Source of truth: `packages/daemon/src/domain/rigspec-schema.ts`, `packages/daemon/src/domain/types.ts`, `packages/daemon/src/domain/startup-validation.ts`, `packages/daemon/src/domain/permission-policy/policy-ref.ts`, `packages/daemon/src/domain/profile-resolver.ts`, `packages/daemon/src/domain/rigspec-preflight.ts`, `packages/daemon/src/adapters/kernel-authority.ts`, `packages/daemon/src/domain/native-permission-store.ts`, `packages/daemon/src/domain/codex-team-workspace.ts`
|
||||
Last validated against code: 2026-04-11
|
||||
Source of truth: `packages/daemon/src/domain/rigspec-schema.ts`, `packages/daemon/src/domain/types.ts`
|
||||
|
||||
This is the canonical reference for the pod-aware RigSpec YAML format. Every field, validation rule, and default documented here was traced from the actual parser and validator code, not from prior documentation.
|
||||
|
||||
---
|
||||
|
||||
For choosing IDs, see [naming rigs, pods and seats](topology-naming.md). Keep the same
|
||||
logical names in edges, startup instructions, workflow targets and runtime presets.
|
||||
|
||||
## Minimal Valid Example
|
||||
|
||||
```yaml
|
||||
@@ -21,7 +18,7 @@ pods:
|
||||
- id: dev
|
||||
label: Development
|
||||
members:
|
||||
- id: build
|
||||
- id: impl
|
||||
agent_ref: "local:agents/impl"
|
||||
profile: default
|
||||
runtime: claude-code
|
||||
@@ -108,7 +105,7 @@ pods:
|
||||
required: true
|
||||
actions: []
|
||||
members:
|
||||
- id: build
|
||||
- id: impl
|
||||
agent_ref: "local:agents/impl"
|
||||
profile: default
|
||||
runtime: claude-code
|
||||
@@ -124,7 +121,7 @@ pods:
|
||||
applies_on: [fresh_start]
|
||||
actions:
|
||||
- type: send_text
|
||||
value: "Read your guidance and begin."
|
||||
value: "Load the implementation-pair skill and begin."
|
||||
phase: after_ready
|
||||
idempotent: true
|
||||
- id: qa
|
||||
@@ -134,7 +131,7 @@ pods:
|
||||
cwd: "."
|
||||
edges:
|
||||
- kind: delegates_to
|
||||
from: build
|
||||
from: impl
|
||||
to: qa
|
||||
|
||||
- id: rev
|
||||
@@ -155,13 +152,13 @@ pods:
|
||||
edges:
|
||||
- kind: delegates_to
|
||||
from: orch.lead
|
||||
to: dev.build
|
||||
to: dev.impl
|
||||
- kind: delegates_to
|
||||
from: orch.peer
|
||||
to: dev.qa
|
||||
- kind: can_observe
|
||||
from: rev.r1
|
||||
to: dev.build
|
||||
to: dev.impl
|
||||
- kind: can_observe
|
||||
from: rev.r2
|
||||
to: dev.qa
|
||||
@@ -173,40 +170,18 @@ edges:
|
||||
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `version` | string | yes | — | Use `"0.2"`. Any non-empty string validates; a spec is treated as pod-aware because `pods` is an array. |
|
||||
| `name` | string | yes | — | Rig name. Used in session naming (`{pod}-{member}@{name}`), snapshot identification, and spec library lookup. `rig up <spec> --name <rig>` launches the spec under another name instead (see below). |
|
||||
| `summary` | string | no | — | Human-readable description. Shown in the spec library, review surfaces and `rig specs preview` (in `rig specs show` only with `--json`). |
|
||||
| `version` | string | yes | — | Must be `"0.2"` for pod-aware specs. |
|
||||
| `name` | string | yes | — | Rig name. Used in session naming (`{pod}-{member}@{name}`), snapshot identification, and spec library lookup. |
|
||||
| `summary` | string | no | — | Human-readable description. Shown in spec library, review surfaces, and `rig specs show`. |
|
||||
| `culture_file` | string | no | — | Relative path to a rig-wide culture/constitution file. Must be a safe relative path (no `..`, no absolute). |
|
||||
| `non_interruptive` | boolean | no | — | Pod-aware rig launch-warning default. With full-bypass Claude/Codex seats, true accepts or hides supported harness warnings using launch flags. Explicit CLI choices override this field; this field overrides the machine default. It does not grant permissions, change native settings files, or bypass login. |
|
||||
| `permission_policy` | string | no | — | Permission policy attached to the rig. Either a built-in (`builtin:locked`, `builtin:standard`, `builtin:open`, `builtin:yolo`, `builtin:auto`) or a safe relative path to a custom policy file (resolved from this spec's directory; no `..`, no absolute, no empty segments, each segment `[A-Za-z0-9][A-Za-z0-9._-]*`), or `none`, a recorded choice of the floor. Absent uses the default floor with the scoped team launch allowances described below. A bare built-in name such as `yolo` is refused ("use 'builtin:yolo'"), and so is an explicit `null`. A custom file that is missing, unreadable or invalid isn't a validation error: it resolves to the floor, and preflight warns. A member may set its own `permission_policy` (not on a terminal member), which takes precedence over the rig-level one; there is no pod level. See "Attaching a permission policy" below. |
|
||||
| `env` | map | no | — | Launch environment for every seat in the rig: `NAME: value` pairs. A member's own `env` overrides it name by name. Names match `^[A-Z_][A-Z0-9_]*$`, names starting `OPENRIG_` are reserved, and values must be non-empty strings (quote numbers and booleans). Values are not secret. See "Launch environment" below. |
|
||||
| `managed_blocks` | map | no | `CLAUDE.md` | File that receives OpenRig's managed instruction blocks for Claude Code members. Only the `claude-code` key is accepted, with `CLAUDE.md` or `CLAUDE.local.md`. Codex, Pi and OMP members use `AGENTS.md`. See "Choosing the Claude instruction file" below. |
|
||||
| `workspace` | object | no | — | The rig's workspace: `workspace_root` (required), `repos[]` of `{name, path, kind}` with `kind` one of `user`, `project`, `knowledge`, `lab` or `delivery` and unique names, an optional `default_repo` naming one of them, and an optional `knowledge_root`. Relative repo paths resolve against `workspace_root`. |
|
||||
| `permission_policy` | string | no | — | Permission policy attached to the rig. Either a built-in (`builtin:locked`, `builtin:standard`, `builtin:open`, `builtin:yolo`, `builtin:auto`) or a safe relative path to a custom policy file (resolved from this spec's directory; no `..`, no absolute). Absent leaves the default floor. A member may set its own `permission_policy`, which takes precedence over the rig-level one. See "Attaching a permission policy" below. |
|
||||
| `managed_blocks` | map | no | `CLAUDE.md` | File that receives OpenRig's managed instruction blocks for Claude Code members. Only the `claude-code` key is accepted, with `CLAUDE.md` or `CLAUDE.local.md`. Codex members always use `AGENTS.md`. See "Choosing the Claude instruction file" below. |
|
||||
| `docs` | Doc[] | no | — | Documentation files that should travel with the rig. Included in rig bundles. Each entry has a `path` field (safe relative path). The engine does not consume these — they are for humans and agents setting up the environment before launch. |
|
||||
| `startup` | StartupBlock | no | — | Rig-level startup files and actions. Applied to all members via the startup layering model. |
|
||||
| `services` | ServicesBlock | no | — | Optional managed services (Docker Compose). When present, `rig up` boots them before any agent launches; `rig import` doesn't boot them. |
|
||||
| `services` | ServicesBlock | no | — | Optional managed services (Docker Compose). When present, services boot before any agent launches. |
|
||||
| `pods` | Pod[] | yes | — | At least one pod required. Each pod is a bounded context containing members and pod-local edges. |
|
||||
| `edges` | CrossPodEdge[] | no | `[]` | Cross-pod edges connecting members in different pods. Must use fully-qualified `pod.member` IDs. |
|
||||
|
||||
**Launching one spec under another name.** `rig up <spec> --name <rig>` creates the rig as `<rig>` instead of the spec's `name:`, so one spec can run as several rigs at once, for example `--name alpha` and `--name beta`, with seats `{pod}-{member}@alpha` and `{pod}-{member}@beta`. The spec file is not changed. The rig keeps the chosen name from then on: `rig ps`, `rig down alpha`, `rig up alpha --existing`, snapshots and restore all use it. The same checks as a launch without `--name` apply to the chosen name: a running rig of that name refuses the launch, and a stopped one is archived and replaced, as an explicit spec import does today. `--name` does not rename an existing rig, so the CLI refuses it with the name of an existing rig to restore, with a topology and with a GitHub bundle link. A library spec name works: `rig up starter --name beta` launches the library spec as `beta` even while a rig named `starter` exists. Over `--host`, pass the spec path or bundle file with `--name`. A spec that sets `services.project_name` refuses `--name`: every rig launched from it would share that Compose project, and `rig down` or a failed service boot of one would stop the others' services. Without `project_name`, each rig gets its own project. Two launches of the same spec started at the same moment can answer 409 (already in progress for this source) even under different names; start them one after the other.
|
||||
|
||||
### Starting one materialized seat
|
||||
|
||||
`rig import ./team.yaml --materialize-only` records the team without starting its harnesses.
|
||||
For a seat that has never started, use its positional logical ID:
|
||||
|
||||
```bash
|
||||
rig launch <rig-id> dev.lead --json
|
||||
```
|
||||
|
||||
This starts only that seat, preserving the rig's node IDs and the other seats. The daemon retains
|
||||
the materialized declaration and resolves its agent and startup files from the original source
|
||||
root at launch time; keep those files available. Current saved model, effort and permission
|
||||
choices take precedence over the retained declaration; launch reports the differences. A prior snapshot isn't required. Seats with
|
||||
session history continue through restore. Explicit `--snapshot-id` and `--seats` use restore too.
|
||||
`--plan` previews restore selection; it requires a snapshot and does not preflight this first start.
|
||||
Rigs materialized by older daemons lack the retained declaration; this path doesn't retrofit them.
|
||||
|
||||
### Attaching a permission policy
|
||||
|
||||
Attach a policy to a rig with `permission_policy`, either at the rig level or on a member:
|
||||
@@ -236,189 +211,6 @@ future managed launches of that stable seat; it does not rewrite this spec or
|
||||
its inherited policy provenance. `inherit` removes that override. See
|
||||
[per-seat permission mode](getting-started.md#per-seat-permission-mode).
|
||||
|
||||
### Per-member Claude tool rules
|
||||
|
||||
Claude members can record tool rules independently, even when they share a project folder:
|
||||
|
||||
```yaml
|
||||
claude_permissions:
|
||||
allow: ["Bash(node lane-reader.mjs *)"]
|
||||
deny: ["Read(./private/**)"]
|
||||
```
|
||||
|
||||
This field accepts only `allow` and `deny` lists of native Claude rule strings. It is
|
||||
also supported on legacy flat Claude nodes. Other runtimes, `ask`, mode settings,
|
||||
arbitrary settings and parenthesized MCP rules are rejected. Shape validation does
|
||||
not establish support by every Claude version.
|
||||
|
||||
The initial spec records the rules on the stable seat. For an existing seat, put the
|
||||
complete replacement in a JSON file and use the existing audited permission command:
|
||||
|
||||
```sh
|
||||
rig seat set-permissions dev-reader@team --rules member-rules.json --reason "Select the reader lane"
|
||||
rig seat status dev-reader@team --json
|
||||
```
|
||||
|
||||
Choose either `--rules` or `--mode`, never both. Empty allow and deny lists clear the
|
||||
seat's rules. Updating rules leaves the permission mode, running process and history
|
||||
unchanged; they apply at the next separately authorized managed launch or resume.
|
||||
Restore and same-seat handover read that same record. A fork copies the source's
|
||||
currently recorded rules independently, including retained-seat updates. Export
|
||||
contains the current record. An invalid or unreadable record refuses that seat's
|
||||
launch, fork or export with a repair message rather than silently omitting its denies.
|
||||
|
||||
OpenRig composes these rules into its one operational `--settings` value, preserving
|
||||
team/kernel defaults, hooks and managed-compaction settings. It never writes them
|
||||
into the shared project's Claude settings. Without the field or a recorded update,
|
||||
launch arguments are unchanged. Status reports the next-launch plan and lists the
|
||||
added rules; it does not verify native enforcement.
|
||||
|
||||
Rules add to inherited native permissions; an allow list cannot withdraw broader
|
||||
user or project grants. In bypass mode, allows do not constrain access. Managed
|
||||
policy and installed mods can change rule behavior; see [Claude's permission
|
||||
precedence](https://code.claude.com/docs/en/permissions#precedence-among-rules-hooks-and-mods).
|
||||
These are native tool rules, not OS-user or credential isolation. Native acceptance
|
||||
and effects must be checked on the Claude version and configuration being used.
|
||||
|
||||
**Downgrade:** a file-backed SQLite and launch-composition check against the
|
||||
pre-feature reader at `75c1f045` found that it can open the upgraded database but
|
||||
omits the recorded rules from launch arguments. This pair is not
|
||||
restriction-preserving. The stored bytes survive and the supporting reader recovers
|
||||
them; a process already launched by older code is unchanged. Keep a copy of the
|
||||
intended rules and establish equivalent native restrictions before using an older
|
||||
managed-launch path. Other version pairs and native enforcement need their own checks.
|
||||
The launch still uses inline JSON, subject to the operating system's argument-size
|
||||
limits.
|
||||
|
||||
### Per-member Codex permissions
|
||||
|
||||
Codex members can record their own sandbox and approval choice, even when they share a project folder:
|
||||
|
||||
```yaml
|
||||
codex_permissions:
|
||||
sandbox: workspace-write # workspace-write or read-only
|
||||
approval: never # never, on-request or untrusted
|
||||
network_access: false # workspace-write only
|
||||
writable_roots: ["/abs/lease"] # workspace-write only; absolute paths
|
||||
exclude_tmpdir_env_var: false # workspace-write only
|
||||
exclude_slash_tmp: false # workspace-write only
|
||||
```
|
||||
|
||||
OpenRig emits this envelope as explicit `-s`, `-a` and `sandbox_workspace_write.*` flags on
|
||||
every managed launch and resume of the seat (fresh, both resume paths, restore and same-seat
|
||||
handover), so a named `codex_config_profile` or a policy posture doesn't override those fields.
|
||||
Omitted workspace-write fields are recorded as `false` or `[]` and emitted as such. Full access
|
||||
is not an envelope: it stays the `full_bypass` mode. The envelope is the seat's explicit choice,
|
||||
so team and kernel launch defaults don't apply to it, and status names the policy posture or
|
||||
ambient `OPENRIG_YOLO` it replaces. With workspace-write, OpenRig still adds its queue-state root
|
||||
and, on a fresh launch, git metadata folders; with read-only it adds no writable roots. It adds
|
||||
no network setting of its own. Codex's implicit roots (the working directory and temporary
|
||||
folders) still apply: this is a native sandbox and approval selection, not a complete
|
||||
filesystem or credential-isolation guarantee. OpenRig's tests prove these launch flags, not
|
||||
that Codex enforces them, so check the seat's actual behaviour before relying on a narrower
|
||||
envelope. An OpenRig older than 0.7.3 doesn't read a recorded envelope, so after a downgrade
|
||||
the seat launches without it. The field is also supported on legacy flat Codex nodes; other
|
||||
runtimes reject it.
|
||||
|
||||
For an existing seat, put the envelope in a JSON file, or change its profile, with the existing
|
||||
audited permission command:
|
||||
|
||||
```sh
|
||||
rig seat set-permissions dev-impl@team --codex-permissions envelope.json --reason "Narrow the implementer"
|
||||
rig seat set-permissions dev-impl@team --codex-profile lease-impl --reason "Use the lease profile"
|
||||
rig seat status dev-impl@team --json
|
||||
```
|
||||
|
||||
Choose one of `--mode`, `--rules`, `--codex-permissions` or `--codex-profile` per call. A seat
|
||||
keeps one explicit permission choice: setting an envelope replaces a recorded mode, and setting
|
||||
a mode (including `inherit`) clears the envelope, in the same audited write that names both.
|
||||
A runtime switch keeps the envelope while the seat runs Claude Code and applies it again when
|
||||
`rig seat set-runtime` brings the seat back to Codex. A switch back to Codex with an explicit
|
||||
`--permission-mode` replaces the envelope when the switch commits, and the switch's plan and
|
||||
event name it. A switch that doesn't commit leaves it in place.
|
||||
A profile name is separate from the envelope and from approval: a resumed conversation keeps
|
||||
its saved approval unless an envelope sets one. `--codex-profile inherit` clears the profile.
|
||||
|
||||
The profile command checks the profile in the config home this seat's launches use: the seat's
|
||||
own `CODEX_HOME` when its `env:` declares one, else the daemon's explicit `CODEX_HOME`. There it
|
||||
reports an absent file (Codex loads it as an empty layer, so base config applies), records the
|
||||
file's hash so a later check can report a change, and refuses a profile that fails to load,
|
||||
keeping the previous one. When neither sets a `CODEX_HOME`, a seat's pane keeps its own, and the
|
||||
command reports the profile as unverified rather than checking a different home. Every launch
|
||||
still runs the native profile check.
|
||||
|
||||
Updates leave the running process and history unchanged; they apply at the next separately
|
||||
authorized managed launch or resume. Restore reads the seat's current record, so an older
|
||||
snapshot doesn't bring back a replaced profile. A fork copies the source's current profile and
|
||||
envelope independently. Export contains the current record. A new generation from `rig up
|
||||
<spec>` starts from the spec. An invalid or unreadable envelope refuses that seat's launch, fork
|
||||
or export with a repair message rather than launching broader. Without the field or a recorded
|
||||
update, launch arguments are unchanged.
|
||||
|
||||
**Downgrade:** an older OpenRig keeps the stored envelope but doesn't read it, so its launches
|
||||
of the seat use the earlier posture decision, which can be broader. This is not
|
||||
restriction-preserving. Keep a copy of the intended envelope and establish equivalent native
|
||||
restrictions before using an older managed-launch path. Native enforcement must be checked on
|
||||
the Codex version and configuration being used.
|
||||
|
||||
### Team launch defaults
|
||||
|
||||
A non-kernel Claude or Codex seat with no authored permission policy, explicit
|
||||
seat permission selection, or named Codex profile receives the team launch
|
||||
default. An explicit policy, including `none` or `builtin:locked`, keeps its
|
||||
existing meaning. The default is derived again for fresh launch, resume, fork
|
||||
and handover; it is not saved as a user choice. Kernel, Pi and terminal behavior
|
||||
is unchanged.
|
||||
|
||||
Claude keeps `acceptEdits` and receives inline session settings allowing ordinary
|
||||
`rig` commands, project reads and common project test commands (for example,
|
||||
`npm test`, `pnpm test`, `pytest`, `go test` and `cargo test`). Lifecycle commands
|
||||
such as `rig up`, `rig down`, `rig restore`, `rig bundle install` and seat stop or
|
||||
handover ask through a session `PreToolUse` hook. Their literal help forms, such
|
||||
as `rig down --help`, `rig bundle install -h` and `rig help down`, run without
|
||||
that lifecycle prompt. Native personal, project and managed deny/ask rules still
|
||||
apply; OpenRig does not remove or override them.
|
||||
|
||||
For allowances, the hook recognizes literal command words (including quoted or absolute paths),
|
||||
leading environment assignments that do not change executable lookup or startup,
|
||||
and `env`, `command` and `exec` wrappers without options other than `--`.
|
||||
Relative executable paths and assignments such as `PATH` or `NODE_OPTIONS` stay
|
||||
with native checks. The same existing team allowances apply after spelling
|
||||
normalization; project `node_modules/.bin/vitest` and `jest` paths match their
|
||||
existing `npx` allowances. It does not automatically allow pipelines, command
|
||||
substitutions, redirects, heredocs, shell functions or other unrecognized syntax.
|
||||
Lifecycle prefixes are checked at every word position, including after wrappers,
|
||||
control-flow words and CLI argument separators. A `--` separator before or after
|
||||
the subcommand ends option parsing, so a later `--help` is an operand and still
|
||||
asks. Ask detection also scans with comment text retained, so a `#` inside a
|
||||
substitution does not hide a later lifecycle command. Unquoted prose or comments
|
||||
containing a lifecycle command may also ask; ordinary trailing comments do not
|
||||
change allowance matching. Quoted messages and quoted heredoc bodies remain data.
|
||||
Arithmetic shifts are not treated as heredoc operators. These are command
|
||||
allowances, not containment: a project's test command can execute code. The
|
||||
hook and allowances are passed with `--settings` at launch, including resume
|
||||
and fork; nothing is written to personal or project permission files.
|
||||
|
||||
If the helper asset is missing at launch, OpenRig falls back to the native lifecycle
|
||||
ask rules; help can prompt in that fallback. A helper that disappears or times out
|
||||
after launch cannot supply a decision, leaving Claude's remaining native rules
|
||||
in effect. The hook is a convenience policy, not a containment boundary.
|
||||
|
||||
Codex keeps `workspace-write` with its existing approval policy and receives the
|
||||
configured OpenRig workspace root plus its pod's shared state directory as
|
||||
additional writable directories. The team workspace preparer creates missing
|
||||
directory ancestors and excludes the home directory and its ancestors from its
|
||||
prepared scopes. Unavailable optional directories are warned about and omitted
|
||||
from that list without blocking launch. When no prepared scopes remain, the
|
||||
runtime adapter retains its existing pod-state `--add-dir` fallback, which this
|
||||
step does not prepare. This does not modify Codex permission files or enable
|
||||
non-interruptive mode.
|
||||
|
||||
**Codex lifecycle commands do not gain a new approval rule.** With Codex's
|
||||
existing `on-request` policy, non-escalated sandboxed commands, including
|
||||
`rig up` and `rig down`, can run without asking. This default addresses writable
|
||||
workspace access; it does not promise a lifecycle confirmation prompt.
|
||||
|
||||
### Built-in permission policies
|
||||
|
||||
The five built-ins live in `packages/daemon/policies/builtin/`. Action names are the
|
||||
@@ -430,27 +222,20 @@ policies' own semantic classes.
|
||||
| `builtin:standard` | config | everything not listed, including `push_to_remote` (`default_posture: allow`) | `create_pr`, `publish_package`, `merge_or_release`, `force_push`, and the destructive class | nothing |
|
||||
| `builtin:open` | config | everything, including PRs, publishing, merges and force pushes (`default_posture: allow`) | the destructive class only | nothing |
|
||||
| `builtin:yolo` | flag (`launch_posture: full_bypass`) | everything; the runtime's permission prompts are bypassed at launch | nothing | nothing |
|
||||
| `builtin:auto` | flag (`launch_posture: auto`) | Claude runs with `--permission-mode auto`; Codex, Pi and OMP launch at the floor | Claude: decided by auto mode; others: as at the floor | Claude: decided by auto mode; others: as at the floor |
|
||||
| `builtin:auto` | flag (`launch_posture: auto`) | Claude runs with `--permission-mode auto`; Codex and Pi launch at the floor | Claude: decided by auto mode; Codex and Pi: as at the floor | Claude: decided by auto mode; Codex and Pi: as at the floor |
|
||||
|
||||
The destructive class is `delete_everything`, `drop_persistent_store` and
|
||||
`reset_or_discard_vcs`; `builtin:locked`'s list also names `delete_files` and `force_push`.
|
||||
`reset_or_discard_vcs`.
|
||||
|
||||
**At launch.** `builtin:yolo` selects Claude `--dangerously-skip-permissions`, Codex
|
||||
`-s danger-full-access -a never`, and Pi `--approve`. `builtin:auto` selects Claude
|
||||
`--permission-mode auto`, while Codex and Pi do not have an auto mode and launch at the floor.
|
||||
Every other seat launches at the floor (a non-kernel seat with no policy also gets the
|
||||
[team launch default](#team-launch-defaults) above):
|
||||
Every other seat launches at the floor:
|
||||
- Claude `--permission-mode acceptEdits`;
|
||||
- Codex `-s workspace-write`, or `-p <profile>` when the member sets
|
||||
`codex_config_profile`, in which case the profile governs its own sandbox;
|
||||
- Pi `--no-approve` by default.
|
||||
|
||||
Seats of the rig named `kernel` are the exception. With no member or rig policy, no
|
||||
per-seat choice and (for Codex) no named profile, Claude launches in `acceptEdits` with a
|
||||
per-launch `--settings` allow list for its file tools and operational commands, and Codex
|
||||
launches with `-s danger-full-access -a never`, plus per-launch `-c` overrides that hide its
|
||||
full-access and GPT-5.1 migration notices, whatever the rig's non-interruptive choice.
|
||||
|
||||
**Config-surface policies are recorded, not applied at launch.** The seat still starts at
|
||||
the floor. The `allow`, `ask` and `deny` rules take effect once they are translated into the
|
||||
runtime's native settings. The `applying-a-permission-policy` skill in `openrig-core` does
|
||||
@@ -471,69 +256,10 @@ OMP variant maps that trust to its approval mode: `yolo` under `--approve`, othe
|
||||
|
||||
**Claude Code's own checks.** The first time Claude Code starts an interactive session
|
||||
with permissions bypassed, it shows a warning dialog asking you to accept responsibility;
|
||||
declining exits. OpenRig reports such a seat as `attention_required` and holds its startup
|
||||
context for `rig seat continue`; `rig up --non-interruptive` or `rig bundle install
|
||||
--non-interruptive` accepts the warning with a launch flag instead (see
|
||||
[non-interruptive mode](non-interruptive-mode.md)). That choice is saved on the rig, not in
|
||||
`rig.yaml`. On Linux and macOS Claude Code refuses that mode when run as root or under `sudo`,
|
||||
declining exits. On Linux and macOS it refuses that mode when run as root or under `sudo`,
|
||||
except inside a recognized sandbox. See Claude Code's
|
||||
[Choose a permission mode](https://code.claude.com/docs/en/permission-modes#skip-all-checks-with-bypasspermissions-mode).
|
||||
|
||||
### Launch environment
|
||||
|
||||
`env:` sets environment variables for the seats of a rig, so a team can share a setting such as a feature flag, a region or a log level without every member hand-editing a shell profile. Declare it on the rig, on a member, or both:
|
||||
|
||||
```yaml
|
||||
env:
|
||||
LOG_LEVEL: info
|
||||
REGION: eu
|
||||
pods:
|
||||
- id: dev
|
||||
members:
|
||||
- id: impl
|
||||
runtime: claude-code
|
||||
env:
|
||||
LOG_LEVEL: debug # overrides the rig's value for this seat only
|
||||
```
|
||||
|
||||
- A seat gets the rig's `env` with its own `env` laid over it, name by name.
|
||||
- The same environment is applied on first launch, on `rig up <rig-name>` restore, and to the successor of a seat handover.
|
||||
- `rig up <spec> --env KEY=VALUE` (repeatable) adds or overrides a value for one launch, except `CLAUDE_CONFIG_DIR` and `CODEX_HOME`, which the CLI leaves out with a note (see "A seat's own account" below). A one-off value belongs to the terminal that launch creates: it stays in that terminal's environment for as long as the terminal lives, and OpenRig removes it from the tmux session's environment as soon as the terminal has started, so a terminal started later in that session does not get it. If OpenRig can't take it out, the seat keeps running and the launch warns, naming the variable and the tmux command to put it back or remove it. Until then, a terminal started later in that session would get it. A restore, a handover successor or any later launch starts from the spec's `env:` alone, so the value is not saved and does not carry forward. To keep a value, put it in `env:`. One exception to "does not carry forward", for a managed Claude seat (see below): a one-off name that the seat's spec does not declare stays on the session's list of names, `OPENRIG_SEAT_ENV_KEYS` (names only, no values), because the first launch and an in-place restart of the same terminal read that list. So if a later pane in that session gets a value for that name from the tmux server's own environment, its managed Claude launch can forward that value, where a launch without `--env` would leave it out. The first launch's one-off value itself is not passed on to that pane. This comes from reading the code and has not been measured. `--env` does not apply to `rig up <rig-name>` (a restore) or to a topology (several rigs from their own specs); the CLI refuses both. For a topology, put `env:` in each rig's spec.
|
||||
- **The runtime directory, on Linux.** When the daemon runs with an absolute `XDG_RUNTIME_DIR` (usually `/run/user/<uid>`), a seat gets the same `XDG_RUNTIME_DIR`, so a tool that keeps its socket there, such as an MCP server's daemon or `gpg-agent`, works inside the seat without per-tool setup. It comes with `DBUS_SESSION_BUS_ADDRESS=disabled:`, an address that D-Bus clients refuse. sd-bus, GDBus and libdbus look for your session bus at `$XDG_RUNTIME_DIR/bus`, or start one, only when that variable is unset, so a seat doesn't find your session bus (the keyring, notifications) on its own. This is a default, not isolation: `systemctl --user` reaches your service manager through its own socket in the runtime directory, as any tool there can.
|
||||
- A seat's own value wins. Set `DBUS_SESSION_BUS_ADDRESS` in `env:` to give a seat a bus. Set `XDG_RUNTIME_DIR` there to choose the directory yourself; the seat then gets no bus address, as before, so its D-Bus clients find the bus in that directory. A name listed in tmux's `update-environment` counts as the seat's own too.
|
||||
- A shell startup file that runs in the seat's terminal can still change either name. One that sets only `XDG_RUNTIME_DIR` now leaves the seat with `disabled:`, where before its clients found your bus; set the bus address in `env:` or in that file to keep it.
|
||||
- With `terminal.inherit_tmux_environment` on, a seat gets tmux's environment as before, and OpenRig adds neither name. On macOS, and for a daemon started without `XDG_RUNTIME_DIR`, nothing changes.
|
||||
- Codex passes only a fixed list of variables to the MCP servers it starts, so a Codex seat's MCP server gets the runtime directory only when its entry in `config.toml` names it: `env_vars = ["XDG_RUNTIME_DIR"]`. Codex's hooks and shell commands get it without that, and so do Claude Code's MCP servers and hooks. Pi and OMP agent processes don't get it (see below).
|
||||
- It applies at a seat's next launch, restore or handover; a seat that is up keeps the environment it started with.
|
||||
- Names starting `OPENRIG_` are reserved for OpenRig and refused. Empty values are refused, because the launch omits empty variables.
|
||||
- `rig export` writes the rig and member `env:` back out.
|
||||
|
||||
**Where the declared names reach, by runtime.** Declared values are handed to the seat's terminal as tmux environment, so most seats take them as given:
|
||||
|
||||
- Plain Claude Code (no permission mode selected), Codex and terminal seats take a spec `HOME`, `PATH` or `CLAUDE_CONFIG_DIR` as given.
|
||||
- The cleared environment (`env -i`) belongs only to a managed Claude launch, which is the one used when a permission mode is selected for the seat (for example `permission_policy: builtin:auto`). It forwards the declared names through the cleared environment, except `PATH`, `HOME` and `CLAUDE_CONFIG_DIR`, which OpenRig sets for that launch itself, and `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN`, for which it sets its own renderer setting. A spec value for any of those four is not forwarded as such; an absolute `CLAUDE_CONFIG_DIR` becomes the config dir OpenRig sets (see "A seat's own account" below). A seat that selected the shipped `openrig-core` plugin also has `CLAUDE_CODE_PLUGIN_DIRS` (the vendored plugin, added after a list the seat declares itself) among its declared names, so it is forwarded like the others and the plugin's hooks load in a seat with a permission mode as in one without; a seat that didn't select the plugin has no such name added. Beyond the declared names, the launch also forwards, by name and only when the seat's terminal has them set, the terminal and locale variables (`TERM`, `COLORTERM`, `TERM_PROGRAM`, `TERM_PROGRAM_VERSION`, `LANG` and the `LC_*` names) and the person's editor and display session: `EDITOR`, `VISUAL`, `DISPLAY`, `XAUTHORITY` and `WAYLAND_DISPLAY`. They let Claude's external-editor action open the person's editor and let image paste reach the clipboard, without a value in a spec. `WAYLAND_DISPLAY` is passed as an absolute path: an absolute value is kept, and a relative one is joined to the terminal's `XDG_RUNTIME_DIR`; if the terminal has no `XDG_RUNTIME_DIR` for it, the name is left out. The runtime directory and its `disabled:` bus address (see "The runtime directory, on Linux" above) are forwarded together, and the runtime directory is also forwarded beside a declared `DBUS_SESSION_BUS_ADDRESS`. A terminal's own `XDG_RUNTIME_DIR` or `DBUS_SESSION_BUS_ADDRESS`, from a shell startup file or tmux's `update-environment`, is not, because D-Bus clients look for the session bus at `$XDG_RUNTIME_DIR/bus` when no address is set; declare it in `env:` to forward it. `XDG_SESSION_TYPE` and `XDG_CURRENT_DESKTOP` are not forwarded. The SSH agent socket (`SSH_AUTH_SOCK`) is forwarded when OpenRig itself was started with one, so git over SSH works in the seat; a socket only the seat's terminal has stays out. To check, run `ssh-add -l` inside the seat. If it can't reach an SSH agent, start the OpenRig daemon from a terminal where `ssh-add -l` works. A running seat picks the names up at its next managed Claude launch, not before: `rig seat launch <seat> --fresh --stop --reason "<why>"` for that seat alone (a new conversation), or a restore of the whole rig (`rig down <rig>`, then `rig up <rig> --existing`, which resumes each conversation but restarts every seat in the rig), or a handover. A seat that is up keeps the environment it started with.
|
||||
- Codex seats run OpenRig's own Codex executable whatever a spec `PATH` says. They use the seat's own `CODEX_HOME` when its `env:` declares an absolute one, else the daemon's when the daemon has one.
|
||||
- On Pi and OMP seats the values reach the terminal. The agent process gets only what the runner passes on, so a spec or one-off value reaches it only for the names the runner always passes: `PATH`, `HOME`, `USER`, `LOGNAME`, `SSH_AUTH_SOCK`, `TERM`, `LANG`, `LC_ALL`, `SHELL` and `TMPDIR`. Pi's agent process receives the runner's `HOME`, so a spec or one-off `HOME` value that reaches the runner is passed to Pi; OMP's agent process gets its seat state directory (`$OPENRIG_HOME/state/omp/<seat>`, see Oh My Pi below) as `HOME`, so a `HOME` value does not reach it. The selected provider's variables are passed separately, as described under each runtime.
|
||||
|
||||
**A seat's own account.** Claude Code keeps its login in its config dir and Codex in its home, so a seat whose `env:`
|
||||
declares an absolute `CLAUDE_CONFIG_DIR` (Claude Code) or `CODEX_HOME` (Codex) runs on whatever login that directory
|
||||
holds. The member's value wins over the rig's. OpenRig follows it everywhere it launches or reads that runtime: the
|
||||
launch, Claude's first-run trust settings, Codex's managed `config.toml`, hooks and plugin, conversation capture for
|
||||
resume, context usage, `rig seat status` and `rig provider status`. A value that isn't an absolute path isn't used:
|
||||
the seat resolves as if it declared none, and `rig seat status` shows the ignored value. Name the home in `env:`: a
|
||||
one-off `rig up --env` value for either variable isn't applied, because a restore, a handover and `rig seat status` read
|
||||
only the stored `env:`. Seats may share a home. Live usage refresh (`rig provider status --refresh`) still reads only the
|
||||
daemon's own logins; reading each seat's home would need a native reader per home. OpenRig doesn't copy logins or conversation history between homes, so a conversation saved under a seat's earlier home
|
||||
doesn't resume after the seat moves to another one. The `openrig-user` skill has the setup steps.
|
||||
|
||||
**Do not put secrets in `env:` or `--env`.** The values are not secret, and nothing here encrypts or hides them (see #306):
|
||||
|
||||
- Spec values are stored in OpenRig's database and in rig snapshots, and `rig export` and bundles copy them, so a secret put there by mistake travels with the rig.
|
||||
- While a seat launches, the values are passed to tmux as command arguments, so other users and processes on the same machine can see them for that time. They then sit in the seat's process environment. Only the managed Claude launch command is value-free: it forwards names, and the terminal supplies the values.
|
||||
- A one-off `--env` value is not stored in the database or in snapshots, but it reaches tmux the same way, so it is visible in the same ways while that launch runs.
|
||||
|
||||
Use `env:` for settings only. Credentials belong in the provider's own login or a secret store the seat reads at run time.
|
||||
|
||||
### Choosing the Claude instruction file
|
||||
|
||||
OpenRig writes its instructions for Claude Code members into managed blocks in
|
||||
@@ -573,9 +299,9 @@ directory's `CLAUDE.md`, including blocks written by other rigs.
|
||||
| `id` | string | yes | — | Pod identifier. Must not contain dots or `@`. Must be unique within the rig. Used as the first segment of session names and logical IDs. |
|
||||
| `label` | string | yes | — | Human-readable pod name. Shown in UI explorer, graph groupings, and detail surfaces. |
|
||||
| `summary` | string | no | — | Pod description. |
|
||||
| `continuity_policy` | ContinuityPolicy | no | — | Pod-level continuity/restore policy, validated and stored with the pod (see "Continuity Policy"). |
|
||||
| `continuity_policy` | ContinuityPolicy | no | — | Pod-level continuity/restore policy. Controls compaction recovery, artifact management, and peer-driven restoration. |
|
||||
| `startup` | StartupBlock | no | — | Pod-level startup files and actions. Applied to all members in this pod via the startup layering model. |
|
||||
| `members` | Member[] | yes | — | The pod's members. It must be an array; validation doesn't refuse an empty one. |
|
||||
| `members` | Member[] | yes | — | At least one member required (enforced by pods needing content). |
|
||||
| `edges` | PodLocalEdge[] | no | `[]` | Edges between members within this pod. Must use unqualified member IDs (not `pod.member`). |
|
||||
|
||||
### Pod ID Rules
|
||||
@@ -596,66 +322,20 @@ directory's `CLAUDE.md`, including blocks written by other rigs.
|
||||
| `agent_ref` | string | yes | — | Reference to an AgentSpec. Must start with `local:` (relative) or `path:` (absolute). Exception: `builtin:terminal` for infrastructure nodes. |
|
||||
| `profile` | string | yes | — | Profile name from the referenced AgentSpec. Use `default` for the default profile. Exception: `none` for terminal nodes. |
|
||||
| `codex_config_profile` | string | no | — | Codex-only native profile passed as `-p <name>`; letters, numbers, `_`, `.`, `-`. Separate from the AgentSpec `profile`. With the normal launch mode, this replaces OpenRig's explicit workspace-write sandbox flag. A full-bypass policy instead emits danger-full-access and omits this profile argument. |
|
||||
| `codex_permissions` | mapping | no | — | Codex-only sandbox and approval envelope, emitted as explicit flags on every managed launch and resume; see [per-member Codex permissions](#per-member-codex-permissions). |
|
||||
| `runtime` | string | yes | — | Agent runtime. Current supported values: `claude-code`, `codex`, `pi`, `omp`, `terminal`, `stub`. `stub` is a deterministic test harness, not an agent: a Node runner in the seat's tmux pane goes through the normal launch, skill projection, startup-file and readiness path, follows `<cwd>/.openrig/stub/script.json` when present, and calls no model. See "What a stub can and cannot prove" in `docs/as-built/test-layers.md`. |
|
||||
| `cwd` | string | yes | — | Working directory for the agent. A relative path resolves against the rig root (the directory containing the rig spec). If that path exists as written, it is used. Otherwise a leading `~` or `~/` expands to the home directory (`~user` does not) and `$VAR` / `${VAR}` expand from the daemon host's environment; a relative result still resolves against the rig root. A reference to an unset variable stays as written, so the cwd is that literal path and works only if it exists. Use `"."` for the rig root itself. Can be overridden at launch time with `rig up --cwd`. A cwd inside the OpenRig installation fails preflight unless `--cwd` is given. Editing this declaration does not update an existing seat; use [`rig seat set-cwd`](agent-startup-guide.md#change-an-existing-seats-working-directory) to save its future launch directory. |
|
||||
| `cwd` | string | yes | — | Working directory for the agent. Resolved relative to the rig root (the directory containing the rig spec). Use `"."` for the rig root itself. Can be overridden at launch time with `rig up --cwd`. |
|
||||
| `label` | string | no | — | Human-readable member name. Shown in UI when present. |
|
||||
| `model` | string | no | — | Model override. Runtime-specific (e.g., `claude-opus-4-6` for Claude Code). |
|
||||
| `effort` | string | no | — | Reasoning effort override, trimmed. Claude gets `--effort`, Codex `-c model_reasoning_effort=…`, Pi `--thinking` (see "Pi" below). A non-string value is ignored with an advisory. |
|
||||
| `advisor` | string | no | — | Claude-only Advisor model for this seat. Overrides the AgentSpec profile/default; blank or non-string values are ignored with an advisory. |
|
||||
| `permission_policy` | string | no | — | Member-level permission policy; overrides the rig's. Not valid on terminal members. |
|
||||
| `env` | map | no | — | Launch environment for this seat, laid over the rig's `env`. Same rules as the rig-level field. Valid on terminal members too. See "Launch environment" below. |
|
||||
| `agent_file` | string | no | — | Claude members only. A Claude agent definition (a `.md` file with `name` in its frontmatter) for this seat. It's copied into the seat's own storage and launched as `--agent openrig:<name>`. A path beside the spec: no `..`, not absolute. |
|
||||
| `append_system_prompt_file` | string | no | — | Claude members only. A prompt file appended to Claude's system prompt for this seat. It's copied into the seat's own storage and passed as `--append-system-prompt-file`. A path beside the spec. |
|
||||
| `plugin_dirs` | list | no | — | Claude members only. Claude plugin folders for this seat, each copied into the seat's own storage and loaded through `CLAUDE_CODE_PLUGIN_DIRS`. Paths beside the spec. Each is copied under its folder name, so two folders with the same name are refused; an empty list is none. A missing file or folder fails that seat's launch by name. `rig bundle create` carries all three; `rig export` names a seat whose additions it doesn't carry. |
|
||||
| `role` | string | no | — | The seat's role, letters, digits, `_`, `.` and `-`. Not valid on terminal members. |
|
||||
| `restore_policy` | string | no | the AgentSpec's | Restore behavior. One of: `resume_if_possible`, `relaunch_fresh`, `checkpoint_only`. The default comes from the AgentSpec's `defaults.lifecycle` (else `resume_if_possible`) as narrowed by its profile; a member value may only narrow it further, in that order. |
|
||||
| `compaction_strategy` | string | no | — | `default-compaction`, `managed-compaction`, `handover` or `apprentice-handover`; `harness_native` and `pod_continuity` are accepted as deprecated aliases, and `custom_prompt` is refused. `managed-compaction` and `apprentice-handover` create their jobs only for `claude-code` seats; see [Codex compaction and sizing](agent-startup-guide.md#codex-compaction-and-sizing). |
|
||||
| `mechanic` | string | no | — | A canonical `seat@rig` session address, for `apprentice-handover`. |
|
||||
| `session_source` | object | no | — | Start the seat from an existing session: `fork` with `native_id`, `rebuild` with `artifact_set`, or `agent_image` with `image_name`. A Claude Code `fork` needs Claude Code 2.0.73 or later. Not valid on terminal members. |
|
||||
| `starter_ref` | object | no | — | `{ name }` of an agent starter (`^[a-zA-Z0-9][a-zA-Z0-9_-]*$`) whose files lead the seat's startup. Not valid on terminal members or with a fork. |
|
||||
| `restore_policy` | string | no | `resume_if_possible` | Restore behavior. One of: `resume_if_possible`, `relaunch_fresh`, `checkpoint_only`. |
|
||||
| `startup` | StartupBlock | no | — | Member-level startup files and actions. Applied only to this member. |
|
||||
|
||||
### Claude Advisor (`runtime: claude-code`)
|
||||
|
||||
Set `advisor` independently of the primary `model`:
|
||||
|
||||
```yaml
|
||||
members:
|
||||
- id: owner
|
||||
agent_ref: local:agents/implementer
|
||||
profile: default
|
||||
runtime: claude-code
|
||||
cwd: .
|
||||
model: claude-sonnet-5-5
|
||||
effort: medium
|
||||
advisor: opus
|
||||
```
|
||||
|
||||
OpenRig passes `--model claude-sonnet-5-5 --effort medium --advisor opus` to this
|
||||
Claude session. The primary model stays Sonnet. Advisor resolution uses the member's
|
||||
`advisor`, then the profile's `preferences.advisor`, then the agent's `defaults.advisor`.
|
||||
Blank candidates are skipped before applying this precedence. Materialization stores
|
||||
the resolved value, so node/graph output, exported specs and snapshots include it even
|
||||
before the first launch. Launching the original spec re-resolves its current preferences.
|
||||
The selection is supplied again on resume, restore, fresh restart and handover. A fork
|
||||
uses the resulting member's configuration and keeps its own conversation identity.
|
||||
|
||||
This requires a Claude Code version that supports `--advisor`. OpenRig never writes
|
||||
`advisorModel` to user or project settings. Members sharing a checkout can therefore
|
||||
choose different Advisors. When Advisor is unset, no flag is emitted and Claude's
|
||||
own defaults/settings apply. Other runtimes ignore this field.
|
||||
|
||||
### Pi (`runtime: pi`)
|
||||
|
||||
`runtime: pi` launches the Pi coding agent (`pi --mode rpc`) through OpenRig's RPC runner.
|
||||
|
||||
- **State:** Each seat uses `$OPENRIG_HOME/state/pi/<session>/agent` as its Pi agent directory, with `sessions/` beside it, instead of your default `~/.pi/agent`. The runner sets `PI_CODING_AGENT_DIR` to that directory. `<session>` is the seat's session name, unchanged; for a pod member it is `{podId}-{memberId}@{rigName}`. `$OPENRIG_HOME` defaults to `~/.openrig`. OpenRig creates these directories at launch and does not copy anything from `~/.pi/agent`.
|
||||
- **Thinking level:** A Pi seat's effort (the choice saved with `rig seat set-effort`, else the spec's `effort`) is sent to Pi as `--thinking <level>` on every managed launch and resume: fresh launch, successor and restore. Pi accepts `off`, `minimal`, `low`, `medium`, `high`, `xhigh` and `max`; OpenRig passes the value as written and does not translate it, so Codex's `none` is not mapped to `off`. Only a value of the shape `set-effort` accepts (a letter, then up to 31 letters, digits, `-` or `_`) is sent; any other spec value, such as one with a space or one that starts with `--`, is left out, and `rig seat effort` says so. An unfamiliar level gets an advisory (a warning from `set-effort`), never a refusal, and Pi itself ignores an unknown level with a warning and keeps the level it would use without the flag: a model suffix, the resumed session's level, or its default. With no effort resolved, no flag is sent. The effort wins over a model suffix, and the model string is never changed. `rig seat effort` reports the level sent at launch and, on Pi 0.99.0 or later, the `thinkingLevel` Pi records on this launch's latest successful assistant turn (error and aborted turns are skipped); that is the session's level after Pi's own cap, not proof the provider applied it, and it is shown apart from the level sent when they differ. On older Pi it is NOT VERIFIED. Without an effort, you can still set the level as a model suffix, for example `model: openrouter/x-ai/grok-4:high`. Pi first looks for a model whose id is the whole pin, and uses it when there is one, suffix included. Only when there is none does Pi read the suffix as the level and record the model without it. Any other suffix, such as OpenRouter's `:free`, stays part of the model id. The model-divergence check reads the pin literally when the seat's `models.json` defines a model with that exact id; otherwise it accepts the model with or without the suffix. If the seat's `models.json` can't be read, a pin with a suffix stays unchecked, with the usual warning, when the recorded model matches the whole pin or the pin without its suffix. A record that matches neither is reported.
|
||||
- **Custom models:** Pi reads `models.json` from its agent directory, so a seat reads `$OPENRIG_HOME/state/pi/<session>/agent/models.json`, not `~/.pi/agent/models.json`. Custom provider and model definitions for a seat go in that file. A seat that uses only providers Pi already includes does not need one. OpenRig does not create or write `models.json`.
|
||||
- **Credentials:** The Pi process receives only `PATH`, `HOME`, `USER`, `LOGNAME`, `SSH_AUTH_SOCK`, `TERM`, `LANG`, `LC_ALL`, `SHELL`, `TMPDIR`, a fixed set of OpenRig seat and instance variables, `PI_CODING_AGENT_DIR`, `PI_CODING_AGENT_SESSION_DIR`, and at most one provider key. That key is `OPENROUTER_API_KEY`, `ZAI_API_KEY`, `KIMI_API_KEY` or `MINIMAX_API_KEY`, passed only when it is set in the seat's environment and the seat's `model` is written as `openrouter/<id>`, `zai/<id>`, `kimi-coding/<id>` or `minimax/<id>`. Naming that variable in `recovery.provider_auth_env_allowlist` (empty by default) makes the daemon add it, when set in the daemon's environment, to the seat's launch environment. No other variable reaches Pi, including other providers' keys and a custom provider's own key variable.
|
||||
|
||||
- **Extension dialogs:** The RPC runner shows extension `select`, `confirm`, `input` and `editor` requests in the pane and cancels them because the managed pane cannot answer them. The seat needs attention through the end of the turn, until a new agent run starts. Review the cancelled request and send an instruction the extension can complete without a dialog. Extension `notify` text is shown without raising attention or sending a response.
|
||||
- **Credentials:** The Pi process receives only `PATH`, `HOME`, `TERM`, `LANG`, `LC_ALL`, `SHELL`, `TMPDIR`, a fixed set of OpenRig seat and instance variables, `PI_CODING_AGENT_DIR`, `PI_CODING_AGENT_SESSION_DIR`, and at most one provider key. That key is `OPENROUTER_API_KEY`, `ZAI_API_KEY` or `KIMI_API_KEY`, passed only when it is set in the seat's environment and the seat's `model` is written as `openrouter/<id>`, `zai/<id>` or `kimi-coding/<id>`. Naming that variable in `recovery.provider_auth_env_allowlist` (empty by default) makes the daemon add it, when set in the daemon's environment, to the seat's launch environment. No other variable reaches Pi, including other providers' keys and a custom provider's own key variable.
|
||||
|
||||
### Oh My Pi (`runtime: omp`)
|
||||
|
||||
@@ -664,8 +344,8 @@ own defaults/settings apply. Other runtimes ignore this field.
|
||||
- **State:** Each seat uses `$OPENRIG_HOME/state/omp/<seat>/agent` and `sessions/` instead of your default `~/.omp` profile, and runs with that seat directory as `HOME`. OpenRig does not copy OMP credentials. The runner finds the real `omp` binary before switching `HOME`, so a version-manager shim such as mise on the daemon's `PATH` still works.
|
||||
- **Credentials:** Provision each seat separately, or put the provider's key variable in `recovery.provider_auth_env_allowlist` (for example `ANTHROPIC_API_KEY` or `MISTRAL_API_KEY`). The allowlist accepts the key variable of every provider in OpenRig's OMP provider map, from `anthropic` through `litellm`. A seat receives a key only when its `model` is written as `provider/id`, such as `anthropic/claude-sonnet-4-5`. Short names such as `opus` pass no key. A provider whose key is scoped to one endpoint also accepts that endpoint's variable: `anthropic`, `openai` and `litellm` each take their `<PROVIDER>_BASE_URL` — `ANTHROPIC_BASE_URL`, `OPENAI_BASE_URL`, `LITELLM_BASE_URL`. The allowlist admits each variable on its own, so an endpoint named without its key is admitted too, which suits a keyless local proxy. The launch gate admits these endpoint names for OMP seats; the match against the seat's declared `provider/id` happens at the OMP child, which forwards a matching endpoint already in the runner's environment just as it forwards a key. OMP also reads the launch directory's `.env`, so use a trusted working directory.
|
||||
- **Approval posture:** The default floor is `--approval-mode always-ask`. Because the runner is headless, OMP approval requests are cancelled and the seat stays in needing-attention after the turn ends, until the next agent run starts. A `full_bypass` permission policy selects `--approval-mode yolo`.
|
||||
- **Model errors:** Errors are printed in the pane. A completed assistant failure with a numeric `errorStatus` of 408, 429, 500, 502, 503, 504, or 529 returns to idle at terminal `agent_end`, allowing an ordinary retry. Until that terminal boundary it stays in needing-attention. Intermediate `agent_end(isTerminal:false)` events do not release attention. A statusless failed retry summary retains that classification only when its attempt matches an announced retry and its final error exactly matches the latest typed transient assistant failure in that attempt. New assistant/turn boundaries invalidate the previous failure; unmatched summaries remain runtime errors. Rejected prompts, auth/configuration failures, exhausted retries without a typed transient status, and untyped errors (including text such as `529 overloaded`) retain attention until the next agent run starts. The runner does not classify diagnostic text. A transient failure does not clear a denied approval or another unresolved runtime failure in the same turn.
|
||||
- **Restore:** OMP creates its session file after the first persisted turn. A new seat with no persisted turn has no resume token, so a restore leaves it awaiting a decision. Start it fresh with `rig seat launch <seat> --fresh --reason "<why>"`, the command `rig start` and `rig up --existing` print for that seat. After that file exists, OpenRig restores that exact session file. If a full rig restore leaves an OMP seat in `attention_required` or `failed`, `rig seat clear-attention` cannot yet reconcile it to `operator_recovered`, even with `--reason`, because restore reconciliation only verifies Claude Code and Codex processes ([#41](https://github.com/mvschwarz/openrig/issues/41)). Relaunch that seat with `rig seat launch <seat> --fresh --reason "<why>"`, or restore it manually. `rig seat launch --fresh` refuses a managed seat whose pane is still running unless you add `--stop`, which ends what is running there; add it only when you mean to replace that session.
|
||||
- **Model errors:** A rejected prompt, a provider or authentication error during a turn, or exhausted automatic retries is printed in the pane and keeps the seat in needing-attention until the next agent run starts.
|
||||
- **Restore:** OMP creates its session file after the first persisted turn. A new seat with no persisted turn has no resume token; restoring it requires `rig up --existing <rig> --fresh <seat>`. After that file exists, OpenRig restores that exact session file. If a full rig restore leaves an OMP seat in `attention_required` or `failed`, `rig seat clear-attention` cannot yet reconcile it to `operator_recovered`, even with `--reason`, because restore reconciliation only verifies Claude Code and Codex processes ([#41](https://github.com/mvschwarz/openrig/issues/41)). Relaunch that seat with `rig up --existing <rig> --fresh <seat>`, or restore it manually.
|
||||
|
||||
### Terminal Nodes
|
||||
|
||||
@@ -679,10 +359,6 @@ profile: none
|
||||
|
||||
All three must be present together. Any partial combination is a validation error.
|
||||
|
||||
A terminal seat no longer waits for a `--fresh` decision just because it has no resume token: on restore it relaunches fresh and re-runs its startup actions. The runtime, identity and replay prerequisites still apply. A runtime mismatch still waits for a decision, an ambiguous occupant still fails, and a missing required replay file still blocks.
|
||||
|
||||
`rig send` to a terminal node types the exact text, without the From/To envelope that agent seats get, because the shell would run the envelope lines. The sender's output says so.
|
||||
|
||||
### agent_ref Rules
|
||||
|
||||
- Must start with `local:` or `path:`
|
||||
@@ -699,7 +375,7 @@ The canonical session name is derived from the pod ID, member ID, and rig name:
|
||||
{podId}-{memberId}@{rigName}
|
||||
```
|
||||
|
||||
Example: pod `dev`, member `build`, rig `my-team` → session `dev-build@my-team`
|
||||
Example: pod `dev`, member `impl`, rig `my-team` → session `dev-impl@my-team`
|
||||
|
||||
Pod and member IDs cannot contain `@` because the first `@` separates their portion
|
||||
of the session address from the rig name. Rig names may still contain `@`.
|
||||
@@ -715,14 +391,10 @@ This is human-authored (you choose the pod/member IDs) and system-validated (the
|
||||
| Kind | Meaning | Use When |
|
||||
|------|---------|----------|
|
||||
| `delegates_to` | Source delegates work to target. Constrains launch order. | Orchestrator → implementer, lead → worker |
|
||||
| `spawned_by` | Source was spawned by target; the target launches first. Constrains launch order. | Child → parent in hierarchical topologies |
|
||||
| `spawned_by` | Target was spawned by source. Constrains launch order. | Parent → child in hierarchical topologies |
|
||||
| `can_observe` | Source can observe target's output. Does NOT constrain launch order. | Reviewer → implementer, monitor → worker |
|
||||
| `collaborates_with` | Peer collaboration relationship. Does NOT constrain launch order. | Co-equal peers working together |
|
||||
| `escalates_to` | Fallback queue escalation for a seat without a declared delegation parent. Does NOT constrain launch order. | Local member or same-daemon `pod-member@rig` address |
|
||||
|
||||
A named `escalates_to` target may be in another rig on the same daemon and need not exist at import time.
|
||||
See [fallback escalation across rigs](edge-types.md#fallback-escalation-across-rigs) for precedence, single-hop delivery,
|
||||
cycle detection and visible fallback outcomes.
|
||||
| `escalates_to` | Source escalates to target for decisions. Does NOT constrain launch order. | Worker → lead for escalation |
|
||||
|
||||
### Pod-Local Edges
|
||||
|
||||
@@ -732,13 +404,13 @@ Edges within a pod use **unqualified member IDs** (just the member `id`, not `po
|
||||
pods:
|
||||
- id: dev
|
||||
members:
|
||||
- id: build
|
||||
- id: impl
|
||||
# ...
|
||||
- id: qa
|
||||
# ...
|
||||
edges:
|
||||
- kind: delegates_to
|
||||
from: build # NOT dev.build
|
||||
from: impl # NOT dev.impl
|
||||
to: qa # NOT dev.qa
|
||||
```
|
||||
|
||||
@@ -752,72 +424,16 @@ Edges between pods use **fully-qualified `pod.member` IDs**:
|
||||
edges:
|
||||
- kind: delegates_to
|
||||
from: orch.lead # pod.member format
|
||||
to: dev.build # pod.member format
|
||||
to: dev.impl # pod.member format
|
||||
```
|
||||
|
||||
Cross-pod edges must reference different pods. An edge where both `from` and `to` are in the same pod is a validation error — use pod-local edges instead.
|
||||
|
||||
### Changing edges on an existing rig
|
||||
|
||||
Use `rig edge add` to ensure relationships between seats that already exist. It
|
||||
accepts a rig name or ID and **fully qualified logical IDs for both same-pod and
|
||||
cross-pod edges**. This command only changes edges; it does not create pods,
|
||||
restart sessions or change seat identity.
|
||||
|
||||
```sh
|
||||
rig edge add my-rig orch.lead review.reviewer --kind delegates_to --plan --json
|
||||
rig edge add my-rig orch.lead review.reviewer --kind delegates_to --json
|
||||
```
|
||||
|
||||
Run it once per edge. It returns `added` with the new edge's ID, or `present` with
|
||||
the existing edge's ID when that `{from, to, kind}` is already there, and then
|
||||
writes nothing. Existing duplicate rows from other creation paths are retained;
|
||||
this operation does not create more copies.
|
||||
|
||||
Unknown endpoints, an invalid kind or a launch-order cycle leave the graph
|
||||
unchanged. Both endpoints must belong to the target rig. `--plan` performs the
|
||||
same validation and returns `would_add` for a new edge without writing anything.
|
||||
|
||||
Each `added` receipt includes a rollback command,
|
||||
`rig edge remove <rig-id> <edge-id>`, which removes exactly that edge in that rig.
|
||||
Removal also supports `--plan` and `--json`. Removing an edge that is already gone changes nothing
|
||||
and returns `edge_not_found` (HTTP 404, exit 1), so a repeated removal reports not found, not success.
|
||||
Rig names resolve only among unarchived rigs, and an ambiguous name requires an
|
||||
explicit ID. These commands target the local daemon, as `rig add` does.
|
||||
|
||||
A `delegates_to` edge also decides routing. A seat's stuck-row findings and recovery go to its most
|
||||
recently started parent. A person's top-level Slack message in the rig's mapped channel goes to the rig's
|
||||
representative, its one delegation root, unless that channel names an `inbound` seat; with no single root it
|
||||
goes to Slack's inbound destination. When an added or removed edge changes either, the receipt says what
|
||||
moved in `routing`:
|
||||
`orchestrator: {seat, from, to}` and `representative: {from, to}`, where `null` is none. The plain output
|
||||
prints a `routing:` line for each. A change that moves nothing has no `routing`, and `--plan` doesn't
|
||||
preview it.
|
||||
|
||||
Changes are persisted immediately and included in `rig export`. Existing snapshots
|
||||
remain unchanged, and restore reads the **selected snapshot's edges**. To restore
|
||||
the modified topology, run `rig snapshot <rig-id>` and use its returned ID with
|
||||
`rig restore <snapshot-id> --rig <rig-id>`.
|
||||
|
||||
---
|
||||
|
||||
## Startup Block
|
||||
|
||||
Startup blocks can appear at three levels: rig, pod, and member. They are merged additively via the startup layering model (see [the layering model](agent-startup-guide.md#the-layering-model)). The rig's `culture_file` joins as a required file with the `auto` hint in the culture layer, on both fresh start and restore.
|
||||
|
||||
`rig export` includes the rig's saved culture file and startup block, and now also
|
||||
writes each pod's saved startup files under that pod. The file order, delivery
|
||||
hints, required flags, orientation and `applies_on` selections are retained.
|
||||
Previously the saved pod file lists were omitted. Pods without a recorded file
|
||||
list, including older rigs, keep their existing export behavior; the exporter
|
||||
does not reconstruct declarations from a member's combined startup context.
|
||||
|
||||
File paths remain relative to the exported spec's folder. When exporting to a
|
||||
different folder, supply the referenced startup files there or import with the
|
||||
original `--rig-root`. The CLI warns once per missing required rig or pod file;
|
||||
missing optional files do not trigger that warning. Pod startup actions and
|
||||
member startup blocks remain outside this export; keep the source spec when you
|
||||
need those declarations.
|
||||
Startup blocks can appear at three levels: rig, pod, and member. They are merged additively via the startup layering model (see `docs/reference/startup-layering.md`).
|
||||
|
||||
### Files
|
||||
|
||||
@@ -827,14 +443,14 @@ need those declarations.
|
||||
| `orientation` | string | no | — | Set to `role` to identify a per-seat role file for `rig queue whoami --json` and refocus. Does not change delivery or replay startup. |
|
||||
| `delivery_hint` | string | no | `auto` | How the file is delivered. One of: `auto`, `guidance_merge`, `skill_install`, `send_text`. |
|
||||
| `required` | boolean | no | `true` | Whether startup fails if this file cannot be delivered. |
|
||||
| `applies_on` | string[] | no | `[fresh_start, restore]` | When this file is delivered. Subset of: `fresh_start`, `restore`. An exact resume of the saved conversation delivers none, apart from putting back a missing managed guidance block. |
|
||||
| `applies_on` | string[] | no | `[fresh_start, restore]` | When this file is delivered. Subset of: `fresh_start`, `restore`. |
|
||||
|
||||
#### Delivery Hints
|
||||
|
||||
| Hint | Behavior |
|
||||
|------|----------|
|
||||
| `auto` | System chooses based on file type and context. |
|
||||
| `guidance_merge` | Merged as a managed block into the runtime's guidance file: for Claude, the `managed_blocks` file (`CLAUDE.md` or `CLAUDE.local.md`); for Codex, Pi and OMP, `AGENTS.md`. Delivered before harness boot. |
|
||||
| `guidance_merge` | Merged into the runtime's guidance file (`CLAUDE.md` or `AGENTS.md`) as a managed block. Delivered before harness boot. |
|
||||
| `skill_install` | Installed as a skill in the runtime's skill directory. Delivered before harness boot. |
|
||||
| `send_text` | Sent as text to the agent's terminal after the harness is ready. Requires the agent TUI to be active. |
|
||||
|
||||
@@ -845,8 +461,8 @@ need those declarations.
|
||||
| `type` | string | yes | — | Action type. One of: `slash_command`, `send_text`, `startup_proof`. Note: `shell` is explicitly NOT supported in v1. |
|
||||
| `value` | string | yes | — | Command/text to send, or `authenticated` / `none` for `startup_proof`. |
|
||||
| `phase` | string | no | `after_files` | When to execute text/commands. One of: `after_files` (after startup files are delivered), `after_ready` (after harness readiness check passes). Proof selection is resolved before projection regardless of phase. |
|
||||
| `idempotent` | boolean | yes | — | Whether this action is safe to run again on a restore without the earlier conversation or a retried start. **Required field.** Non-idempotent actions must NOT include `restore` in `applies_on`. |
|
||||
| `applies_on` | string[] | no | `[fresh_start, restore]` | When this action runs. Subset of: `fresh_start`, `restore`. An exact resume of the saved conversation runs none (see the startup guide). |
|
||||
| `idempotent` | boolean | yes | — | Whether this action is safe to replay on restore. **Required field.** Non-idempotent actions must NOT include `restore` in `applies_on`. |
|
||||
| `applies_on` | string[] | no | `[fresh_start, restore]` | When this action runs. Subset of: `fresh_start`, `restore`. |
|
||||
|
||||
### Startup proof selection
|
||||
|
||||
@@ -891,26 +507,8 @@ The harness readiness window defaults to 30 seconds. On a loaded machine, set
|
||||
`rig config set runtime.readiness_timeout_seconds 60` to give new seats and
|
||||
handover successors longer to become interactive. The setting accepts 1–600
|
||||
seconds, applies to the next launch without a daemon restart, and can also be
|
||||
set with `OPENRIG_RUNTIME_READINESS_TIMEOUT_SECONDS`. It also bounds how long a
|
||||
restore keeps watching a Claude seat whose resume is still starting, so raising
|
||||
it for slow fresh launches lengthens that wait too. The wait is about the
|
||||
setting in total per seat, counting the usual 3.2-second check: the adapter polls
|
||||
for the rest of it (nominally: it counts polls, and each poll's tmux and process
|
||||
reads add a little). A restore
|
||||
starts seats one after another, so each seat that never starts Claude adds up to
|
||||
about this much, minus the 3.2 seconds, to the restore; the time adds up seat by
|
||||
seat, and a longer setting means a longer wait before a stuck seat is reported.
|
||||
A seat that is still not interactive then ends `attention_required` with its
|
||||
launch and resume token kept, and the later readiness wait is skipped for it.
|
||||
That holds at every setting: at 1–3 seconds there are no extra polls, but an
|
||||
unresolved boot is still kept rather than failed. A pane that shows a Codex or
|
||||
another conversation's Claude is not waited for. `rig up` and
|
||||
`rig launch` wait 120 seconds for the daemon, so a restore of several stuck
|
||||
seats can pass that (in one measurement, about 31 seconds a seat at the
|
||||
default, 95 for three). A client timeout and exit code 1 do not mean the
|
||||
restore was rolled back or that it should be run again; check the real state
|
||||
first with `rig ps`. Apart from this, the setting does not change the time
|
||||
spent by the runtime adapter before readiness polling starts.
|
||||
set with `OPENRIG_RUNTIME_READINESS_TIMEOUT_SECONDS`. It does not change the
|
||||
time spent by the runtime adapter before readiness polling starts.
|
||||
|
||||
---
|
||||
|
||||
@@ -966,7 +564,7 @@ surfaces:
|
||||
command: "vault status -address=http://127.0.0.1:8200"
|
||||
```
|
||||
|
||||
Surfaces are metadata only. They are displayed in the UI and in `rig env status --json` output (the text output lists only services) but are NOT executed by OpenRig.
|
||||
Surfaces are metadata only. They are displayed in the UI and in `rig env status` output but are NOT executed by OpenRig.
|
||||
|
||||
### Checkpoint Hooks
|
||||
|
||||
@@ -980,10 +578,10 @@ checkpoints:
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `id` | string | yes | Unique identifier for this checkpoint. |
|
||||
| `export` | string | yes | Shell command to export state. |
|
||||
| `export` | string | yes | Shell command to export state. `{{artifacts_dir}}` is replaced with a daemon-managed path. |
|
||||
| `import` | string | no | Shell command to import state on restore. |
|
||||
|
||||
Checkpoint hooks are validated and stored with the spec. In this version the daemon doesn't run them during snapshot or restore, and doesn't substitute `{{artifacts_dir}}`.
|
||||
Checkpoint hooks are shell commands run by the daemon. They are best-effort — a failed export does not block snapshot, but continuity is classified as `receipt_only` instead of `checkpointed`.
|
||||
|
||||
---
|
||||
|
||||
@@ -1014,20 +612,10 @@ continuity_policy:
|
||||
| `restore_protocol.peer_driven` | boolean | no | — | Whether peers drive the restore process. |
|
||||
| `restore_protocol.verify_via_quiz` | boolean | no | — | Whether to verify restoration via quiz. |
|
||||
|
||||
These fields are validated, stored on the pod and written back on export. In this version nothing acts on
|
||||
`sync_triggers`, `artifacts` or `restore_protocol`.
|
||||
|
||||
---
|
||||
|
||||
## Validation Rules Summary
|
||||
|
||||
Unknown keys at the rig, pod, member and edge levels are refused ("unknown key … refusing the spec because
|
||||
normalization would otherwise discard it"). Keys inside `startup`, `services`, `continuity_policy` and `workspace` are
|
||||
not checked this way. Some rules are enforced at preflight rather than validation: the runtime must be one of the
|
||||
supported values, rig, pod and member names may use only letters, digits, `-`, `_`, `.` and `@` where allowed above,
|
||||
each `agent_ref` must have an `agent.yaml`, Codex profiles must load, and a cwd may not be inside the OpenRig
|
||||
installation.
|
||||
|
||||
Schema validation checks the structural rules below. Pod and member IDs containing
|
||||
`@` are additionally rejected during preflight and member creation or launch; a
|
||||
spec can pass `rig spec validate` and then fail at preflight or import. Run
|
||||
@@ -1068,13 +656,8 @@ These are the built-in specs shipped with OpenRig. Read them as worked examples.
|
||||
|
||||
| Spec | Location | Pods | Members | Services |
|
||||
|------|----------|------|---------|----------|
|
||||
| `starter` | `packages/daemon/specs/rigs/launch/starter/rig.yaml` | dev | 2 (build, review) | no |
|
||||
| `factory` | `packages/daemon/specs/rigs/launch/factory/rig.yaml` | orch, dev, review | 7 (lead, advisor, build, qa, design, r1, r2) | no |
|
||||
| `code-review` | `packages/daemon/specs/rigs/focused/code-review/rig.yaml` | orch, review | 3 (lead, r1, r2) | no |
|
||||
| `research` | `packages/daemon/specs/rigs/focused/research/rig.yaml` | orch, research | 3 (lead, analyst, synthesizer) | no |
|
||||
| `pm` | `packages/daemon/specs/rigs/focused/pm/rig.yaml` | pm, dev | 3 (lead, researcher, build) | no |
|
||||
| `product-team` | `packages/daemon/specs/rigs/preview/product-team/rig.yaml` | orch1, dev1, rev1 | 7 (lead, peer, impl, qa, design, r1, r2) | no |
|
||||
| `implementation-pair` | `packages/daemon/specs/rigs/launch/implementation-pair/rig.yaml` | dev | 2 (impl, qa) | no |
|
||||
| `adversarial-review` | `packages/daemon/specs/rigs/focused/adversarial-review/rig.yaml` | orch, review | 3 (lead, r1, r2) | no |
|
||||
| `research-team` | `packages/daemon/specs/rigs/focused/research-team/rig.yaml` | orch, research | 3 (lead, analyst, synthesizer) | no |
|
||||
| `secrets-manager` | `packages/daemon/specs/rigs/launch/secrets-manager/rig.yaml` | vault | 1 (specialist) | yes (Vault) |
|
||||
|
||||
Also shipped, in the same tree: `launch/kernel`, OpenRig's own team, which starts automatically. `first-project` is
|
||||
starter's old name and still resolves to it. `workshop`, the four-agent middle team, is a rig bundle rather than a
|
||||
built-in. List the built-ins with `rig specs ls --kind rig`.
|
||||
@@ -4,8 +4,7 @@ A roster records who to involve for a purpose and why. The same seat can appear
|
||||
rosters with different capabilities and engagement. Membership is a recommendation, not an
|
||||
assignment or a grant of authority. Contact someone with the existing `rig send` or `rig queue` commands.
|
||||
|
||||
Put JSON files in `<workspace.root>/rosters/`; the included starter and factory leads write
|
||||
their team's `<rig>.json` there at first start and never replace an existing one. Read `workspace.root` with
|
||||
Put JSON files in `<workspace.root>/rosters/`. Read `workspace.root` with
|
||||
`rig config get workspace.root`, or use `--folder` to read another folder in place.
|
||||
|
||||
```sh
|
||||
@@ -49,22 +48,8 @@ Authored files contain recommendations, not runtime facts. Extra fields are igno
|
||||
any authored runtime, model or activity. At read time the command joins by exact host self-id
|
||||
and seat. Unmatched or conflicting observations are `unknown`; a seat not reported running is
|
||||
`stale`, with current runtime/model unknown. The configured model is the registry declaration.
|
||||
Daemon node listings, `rig ps --nodes --full` and roster members also carry the full
|
||||
`modelObservation`: `status`, `model`, `source`, `observedAt`, `generation` and `reason`.
|
||||
Compact JSON uses the smaller shape described below. The configured `model` stays separate; roster's
|
||||
`live.observedModel` is the observation's model or null. Human output says **last observed**.
|
||||
Claude (`claude-assistant-response`) and Pi (`pi-assistant-response`) name response evidence;
|
||||
Codex (`codex-turn-context` or `codex-world-state`) names recorded turn configuration, not a
|
||||
verified backend response. The timestamp is the native record's time, never file mtime or inventory
|
||||
read time. None promises the model that will answer the next turn.
|
||||
|
||||
The daemon reuses the current-occupant record selectors and bounded readers used by divergence
|
||||
monitoring, sharing a process census. Reporting does not need a configured model or comparator.
|
||||
A changed or unverified occupant, a record predating its tenure, missing or invalid record time,
|
||||
unreadable or ambiguous records, unsupported runtimes and older daemons report **UNKNOWN** with
|
||||
a reason, never the configured value as a fallback. An older record from the same verified occupant
|
||||
remains labelled last observed at its original time; this is not a freshness guarantee. No record
|
||||
contents, transcript paths or credentials are returned. Activity includes its own sample time;
|
||||
The observed native model remains unknown: these commands do not open native histories or verify
|
||||
what model the provider is running. Activity includes its sample time when the daemon supplies it;
|
||||
activity and running status do not promise that someone is available for new work.
|
||||
|
||||
The JSON `observations.readAt` is when the inventory read completed, not a native observation
|
||||
@@ -73,22 +58,3 @@ valid rosters remain usable; duplicate IDs make `show` report ambiguity instead
|
||||
Non-regular file targets, such as FIFOs and directories, are skipped with a warning; links to
|
||||
regular files remain readable. Inventory uses `ps --no-cleanup` to preserve even stale local
|
||||
daemon state files. Ordinary `rig ps` keeps its existing cleanup behavior unless given that flag.
|
||||
|
||||
The daemon reuses model facts only while the selected record's identity, size and
|
||||
modification time and the occupant generation remain unchanged. Inventory reads
|
||||
share two bulk pane snapshots and one process census; identity is checked after
|
||||
the final snapshot. A different observation from duplicate host routes makes
|
||||
only that observation UNKNOWN, preserving agreed registry fields.
|
||||
|
||||
`rig ps --nodes --json` keeps an observed model compact as
|
||||
`modelObservation: ["literal-model-id", "evidence-source", "native-record-time"]`.
|
||||
UNKNOWN is `{ "status": "unknown", "reason": "..." }`; older daemons may yield
|
||||
`null`. `--full` and `--fields modelObservation` retain the full object, including
|
||||
its status and occupant generation. Human output and roster reports use the full
|
||||
labelled observation.
|
||||
|
||||
A member marked `"hosted": true` is a hosted member: a tool outside the terminal that reaches the team over MCP, with no node or pane.
|
||||
`rig_team` lists it with its capabilities and caveat, no pane and activity unknown, unless its seat is one of the rig's nodes.
|
||||
`show` and `find` say it's hosted rather than unmatched. See [Hosted members](hosted-members.md).
|
||||
Its entry can declare `wake.webhook`, the secret names for a trigger OpenRig rings when work lands for it
|
||||
(see [Ring it when work lands](hosted-members.md#ring-it-when-work-lands)).
|
||||
@@ -212,11 +212,7 @@
|
||||
"description": "Host settings (for example OPENRIG_YOLO, persisted or native settings) decide the effective permission at launch."
|
||||
},
|
||||
"permissionPrompts": {
|
||||
"enum": [
|
||||
"off",
|
||||
"on",
|
||||
"default"
|
||||
],
|
||||
"enum": ["off", "on", "default"],
|
||||
"description": "Archive declaration per seat: off for full_bypass (including builtin:yolo) on any runtime; on for a Claude/Codex flag-surface floor policy, or Codex under auto; default for Claude/Codex with no declared policy. Omitted for Claude under auto, config-surface policies, host-resolved Codex profiles, and Pi except declared full bypass. Absent means not stated, never on. Host settings may differ; nativeEffect remains unknown."
|
||||
},
|
||||
"sourceRefs": {
|
||||
@@ -237,10 +233,6 @@
|
||||
"nonInterruptive": {
|
||||
"const": "available",
|
||||
"description": "This declared full-bypass Claude/Codex seat can use --non-interruptive launch flags. Availability is not the operator choice or proof that no prompt will appear. Omitted for other postures, unresolved policies and runtimes with no such flags."
|
||||
},
|
||||
"nonInterruptiveDefault": {
|
||||
"type": "boolean",
|
||||
"description": "Optional authored rig-level default for supported full-bypass Claude/Codex launches. An explicit launch option overrides it; absent is not an off or on claim. Native effect remains unknown."
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -421,10 +413,7 @@
|
||||
"commands": {
|
||||
"type": "array",
|
||||
"description": "Unexecuted author setup lines, in order in one shell; the install command follows in the resulting working directory.",
|
||||
"items": {
|
||||
"type": "string",
|
||||
"minLength": 1
|
||||
}
|
||||
"items": { "type": "string", "minLength": 1 }
|
||||
},
|
||||
"status": {
|
||||
"const": "not_checked"
|
||||
@@ -466,102 +455,6 @@
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"services": {
|
||||
"type": "array",
|
||||
"description": "Optional opt-in service declarations from archived Compose YAML. Host-resolved values remain unresolved; no Compose or health probe ran.",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"name",
|
||||
"composeFile",
|
||||
"image",
|
||||
"ports",
|
||||
"privileged",
|
||||
"capAdd",
|
||||
"securityOpt",
|
||||
"devices",
|
||||
"environment",
|
||||
"mounts",
|
||||
"healthcheck",
|
||||
"waitFor",
|
||||
"downPolicy",
|
||||
"unresolved",
|
||||
"notes"
|
||||
],
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "string"
|
||||
},
|
||||
"composeFile": {
|
||||
"type": "string"
|
||||
},
|
||||
"image": {
|
||||
"type": "string"
|
||||
},
|
||||
"ports": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"privileged": {
|
||||
"type": [
|
||||
"boolean",
|
||||
"string"
|
||||
]
|
||||
},
|
||||
"capAdd": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"securityOpt": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"devices": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"environment": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"mounts": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"healthcheck": {},
|
||||
"waitFor": {
|
||||
"type": "array"
|
||||
},
|
||||
"downPolicy": {
|
||||
"type": "string"
|
||||
},
|
||||
"unresolved": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"notes": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"allOf": [
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://openrig.dev/schemas/registry-entry.v1.json",
|
||||
"title": "Registry entry (openrig-registry/registry/<slug>.yaml)",
|
||||
"title": "Registry entry (openrig-world/registry/<slug>.yaml)",
|
||||
"type": "object",
|
||||
"required": [
|
||||
"schema",
|
||||
|
||||
@@ -23,9 +23,8 @@ rig mode unset mission my-project/release-1
|
||||
Unsetting reveals the next applicable explicit choice, or the visible human-led
|
||||
product default. A new, resolved rig with no binding reports `human-led`,
|
||||
`source: product-default`, and `binding: null`. Missing scope identity, conflicting
|
||||
linkage or malformed authored context reports `unknown` with a reason. If the mode
|
||||
store itself is unavailable, the route answers HTTP 503 `rig_policy_store_unavailable`
|
||||
instead. Calling `effective` without a scope does not select a rig implicitly.
|
||||
linkage, unavailable storage or malformed authored context reports `unknown` with
|
||||
a reason. Calling `effective` without a scope does not select a rig implicitly.
|
||||
The existing operator bearer requirement still applies. `set` requires `--confirm`;
|
||||
`unset` is an explicit deletion command and applies immediately.
|
||||
|
||||
@@ -41,12 +40,12 @@ another preference store or infer delegation from workflow existence or activity
|
||||
| --- | --- |
|
||||
| `posture` | `human-led`, `delegated`, or `unknown` |
|
||||
| `source` | `product-default`, `binding`, or `unknown` |
|
||||
| `context` | Resolved rig/project/mission/workstream/qitem IDs, source addresses, canonical authored paths, phase and `warnings` (for example a malformed `rigs` list that project inference skipped); null if scope resolution failed |
|
||||
| `context.phase` | `{value, source}` from an explicit workflow packet step, otherwise slice stage/status, otherwise mission release phase/status. A slice with neither gives `value: null` with its `SPEC.md` as the source; a mission with neither makes the whole read unknown; both fields are null only for rig- or project-only scopes |
|
||||
| `context` | Resolved rig/project/mission/workstream/qitem IDs, source addresses, canonical authored paths and phase; null if scope resolution failed |
|
||||
| `context.phase` | `{value, source}` from an explicit workflow packet step, otherwise slice stage/status, otherwise mission release phase/status; null fields when unavailable |
|
||||
| `binding` | Winning binding ID, scope, timestamp and evidence citation; null for default/unknown |
|
||||
| `reason` | Explanation of the result or the missing/conflicting fact |
|
||||
| `grantsAuthority` | Always `false` |
|
||||
| `members` | For queue-backed findings, each member's qitem, posture, source and binding ID; differing or unknown member postures, or members in different project/mission/workstream contexts, yield unknown aggregate posture |
|
||||
| `members` | For queue-backed findings, each member's qitem, posture, source and binding ID; differing or unknown member postures yield unknown aggregate posture |
|
||||
|
||||
The existing SQLite mode-binding table remains the only preference store. Matching
|
||||
posture bindings resolve in this order: qitem, workstream, mission, project, rig,
|
||||
@@ -58,20 +57,15 @@ the returned identity uses its SPEC ID and project/mission qualification.
|
||||
Project selection reads the declared `projects: [{id, root}]` catalog at
|
||||
`workspace.catalog_path` (default `workspace.yaml` in the workspace root), the
|
||||
same catalog `rig context work-install` uses, or the workspace's own
|
||||
`project.yaml` when no catalog exists. A sole project may be derived. With several
|
||||
projects and no explicit selection, posture picks one the way `rig context work-install`
|
||||
does: a project whose `projects[].rigs` lists the rig, then (for qitem reads) the deepest
|
||||
project root containing the destination seat's working folder, then the only project no rig
|
||||
claims. The method is recorded in the source as `#selected-by=rig:<name>`, `cwd:<path>` or
|
||||
`unclaimed`. If none gives a single answer, the read is unknown.
|
||||
`project.yaml` when no catalog exists. Multiple
|
||||
projects require an explicit project selection. A sole project may be derived.
|
||||
The project manifest validates identity and supplies `missions.root` (default
|
||||
`missions`). Mission and slice identities come from those authored work nodes;
|
||||
missing, duplicate or conflicting identities remain unknown. The selected work
|
||||
must stay inside its canonical project root.
|
||||
|
||||
Qitem reads join explicit `project:`, `mission:`, `slice:`/`workstream:` tags,
|
||||
destination rig, and the existing workflow packet binding. A qitem with a mission but no
|
||||
project gets its project from the selection above. Workflow lifecycle
|
||||
destination rig, and the existing workflow packet binding. Workflow lifecycle
|
||||
project/mission identity must agree with the tags and requested scope. The bound
|
||||
packet's exact step is the phase source; phase names are not classified by guess.
|
||||
An unlinked qitem does not silently inherit the default. Scope reads are observational.
|
||||
@@ -81,18 +75,8 @@ their bindings and ten-field records. They do not imply either operating posture
|
||||
Only human-led/delegated bindings participate in posture precedence. The legacy
|
||||
`effective` and `posture: known|unknown_posture` fields remain for compatibility;
|
||||
`unknown_posture` there means no legacy mode binding and does not override the
|
||||
new `operatingPosture.source: product-default` result. A saved legacy mode and a
|
||||
posture are kept side by side at the same target: a write replaces only the
|
||||
binding of its own kind. Inspect effective posture after any mode change.
|
||||
|
||||
Eight of the record's fields are stored, validated and shown, but nothing in
|
||||
OpenRig acts on them yet: `autonomy_scope`, `heartbeat_cadence`,
|
||||
`inspection_depth`, `update_detail`, `escalation_threshold`, `concurrency_limit`,
|
||||
`permission_prompt_posture` and `expiry_or_stale_rule`. `rig mode effective`,
|
||||
`rig mode defaults` and the `rig mode set` preview mark them `(stored; not applied)`.
|
||||
`scope` is the binding's key, and the posture reads `evidence_citation` into its
|
||||
`binding.evidence`. `permission_prompt_posture` never changes a native permission
|
||||
prompt.
|
||||
new `operatingPosture.source: product-default` result. Setting another mode at the
|
||||
same scope replaces that row; inspect effective posture after any mode change.
|
||||
|
||||
## Diagnosis effects
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# SDLC conventions — the markdown control plane
|
||||
|
||||
> **Source of truth:** this repo document is the living SSOT for the SDLC
|
||||
> conventions. Scaffold templates, the advisory scope audit and the
|
||||
> `mission-slice-sop` skill all point HERE —
|
||||
> conventions. Scaffold templates, the advisory scope audit, the
|
||||
> `mission-slice-sop` skill, and the shipped bootstrap overlay all point HERE —
|
||||
> they must not restate this document in full (restatement is how drift is born).
|
||||
|
||||
OpenRig is a software factory the human steers from a high altitude. The human
|
||||
@@ -37,7 +37,7 @@ one does not deprecate the others. Nothing below deletes or overrides an existin
|
||||
| **PRODUCT / MISSION PREPARATION** | **The product-management pass** — the layer above planning, run by the advisor/PM seat before planners touch a mission. The build is a lossy compression pipeline (PM intent → planner spec → builder code); nothing leaks downward by proximity, so this pass grounds in the raw sources, synthesizes ONE scope of record, presents owner decisions decision-ready, mints slices at plan time, deposits the full design contract INLINE in each design-bearing spec (owner words verbatim, settled decisions, evidence, shape of done, anti-goals), routes the complete reading list and internet-research assignments from the spec itself, frames each slice's planning-dial rung with its reason, and rereads every spec as the narrow downstream reader. The measuring stick: SPEC.md alone, plus what it explicitly routes to, reproduces the intent in a reader with none of the author's context. Full reference: `product-management-pass.md`. |
|
||||
| **PLAN** | **The planning dial** — planning rigor is a spectrum chosen per piece: P0 mini-requirements and pointers (simple, reversible work) · P1 an authored spec with a proof contract (the default) · P2 plus a research round before the spec freezes, run BEFORE build dispatch · P3 plus an adversarial pass by a non-author, judged against product goals, landing amendments with proof-contract teeth · P4 plus a blind from-scratch design diffed against priors before proceeding. Dial up by what the piece is, exactly as build care is priced below. Full reference: `planning-dial.md`. |
|
||||
| **BUILD** | **Part A, the simple flow** (below — the default) · **product-journey components** — a mission-selectable menu for greenfield work, drift recovery, public journey probes, one evidence-gated look at the layer below, minimal repair, independent QA/review, integration, and installed smoke; compose only what the work needs in mission/slice YAML, never as a new mode or mandatory pipeline. Full reference: `product-journey-sdlc.md` · **the wave model** — slices build in parallel in disjoint file territories, an integrator merges serially, and independent review fires once per wave (two reviewers with different vantages, never the writers; fix rounds re-earn verdicts at one final revision; per-slice discipline stays failing-test-first and verify-by-effect). The wave IS the care dial: what shares a wave decides how much review each piece gets · **Part B, the rigorous overlay** (below — only when assigned). These combine: a wave can carry one Part-B piece. Full wave reference: `wave-sdlc.md`. |
|
||||
| **DISPATCH DATA** | **The execution-data conventions (S27)** — three tiny data disciplines that make execution state derivable instead of hand-tabulated, consumed by `rig view show execution`. **EC-1, edges in frontmatter:** every open slice carries its hard edges in `depends_on:` (an inline JSON array; an explicit `[]` is a statement, absence is INDETERMINATE; when the slice's `slice.yaml` carries `execution.depends_on`, that list takes precedence); soft/serialization edges are one machine-readable Territory line, exactly `SOFT-AFTER: [ids] — reason`. **EC-2, wave-as-data:** wave composition + review model live in `mission.yaml` `arrangement.waves` (`{id, slices, review_model?}`; a slice may also name its wave in `slice.yaml` `execution.wave`). Only when the mission has no `mission.yaml`, or it is malformed, does the view fall back to the legacy form: the newest queue row tagged `format:wave-map-v1` and `mission:<mission>` whose body carries one fenced ```json block (`{format:"wave-map-v1", mission, waves:[{id, slices, serialized_order?, review_model?}]}`) — composition only, never status labels (status derives at read time); the planning dial recorded at lock surfaces as the frontmatter field `approved-spec-dial:` beside the approve stamp. **EC-3, dispatch names the worktree:** build batons carry the exact body line `worktree_path=<path>` from dispatch onward — it is Q1's join key; batons without it join by naming only and the view marks them `fragile_join`. **Lanes:** Q1 lists each in-progress row as a lane; a row parked on `external:<what>` also appears as a waiting lane, marked `waiting: {on}`. `external:` records an outside dependency (a review, a decision, a capacity limit, a lifecycle step); it does not mean an outside party owns all the work, or that the parked seat is the slice's builder. The views show it as a waiting row (the seat, the blocker, a link to the row), not as the slice's assignment. It yields to an in-progress lane on the same slice, and it is not counted in `lanes_live`, so `q1_lanes` can be longer than `lanes_live`. Rows parked on a qitem, a human seat, or a `fold:`/`auth:` gate are not lanes. Existing batons are never rewritten. |
|
||||
| **DISPATCH DATA** | **The execution-data conventions (S27)** — three tiny data disciplines that make execution state derivable instead of hand-tabulated, consumed by `rig view show execution`. **EC-1, edges in frontmatter:** every open slice carries its hard edges in `depends_on:` (an inline JSON array; an explicit `[]` is a statement, absence is INDETERMINATE); soft/serialization edges are one machine-readable Territory line, exactly `SOFT-AFTER: [ids] — reason`. **EC-2, wave-as-data:** wave composition + review model live on a durable queue row tagged `wave-map` + `format:wave-map-v1` whose body carries one fenced ```json block (`{format:"wave-map-v1", mission, waves:[{id, slices, serialized_order?, review_model?}]}`) — composition only, never status labels (status derives at read time); the planning dial recorded at lock surfaces as the frontmatter field `approved-spec-dial:` beside the approve stamp. **EC-3, dispatch names the worktree:** build batons carry the exact body line `worktree_path=<path>` from dispatch onward — it is Q1's join key; batons without it join by naming only and the view marks them `fragile_join`. Existing batons are never rewritten. |
|
||||
| **RELEASE** | The release ceremony conventions (publication identity, honest release notes) and the CAPABILITY-DELTA LIFECYCLE LAW: each release's delta is authored at the fence and bound to the exact candidate, then reconciled to the published cut. Expiry requires both the canon header naming the absorbed delta and a distinct successor delta existing; a draft header alone is insufficient. Verify the actual boundary event and stop citing an expired delta. Full statement: `release-boundary.md` §6. |
|
||||
| **BOUNDARY** | **The release boundary** — housekeeping run once per fence so the next release starts clean: seats reset or re-primed per their continuity needs, memory distilled (keep what changed a decision recently), every queue swept by destination and dispositioned, substrate torn down, boards frozen as records, a clean-box baseline captured. A checklist of judgment guides, not gates. Full reference: `release-boundary.md`. |
|
||||
|
||||
@@ -46,7 +46,7 @@ one does not deprecate the others. Nothing below deletes or overrides an existin
|
||||
> planning dial — `planning-dial.md` · the product-journey component catalog —
|
||||
> `product-journey-sdlc.md` · the wave model — `wave-sdlc.md` · the release
|
||||
> boundary (including the capability-delta lifecycle law) — `release-boundary.md` ·
|
||||
> the mission install — `mission-install.md`. The
|
||||
> the mission install — `mission-install.md` (lands with its own slice). The
|
||||
> summaries above remain the one-glance description; this document remains the SSOT
|
||||
> pointer for the whole menu.
|
||||
|
||||
@@ -76,32 +76,11 @@ The authority lookup is `product-journey-sdlc.md#resolve-the-selected-path`.
|
||||
Bring work with evidence that its promised user outcome actually works.
|
||||
|
||||
For a release mission, `mission.yaml` also names the Git strategy before build
|
||||
work starts: the branch/ref that is cumulative integration truth
|
||||
(`arrangement.source.integration_ref`, the ref `rig view show execution` tests
|
||||
a candidate's folding against; `main` when unset), its base, and when that
|
||||
truth is reconciled to main. Continuous integration to main and a
|
||||
work starts: the branch/ref that is cumulative integration truth, its base, and
|
||||
when that truth is reconciled to main. Continuous integration to main and a
|
||||
release-line fold followed by one explicit merge are both valid; leaving the
|
||||
choice implicit is not.
|
||||
|
||||
A candidate that merges by squash or rebase is never an ancestor of that ref, so
|
||||
ancestry alone cannot read it as merged. A `merged:<pr-number>` tag on a queue row
|
||||
bound to the slice (the `slice:` tag, like `candidate:`) is a recorded report of a
|
||||
merge, not a verified one: `rig view show execution` shows it on the "merged" rung
|
||||
(`folded`) as `merge_report` (`pr`, `row`, `recorded_at`, `linked`) and in the basis
|
||||
text, and `recorded_at` is when the row recorded the merge, not when it happened.
|
||||
A report never changes the merged answer by itself: without a candidate, with an
|
||||
unresolvable candidate, with an unusable declared integration ref or with no
|
||||
repository context, the answer, next-up and dependent slices stay as ancestry gives
|
||||
them. A row that carries a `merged:` tag is a report, not a build, so it never picks
|
||||
which commit counts as built: that stays the newest `candidate:<sha>` tag on a row
|
||||
without a `merged:` tag. A report is `linked: true` when its own row's `candidate:<sha>`
|
||||
resolves, through the repository context, to that built commit, and `linked: false`
|
||||
otherwise (no candidate on the row, or a different commit). The answer changes only
|
||||
for a linked report when ancestry answered false (not an ancestor): then the rung
|
||||
reads merged and the basis says so. A linked report never turns an answer ancestry
|
||||
could not give into merged. The report never changes which commit counts as built
|
||||
or reviewed.
|
||||
|
||||
**The heavier flow — proof contracts, plan-lock, C1 drops, proof-lock — is PART B and is not in
|
||||
force unless assigned.**
|
||||
|
||||
@@ -120,75 +99,36 @@ Each slice directory carries:
|
||||
(numbered list). This is the human operator's first structured catchpoint;
|
||||
approval starts here.
|
||||
- **`## Proof contract`** — a checkbox list of promised deliverables (see
|
||||
B1). The UI's DELIVERED section pairs each item with its proof.
|
||||
§3). The UI's DELIVERED section pairs each item with its proof.
|
||||
- **`PROGRESS.md`** — the slice's current delivery state and retained outcome
|
||||
log. Record material changes with links to proof; historical checkboxes are
|
||||
testimony, not current acceptance authority. For a selected proof policy,
|
||||
`rig proof show <mission>/slices/<slice>` derives current readiness from the proof contract
|
||||
`rig proof show <slice>` derives current readiness from the proof contract
|
||||
and attributed judgments. In-process steps stay in the working agent's
|
||||
own todo tool.
|
||||
- **`PROOF.md`** — the retained proof summary, explicitly paired to the
|
||||
`SPEC.md` proof contract.
|
||||
- **`proof/`** — the proof-artifact directory. Curated canonical evidence
|
||||
lands here via `rig proof` with valid C1 headers (B3).
|
||||
lands here via `rig proof` with valid C1 headers (§5).
|
||||
|
||||
Legacy `README.md`, `IMPLEMENTATION-PRD.md`, and pre-convention trees remain
|
||||
readable indefinitely. New scaffolds do not create or mirror them, and repair
|
||||
is additive: it never deletes, renames, or rewrites legacy bytes.
|
||||
|
||||
A slice's frontmatter carries `stage:` (`wip`, `provisional`, `established`,
|
||||
`canonical`, or the exits `superseded` and `retired`) and `verified:`
|
||||
(`<date> against <source>`). Set them with `rig scope slice stage <slice> <stage>`
|
||||
and `rig scope slice verified <slice> --against <source>`; no approval stamp
|
||||
changes either. `rig scope` reads an `established` or `canonical` slice whose
|
||||
`verified:` is missing, has no source, names a tool-scaffolded placeholder, or is
|
||||
older than 90 days as `provisional`.
|
||||
|
||||
When the owning scope selects `proofPolicy.judges`, use `rig proof judge` to
|
||||
record an attributed accept, reject or withdraw decision on a contract item,
|
||||
and `rig proof show` to read derived readiness up through slice, mission and
|
||||
project. The nearest slice, mission or project policy selects authorized judges;
|
||||
`rig proof --help` describes setup, selectors and evidence requirements. In a
|
||||
multi-project workspace catalog, name the project with `--project <id>` or a
|
||||
`<id>:` scope prefix (`alpha:m0/slices/01-t001`); unqualified scopes use the
|
||||
daemon's selected workspace. The prefix counts only when it names a catalogued
|
||||
project and no scope exists at that literal path, so a mission folder with a
|
||||
colon (`alpha:trial/slices/01-t001`) still resolves as written. The scopes views
|
||||
read a catalog project's readiness against the same project root, so they agree
|
||||
with `rig proof show`. A catalog-project read names the project
|
||||
(`project: { id, root }`) and reports its source watcher as unavailable; a
|
||||
judgment carries that root and is refused (409 `project_changed`) if the
|
||||
catalog has since moved the project. A
|
||||
`rig proof --help` describes setup, selectors and evidence requirements. A
|
||||
correction preserves history and unrelated judgments without editing ancestor
|
||||
status checklists. An artifact can identify non-code work without a fabricated
|
||||
commit. Evidence capture (`proof add`), policy acceptance, higher outcome
|
||||
judgment and publication are distinct. This optional component does not select
|
||||
Part B or add a mandatory review gate.
|
||||
|
||||
A judgment binds the slice's path, the item's text and the policy. Moving or
|
||||
renaming a slice (`rig scope slice move`, or by hand) reopens its judged items:
|
||||
`rig proof show` reports each as `unknown`, and each needs a new judgment on its
|
||||
current revision. `rig scope audit` checks structure only and never reads proof
|
||||
readiness, so a passing audit doesn't mean the proof still stands.
|
||||
|
||||
The project readiness that `rig proof show --project` reports counts only
|
||||
missions whose `mission.yaml` carries `metadata.status: active` or
|
||||
`metadata.status: release-candidate`. `rig scope mission create` writes
|
||||
`metadata.status: planned`, for ordinary and release missions alike, so creating
|
||||
a mission does not change the project's readiness. A `planned` mission stays
|
||||
outside the rollup, even after its slices are accepted, until someone changes
|
||||
its status to `active` (or `release-candidate` for a release that is ready to
|
||||
judge). Nothing changes the status automatically. Missions created before this
|
||||
default carry no status and are not counted either; add the line by hand to
|
||||
include them. It also writes `metadata.name`, the mission's folder name, which
|
||||
the project lifecycle compiler requires; a mission created without it refuses to
|
||||
compile with `lifecycle_field_missing` until you add that line.
|
||||
|
||||
The three sections project into the UI's one review structure: a vertical
|
||||
stack of **INTENT → PLAN → DELIVERED**. A slice missing a section still
|
||||
renders (a missing Intent or Delivered source shows a muted "—", missing
|
||||
mini-requirements show "Not compliant · mini-requirements not authored";
|
||||
nothing is invented) —
|
||||
renders (the projection degrades to a muted "—", never invents content) —
|
||||
but it does not carry its weight in review.
|
||||
|
||||
## A3. Honesty rails (public surfaces + cited hashes)
|
||||
@@ -269,31 +209,24 @@ are losslessness checks on the decompression from intent to delivery, not
|
||||
paperwork. Scaffolding emits the sections; it must never mint ceremony.
|
||||
## A6. The audit (advisory, fail-open — always)
|
||||
|
||||
`rig scope audit --mission <name>` (and the advisory `sdlc_convention_sections`
|
||||
row in `rig workspace doctor`) checks these conventions: the section headings
|
||||
present, the proof contract well-formed, `proof/` artifacts carrying valid C1
|
||||
headers, UI slices referencing a mockup. Convention findings are low or info
|
||||
severity, except an invalid C1 header on a `proof/` artifact, which is medium.
|
||||
All of them **record and advise — they never block a write path and never
|
||||
change the exit code**. (`rig scope audit` exits 1 only on high-severity
|
||||
structural findings, such as a missing `PROGRESS.md` or id.) Unknown is
|
||||
`rig scope audit` (and the advisory rows in `rig workspace validate` /
|
||||
`doctor`) checks these conventions: the section headings present, the proof
|
||||
contract well-formed, `proof/` artifacts carrying valid C1 headers, UI slices
|
||||
referencing a mockup. Every finding **records and advises — it never blocks a
|
||||
write path and never changes exit semantics into a gate**. Unknown is
|
||||
reported as unknown, not failure.
|
||||
## A7. Where the knowledge lives (the four pointers)
|
||||
|
||||
- **This document** — the SSOT.
|
||||
- **Scaffold**: `rig scope slice create` emits `SPEC.md` + `slice.yaml` +
|
||||
`PROGRESS.md` + `PROOF.md` + `proof/` for every template kind (and registers
|
||||
the slice in `mission.yaml` when that manifest exists; legacy missions
|
||||
without one remain supported); `rig scope mission create` emits an
|
||||
intent-bearing `SPEC.md` + `mission.yaml` + `PROGRESS.md` + `NOTES.md` +
|
||||
`slices/` (plus `CAPABILITY-DELTA-v<version>.md` for a `release-X.Y.Z`
|
||||
mission). Core emits only this
|
||||
- **Scaffold**: `rig scope slice create` emits `SPEC.md` + `PROGRESS.md` +
|
||||
`PROOF.md` + `proof/` for every template kind; `rig scope mission create`
|
||||
emits an intent-bearing `SPEC.md` + `NOTES.md`. Core emits only this
|
||||
mode-neutral shape; mode plugins add richer material through the extension
|
||||
seam rather than teaching core a mode.
|
||||
- **Skill**: `mission-slice-sop` teaches **Part A**, the light default. **Part B**
|
||||
is defined below and applies only when assigned — never self-selected.
|
||||
- **Bootstrap**: the shipped `pm` rig culture points its seats at the skill
|
||||
and this document; the generic `openrig-start.md` overlay no longer does.
|
||||
- **Bootstrap**: the shipped agent overlay points fresh seats at the skill
|
||||
and this document at boot.
|
||||
|
||||
# PART B — THE RIGOROUS OVERLAY (assigned only)
|
||||
|
||||
@@ -333,8 +266,7 @@ deliverable, written as an observable outcome:
|
||||
that evidence it — that pairing is what the DELIVERED section renders, so
|
||||
the human never hunts through dozens of artifacts to find which one proves
|
||||
what.
|
||||
- **UI deliverables carry a planned mockup** (`plannedRef`, written as an
|
||||
inline image on the checkbox line, e.g. `- [ ] … `): the planning
|
||||
- **UI deliverables carry a planned mockup** (`plannedRef`): the planning
|
||||
agent produces the mockup and attaches it to the locked set. A UI slice
|
||||
with no mockup in its locked set is an incomplete plan. Non-UI slices
|
||||
(backend, skills, markdown) have no mockup and no `plannedRef` — that is
|
||||
@@ -351,18 +283,14 @@ append-only audit row land together):
|
||||
- **Plan-lock:** `rig scope slice approve <slice> --scope spec` — "the spec
|
||||
matches my intent; THIS artifact set is what gets built." Pins `SPEC.md`
|
||||
(and planned mockups, when present) out of everything else in the folder.
|
||||
`--locked-artifacts "SPEC.md,…"` names the set explicitly instead; a
|
||||
plan-lock on an unedited scaffold `SPEC.md` with nothing else to pin refuses.
|
||||
- **Proof-lock:** `rig scope slice approve <slice> --scope delivery`
|
||||
(the default scope) — the terminal "this is done" sign-off. (It does not
|
||||
render the frozen export; the approve result reports `freezeFired: false`.)
|
||||
(the default scope) — the terminal "this is done" sign-off; fires the
|
||||
freeze.
|
||||
|
||||
Approval is freeze/sign-off — **never** proven-green. Proven-green requires a
|
||||
recorded verdict (a C1 proof artifact, B3); presence of an approval stamp does
|
||||
recorded verdict (a C1 proof artifact, §5); presence of an approval stamp does
|
||||
not assert the work was proven. `--on-behalf-of` records delegation honestly
|
||||
(the actor stays the real invoking session). A second approve of the same
|
||||
scope refuses; `--re-approve --reason "<why>"` supersedes the stamp and keeps
|
||||
the prior one in the audit log.
|
||||
(the actor stays the real invoking session).
|
||||
|
||||
## B3. Proof drops and the C1 header (closed sets)
|
||||
|
||||
@@ -395,11 +323,9 @@ that it LOOKED at the evidence. `--media` names the curated media files
|
||||
(relative to the slice's `proof/` dir — co-located, never absolute) this
|
||||
drop stands behind; the composer projects them into the DELIVERED items'
|
||||
proof set. Validation happens at drop time; the audit
|
||||
(A6) backstops artifacts that arrived by other paths. **Hand-placing files
|
||||
in `proof/` without a drop is the anti-pattern**: media alone pairs with
|
||||
nothing, so a deliverable with no covering proof artifact (one whose
|
||||
`evidences` names it) shows as `missing` in the DELIVERED view, or as current
|
||||
acceptance absent under a selected proof policy — always attach media via
|
||||
(§6) backstops artifacts that arrived by other paths. **Hand-placing files
|
||||
in `proof/` without a drop is the anti-pattern**: the deliverable stays
|
||||
unpaired and `unverified` in the DELIVERED view — always attach media via
|
||||
`--media` on a drop.
|
||||
|
||||
## B4. Role contracts (what makes the structure self-enforcing)
|
||||
|
||||
@@ -1,263 +0,0 @@
|
||||
# Per-seat terminal delivery
|
||||
|
||||
The typing guard has six modes. `off` and `hold` are the two ends. Draft-aware adds an
|
||||
opt-in check for unfinished input without a second control or daemon-owned retry
|
||||
scheduler. Between off and hold, three interruption levels choose which automatic messages may
|
||||
type: `openrig-urgent`, `urgent-only` and `sends-only`. Sibling seats keep their own mode.
|
||||
|
||||
| Mode | Terminal input | When input is unavailable |
|
||||
|---|---|---|
|
||||
| `off` (default) | Existing delivery and prompt checks | Existing send result |
|
||||
| `draft-aware` | Paste into a recognized empty composer; check ownership again before Enter | Hold input and retain this attempt for inspection when bookkeeping is available |
|
||||
| `openrig-urgent` | OpenRig's own messages (watchdogs, scheduled wakes, notices) and anything marked urgent type, never over a draft | Other agents' messages are held, the sender is told, and held messages stay readable |
|
||||
| `urgent-only` | Only messages marked urgent type (`rig send --urgent`, or a queue item at priority urgent or critical), never over a draft | Everything else is held, the sender is told, and held messages stay readable |
|
||||
| `sends-only` | Deliberate sends from people and agents type, as with `off`; a terminal member's typing isn't protected, because its shell input can't be read | OpenRig's own notices are held. A terminal member defaults to this level |
|
||||
| `hold` | No automatic terminal input, even at an empty prompt | Retain for inspection outside the pane |
|
||||
|
||||
Lifecycle work is refused at `openrig-urgent` and `urgent-only`, as at `hold`.
|
||||
|
||||
A terminal member (`runtime: terminal`) defaults to `sends-only`, which holds OpenRig's own notices. Set one
|
||||
to `off` and those notices, such as park reminders and other watchdog messages, type into whatever the pane
|
||||
is running, and a shell prompt runs each line as a command, From and To lines included: OpenRig doesn't check
|
||||
a terminal pane's foreground process. `openrig-urgent` and `draft-aware` type only into a recognized empty agent composer, so
|
||||
a shell prompt holds them. Keep the default for a seat that may fall back to a shell.
|
||||
|
||||
Runtime permissions are separate. Recipient and interactive-prompt checks still
|
||||
apply. `--raw` and `--force` do not bypass the typing guard. A deliberate
|
||||
`--dangerously-interact --reason` remains available at every interruption level
|
||||
and uses the existing-input check below. Direct human input remains available.
|
||||
|
||||
A message sent to a busy Codex seat joins its running turn and may redirect it.
|
||||
For separate work, create a queue row instead:
|
||||
`rig queue create --destination <seat> --summary "<one line>" --body-file <file>`.
|
||||
A row that's saved keeps the work apart from its wake, the short pointer typed
|
||||
into the seat. The wake is still typed input, and it isn't proof that the seat
|
||||
claimed or finished the work: the row's state says that.
|
||||
|
||||
`rig send <seat> "<message>" --wait-for-idle <seconds>` suits a sender who
|
||||
watches the result. If the seat is still busy, or its activity is unknown, when
|
||||
the wait ends, nothing is sent (exit 1, "No text was sent.") and OpenRig keeps
|
||||
nothing to send later.
|
||||
|
||||
## Configure and inspect
|
||||
|
||||
### Who may intervene
|
||||
|
||||
`rig seat status <seat>` shows the seat's terminal interaction account alongside
|
||||
its native permissions and interruption level. These choices are independent.
|
||||
The presets `no-peer-interventions`, `help-within-instructions` and `full-control`
|
||||
set the peer row. Self and OpenRig retain their existing authority unless an
|
||||
explicit exception changes it. Named helpers and the delegating instruction are
|
||||
shown; OpenRig does not interpret free-text instructions as executable rules.
|
||||
|
||||
~~~sh
|
||||
rig seat set-terminal-policy reviewer@my-rig --preset help-within-instructions \
|
||||
--helper lead@my-rig --peer-model deny \
|
||||
--reason "Help with compaction; keep the review model"
|
||||
rig seat status reviewer@my-rig
|
||||
~~~
|
||||
|
||||
Each `--peer-compaction`, `--self-compaction`, `--openrig-compaction`,
|
||||
`--peer-model`, `--self-model` or `--openrig-model` exception takes `allow` or
|
||||
`deny`. Model includes reasoning effort. Exceptions apply to the whole actor
|
||||
row: `--peer-compaction allow` also allows unnamed peers. A choice with
|
||||
exceptions reads as Custom. The setter replaces the complete choice; omit
|
||||
exceptions to return to the preset's defaults. Outside a managed seat, use `--operator <address>` for
|
||||
audit attribution. This does not establish an authenticated identity.
|
||||
|
||||
Enforcement covers managed compaction and saved model/effort changes only.
|
||||
The latter take effect at the next managed continuation, not in the current
|
||||
process. Other interventions remain guidance-only. Managed compaction applies
|
||||
to Claude seats; it is not offered for Codex or Pi. A policy change during
|
||||
preparation is checked before further input. It does not undo a submitted
|
||||
`/compact` or abandon an already-owed restore/audit.
|
||||
|
||||
Existing seats retain current behaviour on upgrade. To choose a default for
|
||||
newly added seats in a rig, add `--rig-default` to the setter above: existing
|
||||
seats keep their own copied choices. OpenRig's standing managed-compaction
|
||||
authority stays active unless its exception is deliberately changed.
|
||||
|
||||
Caller attribution is cooperative. An unattributed caller retains current
|
||||
behaviour rather than being labelled the person or a peer. The existing
|
||||
`rig send --dangerously-interact --reason` path remains available; this policy
|
||||
adds no restriction there. Its existing-input check applies independently of the
|
||||
typing mode. Plain tmux is not prevented.
|
||||
|
||||
### Deliberate interaction and existing input
|
||||
|
||||
A managed `rig send <seat> "<answer>" --dangerously-interact --reason "<why>" can
|
||||
drive a recognized native menu as before. Otherwise, with the delivery guard
|
||||
attached, it reads the visible composer under the seat's lease immediately before
|
||||
pasting, after buffer preparation. Empty input proceeds. A recognized dim
|
||||
suggestion is displayed separately and counts as empty; typed or pasted text
|
||||
(author unknown) stops the send with `override_input_present`. An unreadable input
|
||||
stops with `override_input_unknown`, never an empty-input claim. Both return single-send HTTP
|
||||
409, `sent: false`, and caller-only `existingInput` evidence (visible rows, suggestion
|
||||
rows, cursor/dimensions and target binding). A collapsed paste shows its label,
|
||||
not the hidden contents. OpenRig neither holds nor retries this stopped override.
|
||||
|
||||
Inspect the shown input in the native terminal, deliberately clear the prompt with
|
||||
native/tmux controls, then issue the send again. Manual clearing runs outside
|
||||
OpenRig's lease and observation checks and is not recorded. For a deliberate
|
||||
unchecked write, add `--type-without-checking` to that same command. It skips the
|
||||
read and does **not** clear input: the text may join or submit what is already there.
|
||||
The result names that choice. It requires `--dangerously-interact` and `--reason`.
|
||||
|
||||
Observed input is returned only to the caller, never saved in an outbox, held
|
||||
message, capture-observer record or override audit. The audit keeps classifications,
|
||||
counts and the choice, without input contents. The lease serializes OpenRig writes;
|
||||
human typing can still race the capture and paste. Ordinary sends and wakes keep
|
||||
their existing behaviour.
|
||||
|
||||
### Terminal delivery
|
||||
|
||||
Run from a seat shell with `OPENRIG_SESSION_NAME` set; the daemon derives the
|
||||
audit actor from transport identity.
|
||||
|
||||
~~~sh
|
||||
rig seat set-typing-guard dev-impl@my-rig --mode draft-aware \
|
||||
--reason "preserve my unfinished input"
|
||||
rig seat status dev-impl@my-rig
|
||||
rig seat held-messages dev-impl@my-rig --json
|
||||
rig seat held-messages dev-impl@my-rig --id <outbox-id> --json
|
||||
rig seat retire-held-message dev-impl@my-rig <outbox-id> --reason "read outside the pane"
|
||||
~~~
|
||||
|
||||
Use exactly one of `--mode off|draft-aware|openrig-urgent|urgent-only|sends-only|hold` or the compatible
|
||||
`--enabled true|false`: true selects hold, false selects off. There are no
|
||||
retry settings or deadlines. Activation waits for an already-started seat operation
|
||||
to finish. The API may return HTTP 202 with `pending: true`; wait for
|
||||
`pending: false` before relying on the requested mode. Status reports desired
|
||||
and effective modes and retains the text `Typing guard: on (hold)` for hold.
|
||||
|
||||
A held send immediately returns `outcome: "retained"`, `sent: false`, its exact
|
||||
reason (such as `draft_input_busy`) and the saved attempt's `outboxIds`. No automatic
|
||||
retry is scheduled. Each explicit draft-aware request is a new attempt, including
|
||||
one with a reused `deliveryId`; the result warns older callers that this field no
|
||||
longer deduplicates input. The CLI does not generate a deduplication key.
|
||||
|
||||
Clearing a draft, changing modes or restarting does not flush saved messages or
|
||||
callbacks. To try again, send a current request: it rechecks the recipient and input.
|
||||
A caller abort before paste cancels input; after a write may have started, the
|
||||
result preserves that uncertainty rather than claiming nothing was sent.
|
||||
|
||||
Bookkeeping is observational. If its write fails, an otherwise valid input attempt
|
||||
still proceeds and the response includes a warning instead of a saved receipt.
|
||||
Actual transport success stays success; an unknown write stays unknown. If input
|
||||
was held and no record could be saved, the response reports failure with `sent:
|
||||
false` and the protection reason, rather than claiming durable custody.
|
||||
|
||||
Reading never sends. Retirement frees that record's active retention quota while
|
||||
preserving evidence; it does not deliver a message or close queue work.
|
||||
|
||||
## Input evidence and outcomes
|
||||
|
||||
The cursor-aware reader lives in `session-transport.ts` and shares the composer
|
||||
matchers with ordinary delivery. It recognizes framed Claude input and Codex input
|
||||
with a known footer. The visible input containing the cursor is checked independently
|
||||
of activity hooks, again after buffer preparation, and immediately before Enter.
|
||||
Copy mode, an unreadable capture and an unsupported layout cannot authorize input.
|
||||
|
||||
The final check preserves authored whitespace: the cursor distinguishes trailing
|
||||
spaces from screen padding or omitted blank capture cells. A numbered message is
|
||||
recognized as this operation's own text only within its previously empty composer;
|
||||
a newly observed numbered menu is still refused. Human edits after paste stay
|
||||
visible and Enter is refused.
|
||||
|
||||
Faint placeholders and autocomplete suffixes are display hints only when the
|
||||
capture preserves their styling. Typing the same words and moving the cursor to
|
||||
the start still counts as a draft. Current footer and indentation anchor the
|
||||
Claude frame, so quoted prompt/frame examples inside a draft do not become proof
|
||||
of empty input.
|
||||
|
||||
A large paste can appear as several labels plus a literal tail. The existing
|
||||
`hasExpectedStagedText` check validates the tail and the labels' combined source
|
||||
boundary. That complete rendering must be observed after this operation's paste
|
||||
and remain unchanged before Enter. Labels alone do not prove arbitrary content.
|
||||
|
||||
| Historical delivery state | Meaning |
|
||||
|---|---|
|
||||
| `sending` | This saved attempt has an unresolved write outcome |
|
||||
| `held` | No input was written; this attempt remains retained or has been retired |
|
||||
| `complete` | Transport execution succeeded, including render verification if requested; native consumption is not asserted |
|
||||
| `indeterminate` | Input may have occurred or requested render verification failed |
|
||||
| `failed` | A definite failure before input, such as caller cancellation |
|
||||
|
||||
Migration `100_typing_guard_modes` extends the existing guard/audit rows and
|
||||
adds receipt metadata to the original outbox rows; it creates no tables, retry
|
||||
indexes or executable requests. Combined wakes retain each original ID and body.
|
||||
A held queue wake stays on the existing queue recovery path. Interrupted historical
|
||||
writes become indeterminate at startup. That history never suppresses a current
|
||||
explicit request and is not consulted to determine its result.
|
||||
|
||||
At startup, the queue recovery pass retries still-current failed or unconfirmed
|
||||
wake notifications. It preserves their original envelopes and warns that delivery
|
||||
may repeat. Each notification is attempted once per pass, including coalesced
|
||||
wakes; a failed attempt cannot spin in that pass. A no-write failure on a later
|
||||
retry does not resolve an earlier unknown delivery. Prior-process claims are
|
||||
reconciled before new startup sends can begin. Known deliveries and held or
|
||||
retired messages stay untouched. Closed, claimed or reassigned work is not woken,
|
||||
and the retry never repeats the queue mutation or a lifecycle action.
|
||||
|
||||
The existing retention limits apply: 100 records and 8 MiB per seat, with a 1 MiB
|
||||
message limit. Hold mode cannot retain another message at capacity. Draft-aware
|
||||
input attempts continue with a bookkeeping warning if a record cannot be saved;
|
||||
already-committed queue intent remains durable.
|
||||
|
||||
## Rollback and lifecycle
|
||||
|
||||
Persisted legacy guard bits are on for both hold and draft-aware, so an older
|
||||
daemon holds messages instead of typing into a protected seat. On re-upgrade,
|
||||
the most recent guard audit row and change timestamp determine whether the saved
|
||||
mode is still authoritative. A later boolean write by the older daemon takes
|
||||
precedence, including a same-value on-to-on write in the same clock tick.
|
||||
Without a later setting change, the draft-aware mode survives re-upgrade.
|
||||
Held and uncertain deliveries are never replayed by this reconciliation.
|
||||
|
||||
Current API `desired` and `effective` booleans continue to describe hold-all;
|
||||
mode fields describe draft-aware protection. Storage's fail-safe legacy bits
|
||||
are deliberately broader.
|
||||
|
||||
With hold, writing lifecycle operations refuse before effects. With draft-aware,
|
||||
an active seat requires an explicit switch to off before writing lifecycle work.
|
||||
Fresh startup is exempt only after creating a new pane or successfully respawning
|
||||
a dead pane within the same lifecycle operation. Adopting or rebinding an existing
|
||||
pane grants no such exemption.
|
||||
|
||||
Terminal capture is observational, not an atomic editor API. A direct tmux writer
|
||||
can still act between the last observation and paste. The resulting changed input
|
||||
refuses Enter and is not replayed. Unsupported provider layouts remain held.
|
||||
Use off when that tradeoff is unsuitable.
|
||||
|
||||
HTTP configuration uses `POST /api/seat/set-typing-guard/:seatRef` with
|
||||
`{mode, reason}` or `{enabled, reason}`. Status and held-message routes are
|
||||
unchanged; no RigSpec field is required.
|
||||
|
||||
## Verification scope
|
||||
|
||||
Regression tests exercise rollback/re-upgrade, same-value legacy writes, exact
|
||||
retained outcomes, current requests after restart, coalesced queue bodies, trailing
|
||||
spaces, numbered bodies, real-menu refusals and multi-placeholder ownership. Native tests
|
||||
use private real tmux panes with scripted editable composers. These verify the
|
||||
transport mechanics; they are not live Claude/Codex provider sessions.
|
||||
|
||||
## Watchdog reminders
|
||||
|
||||
A currently due watchdog reminder makes a new delivery attempt, including after an interrupted attempt or job
|
||||
accounting. Historical outbox receipts do not suppress a lone reminder or prevent it from joining a digest. The
|
||||
message tells its recipient that delivery may repeat after an unconfirmed attempt. Its job history records the
|
||||
current transport result; an unknown write is not proof that nothing arrived.
|
||||
|
||||
The transport still protects approval/question prompts, human drafts and recipient identity. Scheduler timing,
|
||||
current parked-row eligibility and stop checks still apply. This changes message retries, not the idempotence of
|
||||
structured continuity actions such as creating a cutover baton.
|
||||
|
||||
The parked-owner supervisor also retries current obligations despite an earlier failed, unknown or unrecorded attempt.
|
||||
Its first reminder to a seat waits until the seat's waiting state has been unchanged for 5 minutes, then goes on the next
|
||||
watchdog tick, so a seat that just handed work off or asked a person isn't interrupted; a seat still holding the work after
|
||||
that is reminded as before. A seat at an approval or question prompt gets no grace, so the prompt-blocked alert isn't delayed.
|
||||
A recorded success to the same known occupant waits for a change in its obligations. Rotation includes retained attempts,
|
||||
so a held input cannot starve another owner. Interactive prompts stay with the existing prompt-refusal recovery.
|
||||
Its own reminders wait while managed compaction owes the turn boundary, restore or audit, including a fresh check
|
||||
at the paste and Enter boundary. A stage that begins after paste leaves an honest partial-input result; OpenRig
|
||||
does not erase or replay that text. Peer messages and unrelated reminder policies keep their existing behavior.
|
||||
@@ -1,17 +0,0 @@
|
||||
# Seat settings by node ID
|
||||
|
||||
Clients that present a specific seat can save its later-launch settings using its durable `nodeId`. The node ID is distinct from the current session and native conversation. These routes never launch, stop, or resume the seat.
|
||||
|
||||
| Read or save | Node-addressed route |
|
||||
| --- | --- |
|
||||
| Status | `GET /api/seat/status/node/:nodeId` |
|
||||
| Native permissions | `POST /api/seat/set-permissions/node/:nodeId` |
|
||||
| Permission policy | `POST /api/seat/set-policy/node/:nodeId` |
|
||||
| Model | `POST /api/seat/set-model/node/:nodeId` |
|
||||
| Effort | `POST /api/seat/set-effort/node/:nodeId` |
|
||||
|
||||
The POST bodies and responses follow the corresponding name-addressed routes. A successful save's `seat.nodeId` and `seat.rigId` identify the node actually updated. The exact status response adds `node_id`, `contract: "seat-node.v1"`, and `supported_actions` listing the four setters. Existing name status responses retain their shape.
|
||||
|
||||
An unknown, deleted, or archived node returns `seat_not_found` (HTTP 404) at node resolution. After awaited validation of a native Claude permission mode or Codex profile returns, the exact node-ID path checks availability again before saving; an unavailable node then returns `seat_not_found` without a setting or audit write. Existing native validation may refuse a changed target before this check: for example, Claude's managed context guard can report `permission_selection_refused` during preparation. The daemon never resolves a node ID through a reusable seat name. Setting writes have no general session precondition; a changed occupant on the same available node can receive a later save.
|
||||
|
||||
For example, `POST /api/seat/set-model/node/<nodeId>` accepts the existing `{ "model": "...", "reason": "...", "operator": "..." }` body. The existing audit actor, reason, native validation, permission precedence, and terminal policy rules still apply. The older `/:seatRef` routes remain available, including their name ambiguity behavior.
|
||||
@@ -30,13 +30,8 @@ been confirmed against a real creation run. Slack's form may ask for something t
|
||||
not fill in; if so, follow the form.
|
||||
|
||||
1. Open the link from `rig slack manifest --url` in a browser.
|
||||
> **Note on Slack's manifest dialog:** If opening the link results in an empty manifest `{}`
|
||||
> or Slack reports an error translating the manifest, copy the output of `rig slack manifest`
|
||||
> (run without flags) and paste it directly into the **YAML** tab in Slack's "Create an app from
|
||||
> an app manifest" dialog.
|
||||
2. Sign in to Slack if asked, pick the workspace, review the prefilled manifest, and click
|
||||
**Next**, then **Create**. (If **Create** stays disabled, go **Back** and check that a
|
||||
development workspace is selected and the manifest step shows no error).
|
||||
**Create**.
|
||||
3. Under **Socket Mode**, confirm it is enabled. Enable it if it is not.
|
||||
4. Under **Basic Information → App-Level Tokens**, generate a token with the
|
||||
`connections:write` scope and copy it (it starts with `xapp-`).
|
||||
@@ -49,24 +44,9 @@ not fill in; if so, follow the form.
|
||||
SLACK_APP_TOKEN=xapp-...
|
||||
```
|
||||
|
||||
8. Invite the bot to the channel you will use (`/invite @OpenRig` in that channel).
|
||||
`rig slack verify` reports NOT ready until the app is a member.
|
||||
9. Register yourself as the human the connector delivers to, with a Slack binding that names
|
||||
your Slack user ID (`rig gateway human add`; its `--help` shows the binding format).
|
||||
Messages from Slack users who are not registered are not delivered. `rig slack enable`
|
||||
needs a readable human registry: on a fresh install with no registry, or with an invalid
|
||||
one, it is refused.
|
||||
10. Run `rig slack setup --channel <channel-id> --secrets-env-file <path>`, then
|
||||
`rig slack verify`, then `rig slack enable`.
|
||||
11. Enabling treats the asks already open as seen, so none of them post. To see them in Slack, run
|
||||
`rig slack post-open-asks`. Each goes through ordinary delivery at the level it was asked at
|
||||
(quiet hours, digest and the posting floor apply), and the command says what became of each:
|
||||
posted, already posted, queued awaiting its receipt, held, below the posting floor, no longer
|
||||
active, superseded, recipient changed, state unavailable, transport failed or uncertain. An ask
|
||||
asked at RECORD stays on Steering and the Feed without a post. Running it again reuses each ask's
|
||||
one decision rather than making another, so an ask whose post is confirmed isn't posted again. As
|
||||
with any Slack post, one whose earlier attempt Slack couldn't confirm may post once more, marked as
|
||||
a possible repeat. `--wait <seconds>` (default 10) is how long it waits for Slack receipts.
|
||||
8. Run `rig slack setup --channel <channel-id> --secrets-env-file <path>`, then
|
||||
`rig slack verify`, then `rig slack enable`.
|
||||
9. Invite the bot to the channel you configured (`/invite @OpenRig` in that channel).
|
||||
|
||||
## What the app asks for
|
||||
|
||||
@@ -77,10 +57,9 @@ groups:
|
||||
a member of, and reading channel details.
|
||||
`rig slack verify` checks these.
|
||||
- **Feature scopes**: `files:read` (download attachments people send), `files:write` (upload
|
||||
attachments to Slack), `app_mentions:read` (receive @-mentions of the app), `reactions:read`
|
||||
(receive emoji reactions), and `users:read` (identify a named bot, below). `rig slack verify` warns
|
||||
when one of these is missing (if Slack returns the granted scopes) but does not require them, so a
|
||||
READY from verify does not prove attachments, mentions, reactions or named bots will work.
|
||||
attachments to Slack), and `app_mentions:read` (receive @-mentions of the app). `rig slack verify`
|
||||
does **not** check these, so a READY from verify does not prove attachments or mentions will
|
||||
work.
|
||||
|
||||
If a feature scope was not granted, the effect differs by feature:
|
||||
|
||||
@@ -88,48 +67,20 @@ If a feature scope was not granted, the effect differs by feature:
|
||||
message with an attachment that could not be downloaded is still delivered, with the failed
|
||||
file named in it. A post whose attachment could not be uploaded still delivers its text, and
|
||||
the failure appears only in the daemon log (`rig daemon logs`).
|
||||
- **Mentions** (`app_mentions:read`): Slack does not deliver `app_mention` events to the app.
|
||||
Only `rig slack verify` warns that the scope is missing; nothing reports the missing events.
|
||||
- **Reactions** (`reactions:read`): Slack does not deliver `reaction_added` events, so a reaction
|
||||
on an ask doesn't reach the asking agent. A reply in the ask's thread still does.
|
||||
- **Named bots** (`users:read`): Slack refuses the bot lookup, so a named bot's posts are not
|
||||
delivered, and the daemon log names the refusal. Nothing else changes.
|
||||
- **Mentions** (`app_mentions:read`): Slack does not deliver `app_mention` events to the app, and
|
||||
nothing in OpenRig reports that they are missing.
|
||||
|
||||
So after installing, compare the granted scopes Slack shows for the app with all eight scopes that
|
||||
So after installing, compare the granted scopes Slack shows for the app with all six scopes that
|
||||
`rig slack manifest --json` lists.
|
||||
|
||||
The app subscribes to messages in public channels it is a member of (`message.channels`), to
|
||||
mentions of the app (`app_mention`), and to emoji reactions (`reaction_added`). It does not request
|
||||
direct-message or private-channel access.
|
||||
|
||||
A reaction added to an ask reaches the agent that asked, as a note naming who reacted and with
|
||||
which emoji; the agent decides what it means. Every message OpenRig posted for the ask counts:
|
||||
its first message, a long ask's numbered parts, and an ask posted as a reply in a thread. A
|
||||
reaction on any other message, including a person's reply in the thread, is ignored. An app created from an older manifest has neither the `reactions:read` scope nor the
|
||||
`reaction_added` event: add both under **OAuth & Permissions** and **Event Subscriptions**, then
|
||||
reinstall the app to the workspace.
|
||||
The app subscribes to messages in public channels it is a member of (`message.channels`) and to
|
||||
mentions of the app (`app_mention`). It does not request direct-message or private-channel access.
|
||||
|
||||
The manifest also turns on **Interactivity**, so the human can answer a decision's structured
|
||||
questions by clicking a button (`rig queue create --human-questions-file`). In Socket Mode the
|
||||
clicks arrive over the same socket, so no request URL is needed. An app created from an older
|
||||
manifest has Interactivity off: turn it on under **Interactivity & Shortcuts**, or the buttons
|
||||
will do nothing. A typed reply in the thread still answers the decision either way.
|
||||
Each click gets one short reply in the decision's thread: what was recorded, or, when OpenRig
|
||||
refuses the click or can't record it, why and what to do instead (the sender isn't registered, the
|
||||
decision is no longer waiting for answers or was sent to someone else, the button no longer
|
||||
matches its questions, or the message can't be matched to a decision). Slack's redelivery of a
|
||||
click OpenRig already handled gets no second reply. The reply is best effort: while Slack is
|
||||
rate-limiting OpenRig's posts it may not be posted, and the click is handled the same either way.
|
||||
|
||||
In the decision's `humanAnswers`, clicked answers remain option-id strings. A whole typed reply
|
||||
is stored as `{kind: "typed-reply", text: "…", placement: "first-unanswered", unansweredCount: N}`
|
||||
under the first unanswered question. That placement is automatic; it does not mean the person
|
||||
selected that question. `N` counts the other question slots still empty in `humanAnswers` after
|
||||
that placement. Earlier button answers are preserved; no other questions are filled in.
|
||||
Read `text` as the person's words,
|
||||
even when it equals an option id. The reply still closes the decision, so `done` is not approval.
|
||||
A file-only reply closes the decision without recording a typed answer. If all button answers were
|
||||
already recorded, they stay final and the typed reply remains in the correlated reply row.
|
||||
|
||||
## What the connector does with the tokens
|
||||
|
||||
@@ -144,304 +95,40 @@ part of OpenRig.
|
||||
- `rig slack status` shows what is still missing, without contacting Slack.
|
||||
- `rig slack verify` checks the granted baseline scopes and channel membership with Slack.
|
||||
|
||||
## One channel per rig or seat (optional)
|
||||
|
||||
Every ask to a person posts to Slack by default: that's their Slack subscription's `every-ask` preset. A person who wants
|
||||
Slack for urgent asks only sets `rig gateway human set <id> slack-subscription urgent-only`: then only an ask marked
|
||||
`--alert` posts, and the rest wait on Steering and the TUI. An ask marked `--alert` stands out either way (an interrupt with a mention). By default every post goes to the one channel from `rig slack setup --channel`.
|
||||
To follow each rig separately, post a rig's items, or a single seat's, to its own channel:
|
||||
|
||||
```bash
|
||||
rig slack channel-map set my-rig C0EXAMPLE1
|
||||
rig slack channel-map set pr@my-rig C0EXAMPLE2
|
||||
rig slack channel-map list
|
||||
rig slack channel-map remove pr@my-rig
|
||||
```
|
||||
|
||||
- **Which channel an item posts to.** The item's seat is matched exactly first (`pr@my-rig`),
|
||||
then its rig (`my-rig`). Anything unmapped posts to the default channel, so a config
|
||||
without a map behaves exactly as before. Aggregate delivery digests have no single seat and
|
||||
always post to the default channel.
|
||||
- **Threads.** Updates, `--reply-to` and later notifications for an item stay in its thread.
|
||||
With a map configured, if a seat's channel has changed since the thread was opened, the
|
||||
next post opens a new thread in the seat's current channel, and `--reply-to` records the
|
||||
fallback as `root-other-channel`. With no map, threads behave exactly as before: an item's
|
||||
next notification reuses its open thread in whatever channel that thread was posted in.
|
||||
- **Changing the map.** A change applies to new posts. A post already in flight (one being
|
||||
retried after a failure or an unconfirmed send) finishes in the channel and thread it started
|
||||
in, and its retry checks that channel first so it is not posted twice. This includes adding
|
||||
the first map: a post first tried before any map existed finishes in the default channel.
|
||||
Without a map, OpenRig records nothing about a post's channel, so if the default channel
|
||||
changes while a post is being retried, the retry goes to the new default channel (as it always
|
||||
has); that also applies to a post first tried before the map was added.
|
||||
- **Rate limits on posts.** When Slack rate-limits a post and asks for a pause of 10 seconds or
|
||||
less, OpenRig waits that long and retries the post once. A longer pause, or a second refusal,
|
||||
is left to the retry of retained posts.
|
||||
- **Replies and new messages.** A reply in an item's thread reaches that item's seat, in any
|
||||
channel. To answer it in the same thread, the seat sends `rig queue create --human-intent update
|
||||
--summary "<subject>" --reply-to <the inbound reply's row>`.
|
||||
- **A new message a person starts in a rig's channel** goes to that rig's representative, the
|
||||
seat the rest of its rig reports to (its one `delegates_to` root). To send it to another seat,
|
||||
name it: `rig slack channel-map set my-rig C0EXAMPLE1 --inbound lead@my-rig`. A rig entry on the
|
||||
connector's default channel only sends that rig's posts there: new messages in the default
|
||||
channel still go to the inbound destination, unless the entry names `--inbound`.
|
||||
- **Every other new message,** in the default channel or a seat's channel, goes to the
|
||||
connector's inbound destination, as does a reply in a thread OpenRig doesn't know, or a rig's
|
||||
channel whose representative can't be found.
|
||||
- **Answers come back to where the person asked.** A person's new message is the root of its
|
||||
answer: when the seat it reached replies with `--reply-to` that message's row, the answer and
|
||||
later updates land in the person's thread, in the channel they used.
|
||||
- **One conversation, whoever writes.** Messages routed to the same continuing agent
|
||||
conversation can use that conversation's earlier context, whoever sent them. A queue row
|
||||
records who sent a message and which seat owns it; it doesn't start a separate agent
|
||||
conversation. If people need separate conversations, route them to separate seats
|
||||
(`--inbound` names the seat a channel's new messages reach). Separate channels help only when
|
||||
their routing also keeps the conversations separate: new messages in a seat's own channel
|
||||
still go to the inbound destination unless its entry names `--inbound`. A conversation shared
|
||||
on purpose is fine.
|
||||
- Missed-message recovery (below) covers the default channel only.
|
||||
|
||||
Invite the app to every mapped channel (`/invite @OpenRig`). `rig slack verify` checks
|
||||
membership in the default channel and every mapped channel, and reports NOT ready until the
|
||||
app is in all of them. A saved change reaches a running connector when it next rewires, which a
|
||||
daemon restart does (`rig daemon stop`, then `rig daemon start`). `rig slack disable --reason
|
||||
"<why>"` then `rig slack enable` rewires too, but alerts still waiting to be posted when it's
|
||||
re-enabled are treated as already seen and aren't posted. Only an earlier post that failed or
|
||||
didn't finish still posts: an alert whose row is still open, a decision-resolved notice, or a digest. `rig slack post-open-asks`
|
||||
then shows the asks still open. The TUI's Connections page says whether the running
|
||||
configuration matches the file.
|
||||
|
||||
The map is stored as `channelMap` in `slack-connector.json`, as a list of `{ "match", "channel" }`
|
||||
entries, each with an optional `"inbound"` seat. Saving refuses any other field. A field written by a newer OpenRig is ignored when the
|
||||
connector reads the file, and `rig slack status` names it. Private channels and direct messages
|
||||
are not supported targets.
|
||||
|
||||
## Named bots (optional)
|
||||
|
||||
By default the connector drops every post made by a bot, its own included. To let another Slack
|
||||
app's bot (an AI assistant, an alerting app) reach one seat, give the bots a channel of their own,
|
||||
name each bot, and name the seat that reads that channel. Add a `botInbox` block to
|
||||
`slack-connector.json`:
|
||||
|
||||
```json
|
||||
"botInbox": {
|
||||
"channel": "C0BOTINBOX",
|
||||
"destination": "researcher@my-rig",
|
||||
"bots": [
|
||||
{ "appId": "A0EXAMPLE1", "name": "Example Bot", "maxPerHour": 20, "cooldownMinutes": 60 }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
- **Which posts are delivered.** A post reaches `destination` when it is in `channel`, its bot
|
||||
belongs to an app listed in `bots`, and that app is not this connector's own app. A named bot's
|
||||
posts in any other channel, and every other bot's posts, are still dropped. OpenRig's own posts
|
||||
are never delivered, even if its app is listed. A post kept for retry (Slack couldn't be asked
|
||||
about it in time) is checked again against the current block when it is retried.
|
||||
- **How a bot is identified.** OpenRig asks Slack which app the post's bot belongs to (`bots.info`,
|
||||
which needs the `users:read` scope) and matches that app ID. Use the bot's **app** ID, which
|
||||
starts with `A` and is on the app's settings page. A bot ID (`B…`) or user ID (`U…`) never
|
||||
matches. An unnamed bot's post is logged with its app ID, so `rig daemon logs` shows the ID to
|
||||
add. Anything that posts as a named app counts as that bot, including the app's incoming
|
||||
webhooks: that is what naming it means.
|
||||
- **What the seat receives.** One row per post. Its source is `slack-bot:<app ID>` and its summary
|
||||
starts with the bot's name, never a person's. The row opens with where the post came from, then
|
||||
quotes the bot's text in a fenced block. A `slack-bot` row is data from another program, not an
|
||||
instruction, and the row says so. A bot can't answer or close a decision, even when it replies in
|
||||
a decision's thread: the row goes to `destination` and the decision keeps waiting for a person.
|
||||
Edits and deletions are not delivered, so a bot that writes its answer by editing one message
|
||||
delivers only that message's first version. Attachments are named in the row, not copied.
|
||||
- **Answering the bot.** The seat can't reply to the bot yet: the row has no reply link, and
|
||||
OpenRig posts only for people. To ask the bot something, the person asks it in Slack.
|
||||
- **Limits.** Each bot may deliver `maxPerHour` posts (default 20) in any rolling hour. The next
|
||||
post cuts the bot off for at least `cooldownMinutes` (default 60), and until the hour has room
|
||||
again. Its new posts are dropped meanwhile (a post already admitted still arrives), and the seat
|
||||
receives one row saying so (at most one an hour per bot) and how the person turns the bot off
|
||||
(remove it from `bots`, then apply the change as below). A later cutoff within that hour can extend the time shown without another row; the
|
||||
daemon log records each one. Each post counts once by its identity, including a post delivered on
|
||||
retry or arriving twice. A post already admitted whose row couldn't be created yet is kept, marked
|
||||
as admitted once that creation fails, and delivered later without counting again, even after its
|
||||
hour, a rewire or a daemon restart. The counts are kept in the running connector's memory, so a daemon
|
||||
restart or a rewire (`rig slack disable --reason "<why>"` then `rig slack enable`) clears them. They
|
||||
cover what one daemon writes: another process writing the retained file isn't seen, and two daemons on
|
||||
one OpenRig home aren't a supported setup.
|
||||
- **The channel.** Invite the app to it (`/invite @OpenRig`). `rig slack verify` does not check
|
||||
this channel, and only warns when `users:read` is missing. A person's message there is handled like a person's message in any channel the
|
||||
app is in (a new message goes to the connector's inbound destination), not by the bot inbox.
|
||||
Missed-message recovery does not cover the bot inbox.
|
||||
|
||||
`rig slack status` shows a `bot-inbox` line: what it delivers, or why it is off. An invalid block
|
||||
(for example a bot ID where an app ID belongs) turns only the bot inbox off. A saved change
|
||||
reaches a running connector when it next rewires, which a daemon restart does (`rig daemon stop`,
|
||||
then `rig daemon start`). `rig slack disable --reason "<why>"` then `rig slack enable` rewires too,
|
||||
but alerts still waiting to be posted when it's re-enabled are treated as already seen and aren't
|
||||
posted. Only an earlier post that failed or didn't finish still posts: an alert whose row is still
|
||||
open, a decision-resolved notice, or a digest. `rig slack post-open-asks` then shows the asks still open.
|
||||
|
||||
## One app across machines (optional)
|
||||
|
||||
Slack delivers each event of an app to one of its connections, so one app can serve several
|
||||
OpenRig machines only if one machine, the hub, holds the connection and relays each other machine's
|
||||
channels to it. Each machine still decides who its messages reach, keeps its own threads and
|
||||
decisions, and posts its own replies.
|
||||
|
||||
- **On the hub:** the bot token and the app-level token, as usual, plus `forwardChannels` in
|
||||
`slack-connector.json`, one entry per channel another machine owns:
|
||||
|
||||
```json
|
||||
"forwardChannels": [
|
||||
{ "channel": "C0EXAMPLE3", "host": "vps04" },
|
||||
{ "channel": "C0EXAMPLE4", "host": "vps04" }
|
||||
]
|
||||
```
|
||||
|
||||
`host` is that machine's id in the hub's host registry (`rig host list`). It needs an http
|
||||
entry, which `rig host pair` writes with that machine's token; the hub sends it with each relay,
|
||||
and the machine checks it when it has `OPENRIG_AUTH_BEARER_TOKEN` set.
|
||||
- **What the receiving machine trusts:** a relayed event comes from whoever holds that machine's
|
||||
daemon token (or, with no token set, anything that can reach its daemon), not from Slack directly, and nothing checks Slack's own signature on it. The
|
||||
credential issued by `rig host pair` is the daemon API bearer, not a relay-only credential; it also authorizes the other daemon write APIs that use that bearer. The
|
||||
machine still looks up the sender in its own list of people, but on a relayed event that's no
|
||||
proof a person just typed or clicked it in Slack: it trusts the caller for where the event came
|
||||
from.
|
||||
- **On every other machine:** the same app's bot token only, with no app-level token, so it opens
|
||||
no connection of its own. Set its default `channel` to its own channel and, for a rig's channel,
|
||||
a channel map entry. Its connector is enabled as usual. Its `rig slack status` reports
|
||||
`relayedInbound`: that it can take relayed events, and how many have arrived since it started.
|
||||
It also retries its own kept events every five minutes, including any it kept before it stopped
|
||||
holding a connection of its own, so those still land.
|
||||
- **What happens to a message:** the hub relays the event, a reaction or a button click untouched
|
||||
to the machine that owns the channel. That machine handles it exactly as if it had received it:
|
||||
who may send, where it goes, its thread and its decisions. If the relay fails (the machine is
|
||||
down or its registry entry is wrong), the hub keeps it and retries every five minutes, after its
|
||||
own kept events and clicks; `rig slack status` counts it in the dead-letter backlog. A machine
|
||||
that's down costs one attempt per retry: its other relays wait for the next one. A relay the
|
||||
machine keeps refusing is kept and retried with no limit, because dropping it would lose a
|
||||
person's message.
|
||||
- **Changing forwarding entries is not a drain or cancellation:** relays already retained keep
|
||||
their original host and remain visible in `rig slack status`, even after the last entry is
|
||||
removed. An enabled connector retries them; disabling it pauses retry without deleting them.
|
||||
Let relays finish before removing a forward entry. A zero dead-letter backlog alone does not
|
||||
prove they have drained: it does not count relay HTTP requests still in flight.
|
||||
- **Who answered:** every post starts `From <seat> on <machine>`, using the machine's host id (set
|
||||
it with `host.name`).
|
||||
- **The hub's own channels** are handled on the hub, as before. A channel can be relayed to one
|
||||
machine only, and never the hub's own default channel.
|
||||
Messages that match neither forwarding nor an existing thread or channel route fall back locally
|
||||
to `inboundDestination`; `rig slack status` names that policy and destination. These lists do not
|
||||
establish exclusive channel ownership: two machines can still both handle a channel.
|
||||
- **Missed messages:** each machine recovers the channels it owns: the hub its own channels, and
|
||||
every other machine its default channel and its channel map's (the hub never recovers a channel
|
||||
it relays). See [Reconnect recovery and status](#reconnect-recovery-and-status).
|
||||
- **Not covered yet:** `rig slack verify` on the hub doesn't check the app's membership in relayed
|
||||
channels.
|
||||
|
||||
## Quiet hours for a person (optional)
|
||||
|
||||
Quiet hours hold a person's routine asks while they're on, and post them once they end.
|
||||
|
||||
- **Set them** with `rig gateway human quiet set <entityId> --daily 22:00-07:00` (every day) or `--until 07:00` (from now
|
||||
until then), with `--tz` for the person's zone. `show` reports whether they're on, `end` ends tonight's early ("I'm back";
|
||||
a daily rule stays for tomorrow), and `clear` removes the rule. A person's mode can set them too (`rig gateway human
|
||||
mode save … --quiet`).
|
||||
- **While quiet is on,** an ask that would post to the person isn't posted and doesn't mention them, whatever their delivery
|
||||
class: it's held, and its row records the hold.
|
||||
- **Not held:** an urgent ask, meaning one tagged `escalation` or `wake-escalation` that isn't an update, and the operator's
|
||||
wake-ladder alerts. These reach the person exactly as they would outside quiet. An ask below the posting level is only
|
||||
logged, as at any time.
|
||||
- **When quiet ends,** each held ask that never started posts once, on its own, with no mention. One that no longer applies
|
||||
isn't posted, and its row says why: it closed, a newer notification replaced it, its recipient changed, or it's now below
|
||||
the posting level.
|
||||
- **A post that may already be in Slack**, confirmed or only partly sent, isn't held: it finishes as itself, in its own
|
||||
thread.
|
||||
- **If quiet hours can't be read,** nothing is posted to that person until they can.
|
||||
|
||||
## Reconnect recovery and status
|
||||
|
||||
The daemon scans available top-level messages and replies broadcast with **Also send to
|
||||
channel** in the channels this machine owns: its default channel and its channel map's, except a
|
||||
channel it relays to another machine. It also scans replies in the threads it tracks in those
|
||||
channels whose root was posted, or which closed, within the last seven days. A root's age is its
|
||||
Slack posting time, so rebuilding the thread map doesn't make an old thread eligible again. An old
|
||||
thread that closed within seven days is scanned from its root, so this isn't a seven-day history
|
||||
limit. Missed replies in older open threads aren't caught up; live delivery is unchanged.
|
||||
|
||||
The hub scans after a Socket Mode connection and on its existing five-minute retry cadence. A
|
||||
machine the hub relays to scans every five minutes, and recovers only the channels it owns that the
|
||||
hub has relayed it an event for. Each such channel's coverage starts when its first relayed event
|
||||
arrives, and is kept across restarts, so a restart needs no new event. A channel the machine no
|
||||
longer owns isn't scanned, and a machine nothing is relayed to never reads its channels' history.
|
||||
|
||||
Broadcast replies keep their thread's routing. Recovered tasks say **Recovered after a gap** and
|
||||
show the original Slack posting time. A recovered thread reply lands as a reply in its thread,
|
||||
marked late, and never answers a decision, even one still open: the seat reads it and decides. A
|
||||
recovered broadcast reply does the same in every channel except the default channel of the machine
|
||||
that holds the Socket Mode connection, where it behaves as before; a relayed machine's default
|
||||
channel counts as newly covered. A dead-lettered recovered reply keeps that mark when it's retried.
|
||||
The daemon scans available top-level messages in the configured channel after a
|
||||
Socket Mode connection and on its existing five-minute retry cadence. Recovered
|
||||
queue rows say **Recovered after a gap** and show the original Slack posting time.
|
||||
They use the same sender admission, routing, attachment handling, fixed identity
|
||||
and dead-letter path as live messages. A durable dead letter is custody of a
|
||||
failed delivery, not successful delivery.
|
||||
|
||||
Recovery keeps a per-channel checkpoint across reconnects, restarts and channel
|
||||
switches. For the hub's default channel it initializes once from the newest retained accepted
|
||||
channel landing; without such evidence it starts at feature adoption. Every other channel starts
|
||||
when recovery first adopts it. **Older history is unknown.** A tracked thread's checkpoint starts
|
||||
at its root, so its first scan reads the whole thread; replies that already landed are recognized
|
||||
and not delivered twice. New live messages never move the recovery checkpoint. A
|
||||
switches. On upgrade it initializes once from the newest retained accepted
|
||||
channel landing; without such evidence it starts at feature adoption. **Older
|
||||
history is unknown.** New live messages never move the recovery checkpoint. A
|
||||
partial scan resumes its saved interval; only an exhausted interval advances the
|
||||
covered boundary. The checkpoint moves past a message once it landed, was a duplicate, was
|
||||
dead-lettered, was refused because its sender isn't admitted, or was skipped as a kind inbound
|
||||
doesn't take (a bot's post, an edit or join, an empty message). Each new interval ends five seconds before the local clock to
|
||||
covered boundary. Each new interval ends five seconds before the local clock to
|
||||
allow recent messages to become visible; larger clock skew or visibility lag is
|
||||
not covered by that margin. A corrupt or unreadable checkpoint leaves recovery unavailable
|
||||
and preserves the existing file; live inbound continues.
|
||||
|
||||
Each pass admits at most four history calls, 100 entries and 15 seconds of work, with a
|
||||
five-second request ceiling. Channels and threads take turns within that one budget, so with many
|
||||
tracked threads each thread is scanned every few passes; `rig slack status` shows how far behind
|
||||
the oldest waiting thread is. Work already started on a message, such as
|
||||
an attachment transfer, is not cancelled by these limits or by a stop, and a new
|
||||
pass waits for it to finish. Rate limits retain Slack's Retry-After across restart, and hold back
|
||||
only the method Slack limited (channel history or thread replies).
|
||||
Each pass admits at most four pages, 100 entries and 15 seconds of work, with a
|
||||
five-second history-request ceiling. An already admitted attachment/landing keeps
|
||||
its owner until it settles. Rate limits retain Slack's Retry-After across restart.
|
||||
Transport and server failures use a five-second backoff unless Slack supplies Retry-After.
|
||||
When Slack reports a plan history limit, recovery still lands the available page
|
||||
and advances normally, retaining an older-history limitation in status across restarts.
|
||||
Missing bot credentials, history scope, membership, retention limits and API
|
||||
failures appear as recovery limitations. A tracked thread Slack can't find stays incomplete in
|
||||
status, with no further call, until its thread mapping changes or the daemon restarts or rewires
|
||||
the connector; that isn't proof the thread was deleted. No additional scope is required to keep
|
||||
live delivery working. Threads nobody tracks, older open threads, threads closed more than seven
|
||||
days ago and other channels remain outside this recovery scope; global chronological order is
|
||||
not promised. This change does not replay intervals already checkpointed before broadcast-reply
|
||||
recovery was added.
|
||||
failures appear as recovery limitations. No additional scope is required to keep
|
||||
live delivery working. Thread-reply catch-up and dead-connection detection remain
|
||||
outside this recovery scope; global chronological order is not promised.
|
||||
|
||||
`rig slack status` retains local configuration checks and adds a bounded daemon
|
||||
snapshot: socket state/generation, last event, recovery interval/state/reason for each
|
||||
channel, a thread line (tracked, scanned, waiting and why any are backing off or incomplete),
|
||||
retry time and accepted/dead-lettered recovery counts since the connector last
|
||||
started, including threads that have since left the window (they reset when it is enabled or disabled, and when the daemon restarts).
|
||||
It also reports the durable dead-letter backlog: the retained records for inbound messages,
|
||||
reactions and click answers that await retry, including retained relays, counted across all three
|
||||
dead-letter files so the number survives a restart. Retry is paused while the connector is disabled.
|
||||
If a file cannot be read, status shows unknown with a reason and no count.
|
||||
snapshot: socket state/generation, last event, recovery interval/state/reason,
|
||||
retry time and accepted/dead-lettered recovery counts for this daemon process.
|
||||
Human-readable coverage and pending bounds use ISO timestamps; JSON keeps Slack timestamps.
|
||||
The status read calls no Slack API and starts no scan. If the daemon cannot be
|
||||
observed, local configuration remains visible and live state is unknown. A
|
||||
connected socket or valid configuration alone does not prove end-to-end delivery.
|
||||
|
||||
### Slack rejects a message with `invalid_blocks`
|
||||
|
||||
`rig queue show <qitemId> --json` records the failure as
|
||||
`class=slack-invalid-blocks error=invalid_blocks` in the delivery transition.
|
||||
Slack rejected that message's blocks, so OpenRig retains the notification as
|
||||
undelivered and does not post the same payload again, including after a daemon
|
||||
restart. The rejection is tied to the rendered payload: corrected content can
|
||||
make a new attempt. Network failures, server errors and rate limits still retry
|
||||
as before; a timed-out request remains uncertain until reconciliation.
|
||||
|
||||
The source seat gets a `slack-undeliverable` queue item explaining the failure.
|
||||
Check the evidence links and message content, then send a corrected ask as a new
|
||||
queue item. Close the original when you have handled it. If a long ask was split
|
||||
into several messages, earlier parts may already be in Slack; the notice says
|
||||
when only part of the ask was posted. A failed part never counts as delivery of
|
||||
the whole ask.
|
||||
@@ -61,19 +61,12 @@ The smaller of `--limit` and the configured request maximum bounds the wake.
|
||||
Unknown answers remain null; a wholly unknown answer abstains. Invalid model,
|
||||
provider, answer keys, choices, probabilities or response bytes reject the whole
|
||||
answer. Probability sums retain the strict 0.001 tolerance; there is no rounding
|
||||
repair or partial salvage. Unavailable/invalid provider work, Ctrl-C or SIGTERM
|
||||
stops that run with no classification write; when the classifier returns that
|
||||
outcome, the item in hand is recorded as an abstention, final for that classifier
|
||||
version, taxonomy version and evidence epoch. The worker's own deadline (the lesser
|
||||
of the request timeout and the time left before the next lease heartbeat) is
|
||||
different: when it fires
|
||||
first, the attempt is recorded as `error` with a retry time, or `exhausted` once the
|
||||
retry budget is spent, not as an abstention. Inspect the returned attempt state: terminal abstentions
|
||||
repair or partial salvage. Unavailable/invalid provider work stops that run with
|
||||
no classification write. Inspect the returned attempt state: terminal abstentions
|
||||
are not reopened, and failed/unknown daemon writes must be reconciled through the
|
||||
existing ledger. Never change the evidence epoch merely to retry an experiment.
|
||||
|
||||
Disable, a changed `--max-requests` or `--timeout-ms`, or an unreadable configuration
|
||||
is checked before each call and before applying its result, and stops the run. A separate
|
||||
Disable is checked before each call and before applying its result. A separate
|
||||
disable command cannot cancel an already forwarded remote request; its late
|
||||
result is discarded, with the existing deadline bounding the wait. Ctrl-C or
|
||||
SIGTERM requests immediate cancellation of the foreground run. An uncooperative
|
||||
@@ -102,34 +95,6 @@ transport or inventory. Failed runs preserve already written output; inspect
|
||||
`unavailable`, `remaining`, call count and stop reason rather than treating a file
|
||||
as proof of success.
|
||||
|
||||
From 0.7.2, `rig project wake --experiment` records its attempts under
|
||||
`<classifier-version>+experiment`. `rig stream show` labels its classifications
|
||||
`experiment`, not intake's, and its abstentions don't keep an item from the typed
|
||||
decisions path below. It still creates no work.
|
||||
|
||||
## Typed decisions in the intake turn (`--decide`)
|
||||
|
||||
With `decisions.enabled` and the `stream` consumer configured (`rig project decisions
|
||||
status`), `rig project wake --decide` takes the same options as a wake and asks a typed
|
||||
decision for each eligible item, within the run's call budget. An accepted answer is
|
||||
written with the item's classification and becomes owned work (a created or joined queue
|
||||
row) or a recorded no-action or duplicate; `rig stream show <id>` shows what became of it.
|
||||
Everything else stays with the intake seat: abstentions, errors, a deferral's reason, and
|
||||
any item that intake or an earlier version already abstained on (an experiment's
|
||||
abstentions excepted). The manual path (`rig project classify`, or a wake with
|
||||
`--decisions`) is unchanged and remains the fallback.
|
||||
|
||||
**Turning decisions off, or changing them mid-run:**
|
||||
- Off means no new provider calls. A run rechecks the settings before every send and halts
|
||||
with `settings_changed`; an answer that arrives after a change is `stale` and isn't applied.
|
||||
- Nothing already committed is discarded. Classifications, dispositions and work are kept,
|
||||
and a disposition accepted before the change but not yet applied is still applied:
|
||||
`rig project wake --decide` with decisions off asks nothing, takes the classifier lease
|
||||
and applies those effects (`recovered` in its output).
|
||||
- One classifier lease serves every path; an effect is applied only by the lease holder.
|
||||
- Old unclassified items are bounded by stream retention (`retention.stream_days`,
|
||||
`retention.stream_max_items`), which keeps items any of these records name.
|
||||
|
||||
## One bounded wake
|
||||
|
||||
From the selected occupant, read candidates using the configured project ID:
|
||||
@@ -204,8 +169,7 @@ source churn can require repeated preparation and is not a throughput claim.
|
||||
Each wake processes at most `--limit` items (1–100; default 20), starting with the
|
||||
oldest eligible work rather than relying on a lossy notification cursor. Durable
|
||||
terminal attempts stay excluded. A new candidate version does **not** authorize
|
||||
another pass: only a new classifier version, taxonomy version or owner-selected
|
||||
evidence epoch changes that attempt identity.
|
||||
another pass: only an owner-selected evidence epoch changes that attempt identity.
|
||||
Retain the candidates output beside the decisions and result so its version is
|
||||
reproducible. The CLI does not keep a second local ledger.
|
||||
|
||||
@@ -233,9 +197,6 @@ capture. Retained-no-write is a separate event, never delivery evidence.
|
||||
|
||||
Activation requires explicitly supplied `OPENRIG_SHADOW_CAPTURE` JSON at a later
|
||||
authorized daemon start. Absence or invalid configuration leaves capture disabled.
|
||||
Daemon start checks only that `destination` is an absolute normalized path and the
|
||||
numeric ceilings; the private-directory checks and exclusive file creation happen
|
||||
at the first drain, and a failure there stops the sink.
|
||||
This document supplies no live destination or activation instruction. Required
|
||||
fields and engineering ceilings are:
|
||||
|
||||
@@ -259,7 +220,7 @@ observation; explicit production configuration supplies each value.
|
||||
`rig project shadow-drain` asks the existing HTTP service to drain up to 64 rows;
|
||||
it requires an actor (outside a managed seat, name one with `--actor <name>`)
|
||||
and never enables capture. No background drain timer is added.
|
||||
`rig project shadow-stop` (which needs an actor the same way) disables new enqueueing immediately, finishes any active
|
||||
`rig project shadow-stop` disables new enqueueing immediately, finishes any active
|
||||
drain and the finite retained queue, then closes the sink. Repeated stop is
|
||||
idempotent; it cannot enable capture or delete the existing archive. Existing
|
||||
quota and sink-failure losses remain counted. A slow disk can leave stop pending;
|
||||
@@ -276,9 +237,8 @@ start another writer. Overflow drops new observations. Capacity exhaustion stops
|
||||
the sink. Errors stop writes, count losses and preserve any partial file; failed
|
||||
batches are not replayed. `reservedRecords/Bytes` include attempted writes, while
|
||||
`completedRecords/Bytes` count successful appends. `drained` means removed from
|
||||
the observer, not necessarily persisted. Queue drops (count-bound and byte-bound
|
||||
together in `dropped`; `droppedBytes` adds the bytes of byte-bound drops), record
|
||||
errors, missing/unavailable captures and sink failures remain separate.
|
||||
the observer, not necessarily persisted. Queue count drops, byte-bound drops,
|
||||
record errors, missing/unavailable captures and sink failures remain separate.
|
||||
|
||||
Live collection, private destination/retention selection, corpus labels, hosted
|
||||
calibration, native placement, package/install proof and independent visible /
|
||||
|
||||
@@ -7,7 +7,6 @@ private SQLite schema. It neither watches nor automatically drains history.
|
||||
```sh
|
||||
rig telemetry events --json
|
||||
rig telemetry events --start retained --node NODE_ID --limit 128 --json
|
||||
rig telemetry events --start retained --rig RIG_ID --json
|
||||
rig telemetry events --cursor CURSOR --node NODE_ID --json
|
||||
rig telemetry transitions --start retained --qitem QUEUE_ITEM_ID --json
|
||||
rig telemetry tenures NODE_ID --json
|
||||
@@ -21,9 +20,6 @@ An empty match set can still have more source records: check `page.hasMore` and
|
||||
`page.nextCursor`. The cursor binds the stream and filters; retain the same filter
|
||||
options when continuing. Do not use `--start` with `--cursor`.
|
||||
|
||||
`rig mcp serve` offers the events read as the `rig_telemetry_events` tool, with the
|
||||
same parameters and envelope; its `rigId` also takes a rig name.
|
||||
|
||||
## HTTP and envelope
|
||||
|
||||
These reads use the daemon's existing browser/access boundary:
|
||||
@@ -73,8 +69,7 @@ Physical `fetched` can therefore exceed logical `scanned`.
|
||||
Responses are at most 128 KiB, with a 4 KiB projected-record cap. SQL guards bound
|
||||
fields before fetching them: identifiers 256 bytes, timestamps/enums 128 bytes,
|
||||
and actor/closure references 512 bytes. Oversized fields become null with an
|
||||
`oversized_field` gap, and non-text values become null with an `invalid_type` gap;
|
||||
they are never truncated into a different identity. A record
|
||||
`oversized_field` gap; they are never truncated into a different identity. A record
|
||||
whose JSON escaping still exceeds 4 KiB is withheld and counted. A response-byte
|
||||
stop leaves the next unprocessed record for the continuation. Gap details are
|
||||
capped at 32; `gapCount` and `gapDetailsTruncated` preserve the count. Cursor input
|
||||
|
||||
@@ -1,308 +0,0 @@
|
||||
# Choose a Herdr session for a terminal view
|
||||
|
||||
Use `--session <name>` to open a view in a named Herdr session on the daemon's
|
||||
host. For example, keep development and production rigs in separate sessions:
|
||||
|
||||
```sh
|
||||
rig terminal open future-rig --provider herdr --session default --json
|
||||
rig terminal open future-prod-rig --provider herdr --session future-prod --json
|
||||
rig terminal status --provider herdr --session future-prod --json
|
||||
```
|
||||
|
||||
The explicit provider form places the view in the existing Herdr session
|
||||
without opening a desktop window. Use Herdr's own session management to prepare
|
||||
the session. An unavailable selected session returns `herdr_unavailable`; it
|
||||
does not redirect the view to a different session.
|
||||
|
||||
The `session` field in an open result confirms the requested selection. Status
|
||||
also names the session and returns its resolved control socket in `status.launch`.
|
||||
Session names are a single non-empty name, such as `future-prod`, rather than a
|
||||
socket path. `--session default` explicitly selects Herdr's default session.
|
||||
|
||||
## Default selection and scope
|
||||
|
||||
When Herdr is selected with no `--session`, the daemon uses the endpoint selected when it started:
|
||||
its `HERDR_SOCKET_PATH`, then its `HERDR_SESSION`, then the default endpoint.
|
||||
Setting either variable only on a later `rig terminal open` command does not
|
||||
change that daemon configuration. Pass `--session` for a per-command selection.
|
||||
|
||||
With neither a provider nor a session, the daemon's open and preview APIs try
|
||||
a live Herdr first, then a live cmux. An explicit session always selects Herdr
|
||||
and skips that fallback, including when the daemon's default Herdr endpoint is down.
|
||||
|
||||
Session paths use the daemon's `XDG_CONFIG_HOME` when set, or `HOME/.config`
|
||||
when unset. Relative paths (including an empty value) resolve from the daemon's
|
||||
startup directory, matching Herdr's configuration selection. Named sessions live under
|
||||
`herdr/sessions/<name>/herdr.sock`; `default` uses `herdr/herdr.sock` directly.
|
||||
These settings are captured when the daemon starts.
|
||||
|
||||
If the requested name equals the daemon's `HERDR_SESSION`, it keeps that
|
||||
session's explicit `HERDR_SOCKET_PATH`. A different requested name uses the
|
||||
configuration-tree path, without reusing the override or inferring a session
|
||||
from an arbitrary socket path. With an explicit socket but no configured
|
||||
session name, omit `--session` to keep that exact endpoint. A missing selected
|
||||
socket never falls back to another session. Viewer and follow operations carry
|
||||
that exact socket to the CLI through `HERDR_SOCKET_PATH`, without an explicit
|
||||
CLI `--session` that would override it. They check that the CLI reports the
|
||||
selected socket before changing its panes. Daemon-side CLI calls retain the
|
||||
startup environment; desktop follow uses the socket confirmed by the daemon.
|
||||
|
||||
The selection belongs to the request. Saved views still describe membership
|
||||
and layout, so pass `--session` again when reopening the view in that session.
|
||||
|
||||
The existing view rules apply: saved views, rig and pod views, read-only mission
|
||||
and slice views, pagination, absent seats and partial results all use the same
|
||||
composer. Selecting a session changes where those tiles are placed. It does
|
||||
not relaunch the seats' tmux sessions or move queue ownership.
|
||||
|
||||
## Open results
|
||||
|
||||
For Herdr, a successful layout request alone does not count its seats as opened.
|
||||
OpenRig checks the returned tab's pane list. A missing tab identity or an
|
||||
unreadable, empty or unattributable listing puts the affected seats in
|
||||
`degraded`, with `code: "pane_unconfirmed"`, instead of `opened`. The CLI and
|
||||
TUI name those seats as unconfirmed. Inspect the terminal before retrying:
|
||||
the layout may have taken effect even though its panes could not be confirmed.
|
||||
Confirmed seats on other pages still count; with none confirmed, the command
|
||||
returns a nonzero exit status. Reusing an existing workspace keeps its separate
|
||||
reuse result. This pane check does not prove desktop visibility or create a
|
||||
verified viewer mapping.
|
||||
|
||||
## Replacing a seat's session
|
||||
|
||||
New tiles keep their place when a seat's tmux session is replaced. They wait up
|
||||
to 30 seconds for the same session name and managed seat identity to return,
|
||||
then reattach with the original read-only setting. This uses the shared tile
|
||||
command for Herdr, cmux, Rex and plain tmux, including SSH tiles. In-place
|
||||
handover and restart keep the existing attachment.
|
||||
|
||||
A deliberate detach closes the tile after about two seconds. A different seat
|
||||
under the old name is never followed. If no replacement returns in time, or a
|
||||
session has no managed identity, reopen the rig view with
|
||||
`rig terminal open rig:<name> --window` (or your explicit provider). Views
|
||||
opened before this change must be closed and reopened to get this behavior.
|
||||
|
||||
## Desktop windows and previews
|
||||
|
||||
```sh
|
||||
rig terminal open future-prod-rig --session future-prod --window --json
|
||||
```
|
||||
|
||||
The window launcher, readiness checks, workspace inventory, reuse and layout
|
||||
application use the selected endpoint. When launched inside Herdr, the current
|
||||
Herdr endpoint must match that selection to reuse the current terminal. To
|
||||
place a view in another existing session from such a caller, use the explicit
|
||||
`--provider herdr` form without `--window`.
|
||||
|
||||
An endpoint-mismatch error also gives a command for the caller's own session,
|
||||
such as `rig terminal open future-rig --session work`. Previously it only
|
||||
explained how to place the view in the daemon's selected session. The caller's
|
||||
name comes from the same resolved socket path used by the endpoint check:
|
||||
`~/.config/herdr/sessions/<name>/herdr.sock`, or `default` for
|
||||
`~/.config/herdr/herdr.sock`. An explicit `HERDR_SOCKET_PATH` takes precedence
|
||||
over `HERDR_SESSION` for both the check and the suggestion. Other custom socket
|
||||
paths keep the existing guidance without guessing a session name, even when
|
||||
`HERDR_SESSION` is set. Reporting the mismatch opens nothing.
|
||||
|
||||
Previews include the selected session in their fingerprint. A preview from one
|
||||
session cannot authorize an open in another; refresh the preview after changing
|
||||
the selection. The CLI asks the daemon to confirm named-session support before
|
||||
requesting an open, so an older daemon cannot silently ignore the option and
|
||||
write into its default session. An unconfirmed reply after an open is reported
|
||||
as an unknown outcome; inspect the selected session before retrying.
|
||||
|
||||
`--session` applies to Herdr. A named session does not fall back to plain tmux
|
||||
when Herdr is absent, and combining a session with cmux is rejected. Existing
|
||||
workspaces are kept during reuse checks. Any suggested cleanup command for a
|
||||
stale named-session workspace includes the selected socket.
|
||||
|
||||
## Rex
|
||||
|
||||
```sh
|
||||
rig terminal open future-rig --provider rex --json
|
||||
rig terminal open future-rig --window --json
|
||||
rig terminal status --provider rex --json
|
||||
```
|
||||
|
||||
`--provider rex` opens the view as a new session on the daemon's Rex server,
|
||||
one window per page of the view, without switching any app to it. A tile whose
|
||||
attach fails within ten seconds stays open showing the error, and the result
|
||||
lists that seat as degraded when the failure shows up in the check made about
|
||||
two seconds after opening. OpenRig picks
|
||||
Rex only when it is named, or for `--window` (or no provider) when the command
|
||||
runs inside a Rex block, including in a tmux started there. Everywhere else the
|
||||
defaults above are unchanged, and the daemon's open and preview APIs never pick
|
||||
Rex for a request that names no provider.
|
||||
|
||||
From inside Rex, the window form first checks that the daemon uses the same Rex
|
||||
server as the calling terminal. When they differ, nothing is opened. After the
|
||||
open it asks the Rex app showing the caller's session to switch to the new one,
|
||||
choosing the app whose window holds the caller's terminal when several show it.
|
||||
When no app can be chosen, or the app refuses the switch, the result names the
|
||||
session to select by hand. A Rex app accepts the switch only with Remote Control
|
||||
turned on in its Settings, under Rex Server.
|
||||
|
||||
The daemon finds `rex` in `$REX_BIN_DIR`, then on `PATH`, then inside the Rex
|
||||
app on macOS, and uses its own `REX_SERVER` when set. It never starts a Rex
|
||||
server. An open view is not reused: opening it again adds a numbered session,
|
||||
such as `future-rig (2)`. `--session` applies to Herdr only. An unreachable Rex
|
||||
server returns `rex_unavailable` and a failed session create returns
|
||||
`rex_session_failed`, both as HTTP 200 results with `ok: false`. When Rex
|
||||
doesn't confirm a session create or a page, for example because its reply
|
||||
timed out, OpenRig closes nothing: the result says `rex_outcome_unknown`, or
|
||||
adds a note when other pages opened, and names the session to check in Rex
|
||||
before retrying. `rig terminal status` gives Rex about a second to answer.
|
||||
|
||||
## HTTP API
|
||||
|
||||
- `POST /api/terminal/open`: `{ view, provider?: "herdr", session?: string, expectedPlan?: string }`.
|
||||
- `GET /api/terminal/preview?view=<view>&provider=herdr&session=<name>`.
|
||||
- `GET /api/terminal/status?provider=herdr&session=<name>`.
|
||||
- The alias `POST /api/rigs/:rigId/terminal/open` accepts the same session and
|
||||
preview binding, with the rig determining the view.
|
||||
|
||||
Malformed names and unsupported provider/session combinations return HTTP 400
|
||||
before socket calls. A changed preview returns HTTP 409. An unavailable Herdr
|
||||
session keeps the normal HTTP 200 provider result with `ok: false`, its selected
|
||||
`session`, an error code and direct-attach guidance.
|
||||
The `kernel_seats_unavailable` result also keeps the selected session, so the CLI
|
||||
reports that known failure instead of replacing it with an unconfirmed-session error.
|
||||
|
||||
## Task terminal views
|
||||
|
||||
`rig terminal open qitem:<id> --provider herdr --json` opens a derived, read-only
|
||||
view of the current owners of a local queue episode. The episode includes the
|
||||
requested row and explicitly linked descendants; only pending, in-progress and
|
||||
blocked obligations contribute owners. It does not include historical senders,
|
||||
closed predecessors, parent episodes or siblings. Membership is not input
|
||||
permission.
|
||||
|
||||
The existing daemon endpoints accept the same view:
|
||||
|
||||
```text
|
||||
GET /api/terminal/preview?view=qitem:<id>&provider=herdr
|
||||
POST /api/terminal/open {"view":"qitem:<id>","provider":"herdr","expectedPlan":"<preview planId>"}
|
||||
```
|
||||
|
||||
Preview and open include `task: {qitemId, name, complete, issues, members}`. Each member
|
||||
names its structured `{hostId, nodeId}` key (null when unresolved), seat,
|
||||
contributing `obligations`, `availability` and `viewerStatus`. Stopped, missing,
|
||||
external and unresolved remote owners remain visible. Remote queues are not
|
||||
crawled and no remote tmux socket is guessed. A bounded or damaged lineage is
|
||||
explicitly incomplete; it is never silently presented as the whole team.
|
||||
|
||||
The local lineage read has work limits: 50,000 scanned rows (plus one overflow
|
||||
sentinel), 8 MiB of encoded lineage, 100,000 links, and 16 KiB per chain record.
|
||||
It reads one snapshot from the requested task forward, then probes earlier active
|
||||
obligations using the queue's existing state index and follows references by exact
|
||||
ID, including closed intermediaries. A child may arrive before its referenced root.
|
||||
All these reads share the work limits; unrelated older closed history is not scanned.
|
||||
Only the requested episode is expanded, up to 256 rows. Caller-supplied task IDs
|
||||
are supported.
|
||||
Hitting a work limit preserves known members and reports incomplete membership;
|
||||
it does not claim that an owner outside the scanned history is absent.
|
||||
|
||||
Preview and open also include `viewDescriptor: {kind, name}`: `following` for
|
||||
derived views and `fixed` for a saved layout. A task uses its row summary as
|
||||
its name, falling back to the qitem ID. The existing preview `view` string is
|
||||
unchanged. A following view derives membership when requested; it does not
|
||||
mean an open workspace updates itself.
|
||||
|
||||
Preview is read-only. A member without owned viewer provenance is
|
||||
`not-provisioned`; the ensure operation below can establish a reusable provider
|
||||
mapping. An explicit open retains the provider's existing workspace behavior;
|
||||
it does not continuously reconcile the view or change an agent's lifecycle.
|
||||
|
||||
## Following one task
|
||||
|
||||
`rig terminal open qitem:<id> --follow` keeps one workspace following the
|
||||
task's current obligation owners. A joining member gets a verified local
|
||||
viewer tile without taking focus. A departing member loses only its viewer,
|
||||
after a grace period; the agent and its conversation keep running. The
|
||||
explanation strip names joins, departures, unavailable terminals and limits.
|
||||
The first workspace on an empty provider may become focused.
|
||||
|
||||
This increment supports the qualified **Linux Herdr 0.9.5/protocol 22**
|
||||
endpoint. Other platforms/providers and other selector kinds retain ordinary
|
||||
one-shot open. Use `--provider herdr --json` to operate without opening a
|
||||
desktop window, and `--session <name>` to select that endpoint. Opening a tile
|
||||
can change the agent's terminal size; `ignore-size` does not guarantee isolation.
|
||||
|
||||
```bash
|
||||
rig terminal open qitem:example --follow --provider herdr --json
|
||||
rig terminal open qitem:example --follow --provider herdr --pin reviewer@team
|
||||
rig terminal open qitem:example --follow --provider herdr --max-tiles 12
|
||||
rig terminal open qitem:example --follow --provider herdr --suppress reviewer@team --suppression-ms 60000
|
||||
rig terminal open qitem:example --no-follow
|
||||
```
|
||||
|
||||
`--unpin` and `--unsuppress` reverse those presentation choices. The default
|
||||
cap is eight tiles; explicitly raising `--max-tiles` overrides it. Pins can
|
||||
exceed the cap rather than being evicted. A departed tile retained for typed or
|
||||
unconfirmed input does not consume a slot for joining members. Disabling removes
|
||||
the saved following selector and keeps the existing layout intact.
|
||||
|
||||
The default departure grace is four seconds (`--grace-ms`). A focused leaver
|
||||
gets another twelve seconds for reading (`--focus-retention-ms`); before its
|
||||
tile closes, focus moves to a verified surviving member, or to the explanation
|
||||
strip when none remains. Typed or unconfirmed input keeps the tile, labeled
|
||||
as no longer participating. Explicit suppression also retains a typed draft.
|
||||
Pi, terminal and community harness input may be unreadable to the composer
|
||||
inspector: those tiles remain while input is unconfirmed, even after unpinning.
|
||||
Each input-retained departure gets one delayed recheck after thirty seconds.
|
||||
After that, queue or node/session lifecycle events, or an explicit repeat of
|
||||
the follow command, can reconsider it. Activity hooks do not wake following,
|
||||
and input is not repeatedly polled. Draft text is never saved.
|
||||
|
||||
Following consumes Core events and one-shot retention/suppression deadlines,
|
||||
not repeated CLI membership queries. Complete empty membership drains the
|
||||
tiles and preserves the workspace. Once no retained tiles remain, following
|
||||
stops and the selector releases its active slot; new work does not automatically
|
||||
restart it. Run `--follow` again to resume the same workspace. An incomplete source, failed provider read
|
||||
or changed pane/terminal generation retains the previous view and reports
|
||||
the uncertainty. It never authorizes a blind workspace rebuild or close.
|
||||
`rig terminal views --json` and `rig terminal status --json` include the saved
|
||||
active selectors and latest following status. Active selectors and owned viewer provenance
|
||||
survive daemon restarts; task membership is always re-derived.
|
||||
|
||||
The owner-authorized HTTP operation is `POST /api/terminal/follow` with
|
||||
`{view:"qitem:<id>",provider:"herdr",session?,enabled:true,maxTiles?,pin?,unpin?,
|
||||
suppress?,unsuppress?,suppressionMs?,graceMs?,focusRetentionMs?,expectedPlan?}`.
|
||||
Seat controls are arrays of names from the current/retained view. It uses the
|
||||
existing terminal bearer boundary, like ensure-viewer. The response includes
|
||||
the stable `workspaceId`, normal open partitions, `viewDescriptor`, and
|
||||
`following:{id,enabled,state,maxTiles,tiles,events,overflow,nextAt?}`. Presentation
|
||||
provenance grants no membership or input authority. This is a local native
|
||||
viewer operation; browser input and remote-host provisioning are separate.
|
||||
|
||||
## Ensuring an owner viewer
|
||||
|
||||
The owner-facing HTTP operation `POST /api/terminal/viewer/ensure` accepts
|
||||
`{view:"qitem:<id>", member:{hostId,nodeId}, provider:"herdr", session,
|
||||
expectedPlan}`. Use a current preview's member key and plan. This explicit
|
||||
operation uses the daemon's existing terminal bearer and browser boundary;
|
||||
a bridge must retain its signed-in owner, Origin and expiry controls. It does
|
||||
not grant authority based on task membership or accept a caller terminal ID.
|
||||
|
||||
On the qualified Linux Herdr 0.9.5/protocol 22 endpoint, it creates one viewer
|
||||
or reuses an owned, verified `{workspaceId,paneId,terminalId,readOnly}` mapping.
|
||||
A repeated/concurrent request does not create another viewer. A lost create
|
||||
reply is reconciled before starting anything else; a lost run reply is checked
|
||||
against the actual foreground process, never blindly repeated. Unknown or
|
||||
changed terminal identity remains unconfirmed. The operation does not relayout,
|
||||
close departed viewers, take over control, focus existing panes or launch/stop
|
||||
agents. A first workspace on an otherwise empty Herdr server may become focused.
|
||||
|
||||
Preview remains passive and names `not-provisioned`, `verified` or `unconfirmed`
|
||||
viewer status. Studio can ensure a new member, add its browser frame, and retain
|
||||
a pinned leaver labeled as no longer participating. The provider mapping is
|
||||
small presentation provenance, separate from queue membership. Herdr display
|
||||
labels are not that provenance. Other providers/platforms remain unsupported
|
||||
for ensure-viewer until qualified; ordinary open retains its existing behavior.
|
||||
|
||||
Writable tile clients use `tmux attach -f ignore-size`; read-only clients keep
|
||||
`-r` (which also implies ignore-size). This can avoid contributing to sizing
|
||||
when other clients establish the agent window's dimensions. It is **not resize
|
||||
isolation**: opening a tile can change the agent's terminal size when it is the
|
||||
only sizing client. Observers of a Herdr terminal do not themselves resize it;
|
||||
a controlling browser can. No cross-version resize guarantee is implied.
|
||||
@@ -1,83 +0,0 @@
|
||||
# Naming rigs, pods and seats
|
||||
|
||||
Names tell people and agents what a team does and who does each part. Use the
|
||||
team's purpose for the rig, a domain for each pod, and a role for each seat.
|
||||
These are authoring conventions, not additional parser restrictions.
|
||||
|
||||
## What each name means
|
||||
|
||||
| Level | Meaning | Example |
|
||||
| --- | --- | --- |
|
||||
| Fleet | A group of OpenRig instances | Your development fleet |
|
||||
| Instance | One daemon and its rigs; several instances can share a machine | The instance selected by a registered host route |
|
||||
| Rig | A team or project purpose | `starter`, `workshop`, `factory`, or your project's name |
|
||||
| Pod | A domain or shared context | `orch`, `dev`, `review`, `research`, `sre` |
|
||||
| Seat (member) | A role within that pod | `lead`, `advisor`, `build`, `qa`, `design`, `review` |
|
||||
|
||||
The logical seat ID is `pod.member`: `dev.build`. Its session address is
|
||||
`pod-member@rig`: `dev-build@workshop`. A cross-instance command also selects the
|
||||
registered host route; a display label is not a route. Discover actual addresses
|
||||
with `rig ps --nodes` and host routes with `rig host list` before sending work.
|
||||
|
||||
Runtime, model and account belong in configuration. Changing a provider does not
|
||||
change the role's name. Keep machine and instance identifiers stable rather than
|
||||
renaming them whenever their workload changes.
|
||||
|
||||
What a seat runs has its own words:
|
||||
|
||||
| Term | Meaning | Example |
|
||||
| --- | --- | --- |
|
||||
| Runtime | What a seat runs: a harness, a terminal, or the stub (a scripted stand-in used in tests). It's the rig spec's `runtime` field and the TUI's runtime column | `claude-code`, `codex`, `terminal` |
|
||||
| Harness | The agent software around a model | Claude Code, Codex, Pi |
|
||||
| Community harness | A harness an outside contributor maintains. It's installed as a preset under `$OPENRIG_HOME/community-harnesses/` ([format](community-harness-presets.md)), listed by `rig community-harness list`, and OpenRig doesn't test it | A preset's name in a member's `runtime` |
|
||||
| Terminal | A seat with no agent: a shell for infrastructure processes | `runtime: terminal` |
|
||||
|
||||
## How the software teams grow
|
||||
|
||||
| Team | Logical seats |
|
||||
| --- | --- |
|
||||
| Starter | `dev.build`, `dev.review` |
|
||||
| Workshop | `orch.lead`, `dev.build`, `dev.qa`, `dev.review` |
|
||||
| Factory | `orch.lead`, `orch.advisor`, `dev.build`, `dev.qa`, `dev.design`, `review.r1`, `review.r2` |
|
||||
|
||||
Starter and Factory are built-in teams. Workshop is a
|
||||
[bundle](https://github.com/mvschwarz/openrig-world/tree/main/rigs/workshop).
|
||||
The built-in specs live under `packages/daemon/specs/rigs/launch/` in the product
|
||||
source. Runtime presets keep these logical names.
|
||||
|
||||
Workshop's one code reviewer is `dev.review`; Factory has an independent review
|
||||
pod with `review.r1` and `review.r2`. Both are intentional. A small team does not
|
||||
need every pod or role from a larger one.
|
||||
|
||||
## Name a new team
|
||||
|
||||
Start with the outcome, then group its work by domain. For a team studying a
|
||||
dataset, `research.analyst` and `research.synthesizer` describe useful roles.
|
||||
For operating a service, `sre.admin` describes the domain and responsibility.
|
||||
Use a project-specific rig name when that helps distinguish two teams.
|
||||
|
||||
Avoid a generic operation such as `check` as the pod name: it does not say whether
|
||||
the team owns software quality, research validation or service health. Put the
|
||||
role in its domain, such as `dev.qa`. This is a rule for choosing new names, not a
|
||||
word blacklist or a demand that all teams share one roster.
|
||||
|
||||
Use the same IDs in the rig spec, edges, workflow targets, configuration presets,
|
||||
startup instructions and terminal views. Validate those references together.
|
||||
See [RigSpec](rig-spec.md) and [publishing a bundle](publishing-a-rig-bundle.md).
|
||||
|
||||
## Existing identities and retained references
|
||||
|
||||
An existing team's address remains its actual address until it is deliberately
|
||||
migrated. Changing a label does not rename a seat or move its conversation, queue
|
||||
or work. Preserve those records and verify the new routes when doing a migration;
|
||||
do not edit a database or restart a team just to make a display match an example.
|
||||
|
||||
`first-project` is the compatibility name for Starter; it is not a second team
|
||||
template. Existing-name safeguards still apply. See
|
||||
[getting started](getting-started.md) before using the alias.
|
||||
|
||||
The `factory-rsi` bundle is a retained reference with original workflow-bound
|
||||
addresses, including `build.implementer` and `check.qa`. It is distinct from the
|
||||
current built-in Factory and is not the naming template for a new team. Old
|
||||
release notes, pinned bundles, run records and compatibility tests keep the
|
||||
identities they describe.
|
||||
Loaded 100 of 2183 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user