mirror of
https://github.com/mvschwarz/openrig.git
synced 2026-11-08 17:31:56 -10:00
Compare commits
1
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 mvschwarzandClaude Opus 4.7
|
1e0152f0ee |
No files matched your search
@@ -1,60 +0,0 @@
|
||||
name: Bug report
|
||||
description: Something OpenRig does is wrong, or a command fails
|
||||
labels: ["bug"]
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
Thanks. Include a small reproduction and the relevant versions.
|
||||
This report will be public. Remove API keys, tokens, private prompts, personal details and private paths from commands, logs and configuration.
|
||||
For a suspected vulnerability, follow our [security policy](https://github.com/mvschwarz/openrig/security/policy) instead of posting details here.
|
||||
- type: input
|
||||
id: version
|
||||
attributes:
|
||||
label: OpenRig version
|
||||
description: Output of `rig --version`
|
||||
placeholder: 0.5.14 (2edc1b7a)
|
||||
validations:
|
||||
required: true
|
||||
- type: input
|
||||
id: platform
|
||||
attributes:
|
||||
label: OS, Node and tmux versions
|
||||
placeholder: macOS 15.6, Node 22.22.1, tmux 3.5a
|
||||
validations:
|
||||
required: true
|
||||
- type: dropdown
|
||||
id: harness
|
||||
attributes:
|
||||
label: Harnesses involved
|
||||
multiple: true
|
||||
options:
|
||||
- None / not sure
|
||||
- Claude Code
|
||||
- Codex
|
||||
- Pi / Oh My Pi
|
||||
- Other (say which below)
|
||||
validations:
|
||||
required: true
|
||||
- type: textarea
|
||||
id: repro
|
||||
attributes:
|
||||
label: What you ran and what happened
|
||||
description: The command(s), relevant redacted output, and what you expected instead. Paste text where you can; screenshots are useful for visual issues.
|
||||
render: shell
|
||||
validations:
|
||||
required: true
|
||||
- type: textarea
|
||||
id: state
|
||||
attributes:
|
||||
label: Instance state that might matter
|
||||
description: Fresh install or upgrade? Include only relevant redacted lines from status output or your rig spec; do not upload full transcripts, credentials or your instance directory.
|
||||
- type: checkboxes
|
||||
id: checks
|
||||
attributes:
|
||||
label: Checks
|
||||
options:
|
||||
- label: I searched existing issues and Discussions for this.
|
||||
required: true
|
||||
- label: I am on the latest published version, or I said which version above.
|
||||
required: true
|
||||
@@ -1,14 +0,0 @@
|
||||
blank_issues_enabled: true
|
||||
contact_links:
|
||||
- name: Ask a question
|
||||
url: https://github.com/mvschwarz/openrig/discussions/categories/q-a
|
||||
about: Setup, usage and "is this expected" questions go to Discussions Q&A.
|
||||
- name: Share an idea or a setup
|
||||
url: https://github.com/mvschwarz/openrig/discussions
|
||||
about: Ideas and Show and tell live in Discussions.
|
||||
- name: Documentation
|
||||
url: https://openrig.dev/docs
|
||||
about: Getting started, CLI reference, configuration and troubleshooting.
|
||||
- name: Security report
|
||||
url: https://github.com/mvschwarz/openrig/security/policy
|
||||
about: Read how to arrange a private report. Do not include vulnerability details in public issues.
|
||||
@@ -1,32 +0,0 @@
|
||||
name: Feature request
|
||||
description: Something you want OpenRig to do that it does not
|
||||
labels: ["enhancement"]
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
For open-ended ideas or "how should this work" questions, [Discussions › Ideas](https://github.com/mvschwarz/openrig/discussions/categories/ideas) is the better place. Use this form when you can name the outcome you want.
|
||||
This request will be public; use examples without credentials, private prompts or personal details.
|
||||
- type: textarea
|
||||
id: outcome
|
||||
attributes:
|
||||
label: What are you trying to do, and what stops you today?
|
||||
description: Describe the situation, not the solution. One real example beats a general case.
|
||||
validations:
|
||||
required: true
|
||||
- type: textarea
|
||||
id: proposal
|
||||
attributes:
|
||||
label: What would you like OpenRig to do?
|
||||
description: A command, a setting, a behaviour. Rough is fine.
|
||||
validations:
|
||||
required: true
|
||||
- type: textarea
|
||||
id: workaround
|
||||
attributes:
|
||||
label: How do you handle it now?
|
||||
- type: input
|
||||
id: version
|
||||
attributes:
|
||||
label: OpenRig version
|
||||
placeholder: 0.5.14
|
||||
@@ -1,21 +0,0 @@
|
||||
<!-- Thanks for the PR. Three short answers are all a reviewer needs. -->
|
||||
|
||||
## What a user gets
|
||||
|
||||
<!-- One or two sentences: the behaviour before, the behaviour after. Link the issue if there is one. -->
|
||||
|
||||
## How you verified it
|
||||
|
||||
<!-- What you actually ran and saw, and which revision/local changes you tested. The documented checks are `npm run build`, `npm test`, and `npm run lint`; say what you could not run. Redact credentials and private information from logs or screenshots. -->
|
||||
|
||||
## Anything you were unsure about
|
||||
|
||||
<!-- Design choices, edge cases you did not cover, places a reviewer should look hardest. Empty is a fine answer. -->
|
||||
|
||||
## If this is security-related
|
||||
|
||||
<!-- Exploitable? Report it privately first (SECURITY.md). Otherwise: how does this go wrong for someone using OpenRig as designed (your own machine or a trusted private network), with evidence? Who causes it, and how do they reach the install? What does the change cost everyone else? See CONTRIBUTING.md. -->
|
||||
|
||||
- [ ] One concern per PR; no version bump; no `CHANGELOG.md` edit
|
||||
- [ ] Tests added or updated where the change is testable
|
||||
- [ ] I listed the checks I ran, their results, and any checks I could not run
|
||||
@@ -1,17 +0,0 @@
|
||||
# Getting help with OpenRig
|
||||
|
||||
- **Docs:** https://openrig.dev/docs — getting started, CLI reference, configuration,
|
||||
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`.
|
||||
- **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 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).
|
||||
- **Videos:** https://www.youtube.com/@openrig
|
||||
- **Security:** see [SECURITY.md](../SECURITY.md); please report privately.
|
||||
|
||||
We aim to acknowledge issues and pull requests within one day. A substantive PR review decision
|
||||
within seven days is a target, not a guaranteed deadline. Details in [CONTRIBUTING.md](../CONTRIBUTING.md).
|
||||
@@ -1,33 +0,0 @@
|
||||
name: Portability report
|
||||
|
||||
# Lists lines a pull request adds that contain values tied to one machine, network or account
|
||||
# (credentials, home paths, temporary paths, network addresses, email addresses). Findings never
|
||||
# fail the job; the author reads the report and decides what to change. An operational error (for
|
||||
# example a git failure) does fail it. The repository is public, so this summary lists file and
|
||||
# line only; authors see the matched text when they run the report locally or on push.
|
||||
# See scripts/portability-report.mjs.
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
branches: [main]
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
portability-report:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 22
|
||||
- name: Report added lines with machine-specific values
|
||||
run: >
|
||||
node scripts/portability-report.mjs
|
||||
--from ${{ github.event.pull_request.base.sha }}
|
||||
--to ${{ github.event.pull_request.head.sha }}
|
||||
--locations-only
|
||||
--out "$GITHUB_STEP_SUMMARY"
|
||||
@@ -1,139 +0,0 @@
|
||||
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 deny external networking; scenario runtime has no external route.
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
branches: [main]
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
concurrency:
|
||||
group: tests-${{ github.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
jobs:
|
||||
build-and-package:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 30
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
persist-credentials: false
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 22
|
||||
cache: npm
|
||||
- run: npm ci
|
||||
- run: npm run build
|
||||
- name: Record the published file list of each package
|
||||
run: |
|
||||
set -euo pipefail
|
||||
mkdir -p pack-lists
|
||||
for p in cli daemon tui; do
|
||||
(cd packages/$p && npm pack --dry-run --json --ignore-scripts) \
|
||||
| node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{for(const f of JSON.parse(s)[0].files)console.log(f.path)})' \
|
||||
| sort > pack-lists/$p.txt
|
||||
echo "$p: $(wc -l < pack-lists/$p.txt) files"
|
||||
done
|
||||
- uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: pack-lists
|
||||
path: pack-lists/
|
||||
|
||||
typecheck:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 30
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
persist-credentials: false
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 22
|
||||
cache: npm
|
||||
- run: npm ci
|
||||
- run: npm run lint
|
||||
|
||||
repo-checks:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 30
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
persist-credentials: false
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 22
|
||||
cache: npm
|
||||
- run: npm ci
|
||||
- run: npm run test:repo
|
||||
|
||||
package-tests:
|
||||
# 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
|
||||
timeout-minutes: 45
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
package: [daemon, cli, tui, ui]
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
persist-credentials: false
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 22
|
||||
cache: npm
|
||||
- run: brew install tmux
|
||||
- run: npm ci
|
||||
- name: Build the packages the tests import
|
||||
run: npm run build
|
||||
- name: Run the suite without ambient credentials or external network
|
||||
run: |
|
||||
suite_root=$(mktemp -d "$RUNNER_TEMP/opr-test.XXXXXX")
|
||||
suite_root=$(cd "$suite_root" && pwd -P)
|
||||
mkdir -p "$suite_root/home" "$suite_root/bin"
|
||||
# Same system bytes, nonprivileged mode; no system file is changed.
|
||||
/usr/bin/install -m 0755 /bin/ps "$suite_root/bin/ps"
|
||||
# Only this job's temporary sockets (including tmux) are reachable.
|
||||
env -i HOME="$suite_root/home" PATH="$PATH" TMPDIR="$suite_root" TMUX_TMPDIR="$suite_root" \
|
||||
CI=true TERM=xterm-256color \
|
||||
sandbox-exec -D IPC_ROOT="$suite_root" -p '(version 1)(allow default)(deny network-outbound)(allow network-outbound (remote ip "localhost:*"))(allow network-outbound (subpath (param "IPC_ROOT")))' \
|
||||
/bin/bash -s "${{ matrix.package }}" <<'SUITE'
|
||||
set -euo pipefail
|
||||
node scripts/ci-macos-process-probe.mjs
|
||||
# The production readers use bare ps. Select real system bytes only after
|
||||
# self/owned-child observation and network/IPC confinement are proved.
|
||||
export PATH="$TMPDIR/bin:$PATH"
|
||||
test "$(command -v ps)" = "$TMPDIR/bin/ps"
|
||||
exec npm run test -w "packages/$1"
|
||||
SUITE
|
||||
|
||||
installed-scenario:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 35
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
persist-credentials: false
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 22
|
||||
cache: npm
|
||||
- run: npm ci
|
||||
- name: Installed package, daemon restart, and seeded durability failure
|
||||
run: bash scripts/run-pr-scenarios.sh
|
||||
- uses: actions/upload-artifact@v4
|
||||
if: always()
|
||||
with:
|
||||
name: installed-scenario-evidence
|
||||
path: dist/pr-scenarios/
|
||||
if-no-files-found: error
|
||||
@@ -1,5 +1,4 @@
|
||||
node_modules/
|
||||
node_modules
|
||||
dist/
|
||||
.DS_Store
|
||||
*.log
|
||||
@@ -32,10 +31,3 @@ demo/proof/
|
||||
|
||||
# Build artifacts
|
||||
*.tgz
|
||||
|
||||
# OPR.0.5.3.7 R2 — the shipped context-pack projection is DERIVED AT PACKAGE TIME
|
||||
# (scripts/generate-context-packs.mjs), never committed or edited in place.
|
||||
packages/daemon/context-packs/
|
||||
|
||||
# Internal build receipts; never commit
|
||||
/.evidence/
|
||||
+2
-2407
File diff suppressed because it is too large.
Load diff
@@ -1,75 +0,0 @@
|
||||
# Code of Conduct
|
||||
|
||||
## Our pledge
|
||||
|
||||
We as members, contributors, and maintainers pledge to make participation in OpenRig a
|
||||
harassment-free experience for everyone, regardless of age, body size, visible or invisible
|
||||
disability, ethnicity, sex characteristics, gender identity and expression, level of experience,
|
||||
education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual
|
||||
identity and orientation.
|
||||
|
||||
We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive,
|
||||
and healthy community.
|
||||
|
||||
## Our standards
|
||||
|
||||
Examples of behaviour that contributes to a positive environment:
|
||||
|
||||
- Demonstrating empathy and kindness toward other people
|
||||
- Being respectful of differing opinions, viewpoints, and experiences
|
||||
- Giving and gracefully accepting constructive feedback
|
||||
- Accepting responsibility and apologizing to those affected by our mistakes, and learning from
|
||||
the experience
|
||||
- Focusing on what is best not just for us as individuals, but for the overall community
|
||||
|
||||
Examples of unacceptable behaviour:
|
||||
|
||||
- The use of sexualized language or imagery, and sexual attention or advances of any kind
|
||||
- Trolling, insulting or derogatory comments, and personal or political attacks
|
||||
- Public or private harassment
|
||||
- Publishing others' private information, such as a physical or email address, without their
|
||||
explicit permission
|
||||
- Other conduct which could reasonably be considered inappropriate in a professional setting
|
||||
|
||||
## Enforcement responsibilities
|
||||
|
||||
Project maintainers are responsible for clarifying and enforcing our standards of acceptable
|
||||
behaviour and will take appropriate and fair corrective action in response to any behaviour that
|
||||
they deem inappropriate, threatening, offensive, or harmful. Maintainers have the right and
|
||||
responsibility to remove, edit, or reject comments, commits, code, issues, and other contributions
|
||||
that are not aligned to this Code of Conduct, and will communicate reasons for moderation
|
||||
decisions when appropriate.
|
||||
|
||||
## Scope
|
||||
|
||||
This Code of Conduct applies within all project spaces (the repository, Discussions, issues and
|
||||
pull requests) and when an individual is officially representing the project in public spaces.
|
||||
|
||||
## Enforcement
|
||||
|
||||
Instances of abusive, harassing, or otherwise unacceptable behaviour may be reported to the
|
||||
maintainers at **[email protected]**. All complaints will be reviewed and investigated
|
||||
promptly and fairly.
|
||||
All maintainers are obligated to respect the privacy and security of the reporter of any incident.
|
||||
|
||||
## Enforcement guidelines
|
||||
|
||||
Maintainers will follow these community impact guidelines in determining the consequences for any
|
||||
action they deem in violation of this Code of Conduct:
|
||||
|
||||
1. **Correction.** A private, written warning, with clarity around the nature of the violation and
|
||||
an explanation of why the behaviour was inappropriate. A public apology may be requested.
|
||||
2. **Warning.** A warning with consequences for continued behaviour, including no interaction with
|
||||
the people involved for a specified period.
|
||||
3. **Temporary ban.** A temporary ban from any sort of interaction or public communication with
|
||||
the community for a specified period.
|
||||
4. **Permanent ban.** A permanent ban from any sort of public interaction within the community.
|
||||
|
||||
## Attribution
|
||||
|
||||
This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
|
||||
version 2.1 by Coraline Ada Ehmke, available at
|
||||
https://www.contributor-covenant.org/version/2/1/code_of_conduct.html and licensed under
|
||||
[Creative Commons Attribution 4.0 International](https://creativecommons.org/licenses/by/4.0/).
|
||||
This adaptation names OpenRig and its maintainers and summarizes the enforcement guidelines. Community impact guidelines
|
||||
were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
|
||||
-110
@@ -1,110 +0,0 @@
|
||||
# Contributing to OpenRig
|
||||
|
||||
Thanks for being here. OpenRig is built in the open and by the thing it is: a rig of coding
|
||||
agents and a small group of people. External pull requests and issues have started arriving
|
||||
faster than we planned for, which is the best problem to have. This page says how to get a
|
||||
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 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. 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.
|
||||
|
||||
## Before a security or integration PR
|
||||
|
||||
OpenRig connects your coding agents to each other: shared context, messaging, coordination and long-running seats.
|
||||
It's designed for your own machine or a trusted private network, for you and people you trust, not for the open
|
||||
internet. It doesn't try to act for you in the outside world; your agents already have tools for that.
|
||||
|
||||
**Security-related PRs.** If you've found something exploitable, report it privately first (see
|
||||
[SECURITY.md](SECURITY.md)) rather than in a public PR. For hardening changes, tell us in the PR description:
|
||||
|
||||
- the scenario: how this goes wrong for someone using OpenRig as it's designed to be used, and the evidence you have
|
||||
- who or what causes it, and how they reach the install
|
||||
- what the change costs everyone else: a refusal, an extra step, a new setting
|
||||
|
||||
We look at the finding and the fix separately. We may agree with a finding and fix it differently, or decide the fix
|
||||
costs more than it protects. If the answers are missing we'll ask once, and close the PR with thanks if they don't
|
||||
come.
|
||||
|
||||
**Integrations with other tools or projects.** Open an issue or an Ideas Discussion and wait for a maintainer's yes on
|
||||
scope before you build it; an issue on its own isn't a yes. Often the best home for an integration is your own
|
||||
repository, and we're happy to link to it.
|
||||
|
||||
## Setting up
|
||||
|
||||
Node `^22 || ^24` and a working `tmux` are required. Then:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/mvschwarz/openrig.git
|
||||
cd openrig
|
||||
npm install
|
||||
npm run build # all workspaces
|
||||
npm test # repo checks + daemon, cli, tui test suites
|
||||
npm run lint # typecheck every package
|
||||
```
|
||||
|
||||
`npm test` builds the daemon and runs repository checks before the package suites. Read the
|
||||
specific failure: `npm run mirror-skills` updates skill mirrors, and
|
||||
`npm run generate-context-packs` updates generated packs. Use them when their source changed and
|
||||
review the generated diff; neither command fixes every documentation failure. The UI unit-test
|
||||
suite is advisory and separate: `npm run test:ui`.
|
||||
|
||||
For hands-on development, read the [check requirements](docs/reference/developing.md),
|
||||
[worktree setup](docs/reference/worktree-builds.md), and
|
||||
[machine changes](README.md#what-openrig-changes-on-your-machine). Use an isolated environment
|
||||
for changes that start daemons or agents; `OPENRIG_HOME` alone does not isolate provider settings.
|
||||
Permission configuration is an [explicit choice](docs/reference/getting-started.md#have-your-agent-configure-permissions).
|
||||
A checked-out tree is not the installed daemon; restarting an installed daemon does not adopt
|
||||
your working copy.
|
||||
|
||||
## Making the change
|
||||
|
||||
- One concern per pull request. Keep unrelated refactors separate; explain any refactor needed
|
||||
for the fix.
|
||||
- Keep the diff small enough to review in one sitting. If it is not, say why in the description.
|
||||
- Add or update a test where the change is testable. Use focused deterministic tests where
|
||||
possible. For terminal or provider behaviour, state what was exercised with the actual runtime
|
||||
and what was simulated; a stub alone does not prove the native interaction works.
|
||||
- Do not edit `CHANGELOG.md`. Maintainers write release notes at the tag.
|
||||
- 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): …`, `harness: …`.
|
||||
|
||||
## The pull request
|
||||
|
||||
Fill in the template. The three things a reviewer needs are: what a user gets, how you verified
|
||||
it, and anything you were unsure about. State the revision and relevant local changes you tested,
|
||||
what you actually ran, and any checks you could not run. Redact private information from evidence.
|
||||
|
||||
Contributions follow the repository's [Apache-2.0 license](LICENSE). Preserve attribution and any
|
||||
applicable license notices when adapting third-party material.
|
||||
|
||||
## What to expect from us
|
||||
|
||||
- We aim to acknowledge issues and pull requests within **one day**. An acknowledgement is not
|
||||
a completed review or a merge decision.
|
||||
- Our target for a first substantive review decision on an external PR is **seven days**. If it
|
||||
takes longer, we explain what is pending on the PR. This is a target, not a guaranteed deadline.
|
||||
- Labels you will see: `needs-repro` (we could not reproduce it yet; waiting on versions or steps),
|
||||
`fixed-on-main` (merged, not yet on npm), `good first issue`, `help wanted`, `discussion`
|
||||
(direction question; continues in Discussions).
|
||||
|
||||
Reviews here are done by people and by the project's own agents. An agent may ask the first
|
||||
clarifying question or run the reproduction; a maintainer makes the merge decision.
|
||||
|
||||
## Where things live
|
||||
|
||||
- Repository reference: `docs/reference/`; user documentation: [openrig.dev/docs](https://openrig.dev/docs).
|
||||
- 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`.
|
||||
@@ -1,162 +1,42 @@
|
||||
# OpenRig
|
||||
|
||||
[](https://www.npmjs.com/package/@openrig/cli) [](https://www.npmjs.com/package/@openrig/cli) [](LICENSE) [](https://github.com/mvschwarz/openrig/stargazers)
|
||||
Open source multi-agent harness for coding teams.
|
||||
|
||||
A harness wraps a model. A rig wraps your harnesses. Define your agent team in YAML, boot it with one command. Claude Code and Codex in the same rig, managed as one system.
|
||||
|
||||
OpenRig turns AI coding agents from a pile of terminal sessions into a persistent, organized team. Talk to a lead agent about the outcome you want; it can coordinate specialists across teams and bring you results and decisions that need your attention. Start with a repository and one useful change, then keep the team's work and context at the same addresses.
|
||||
|
||||
|
||||
**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/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
|
||||
|
||||
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.
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Install
|
||||
npm install -g @openrig/cli
|
||||
rig setup --dry-run
|
||||
|
||||
# Prepare the machine (attempts tmux, cmux, Claude Code, Codex, tmux defaults — reports what worked)
|
||||
rig setup
|
||||
|
||||
# Boot the conveyor starter rig (4 seats, mixed runtimes)
|
||||
rig up conveyor
|
||||
|
||||
# Open the UI
|
||||
rig ui open
|
||||
```
|
||||
|
||||
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.
|
||||
After the conveyor rig boots, open the UI and click **intake.lead** in the topology graph. Use **Open CMUX** to jump into a terminal for that node. If cmux is not available, use the tmux attach command shown in the node detail panel instead.
|
||||
|
||||
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).
|
||||
## Launch Walkthrough
|
||||
|
||||
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.
|
||||
The launch path above has been walked end-to-end on fresh macOS VMs. The only thing your agent can't do would be the oauth logins for claude and openai and dealing with permission prompts.
|
||||
|
||||
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.
|
||||
### 1. Open the conveyor rig
|
||||
|
||||
| Team | Starter | Models |
|
||||
| --- | --- | --- |
|
||||
| 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` |
|
||||
When the UI opens, the explorer is already visible on the left. Click the `conveyor` rig to load its live topology.
|
||||
|
||||
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.
|
||||
### 2. Click `CMUX` on `intake.lead`
|
||||
|
||||
```bash
|
||||
cd /path/to/your/repository
|
||||
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
|
||||
```
|
||||
Once the topology loads, go to the `intake.lead` node and click its `CMUX` button. That opens the intake terminal directly.
|
||||
|
||||
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. Then give the owner one bounded outcome from your repository:
|
||||
|
||||
```bash
|
||||
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 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
|
||||
|
||||
## Community
|
||||
|
||||
- **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)
|
||||
- **Videos:** [youtube.com/@openrig](https://www.youtube.com/@openrig)
|
||||
- **Releases:** [GitHub Releases](https://github.com/mvschwarz/openrig/releases) and npm `@openrig/cli`
|
||||
|
||||
We aim to acknowledge issues and pull requests within one day; see [CONTRIBUTING.md](CONTRIBUTING.md#what-to-expect-from-us) for review targets.
|
||||
|
||||
## What OpenRig changes on your machine
|
||||
|
||||
OpenRig writes instance state, provider integration and workspace files as part
|
||||
of setup and operation. These include **trust settings and executable hooks**.
|
||||
The summary below follows this source revision; check `rig --version` when
|
||||
using a published package, since repository guidance can be ahead of npm.
|
||||
|
||||
| When | What changes and why |
|
||||
| --- | --- |
|
||||
| **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`. `--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.
|
||||
|
||||
- **Claude Code:** managed startup writes workspace trust and onboarding completion
|
||||
to `~/.claude.json`. In the workspace, `.claude/settings.local.json` receives
|
||||
the context collector's `statusLine` command and selected activity hooks;
|
||||
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. The trust writer uses the daemon home, so a custom
|
||||
`CLAUDE_CONFIG_DIR` is not a general relocation of these writes.
|
||||
- **Codex:** writes the daemon's `CODEX_HOME/config.toml` (normally
|
||||
`~/.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. 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`
|
||||
endpoint, using its activity token. That payload excludes prompt text and tool
|
||||
arguments. Claude's collector writes context/token usage, session/transcript-path
|
||||
metadata and available rate-limit data to the instance's `state/context-usage`
|
||||
and `state/provider-usage`. Provider and selected MCP connections have their own
|
||||
data flows. Daemon plugin initialization also checks the OpenRig plugin release
|
||||
endpoint on GitHub.
|
||||
|
||||
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.
|
||||
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`.
|
||||
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 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
|
||||
policy configuration (the four `rig policy` aliases remain compatible). Use
|
||||
`rig seat set-permissions <seat> --mode <mode> --reason <text>` for an audited
|
||||
future-launch choice: `floor`, `full_bypass`, or `inherit` to clear the seat
|
||||
override. Additional Claude modes such as `auto` require support from the exact
|
||||
managed Claude executable at the seat's working directory; selection and launch
|
||||
each check it. Unsupported or changed contexts refuse without a fallback.
|
||||
This does not relaunch the seat
|
||||
or change its current native process, history, rules or hooks. `rig seat status`
|
||||
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, 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.
|
||||
> From here, give the intake agent a packet of work and watch it move through planning, build, review, and closeout.
|
||||
|
||||
## What It Does
|
||||
|
||||
@@ -164,87 +44,71 @@ OpenRig is a multi-agent harness — it manages the system that coding agents fo
|
||||
|
||||
- **Define** topologies in YAML (RigSpec) with pods, edges, and continuity policies
|
||||
- **Boot** everything with `rig up` — tmux sessions, harnesses, startup files, readiness checks
|
||||
- **See** rigs, pods, and seats in the TUI topology table and graph; inspect projects, specs, feeds, and instance health
|
||||
- **See** the topology in a live graph with explorer, node detail, and system log
|
||||
- **Discover** existing Claude Code and Codex sessions in tmux and adopt them into a managed rig
|
||||
- **Snapshot** the topology with `rig down --snapshot`, restore by name with `rig up <name>`
|
||||
- **Snapshot** the full topology on `rig down`, restore by name with `rig up <name>`
|
||||
- **Communicate** across agents with `rig send`, `rig broadcast`, and `rig chatroom`
|
||||
- **Protect** a seat where you type by hand: `rig seat set-typing-guard <seat> --enabled true --reason <text>` holds automatic messages and wakes instead of typing them into that seat (off by default; see `rig seat set-typing-guard --help`)
|
||||
- **Connect** Slack through an app you create in your own workspace; the experimental `rig slack manifest` prints that app's manifest ([setup guide](docs/reference/slack-app-setup.md))
|
||||
- **Evolve** running topologies with `rig grow`, `rig shrink`, `rig launch`, `rig remove`
|
||||
- **Evolve** running topologies with `rig expand`, `rig shrink`, `rig launch`, `rig remove`
|
||||
|
||||
Every agent runs in a tmux session you can attach to, inspect, and work with directly.
|
||||
|
||||
## Starter Rigs
|
||||
|
||||
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 product-team --kind rig
|
||||
rig up product-team
|
||||
```
|
||||
|
||||
Use it when you want a larger product squad: two orchestrators, implementation, QA, design, and two independent reviewers.
|
||||
|
||||
For a smaller starter, use `conveyor`:
|
||||
OpenRig ships with a conveyor starter rig for learning workflow handoff:
|
||||
|
||||
```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.
|
||||
```
|
||||
conveyor (rig, pod_aware)
|
||||
Starter workflow rig: a station pipeline that can move multiple
|
||||
work packets at once, with queue depth acting as natural backpressure.
|
||||
|
||||
Pod: intake (1 member)
|
||||
lead — claude-code
|
||||
Pod: plan (1 member)
|
||||
planner — codex
|
||||
Pod: build (1 member)
|
||||
builder — claude-code
|
||||
Pod: review (1 member)
|
||||
reviewer — codex
|
||||
```
|
||||
|
||||
For a larger human-operated product-development topology, inspect `product-team`:
|
||||
|
||||
```bash
|
||||
rig specs preview product-team
|
||||
```
|
||||
|
||||
Also ships: `implementation-pair`, `adversarial-review`, `research-team`, and `secrets-manager` (HashiCorp Vault managed by a specialist agent).
|
||||
|
||||
Browse the library:
|
||||
|
||||
```bash
|
||||
rig specs ls
|
||||
```
|
||||
Browse the library: `rig specs ls`
|
||||
|
||||
## How It Works
|
||||
|
||||
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.
|
||||
OpenRig is a local daemon + CLI + MCP server + React UI, built on tmux.
|
||||
|
||||
```
|
||||
CLI / TUI / MCP
|
||||
CLI / UI / MCP
|
||||
|
|
||||
Hono HTTP daemon
|
||||
|
|
||||
Domain services
|
||||
Domain services (52)
|
||||
|
|
||||
SQLite + tmux + runtime adapters
|
||||
```
|
||||
|
||||
- **CLI**: Commands for both humans and agents to launch teams, inspect state, send messages, track owned work, and manage context.
|
||||
- **TUI**: Topology explorer, table and graph views, seat details, Specs, Projects, Terminals, Feed, and System. Navigate with the keyboard, mouse, or command bar.
|
||||
- **MCP**: Tools so agents can manage their own topology (`rig_up`, `rig_ps`, `rig_send`, `rig_chatroom_send`, etc.)
|
||||
- **Runtimes**: Native Claude Code and Codex sessions, terminal nodes, and a Pi adapter using an RPC runner inside a terminal pane.
|
||||
|
||||
## Terminal UI and Workspaces
|
||||
|
||||
The TUI shows the team's coordination state; herdr and cmux show the actual agent terminals alongside it. Use `rig tui commands` to list the TUI's command-bar navigation, or [try the interactive TUI tour](https://openrig.dev/tour/workspace).
|
||||
|
||||
|
||||
|
||||
*Captured from the interactive TUI demo using fictional project data.*
|
||||
|
||||
With herdr installed and connected, open the starter's terminals together:
|
||||
|
||||
```bash
|
||||
rig terminal open first-project --provider herdr
|
||||
```
|
||||
|
||||
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.
|
||||
- **CLI**: 40+ commands designed for both humans and agents. Every mutating command ends with what happened, current state, and next action.
|
||||
- **UI**: Explorer sidebar, topology graph with pod grouping, node detail panel, system log, chatroom.
|
||||
- **MCP**: 17 tools so agents can manage their own topology (`rig_up`, `rig_ps`, `rig_send`, `rig_chatroom_send`, etc.)
|
||||
- **Runtimes**: Claude Code, Codex, and terminal nodes. Adapters for Pi and OpenCode in development.
|
||||
|
||||
## Key Concepts
|
||||
|
||||
- **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-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.
|
||||
- **Pod**: Bounded context group. Agents in a pod share memory and can maintain each other's context.
|
||||
- **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, or failed).
|
||||
- **RigBundle**: Portable archive with vendored AgentSpecs and SHA-256 integrity. Share topologies across machines.
|
||||
@@ -262,83 +126,13 @@ rig send vault-specialist@secrets-manager "Check Vault health and report status.
|
||||
|
||||
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). 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
|
||||
|
||||
OpenRig 0.6.0 supports Node.js 22 and 24 only. Its SQLite binding
|
||||
(better-sqlite3 13) requires Node 22 or newer. Node 20 is no longer supported;
|
||||
the install check refuses it with an explanation.
|
||||
|
||||
If you run OpenRig on Node 20, switch Node first, then reinstall the CLI under
|
||||
the new Node (a version manager keeps a separate global package set for each
|
||||
Node):
|
||||
|
||||
```bash
|
||||
nvm install 22 # or 24; fnm or your package manager work the same way
|
||||
npm install -g @openrig/cli
|
||||
rig --version
|
||||
```
|
||||
|
||||
Your existing OpenRig data stays where it is. The daemon reopens the same
|
||||
database under the new binding and applies any pending migrations in place.
|
||||
Restart the daemon under the new Node by following the upgrade procedure above.
|
||||
|
||||
### Crossing the 0.5.9 layout boundary
|
||||
|
||||
The migration below still applies when upgrading from a pre-0.5.9 instance.
|
||||
|
||||
0.5.9 makes `$OPENRIG_HOME/context` the addressable context library, writes
|
||||
Claude telemetry to `state/context-usage` (and provider telemetry to
|
||||
`state/provider-usage`), and installs the default System World at
|
||||
`context/system/system-world.yaml`. Existing instances cross this boundary by
|
||||
an **Agent-Operated Migration** from the shipped `openrig-upgrade` skill. The
|
||||
target runtime reads canonical-first with legacy-fallback while new writes use
|
||||
the canonical roots; a custom context-library root stays stable during
|
||||
activation. This is not a directory rename to do while an old collector writes.
|
||||
|
||||
```bash
|
||||
# SKILL_DIR is the installed openrig-upgrade skill directory.
|
||||
node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" --help
|
||||
node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" --home "$OPENRIG_HOME"
|
||||
node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" --home "$OPENRIG_HOME" --apply-state --preimage /safe/path/layout-0.5.9-before
|
||||
|
||||
# Activate the exact target runtime separately. After every bounded legacy tail is followed by newer paired samples at both new state roots:
|
||||
node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" --home "$OPENRIG_HOME" --verify --preimage /safe/path/layout-0.5.9-before > /safe/path/layout-0.5.9-verify.json
|
||||
|
||||
# Run the separately invoked non-destructive finalizer only with that exact receipt:
|
||||
node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" --home "$OPENRIG_HOME" --apply-library --preimage /safe/path/layout-0.5.9-before --verification /safe/path/layout-0.5.9-verify.json
|
||||
|
||||
# Restore only helper-owned preparation/finalizer effects if the observed upgrade must be reversed:
|
||||
node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" --home "$OPENRIG_HOME" --rollback /safe/path/layout-0.5.9-before
|
||||
```
|
||||
|
||||
`--help` prints the phase grammar without inventorying the instance. No phase
|
||||
flag intentionally runs the read-only plan; unknown options fail nonzero before
|
||||
plan or mutation.
|
||||
|
||||
Every phase emits JSON. Stop on any issue or incomplete receipt and follow its
|
||||
`next` action; do not continue from copied legacy telemetry or retry a partial
|
||||
mutation blindly. Preparation leaves legacy state and collector settings in
|
||||
place. Verification accepts exact tail bytes only when that same seat has newer
|
||||
paired context and provider samples under `state/`; finalization revalidates the
|
||||
accepted tails, copies the library without overwrite, and switches config last.
|
||||
The helper never removes the legacy telemetry or library. Retirement follows
|
||||
separate stable runtime, writer, reader, and recovery proof. Daemon, database,
|
||||
seat, plugin, and release lifecycle actions remain agent-owned.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Node.js 22 or 24 (the supported versions in this release). Node 20 is no
|
||||
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).
|
||||
- Node.js 20, 22, or 24 (even-numbered LTS releases; odd releases like 25 lack native addon prebuilds)
|
||||
- tmux
|
||||
- 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
|
||||
- cmux for `Open CMUX` node surface controls
|
||||
- Docker for service-backed rigs and managed apps
|
||||
|
||||
## Setup and Troubleshooting
|
||||
@@ -349,31 +143,30 @@ Optional:
|
||||
|
||||
Both commands support `--json` for agent-driven workflows.
|
||||
|
||||
Before setup or managed launch, review [what OpenRig changes on your machine](#what-openrig-changes-on-your-machine), including provider trust, hooks and selected runtime resources.
|
||||
Managed runtime boot (during `rig up`) may modify runtime config for core bootstrap and spec-selected runtime resources. `rig setup` discloses these paths so agents know what may be changed:
|
||||
- global Claude: `~/.claude/settings.json` for minimal OpenRig command allowlisting
|
||||
- global Claude state: `~/.claude.json` for managed workspace trust and onboarding completion
|
||||
- project Claude: `.claude/settings.local.json` for context collector/activity hooks and selected `claude_settings_fragment` resources
|
||||
- project Claude MCP: `.mcp.json` for selected `claude_mcp_fragment` resources
|
||||
- global Codex: `~/.codex/config.toml` for workspace trust and selected `codex_config_fragment` resources
|
||||
|
||||
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. 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.
|
||||
**For agents:** Ask the user whether they want core setup (`rig setup`) or the fuller workstation path (`rig setup --full`) before choosing the invocation. Inspect the result with `--json` and use `rig doctor` to finish any remaining machine-specific issues.
|
||||
|
||||
## Comparison with Claude Managed Agents
|
||||
|
||||
OpenRig is open source and self-hosted, with Claude Code and Codex in the same team. You operate it on your own infrastructure; the selected providers' model usage costs still apply.
|
||||
Anthropic shipped Claude Managed Agents — a cloud-hosted, Claude-only runtime at $0.08/session-hour. OpenRig is the local side: open source, cross-harness, runs on your machine, costs nothing.
|
||||
|
||||
[Full comparison](https://openrig.dev/compare/claude-managed-agents)
|
||||
|
||||
## Links
|
||||
|
||||
- **Website**: [openrig.dev](https://openrig.dev)
|
||||
- **Docs**: [openrig.dev/docs](https://openrig.dev/docs) ([documentation index for agents](https://openrig.dev/llms.txt))
|
||||
- **Blog**: [openrig.dev/blog](https://openrig.dev/blog) · [Why I Built OpenRig](https://esoteric.run/blog/why-i-built-openrig)
|
||||
- **Blog**: [Why I Built OpenRig](https://esoteric.run/blog/why-i-built-openrig)
|
||||
- **Docs**: [openrig.dev/docs](https://openrig.dev/docs)
|
||||
- **Open Specification**: [openrig.dev/specs](https://openrig.dev/specs)
|
||||
- **Videos**: [youtube.com/@openrig](https://www.youtube.com/@openrig)
|
||||
- **X**: [@_feralmachine](https://twitter.com/_feralmachine)
|
||||
- **Follow the project**: [openrig.dev/follow](https://openrig.dev/follow)
|
||||
|
||||
## Star History
|
||||
|
||||
[](https://star-history.com/#mvschwarz/openrig&Date)
|
||||
- **Twitter**: [@_feralmachine](https://twitter.com/_feralmachine)
|
||||
|
||||
## License
|
||||
|
||||
|
||||
-51
@@ -1,51 +0,0 @@
|
||||
# Security policy
|
||||
|
||||
## Supported versions
|
||||
|
||||
Only the latest published version on npm (`@openrig/cli`) is supported. Fixes are developed on
|
||||
`main` and released after verification; a merged fix is not necessarily in the published package.
|
||||
Include the affected version even when reporting a problem in an older installation.
|
||||
|
||||
## What OpenRig touches
|
||||
|
||||
OpenRig runs a local daemon, drives coding agents in tmux sessions on your machine, and writes
|
||||
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.
|
||||
|
||||
## Reporting a vulnerability
|
||||
|
||||
Please do not open a public issue for a vulnerability.
|
||||
|
||||
Open the repository's [Security page](https://github.com/mvschwarz/openrig/security). If
|
||||
**Report a vulnerability** is available, use it to send a private report to the maintainers.
|
||||
The reporter and authorized advisory collaborators can also see that report; it is not public.
|
||||
Availability depends on the repository setting, not on this file being present.
|
||||
|
||||
If that option is unavailable, ask in [Discussions Q&A](https://github.com/mvschwarz/openrig/discussions/categories/q-a)
|
||||
for a private security contact. Post only the request for a channel: do not include the
|
||||
vulnerability details, reproduction, logs, credentials or affected private systems in public.
|
||||
Wait for the private channel before sharing the report.
|
||||
|
||||
Include: the OpenRig version, the harnesses involved, the steps to reproduce, and what an attacker
|
||||
could do. A proof of concept is welcome; a working exploit against a third party's machine is not.
|
||||
|
||||
## What to expect
|
||||
|
||||
- We will acknowledge the report and coordinate assessment and next steps privately.
|
||||
- Assessment and fix timing depend on impact and reproduction; no fixed deadline is promised.
|
||||
- We will agree on disclosure and credit with you. You can ask to remain anonymous.
|
||||
|
||||
## Scope notes
|
||||
|
||||
- OpenRig is designed for your own machine or a trusted private network, for you and people you trust, not for the
|
||||
open internet. We assess reports by their practical impact on a user in that setup. Exposing an install to the open
|
||||
internet isn't a supported deployment. OpenRig's own gateway integrations with outside services, such as Slack, and
|
||||
anything that lets an untrusted party reach the daemon or an agent are in scope.
|
||||
- OpenRig assumes the machine and the accounts it runs under are trusted by their owner. Reports
|
||||
that require a hostile local user with the same account are still welcome but are unlikely to be
|
||||
treated as high severity.
|
||||
- A harness carrying out an intentionally authorized operation is not by itself evidence of an
|
||||
OpenRig vulnerability. Reports of OpenRig bypassing a chosen permission, changing trust
|
||||
unexpectedly, or routing data or actions to the wrong destination are in scope.
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 1.3 MiB |
Binary file not shown.
|
Before Width: | Height: | Size: 71 KiB |
@@ -1,30 +0,0 @@
|
||||
{
|
||||
"url": "https://context7.com/mvschwarz/openrig",
|
||||
"public_key": "pk_HcRwWEoFBsmU1mo5VIvWw",
|
||||
"projectTitle": "OpenRig",
|
||||
"description": "OpenRig is an open-source multi-agent harness: define a team of Claude Code and Codex agents in YAML, boot it with the rig CLI, and coordinate the agents through tmux sessions, a durable queue and a local daemon.",
|
||||
"folders": [],
|
||||
"excludeFolders": [
|
||||
"docs/releases",
|
||||
"packages/daemon/specs",
|
||||
"packages/daemon/test",
|
||||
"packages/test-system",
|
||||
"skills/_canonical/process",
|
||||
"skills/_canonical/pm",
|
||||
"spike",
|
||||
"docker",
|
||||
"**/node_modules",
|
||||
"**/fixtures"
|
||||
],
|
||||
"excludeFiles": [],
|
||||
"rules": [
|
||||
"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.",
|
||||
"rig send <session> \"message\" types into a peer's terminal and presses Enter; rig capture <session> reads that peer's screen.",
|
||||
"Work another agent must act on goes in the queue (rig queue create or rig queue handoff); a message informs but does not assign work.",
|
||||
"Use rig start to bring rigs back after a reboot or daemon restart.",
|
||||
"Run rig --help for the current command surface; the CLI is authoritative over older examples."
|
||||
]
|
||||
}
|
||||
+2
-2
@@ -80,7 +80,7 @@ This produces automated proof artifacts in `demo/proof/`:
|
||||
| Artifact | Source | Type |
|
||||
|----------|--------|------|
|
||||
| `up-transcript.txt` | `rig up demo/rig.yaml` output | Automatic |
|
||||
| `ps-nodes.txt` | `rig ps --nodes --rig <rig>` after boot | Automatic |
|
||||
| `ps-nodes.txt` | `rig ps --nodes` after boot | Automatic |
|
||||
| `health-after-boot.json` | `check-demo-health.ts` after boot | Automatic |
|
||||
| `native-resume-after-boot.txt` | immediate native probe after boot | Automatic |
|
||||
| `native-resume-after-boot.json` | immediate native probe machine output | Automatic |
|
||||
@@ -91,7 +91,7 @@ This produces automated proof artifacts in `demo/proof/`:
|
||||
| `down-transcript.txt` | `rig down` output | Automatic |
|
||||
| `tmux-check.txt` | `tmux ls` after teardown | Automatic |
|
||||
| `restore-transcript.txt` | `rig restore <snapshotId> --rig <rigId>` output | Automatic |
|
||||
| `ps-restored.txt` | `rig ps --nodes --rig <rig>` after restore | Automatic |
|
||||
| `ps-restored.txt` | `rig ps --nodes` after restore | Automatic |
|
||||
| `browser-screenshot.png` | Explorer + Graph + Detail Panel | **Manual** |
|
||||
| `resume-test.txt` | Post-restore agent context check | **Manual** |
|
||||
|
||||
|
||||
+2
-3
@@ -35,8 +35,7 @@ echo ""
|
||||
|
||||
# 2. Node status
|
||||
echo "Step 2: Node status after boot..."
|
||||
# OPR.0.4.4.21: --nodes requires an explicit target outside a managed session.
|
||||
rig ps --nodes --rig "$RIG_ID" 2>&1 | tee "$PROOF_DIR/ps-nodes.txt"
|
||||
rig ps --nodes 2>&1 | tee "$PROOF_DIR/ps-nodes.txt"
|
||||
echo ""
|
||||
|
||||
# 3. Health check after boot
|
||||
@@ -96,7 +95,7 @@ echo ""
|
||||
|
||||
# 10. Node status after restore
|
||||
echo "Step 10: Node status after restore..."
|
||||
rig ps --nodes --rig "$RIG_ID" 2>&1 | tee "$PROOF_DIR/ps-restored.txt"
|
||||
rig ps --nodes 2>&1 | tee "$PROOF_DIR/ps-restored.txt"
|
||||
echo ""
|
||||
|
||||
echo "=== Automated proof artifacts produced ==="
|
||||
|
||||
+2
-3
@@ -32,8 +32,7 @@ fi
|
||||
# Show node status
|
||||
echo ""
|
||||
echo "Node status:"
|
||||
# OPR.0.4.4.21: --nodes requires an explicit target outside a managed session.
|
||||
rig ps --nodes --rig "$RIG_ID"
|
||||
rig ps --nodes
|
||||
|
||||
# Establish a restore-safe baseline for the demo rig.
|
||||
echo ""
|
||||
@@ -56,6 +55,6 @@ echo "=== Demo topology is running ==="
|
||||
echo "Dashboard: http://localhost:5173"
|
||||
echo ""
|
||||
echo "Next steps:"
|
||||
echo " rig ps --nodes --rig '$RIG_ID' # Check node status"
|
||||
echo " rig ps --nodes # Check node status"
|
||||
echo " rig down $RIG_ID # Tear down (auto-snapshots)"
|
||||
echo " rig restore <snapshotId> --rig $RIG_ID # Restore the exact snapshot you just created"
|
||||
@@ -1,64 +0,0 @@
|
||||
# 51-04 testbed image (openrig-testbed) — see IMPL-PLAN §1. Built HOST-side by
|
||||
# scripts/build-testbed-image.sh, which resolves + records the base digest, pins node, stages the
|
||||
# stub assets, and COPYs the local openrig pack tarball. Byte-reproducible BY CONTRACT: the base is
|
||||
# digest-pinned (the verb refuses a tag-floating reference), node is pinned, and openrig comes from
|
||||
# the tree — never the npm registry (0.5.1 is unreleased). Layers are ordered stable -> volatile.
|
||||
|
||||
# --- base: a digest-pinned LTS-slim Linux, supplied by the build verb (docker/testbed/base-image,
|
||||
# which REFUSES a non-@sha256 reference). No floating tag is baked into this file. ---
|
||||
ARG BASE_IMAGE
|
||||
FROM ${BASE_IMAGE}
|
||||
|
||||
# --- layer 1: userland + tmux + git + PTY/process essentials + the native-build toolchain (most stable) ---
|
||||
# python3/make/g++ are REQUIRED, not optional: the sealed Q2 packaging ruling builds better-sqlite3
|
||||
# FRESH ON TARGET (never a prebuilt/nested binary — that would risk a wrong-arch native module). Its
|
||||
# install is `prebuild-install || node-gyp rebuild`; with a self-contained tarball npm reaches that
|
||||
# step, prebuild-install is absent, and node-gyp needs python3+make+g++ to compile from source. Without
|
||||
# them layer 3 dies ('prebuild-install: not found' → 'Could not find any Python installation'). This is
|
||||
# testbed-image scope only (no multi-stage gold-plating — the image is a throwaway test target).
|
||||
RUN set -eux; \
|
||||
apt-get update; \
|
||||
DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
|
||||
ca-certificates curl xz-utils git tmux tini procps \
|
||||
python3 make g++; \
|
||||
rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# --- layer 2: pinned node (an in-range engines version — see scripts/check-engines) ---
|
||||
ARG NODE_VERSION=22.22.1
|
||||
ARG TARGETARCH
|
||||
RUN set -eux; \
|
||||
case "${TARGETARCH}" in \
|
||||
amd64) NODE_ARCH=x64 ;; \
|
||||
arm64) NODE_ARCH=arm64 ;; \
|
||||
"") 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; \
|
||||
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 ---
|
||||
ARG OPENRIG_TARBALL
|
||||
COPY ${OPENRIG_TARBALL} /tmp/openrig.tgz
|
||||
RUN set -eux; \
|
||||
npm install -g /tmp/openrig.tgz; \
|
||||
rm -f /tmp/openrig.tgz; \
|
||||
rig --version
|
||||
|
||||
# --- layer 4: stub runtime assets (zero-token by construction; staged by the build verb into the
|
||||
# build context as ./stub-assets/, hashed into the manifest via deriveStubAssetsHash) ---
|
||||
COPY stub-assets/ /opt/openrig-testbed/stub-assets/
|
||||
|
||||
# --- layer 5: a non-root openrig user + a tini entrypoint into tmux-server-friendly init ---
|
||||
RUN set -eux; \
|
||||
useradd --create-home --shell /bin/bash openrig; \
|
||||
mkdir -p /opt/openrig-testbed; \
|
||||
chown -R openrig:openrig /opt/openrig-testbed
|
||||
COPY entrypoint.sh /opt/openrig-testbed/entrypoint.sh
|
||||
RUN chmod 0755 /opt/openrig-testbed/entrypoint.sh
|
||||
USER openrig
|
||||
WORKDIR /home/openrig
|
||||
ENTRYPOINT ["/usr/bin/tini", "--", "/opt/openrig-testbed/entrypoint.sh"]
|
||||
CMD ["sleep", "infinity"]
|
||||
@@ -1,7 +0,0 @@
|
||||
# Thin CI layer over the EXISTING installed-package testbed. No credentials,
|
||||
# host mounts, provider binaries or additional package installation.
|
||||
ARG TESTBED_IMAGE
|
||||
FROM ${TESTBED_IMAGE}
|
||||
COPY runner.mjs /opt/openrig-testbed/runner.mjs
|
||||
COPY scenarios/ /opt/openrig-testbed/scenarios/
|
||||
CMD ["node", "/opt/openrig-testbed/runner.mjs", "healthy"]
|
||||
@@ -1,4 +0,0 @@
|
||||
# Docker Hub library/debian bookworm-slim OCI index, resolved 2026-09-29.
|
||||
# Registry response bytes SHA256 verified against Docker-Content-Digest.
|
||||
# amd64 and arm64 are present; image execution is verified in CI, not by this pin.
|
||||
debian:bookworm-slim@sha256:3783cc01769c7b2b1b83a5c5ad96c815348e28ed7da68e2e3687004faa906251
|
||||
@@ -1,13 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# 51-04 testbed entrypoint — runs under tini (PID1 reaping, layer 5). Keeps the container init
|
||||
# tmux-server-friendly (tini reaps the tmux server's children) and seeds the per-container
|
||||
# self-host identity when the operator supplies one (plan §3 — the 51-09 OPENRIG_SELF_HOST_ID
|
||||
# adopt path; N containers boot as N distinct named hosts). Then execs the container command.
|
||||
set -euo pipefail
|
||||
|
||||
if [ -n "${OPENRIG_SELF_HOST_ID:-}" ]; then
|
||||
# Announce the adopted self-host id so `docker logs` shows which simulated host this is.
|
||||
echo "[testbed] self-host-id=${OPENRIG_SELF_HOST_ID}" >&2
|
||||
fi
|
||||
|
||||
exec "$@"
|
||||
@@ -1,54 +0,0 @@
|
||||
# L0 — resolve the host-side build inputs (prerequisite to every build)
|
||||
|
||||
**Runs host-side.** Populates the two documented slots the build verb refuses-until-resolved, so the
|
||||
image is byte-reproducible against a pinned base + a known stub census. Do this once per base/stub
|
||||
change; commit the resolved slots so the pin is durable.
|
||||
|
||||
## L0.1 — resolve the digest-pinned base
|
||||
|
||||
The VM seat cannot pull/inspect a registry digest; do it on the host with a runtime present.
|
||||
|
||||
```bash
|
||||
# Pull the intended LTS-slim base, then read its immutable RepoDigest.
|
||||
docker pull debian:bookworm-slim
|
||||
BASE_REF="$(docker inspect --format '{{index .RepoDigests 0}}' debian:bookworm-slim)"
|
||||
echo "${BASE_REF}" # e.g. debian@sha256:<64-hex> (or docker.io/library/debian@sha256:...)
|
||||
```
|
||||
|
||||
Write the single resolved reference into the slot (replacing the comment block):
|
||||
|
||||
```bash
|
||||
printf '%s\n' "${BASE_REF}" > docker/testbed/base-image
|
||||
# Prove the fence accepts it (readBaseImage returns the digest, or exits non-zero):
|
||||
node -e 'import("./scripts/testbed-build-inputs.mjs").then(m=>console.log(m.readBaseImage("docker/testbed/base-image")))'
|
||||
```
|
||||
|
||||
**PASS:** `readBaseImage` prints `{ ref, name, digest: 'sha256:<64-hex>' }`. **FAIL:** any non-zero /
|
||||
"tag-floating" / "unresolved" — the slot is not a valid digest pin; do not proceed to a build.
|
||||
|
||||
## L0.2 — finalize the stub-assets census list
|
||||
|
||||
The zero-token stub payload (plan §1 layer 4) is the container-local stub `rig.yaml` + its agent
|
||||
fixture + `culture.md` that L3 boots. Add each repo-relative path, one per line, to
|
||||
`docker/testbed/stub-assets.list` (comments/blanks ignored). Ground the exact set against L3 (the
|
||||
`rig up` stub topology it settles) — do not guess; the list IS the census scope the manifest hashes.
|
||||
|
||||
```bash
|
||||
# After populating the list, prove the census resolves over the staged set the build will stage:
|
||||
node -e 'import("./scripts/testbed-build-inputs.mjs").then(m=>{
|
||||
const fs=require("fs");
|
||||
const files=fs.readFileSync("docker/testbed/stub-assets.list","utf8").split("\n").map(s=>s.replace(/#.*/,"").trim()).filter(Boolean);
|
||||
console.log(m.deriveStubAssetsHash(".", files).receipt);
|
||||
})'
|
||||
```
|
||||
|
||||
**PASS:** the receipt lists exactly the intended stub assets, each with a 64-hex content digest.
|
||||
**FAIL:** empty set / a missing file / a path escaping the root — fix the list, never a partial census.
|
||||
|
||||
## L0.3 — record evidence
|
||||
|
||||
```bash
|
||||
GIT_SHA="$(git rev-parse HEAD)"; EVID="dist/testbed-image/evidence/${GIT_SHA}"; mkdir -p "${EVID}"
|
||||
{ echo "docker: $(docker --version)"; echo "base: ${BASE_REF}"; echo "stub-assets.list:"; cat docker/testbed/stub-assets.list; } > "${EVID}/L0-inputs.txt"
|
||||
echo "VERDICT: PASS — base digest pinned + stub census resolved" >> "${EVID}/L0-inputs.txt"
|
||||
```
|
||||
@@ -1,47 +0,0 @@
|
||||
# L1 — PTY allocation (docker run -t + tmux capture returns real bytes; resize propagates)
|
||||
|
||||
**Runs host-side, after L0 + a build.** Proves the image gives a real PTY and that tmux inside it
|
||||
produces genuine captured bytes — the TUI-spike fixed-viewport pattern, reused. Never assert the
|
||||
observable from memory; verdict against the captured bytes.
|
||||
|
||||
## Setup
|
||||
|
||||
```bash
|
||||
GIT_SHA="$(git rev-parse HEAD)"; IMAGE="openrig-testbed:${GIT_SHA}"; EVID="dist/testbed-image/evidence/${GIT_SHA}"; mkdir -p "${EVID}"
|
||||
docker image inspect "${IMAGE}" >/dev/null # built by scripts/build-testbed-image.sh (FAIL loudly if absent)
|
||||
NAME="orig-l1-${GIT_SHA:0:8}"
|
||||
```
|
||||
|
||||
## L1.1 — allocate a PTY + start a tmux session inside
|
||||
|
||||
```bash
|
||||
# -t allocates a PTY; the entrypoint (tini) holds the container. Detached, fixed 80x24 viewport.
|
||||
docker run -d -t --name "${NAME}" "${IMAGE}"
|
||||
docker exec "${NAME}" tmux new-session -d -s l1 -x 80 -y 24
|
||||
docker exec "${NAME}" tmux send-keys -t l1 'printf "PTY-OK:%s\n" "$TERM"; tty' Enter
|
||||
sleep 1
|
||||
docker exec "${NAME}" tmux capture-pane -p -t l1 | tee "${EVID}/L1-capture.txt"
|
||||
```
|
||||
|
||||
**PASS:** the capture contains a real `PTY-OK:` line and `tty` prints a real pts device
|
||||
(`/dev/pts/...`), not "not a tty". **FAIL:** "not a tty" / empty capture.
|
||||
|
||||
## L1.2 — resize propagates
|
||||
|
||||
```bash
|
||||
docker exec "${NAME}" tmux resize-window -t l1 -x 120 -y 40
|
||||
docker exec "${NAME}" tmux display-message -p -t l1 '#{window_width}x#{window_height}' | tee "${EVID}/L1-resize.txt"
|
||||
```
|
||||
|
||||
**PASS:** reports `120x40` (the resize propagated to the in-container tmux). **FAIL:** stays `80x24`.
|
||||
|
||||
## Teardown + evidence
|
||||
|
||||
```bash
|
||||
docker rm -f "${NAME}" >/dev/null
|
||||
{ grep -q 'PTY-OK:' "${EVID}/L1-capture.txt" && grep -q '/dev/pts/' "${EVID}/L1-capture.txt" && grep -q '120x40' "${EVID}/L1-resize.txt" \
|
||||
&& echo "VERDICT: PASS — PTY allocated, real capture bytes, resize propagated" \
|
||||
|| echo "VERDICT: FAIL — see L1-capture.txt / L1-resize.txt"; } | tee "${EVID}/L1-verdict.txt"
|
||||
```
|
||||
|
||||
**Fence:** no `-v` HOME/workspace mounts; the container is disposable (fresh HOME).
|
||||
@@ -1,55 +0,0 @@
|
||||
# L2 — tmux server lifecycle (detach-survive, multi-pane, send-keys + capture round-trip)
|
||||
|
||||
**Runs host-side, after L1.** Proves the tmux server — the substrate the whole product rides —
|
||||
behaves in-container: sessions survive client detach, multiple panes coexist, and a send-keys →
|
||||
capture round-trip returns the exact bytes.
|
||||
|
||||
## Setup
|
||||
|
||||
```bash
|
||||
GIT_SHA="$(git rev-parse HEAD)"; IMAGE="openrig-testbed:${GIT_SHA}"; EVID="dist/testbed-image/evidence/${GIT_SHA}"; mkdir -p "${EVID}"
|
||||
NAME="orig-l2-${GIT_SHA:0:8}"; docker run -d -t --name "${NAME}" "${IMAGE}"
|
||||
```
|
||||
|
||||
## L2.1 — server survives detach
|
||||
|
||||
```bash
|
||||
docker exec "${NAME}" tmux new-session -d -s l2 -x 80 -y 24
|
||||
docker exec "${NAME}" tmux send-keys -t l2 'echo persist-marker-$$ > /tmp/l2.marker' Enter
|
||||
sleep 1
|
||||
# A detached session is the default with -d; confirm the server + session still list after a beat.
|
||||
docker exec "${NAME}" tmux ls | tee "${EVID}/L2-sessions.txt"
|
||||
docker exec "${NAME}" cat /tmp/l2.marker | tee "${EVID}/L2-marker.txt"
|
||||
```
|
||||
|
||||
**PASS:** `tmux ls` shows `l2` still alive; the marker file exists. **FAIL:** "no server running" / no `l2`.
|
||||
|
||||
## L2.2 — multiple panes
|
||||
|
||||
```bash
|
||||
docker exec "${NAME}" tmux split-window -t l2 -h
|
||||
docker exec "${NAME}" tmux list-panes -t l2 -F '#{pane_index}' | tee "${EVID}/L2-panes.txt"
|
||||
```
|
||||
|
||||
**PASS:** at least two pane indices (`0`,`1`). **FAIL:** one pane / error.
|
||||
|
||||
## L2.3 — send-keys + capture round-trip (exact bytes)
|
||||
|
||||
```bash
|
||||
TOKEN="roundtrip-$(date +%s 2>/dev/null || echo fixed)-marker"
|
||||
docker exec "${NAME}" tmux send-keys -t l2.0 "printf '%s\n' '${TOKEN}'" Enter
|
||||
sleep 1
|
||||
docker exec "${NAME}" tmux capture-pane -p -t l2.0 | tee "${EVID}/L2-roundtrip.txt"
|
||||
```
|
||||
|
||||
**PASS:** the capture contains `${TOKEN}` verbatim (the exact bytes round-tripped through the server).
|
||||
**FAIL:** token absent / garbled.
|
||||
|
||||
## Teardown + evidence
|
||||
|
||||
```bash
|
||||
docker rm -f "${NAME}" >/dev/null
|
||||
{ grep -q 'l2' "${EVID}/L2-sessions.txt" && [ "$(wc -l < "${EVID}/L2-panes.txt")" -ge 2 ] && grep -q "${TOKEN}" "${EVID}/L2-roundtrip.txt" \
|
||||
&& echo "VERDICT: PASS — server survives detach, multi-pane, exact round-trip" \
|
||||
|| echo "VERDICT: FAIL — see L2-*.txt"; } | tee "${EVID}/L2-verdict.txt"
|
||||
```
|
||||
@@ -1,146 +0,0 @@
|
||||
# L3 — daemon-in-container (boots vs container-local sqlite; healthz on the PUBLISHED port; `rig up` settles a zero-token stub topology)
|
||||
|
||||
**Runs host-side, after L2.** This is the leg that exercises the stub payload — and where
|
||||
`docker/testbed/stub-assets.list` is finalized (L0.2): the exact stub `rig.yaml` + agent fixture +
|
||||
`culture.md` this `rig up` settles ARE the census scope. Zero tokens by construction (runtime: stub).
|
||||
|
||||
## THE PUBLISHED-DAEMON PROCEDURE (identical on both A/B arms)
|
||||
|
||||
The prior form of this runbook started a LOOPBACK-BOUND daemon and probed it through a published
|
||||
port — unreachable by construction, so the probe failed on BOTH runtimes (operator A/B receipt
|
||||
`Q2-AB-d121568ad-20260807-host/AB-RESULT.md`, sha256 3433e95f427828ce: Docker curl 52 / Apple curl
|
||||
56). A control arm that cannot pass cannot judge the variable arm. The four coupled mechanics
|
||||
below are the fix; all four are grounded at source and all four apply to BOTH arms verbatim.
|
||||
|
||||
**(a) BIND ADDRESS — explicit, never the default.** `packages/daemon/src/index.ts:148` reads
|
||||
`OPENRIG_HOST` (alias `RIGGED_HOST`); when set, `:163` binds exactly that host; when UNSET, `:167`
|
||||
defaults to `127.0.0.1` (+ tailscale when detected). A container reached through published ports
|
||||
MUST set `OPENRIG_HOST=0.0.0.0`.
|
||||
|
||||
**(b) BEARER — required for the daemon to START on this bind, and separately PROVEN.**
|
||||
`assertBindAuthInvariant` (`packages/daemon/src/middleware/auth-bearer-token.ts:240-264`)
|
||||
short-circuits for loopback and tailscale binds; for any other bind it REFUSES TO START unless
|
||||
`OPENRIG_AUTH_BEARER_TOKEN` is non-empty. That refusal is the product being honest — the procedure
|
||||
satisfies it, never routes around it.
|
||||
**VERIFIED-AT-SOURCE CORRECTION (do not "fix" the probe to match a wrong expectation):**
|
||||
`/healthz` is registered directly on the app (`packages/daemon/src/server.ts:574`) and is
|
||||
**UNAUTHENTICATED** — there is no global auth middleware (`app.use("*")` at `:441` only injects
|
||||
deps), and `authBearerTokenMiddleware` is mounted inside exactly six route modules
|
||||
(compaction, hosts, mission-control, rig-policy, sessions, transport). So the health probe does
|
||||
NOT need an Authorization header and MUST NOT be scored on one. The bearer is therefore proven
|
||||
separately, on a genuinely guarded surface: `/api/transport/*` guards its whole router
|
||||
(`packages/daemon/src/routes/transport.ts:9`). Two probes, two distinct facts: the bind, and the
|
||||
auth path.
|
||||
|
||||
**(c) PORT ALLOCATION — an EXPLICIT host port, never `0`.** Apple `container` 1.2.0 rejects the
|
||||
ephemeral publish form (`Error: invalid publish host port range: 0`) where Docker accepts it —
|
||||
a captured runtime-parity difference (operator receipt above). The procedure pins one explicit
|
||||
port so both arms publish identically; ephemeral allocation is not a difference the A/B is
|
||||
measuring.
|
||||
|
||||
**(d) PROBE — byte-identical on both arms.** Probe 1 (`/healthz`, no auth) proves the published
|
||||
path reaches the daemon. Probe 2 (a guarded route WITH the bearer) proves the auth path. Both are
|
||||
recorded; a runbook that records only probe 1 has not tested the bearer at all.
|
||||
|
||||
## Setup (both arms — only the runtime binary differs)
|
||||
|
||||
```bash
|
||||
GIT_SHA="$(git rev-parse HEAD)"; IMAGE="openrig-testbed:${GIT_SHA}"; EVID="dist/testbed-image/evidence/${GIT_SHA}"; mkdir -p "${EVID}"
|
||||
NAME="orig-l3-${GIT_SHA:0:8}"
|
||||
HOSTPORT=19433 # (c) EXPLICIT — never 0 (Apple 1.2.0 rejects ephemeral)
|
||||
TESTBEARER="l3-testbed-$(date +%s)" # (b) throwaway, container-scoped, never a real credential
|
||||
RUNTIME=docker # the Apple arm substitutes its CLI here; ALL ELSE IDENTICAL
|
||||
"${RUNTIME}" run -d -t --name "${NAME}" \
|
||||
-p "${HOSTPORT}:7433" \
|
||||
-e OPENRIG_HOST=0.0.0.0 \
|
||||
-e OPENRIG_AUTH_BEARER_TOKEN="${TESTBEARER}" \
|
||||
-e OPENRIG_SELF_HOST_ID=testbed-l3 \
|
||||
"${IMAGE}"
|
||||
```
|
||||
|
||||
*Apple-arm note (captured, not a workaround): the loopback-qualified publish form
|
||||
(`127.0.0.1:PORT:7433`) resets on Apple 1.2.0 while the unqualified `PORT:7433` works. The
|
||||
unqualified form is therefore the procedure's single published form on BOTH arms — identical
|
||||
input, not an Apple-only concession.*
|
||||
|
||||
## L3.1 — daemon boots vs a container-local sqlite + BOTH probes answer
|
||||
|
||||
```bash
|
||||
"${RUNTIME}" exec "${NAME}" bash -lc 'rig daemon start && sleep 2 && rig status || true' | tee "${EVID}/L3-start.txt"
|
||||
# PROBE 1 — the BIND, unauthenticated by design:
|
||||
curl -fsS "http://127.0.0.1:${HOSTPORT}/healthz" | tee "${EVID}/L3-healthz.txt"; echo
|
||||
# PROBE 2 — the AUTH path, on a genuinely guarded router:
|
||||
curl -sS -o "${EVID}/L3-auth-probe.txt" -w '%{http_code}\n' \
|
||||
-X POST "http://127.0.0.1:${HOSTPORT}/api/transport/send" \
|
||||
-H "Authorization: Bearer ${TESTBEARER}" -H 'Content-Type: application/json' \
|
||||
-d '{"session":"nonexistent@testbed","text":"auth-path probe"}' | tee "${EVID}/L3-auth-code.txt"
|
||||
# NEGATIVE CONTROL — the same call with NO bearer must be refused:
|
||||
curl -sS -o /dev/null -w '%{http_code}\n' \
|
||||
-X POST "http://127.0.0.1:${HOSTPORT}/api/transport/send" \
|
||||
-H 'Content-Type: application/json' -d '{"session":"nonexistent@testbed","text":"x"}' \
|
||||
| tee "${EVID}/L3-auth-negative.txt"
|
||||
"${RUNTIME}" exec "${NAME}" bash -lc 'ls -l "${OPENRIG_HOME:-$HOME/.openrig}"/*.sqlite* 2>/dev/null || find "$HOME" -name "*.sqlite*" 2>/dev/null' | tee "${EVID}/L3-db.txt"
|
||||
```
|
||||
|
||||
**PASS:** probe 1 returns healthy JSON on the PUBLISHED port; probe 2 is NOT 401 (the bearer is
|
||||
accepted — any application-level status such as an unknown-session 4xx still proves the auth path);
|
||||
the negative control IS 401; a container-local sqlite exists.
|
||||
**FAIL:** no healthz on the published port (bind wrong) / probe 2 401 (bearer path wrong) /
|
||||
negative control NOT 401 (the guard is not guarding) / DB outside the container / a mounted real
|
||||
HOME (fence breach).
|
||||
|
||||
## L3.2 — `rig up` settles a zero-token stub topology
|
||||
|
||||
Ship a minimal `runtime: stub` `rig.yaml` (+ agent fixture + culture.md) as the staged stub assets;
|
||||
copy it into a container-local workspace and `rig up` it BY EXPLICIT SOURCE.
|
||||
|
||||
**STAGED PAYLOAD PATH — nested, and deliberately so.** The build verb stages each census entry
|
||||
preserving its full REPO-RELATIVE path (`scripts/build-testbed-image.sh:51-52`:
|
||||
`cp "${REPO_ROOT}/${rel}" "${CONTEXT}/stub-assets/${rel}"`), and the Dockerfile copies that context
|
||||
dir wholesale (`docker/testbed/Dockerfile:52`). So in-container the trio lands at
|
||||
`/opt/openrig-testbed/stub-assets/docker/testbed/stub-assets/`, NOT at the stub-assets root. That
|
||||
nesting is load-bearing, not an accident: the same relative paths are what the manifest hashes into
|
||||
the byte-reproducible census receipt (`build-testbed-image.sh:101`), so flattening the staging would
|
||||
change the receipt bytes r1 verified. The RUNBOOK adapts to the staged reality; the staging stands.
|
||||
(This exact failure was PREDICTED and scoped to this runbook —
|
||||
`51-04-STUB-ASSET-TRIO-REVIEW-VERDICT-review-r1.md` sha-16 5d4a8bb1d0a1605b, "Honest forward-flag";
|
||||
the note simply never reached the text until now.)
|
||||
|
||||
**EXPLICIT SOURCE — never bare `rig up`.** `rig up` takes a REQUIRED positional
|
||||
(`packages/cli/src/commands/up.ts:77`: `.argument("<source>", "Path to a .yaml rig spec or
|
||||
.rigbundle, or a library name…")`); a bare invocation exits `missing required argument 'source'`,
|
||||
which is what the operator hit.
|
||||
|
||||
```bash
|
||||
"${RUNTIME}" exec "${NAME}" bash -lc '
|
||||
set -e
|
||||
STAGED=/opt/openrig-testbed/stub-assets/docker/testbed/stub-assets
|
||||
# Pre-flight fence: assert the payload where the build actually stages it. A staging change must
|
||||
# fail LOUD here naming the path, never as a downstream "missing required argument".
|
||||
[ -f "${STAGED}/rig.yaml" ] || { echo "L3.2 FAIL: no rig.yaml at ${STAGED} — staged payload moved; reconcile the runbook against scripts/build-testbed-image.sh"; ls -R /opt/openrig-testbed/stub-assets | head -40; exit 1; }
|
||||
mkdir -p ~/work && cp -r "${STAGED}/." ~/work/
|
||||
cd ~/work && rig up rig.yaml && sleep 3 && rig ps --json' | tee "${EVID}/L3-topology.txt"
|
||||
```
|
||||
|
||||
**PASS:** the stub seat(s) reach a settled/ready state (zero LLM tokens consumed — `runtime: stub`).
|
||||
**FAIL:** topology never settles / a non-stub runtime is invoked.
|
||||
|
||||
## Teardown + evidence
|
||||
|
||||
```bash
|
||||
"${RUNTIME}" exec "${NAME}" bash -lc 'rig down || true' ; "${RUNTIME}" rm -f "${NAME}" >/dev/null
|
||||
{ grep -qi 'health' "${EVID}/L3-healthz.txt" \
|
||||
&& [ "$(cat "${EVID}/L3-auth-code.txt")" != "401" ] \
|
||||
&& [ "$(cat "${EVID}/L3-auth-negative.txt")" = "401" ] \
|
||||
&& echo "VERDICT: PASS — published bind reachable, bearer path proven, negative control refused, stub topology settles" \
|
||||
|| echo "VERDICT: FAIL — see L3-*.txt"; } | tee "${EVID}/L3-verdict.txt"
|
||||
```
|
||||
|
||||
## ACCEPTANCE GATE (non-negotiable, before any A/B rerun is requested)
|
||||
|
||||
Run this procedure on the **DOCKER** arm alone and prove it GREEN. A control that cannot pass is
|
||||
not a control; the A/B stays blocked until the Docker baseline is green under this exact text.
|
||||
Only then does the Apple arm run the identical procedure with its CLI substituted.
|
||||
|
||||
**Note:** the exact `rig ps` shape / ready predicate is grounded against the shipped stub adapter at
|
||||
execution time — do not assert a remembered field name; read the real `--json` output.
|
||||
@@ -1,51 +0,0 @@
|
||||
# L4 — the 51-02 hermetic contract holds INSIDE the container (fail-closed not weakened)
|
||||
|
||||
**Runs host-side, after L3.** The hermeticity floor is "fresh container = fresh HOME" **by
|
||||
construction** — no real-HOME/workspace mounts (verified in L1–L3 by the no-`-v` fence). This leg
|
||||
proves the *active* half: the 51-02 env-helper still **REFUSES an injected foreign `OPENRIG_URL`**
|
||||
inside the container. The container is not an excuse to weaken the fail-closed guard — a leaked daemon
|
||||
target must hard-refuse exactly as it does host-side (the `DAEMON_TARGET_ENV_VARS` guard class).
|
||||
|
||||
## Claim
|
||||
|
||||
With a foreign `OPENRIG_URL` (a daemon target the helper did not set itself) present in the
|
||||
environment, the 51-02 hermetic env prep **hard-refuses** (non-zero + a refusal naming the foreign
|
||||
target) rather than silently adopting it — inside the container, same as host-side.
|
||||
|
||||
## Grounding note (confirm at execution — do NOT assert from memory)
|
||||
|
||||
Where the helper runs depends on whether the 51-02 hermetic-env module is **packaged** in the openrig
|
||||
tarball the image installs (it currently lives at `packages/daemon/test/helpers/hermetic-env.ts` — a
|
||||
test helper, which may not be in the pack set):
|
||||
- **If packaged / resolvable in-container:** invoke the assertion directly in the container (L4.1).
|
||||
- **If not packaged:** this leg is exercised via the **runner's container-execution mode (step-3)** —
|
||||
see **L6.3** (`L6-container-runner-e2e.md`), which drives a run with a foreign target injected into the
|
||||
base env and the host-side hermetic prep refusing before any container is created — record that as the
|
||||
L4 form. Either way, the leg is real; pick the form the shipped surface supports and say which.
|
||||
|
||||
## L4.1 — in-container assertion (when the helper is resolvable)
|
||||
|
||||
```bash
|
||||
GIT_SHA="$(git rev-parse HEAD)"; IMAGE="openrig-testbed:${GIT_SHA}"; EVID="dist/testbed-image/evidence/${GIT_SHA}"; mkdir -p "${EVID}"
|
||||
NAME="orig-l4-${GIT_SHA:0:8}"; docker run -d -t --name "${NAME}" "${IMAGE}"
|
||||
|
||||
# Inject a foreign daemon target and drive the hermetic prep; expect a LOUD non-zero refusal.
|
||||
docker exec -e OPENRIG_URL='http://foreign-daemon.invalid:9999' "${NAME}" bash -lc '
|
||||
node --input-type=module -e "
|
||||
import { prepareHermeticEnv } from \"@openrig/daemon/test/helpers/hermetic-env.js\";
|
||||
try { prepareHermeticEnv({ baseEnv: process.env }); console.log(\"NO-REFUSAL\"); process.exit(0); }
|
||||
catch (e) { console.error(\"REFUSED: \" + e.message); process.exit(7); }
|
||||
"' 2>&1 | tee "${EVID}/L4-refusal.txt"; RC=${PIPESTATUS[0]:-$?}
|
||||
docker rm -f "${NAME}" >/dev/null
|
||||
```
|
||||
|
||||
**PASS:** non-zero exit + `REFUSED:` naming the foreign `OPENRIG_URL`. **FAIL:** `NO-REFUSAL` /
|
||||
exit 0 (the guard was weakened in-container). Adjust the import specifier to the helper's real shipped
|
||||
path; if it does not resolve, switch to the step-3 form (grounding note) — do not green-pass by memory.
|
||||
|
||||
## Evidence
|
||||
|
||||
```bash
|
||||
{ grep -q 'REFUSED:' "${EVID}/L4-refusal.txt" && echo "VERDICT: PASS — foreign OPENRIG_URL hard-refused inside the container" \
|
||||
|| echo "VERDICT: FAIL / FORM-DEFERRED — see L4-refusal.txt + the grounding note"; } | tee "${EVID}/L4-verdict.txt"
|
||||
```
|
||||
@@ -1,104 +0,0 @@
|
||||
# L5 — multi-host topology (N named self-hosts on one network) + the 51-09 live-leg rider
|
||||
|
||||
**Runs host-side, after L4.** Proves plan §3: N containers each = one simulated **named host**,
|
||||
composed via the shipped **host registry over HTTP** (registry rows point at container-DNS names), one
|
||||
daemon per container, container-local DB/HOME, no real-HOME mounts. The **only** shared surface is the
|
||||
docker network.
|
||||
|
||||
**51-09 live-leg rider (orch, merge desk):** this same two-host setup is the executor for the shipped
|
||||
51-09 collision/alignment runbook. After the topology settles, run BOTH 51-09 legs **in this same
|
||||
host-side session** and return both evidence sets. Fixture + steps:
|
||||
`packages/daemon/test/fixtures/self-host-live-legs/RUNBOOK.md` — **LEG A** (cross-host stamped-triple
|
||||
round-trip: a cross-host send stores the ORIGIN host in the sender identity and the `↩ Reply:` hint
|
||||
round-trips verbatim to the origin) and **LEG B** (founder-collision: a same-named rig on both hosts;
|
||||
the received signature names the origin and the reply lands on the origin, not the local lookalike).
|
||||
|
||||
## L5.1 — boot two named self-hosts on one network
|
||||
|
||||
**IDENTITY IS READ, NEVER PREDICTED (PM ruling — capture-not-compose applied to identity).** The
|
||||
self-host id is minted daemon-side and stored as a never-rewritten singleton; the runbook CAPTURES
|
||||
each container's id from its own surface (`/healthz`, whose `selfHostId` field is emitted at
|
||||
`packages/daemon/src/server.ts:589`) and then uses that CAPTURED value verbatim. It never predicts,
|
||||
hardcodes, or derives an id. (`OPENRIG_SELF_HOST_ID` was NOT the knob: `docker/testbed/entrypoint.sh:8`
|
||||
only ECHOES it for `docker logs`; nothing in the daemon reads it. Do not reintroduce it.)
|
||||
|
||||
**BIND + BEARER, carried from L3 verbatim.** L5 needs cross-container HTTP, so each daemon must be
|
||||
reachable off-loopback — the same three coupled parts L3 proved, for the same reasons, with the same
|
||||
never-weaken-the-guard rail: explicit `OPENRIG_HOST=0.0.0.0`, `OPENRIG_AUTH_BEARER_TOKEN` set (the
|
||||
guard at `packages/daemon/src/middleware/auth-bearer-token.ts:240-264` REFUSES a non-loopback bind
|
||||
without it), and an explicit published port when a host-side probe is used. Registry rows carry a
|
||||
bearer POINTER (`--bearer-env` NAME), never a token value.
|
||||
|
||||
```bash
|
||||
GIT_SHA="$(git rev-parse HEAD)"; IMAGE="openrig-testbed:${GIT_SHA}"; EVID="dist/testbed-image/evidence/${GIT_SHA}"; mkdir -p "${EVID}"
|
||||
NET="orig-net-${GIT_SHA:0:8}"; docker network create "${NET}" >/dev/null
|
||||
TESTBEARER="l5-testbed-$(date +%s)" # throwaway, container-scoped, never a real credential
|
||||
|
||||
for h in H_A H_B; do
|
||||
docker run -d -t --name "$h" --hostname "$h" --network "${NET}" \
|
||||
-e OPENRIG_HOST=0.0.0.0 \
|
||||
-e OPENRIG_AUTH_BEARER_TOKEN="${TESTBEARER}" \
|
||||
-e OPENRIG_TESTBED_BEARER_ENV=OPENRIG_AUTH_BEARER_TOKEN \
|
||||
"${IMAGE}"
|
||||
done
|
||||
for h in H_A H_B; do docker exec "$h" bash -lc 'rig daemon start && sleep 2 && rig status || true'; done | tee "${EVID}/L5-start.txt"
|
||||
|
||||
# CAPTURE each minted id from its own daemon (adopt-by-read; ids are random per boot).
|
||||
ID_A="$(docker exec H_A bash -lc 'curl -fsS http://127.0.0.1:7433/healthz' | python3 -c "import json,sys; print(json.load(sys.stdin).get('selfHostId',''))")"
|
||||
ID_B="$(docker exec H_B bash -lc 'curl -fsS http://127.0.0.1:7433/healthz' | python3 -c "import json,sys; print(json.load(sys.stdin).get('selfHostId',''))")"
|
||||
printf 'H_A selfHostId=%s\nH_B selfHostId=%s\n' "${ID_A}" "${ID_B}" | tee "${EVID}/L5-selfids.txt"
|
||||
[ -n "${ID_A}" ] && [ -n "${ID_B}" ] && [ "${ID_A}" != "${ID_B}" ] || { echo "L5.1 FAIL: missing or identical self-host ids"; exit 1; }
|
||||
```
|
||||
|
||||
**PASS:** both containers report a NON-EMPTY, DISTINCT `selfHostId` on their own `/healthz`, and each
|
||||
id is stable across a daemon restart in that container (51-09 incr 1 — the singleton is never
|
||||
re-keyed). **FAIL:** an empty id / identical ids / an id that changes on restart.
|
||||
|
||||
*Readback note (captured product observation, NOT worked around here): `rig whoami` reports a SEAT
|
||||
identity and a bare host container has no seat, so it cannot answer "which host am I". The
|
||||
daemon-surface read above is the shipped substitute. The declared-identity + host-readback gap is
|
||||
pooled at PM's desk (identity family); this runbook consumes what ships.*
|
||||
|
||||
## L5.2 — compose via the host registry over HTTP
|
||||
|
||||
Register `H_B` in `H_A`'s host registry pointing at the container-DNS name `H_B` (reachable on `${NET}`):
|
||||
|
||||
```bash
|
||||
# CURRENT grammar (packages/cli/src/commands/host.ts:427-433): --id and --transport are REQUIRED;
|
||||
# http transport takes --url; the bearer rides as a POINTER (env var NAME), never a value.
|
||||
# The id is the CAPTURED ${ID_B} — adopt-by-read, never an authored name.
|
||||
docker exec H_A bash -lc "rig host add --id '${ID_B}' --transport http --url http://H_B:7433 --bearer-env OPENRIG_AUTH_BEARER_TOKEN && rig host ls --json" | tee "${EVID}/L5-registry.txt"
|
||||
```
|
||||
|
||||
**PASS:** `H_A`'s registry lists the CAPTURED id `${ID_B}` at the container-DNS URL; a probe reaches `H_B`'s daemon over
|
||||
the network only. **FAIL:** unreachable / resolves off-network. (Ground the exact `rig host` flag shape
|
||||
against the shipped CLI at execution — read `--json`, don't assert a remembered field.)
|
||||
|
||||
## L5.3 — execute the 51-09 live legs (the rider) in this session
|
||||
|
||||
Using `H_A`/`H_B` as the two hosts, follow the shipped runbook end-to-end and bank its evidence here:
|
||||
|
||||
```bash
|
||||
# Source of truth for the exact seats/fixtures/steps + PASS predicates:
|
||||
sed -n '1,200p' packages/daemon/test/fixtures/self-host-live-legs/RUNBOOK.md
|
||||
# LEG A: cross-host send orch@rig-a -> dev@rig-b --host B; expect From: orch@rig-a@A + verbatim reply lands on H_A.
|
||||
# LEG B: same-named rig 'shared' on both; expect From: lead@shared@A + reply lands on H_A's lead@shared.
|
||||
# Capture each received pane + the stored source_session; write to L5-leg-a.txt / L5-leg-b.txt.
|
||||
```
|
||||
|
||||
**PASS:** LEG A signature names `A` + stored `source_session == orch@rig-a@A` + verbatim reply lands on
|
||||
`H_A`; LEG B signature names the origin `A` + reply lands on `H_A`'s lookalike, not `H_B`'s. Include the
|
||||
51-09 fail-open control (stop `H_A`'s daemon → `From:` degrades to 2-part, no crash).
|
||||
|
||||
## Teardown + evidence
|
||||
|
||||
```bash
|
||||
docker rm -f H_A H_B >/dev/null; docker network rm "${NET}" >/dev/null
|
||||
{ echo "topology: 2 named hosts A/B on ${NET}, registry-composed"; echo "51-09 rider: LEG A + LEG B executed against the testbed containers"; \
|
||||
echo "VERDICT: PASS|FAIL — per L5-selfids/registry/leg-a/leg-b captures (verdict on bytes, not memory)"; } | tee "${EVID}/L5-verdict.txt"
|
||||
```
|
||||
|
||||
**Fences:** no real-HOME mounts; the docker network is the only shared surface; scenarios byte-unchanged.
|
||||
**Docker-gap watch (plan §3):** if per-container network identity proves insufficient for a topology the
|
||||
design needs, THAT is the named concrete gap the ruling requires before any Apple-stack revisit — route
|
||||
to PM with the evidence, never install.
|
||||
@@ -1,142 +0,0 @@
|
||||
# L6 — the 51-02 runner drives a REAL scenario through the container (container-mode e2e) + host-mode parity
|
||||
|
||||
**Runs host-side, after L3** (needs the built image + a container-local daemon that boots). This is the
|
||||
live proof of the 51-04 step-3 mechanism: the runner's **container-mode opt-in** stands the
|
||||
scenario-local daemon up INSIDE the testbed image (by manifest identity), drives the SAME shipped
|
||||
scenario through the SAME host-side reads pointed at the container's **published port**, and stamps the
|
||||
image manifest id onto every results-ledger row. It also carries the **L4 hermetic fail-closed leg's
|
||||
step-3 form** (the grounding note in `L4-hermetic-fail-closed.md` points here) and the **host-mode
|
||||
byte-intact parity** check that closes the additive-opt-in fence behaviorally.
|
||||
|
||||
The step-3 pieces this exercises are unit-proven in the VM (`test/scenario-container.test.ts`,
|
||||
`test/scenario-daemon-mode.test.ts`) with an INJECTED docker runner; L6 is where the REAL `docker`
|
||||
invoker + a live container replace the injection — the leg no source-only proof can give.
|
||||
|
||||
## Topology of a container-mode run (what talks to what)
|
||||
|
||||
- The **daemon** runs inside the container (`rig daemon start` on the container port, container-local
|
||||
HOME/DB, no mounts).
|
||||
- The host-side **`rig` reads/writes** (the shipped CLI subprocesses the runner already uses) run on the
|
||||
HOST against `OPENRIG_URL = http://127.0.0.1:<published port>` — the adapter self-sets that URL to its
|
||||
OWN container (never a foreign target). So the host still needs the built CLI bin for the READ side.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
```bash
|
||||
# L0 resolved the base + stub-assets slots; the build verb produced the image + manifest.
|
||||
scripts/build-testbed-image.sh # -> dist/testbed-image/manifest.json
|
||||
GIT_SHA="$(git rev-parse HEAD)"; IMAGE="openrig-testbed:${GIT_SHA}"
|
||||
EVID="dist/testbed-image/evidence/${GIT_SHA}"; mkdir -p "${EVID}"
|
||||
# Built HOST rig bin for the read side (the same bin run-scenarios.mjs uses).
|
||||
npm run build -w packages/cli && npm run build -w packages/daemon
|
||||
test -x packages/cli/dist/bin-wrapper.js || { echo "BLOCKER: build the CLI bin first"; exit 1; }
|
||||
command -v docker >/dev/null || { echo "BLOCKER: docker not on PATH"; exit 1; }
|
||||
```
|
||||
|
||||
## L6.1 — drive a real scenario through container-mode (the runner as a host-side wrapper)
|
||||
|
||||
The operator runs the runner in container-mode by supplying the step-3 `daemon` spawner + `imageId`.
|
||||
This wiring composes only already-tested helpers (`spawnContainerDaemon`, `runScenarioFile`,
|
||||
`withImageId`, `makeRealStagingDocker`). The REAL `docker` invoker is a COMMITTED helper, imported —
|
||||
never re-inlined here. (The prior inline `execFile` invoker predated the `stdinFrom` tar-pipe
|
||||
contract and ignored it, leaving the in-container `tar -xf -` an open never-fed stdin: the 08-12
|
||||
seven-minute extraction hang, row 42576855. The committed helper feeds the pipe, checks BOTH exits,
|
||||
and bounds every step with a timeout so a stall is a NAMED failure — proven hermetically in
|
||||
`test/staging-docker-invoker.test.ts`. That proof covers the invoker only; live containment on a
|
||||
real engine still rides THIS leg.) Run it host-side with the tsx loader:
|
||||
|
||||
```bash
|
||||
node --import tsx - "$IMAGE" "$(jq -r .manifestDigest dist/testbed-image/manifest.json)" <<'RUN' | tee "${EVID}/L6-container.txt"
|
||||
import { resolve } from "node:path";
|
||||
import { runScenarioFile } from "./packages/daemon/test/helpers/scenario-pipeline.ts";
|
||||
import { spawnContainerDaemon } from "./packages/daemon/test/helpers/scenario-container.ts";
|
||||
import { makeRealStagingDocker } from "./packages/daemon/test/helpers/staging-docker-invoker.ts";
|
||||
|
||||
const [image, imageId] = process.argv.slice(2);
|
||||
const RIG_BIN = resolve("packages/cli/dist/bin-wrapper.js");
|
||||
const SCENARIO = resolve("packages/daemon/test/fixtures/scenarios"); // pick one committed scenario file below
|
||||
|
||||
// The committed real invoker: two-process tar pipe, dual-exit check, per-step timeout.
|
||||
const docker = makeRealStagingDocker();
|
||||
|
||||
// Container-mode: inject the ScenarioDaemon-shaped container adapter + the manifest id.
|
||||
const daemon = (scaffold /*, opts */) => spawnContainerDaemon(scaffold, { image, docker });
|
||||
// COMMITTED scenario (the prior literal `scenario-collision.yaml` DOES NOT EXIST in the tree —
|
||||
// operator-caught at the L4/L6 re-entry). L6 proves the container RUNNER, so it drives a real
|
||||
// shipped scenario; override with L6_SCENARIO to run another COMMITTED file, never an improvised one.
|
||||
const scenario = `${SCENARIO}/` + (process.env.L6_SCENARIO ?? "scenario-02-baton.yaml");
|
||||
const baseEnv = { HOME: process.env.HOME, PATH: process.env.PATH, TERM: "xterm" };
|
||||
|
||||
const records = [];
|
||||
const result = await runScenarioFile(scenario, {
|
||||
rigBin: RIG_BIN, baseEnv, daemon, imageId,
|
||||
deps: { appendRecord: (r) => records.push(r), normalizer: (_s, v) => v },
|
||||
});
|
||||
console.log("VERDICT:", result.verdict, "scenario:", result.scenario);
|
||||
console.log("LEDGER:", JSON.stringify(records));
|
||||
process.exit(result.verdict === "PASS" ? 0 : 1);
|
||||
RUN
|
||||
```
|
||||
|
||||
**PASS:** the scenario reaches its expected verdict driven against the in-container daemon, AND every
|
||||
ledger row carries `imageId == manifest.manifestDigest` (grep the `LEDGER:` line). **FAIL:** the daemon
|
||||
never comes up in the container / a read cannot reach the published port / a ledger row is missing the
|
||||
image id. (Ground the exact expected verdict against the chosen scenario — a 51-03-dependent
|
||||
cross-surface scenario is not expected green until its normalizer ships; pick a settled scenario.)
|
||||
|
||||
## L6.2 — host-mode parity (the additive-opt-in fence, behaviorally)
|
||||
|
||||
Run the IDENTICAL scenario in **host-mode** (no `daemon` override, no `imageId`) and compare verdicts:
|
||||
|
||||
```bash
|
||||
L6_MODE=host node --import tsx packages/daemon/scripts/run-scenarios.mjs \
|
||||
packages/daemon/test/fixtures/scenarios/scenario-02-baton.yaml | tee "${EVID}/L6-host.txt"
|
||||
```
|
||||
|
||||
**PASS:** the host-mode verdict for the same scenario matches the container-mode verdict from L6.1 —
|
||||
container-mode changed nothing about the host-mode path (the 51-02 contract is byte-intact; the ledger
|
||||
rows differ ONLY by the added `imageId` key in container-mode). **FAIL:** host-mode verdict diverges
|
||||
from pre-51-04 for the same scenario (a fence breach — that would demand a PM 51-02 gate).
|
||||
|
||||
## L6.3 — container-mode fail-closed (the L4 step-3 form)
|
||||
|
||||
Inject a FOREIGN daemon target into the base env and confirm the run HARD-REFUSES before standing any
|
||||
container up (the container is not an excuse to weaken the `DAEMON_TARGET` guard — same as host-mode):
|
||||
|
||||
```bash
|
||||
OPENRIG_URL='http://foreign-daemon.invalid:9999' node --import tsx - "$IMAGE" <<'RUN' 2>&1 | tee "${EVID}/L6-failclosed.txt"; RC=${PIPESTATUS[0]:-$?}
|
||||
import { resolve } from "node:path";
|
||||
import { runScenarioFile } from "./packages/daemon/test/helpers/scenario-pipeline.ts";
|
||||
import { spawnContainerDaemon } from "./packages/daemon/test/helpers/scenario-container.ts";
|
||||
const [image] = process.argv.slice(2);
|
||||
const daemon = (scaffold) => spawnContainerDaemon(scaffold, { image, docker: async () => ({ stdout: "", stderr: "", code: 0 }) });
|
||||
try {
|
||||
await runScenarioFile(resolve("packages/daemon/test/fixtures/scenarios/scenario-02-baton.yaml"),
|
||||
{ rigBin: resolve("packages/cli/dist/bin-wrapper.js"), baseEnv: process.env, daemon });
|
||||
console.log("NO-REFUSAL"); process.exit(0);
|
||||
} catch (e) { console.error("REFUSED: " + e.message); process.exit(7); }
|
||||
RUN
|
||||
```
|
||||
|
||||
**PASS:** non-zero exit + `REFUSED:` naming the foreign `OPENRIG_URL` — `prepareHermeticEnv` fail-closes
|
||||
on the foreign target in `baseEnv` and NO container is created. **FAIL:** `NO-REFUSAL` / exit 0 (the
|
||||
guard was bypassed in container-mode). This is the step-3 form of the L4 leg (the packaged-helper form
|
||||
lives in `L4-hermetic-fail-closed.md`); either form is real — record which one the shipped surface ran.
|
||||
|
||||
## Teardown + evidence
|
||||
|
||||
Container-mode tears its own container down (the adapter's `stop` = `docker rm -f`), so a clean run
|
||||
leaves nothing. Sweep any strays from a failed run, then verdict on the captured bytes:
|
||||
|
||||
```bash
|
||||
docker ps -aq --filter "ancestor=${IMAGE}" | xargs -r docker rm -f >/dev/null
|
||||
{ grep -q 'VERDICT: PASS' "${EVID}/L6-container.txt" \
|
||||
&& grep -q "$(jq -r .manifestDigest dist/testbed-image/manifest.json)" "${EVID}/L6-container.txt" \
|
||||
&& grep -q 'REFUSED:' "${EVID}/L6-failclosed.txt" \
|
||||
&& echo "VERDICT: PASS — container-mode drives a real scenario by image identity, ledger carries the manifest id, host-mode parity holds, fail-closed refuses" \
|
||||
|| echo "VERDICT: FAIL / FORM-DEFERRED — see L6-*.txt"; } | tee "${EVID}/L6-verdict.txt"
|
||||
```
|
||||
|
||||
**Fences (binding):** the scenario YAML is byte-unchanged (51-03 fence); host-mode stays byte-intact
|
||||
(L6.2 is the behavioral proof — any divergence is a PM 51-02 gate, not a fold); no real-HOME mounts;
|
||||
the image is selected BY MANIFEST IDENTITY and its digest is the ledger's cross-version key.
|
||||
@@ -1,61 +0,0 @@
|
||||
# openrig-testbed verification runbooks (51-04 step-2, plan §2)
|
||||
|
||||
These are **host-executed, evidence-defined** runbooks — the 51-09 live-legs pattern. The VM seat has
|
||||
no container runtime (locus ruling (a) host-side), so the daemon/operator lane runs them **host-side**
|
||||
against the image `scripts/build-testbed-image.sh` produces, and returns evidence per the
|
||||
census-receipt discipline. Each leg is a scripted check that never asserts from memory (the clause
|
||||
that caught the Apple-container premise): run it, capture the real bytes, verdict against them.
|
||||
|
||||
## Legs
|
||||
|
||||
| Leg | Proves | Runbook |
|
||||
|---|---|---|
|
||||
| L0 | the digest-pinned base + stub-assets census are resolved (prerequisite to a build) | `L0-resolve-inputs.md` |
|
||||
| L1 | PTY allocation: `docker run -t` + tmux capture-pane returns real bytes; resize propagates | `L1-pty-allocation.md` |
|
||||
| L2 | tmux server lifecycle: detach-survive, multi-pane, send-keys + capture round-trip | `L2-tmux-server-lifecycle.md` |
|
||||
| L3 | daemon-in-container: boots vs container-local sqlite, healthz on the published port, `rig up` settles a zero-token stub topology | `L3-daemon-in-container.md` |
|
||||
| L4 | the 51-02 hermetic contract: the env-helper still REFUSES a foreign `OPENRIG_URL` **inside** the container (fail-closed not weakened by "we're in a container anyway") | `L4-hermetic-fail-closed.md` |
|
||||
| L5 | multi-host: N containers as N distinct named self-hosts on one docker network, composed via the shipped host registry over HTTP (plan §3) — **and** the 51-09 live-leg rider | `L5-multi-host-and-51-09.md` |
|
||||
| L6 | the 51-02 runner's **container-mode** (step-3) drives a REAL scenario through a container by manifest identity + host-mode byte-intact parity + the L4 fail-closed step-3 form; the ledger carries the image manifest id | `L6-container-runner-e2e.md` |
|
||||
|
||||
Sequencing: **L0 → build → L1 → L2 → L3 → L4 → L5**, with **L6 after L3** (it needs only the built image
|
||||
+ an in-container daemon, plus the built HOST CLI bin for the read side). L3 is where the stub payload is
|
||||
exercised (and where `docker/testbed/stub-assets.list` is finalized). L4 depends on the 51-02 hermetic
|
||||
env-helper being present in the packaged image (it ships in the openrig package the Dockerfile installs);
|
||||
if it is NOT packaged, its fail-closed leg is exercised in the **step-3 form** — L6.3.
|
||||
|
||||
**51-09 live-leg rider (orch, merge desk).** The testbed image's first multi-host run doubles as the
|
||||
51-09 live-leg executor: L5 boots the containers as the two named hosts `H_A`/`H_B` and then runs the
|
||||
shipped 51-09 collision/alignment runbook **in the same host-side session** —
|
||||
`packages/daemon/test/fixtures/self-host-live-legs/RUNBOOK.md` (LEG A cross-host stamped-triple
|
||||
round-trip, LEG B founder-collision). Execute both families together; return both evidence sets.
|
||||
|
||||
## Shared conventions
|
||||
|
||||
**Image identity.** All legs run against the image the build verb tagged, by manifest identity:
|
||||
```bash
|
||||
GIT_SHA="$(git rev-parse HEAD)"
|
||||
IMAGE="openrig-testbed:${GIT_SHA}" # == manifest.image
|
||||
```
|
||||
Cross-check the running image against the emitted manifest before trusting a leg's result:
|
||||
```bash
|
||||
test "$(docker image inspect "${IMAGE}" --format '{{.Id}}')" # exists
|
||||
cat dist/testbed-image/manifest.json # the census identity this run is comparable under
|
||||
```
|
||||
|
||||
**Evidence dir (hashed, per the census-receipt discipline).** Each leg writes its captures + a
|
||||
`VERDICT` line into a per-run evidence dir, then the operator hashes the dir so the evidence is
|
||||
tamper-evident and comparable across image versions:
|
||||
```bash
|
||||
EVID="dist/testbed-image/evidence/${GIT_SHA}"
|
||||
mkdir -p "${EVID}"
|
||||
# ... leg writes L1-capture.txt, L1-resize.txt, etc. ...
|
||||
( cd "${EVID}" && find . -type f -print0 | sort -z | xargs -0 sha256sum ) > "${EVID}.sha256"
|
||||
```
|
||||
Record in each leg's evidence: the exact command, the captured bytes, and a single
|
||||
`VERDICT: PASS|FAIL — <one line>` on the observed bytes (never from memory).
|
||||
|
||||
**Fences (binding on every leg).** No real-HOME / real-workspace volume mounts (fresh container =
|
||||
fresh HOME is the hermeticity floor); scenarios byte-unchanged; the only shared surface between
|
||||
multi-host containers is the docker network. A leg that cannot run its check reports a **loud
|
||||
blocker** with the exact command + the missing capability — it never green-passes from memory.
|
||||
@@ -1,14 +0,0 @@
|
||||
# openrig-testbed stub runtime assets (plan §1 layer 4: "the 51-01 stub script + its registry
|
||||
# wiring — zero tokens by construction"). This file is the EXACT census scope the manifest hashes
|
||||
# and the build verb stages into the image (census-scope-match-code-path — this list IS the code
|
||||
# path; never a recursive walk that would over-count).
|
||||
#
|
||||
# One repo-relative path per line; comments (#) and blank lines are ignored.
|
||||
#
|
||||
# RESOLVED (2026-08-06 VM-side) — the concrete zero-token stub payload: a runtime:stub rig.yaml +
|
||||
# its agent fixture + culture.md that boot a settled topology for the L3 daemon-in-container leg.
|
||||
# Shape grounded on the proven 51-02 runner fixture (test/fixtures/scenarios/topo-stub-baton.yaml),
|
||||
# not guessed. The base-image digest slot (docker/testbed/base-image) remains host-resolved (L0.1).
|
||||
docker/testbed/stub-assets/rig.yaml
|
||||
docker/testbed/stub-assets/culture.md
|
||||
docker/testbed/stub-assets/agents/worker/agent.yaml
|
||||
@@ -1,8 +0,0 @@
|
||||
name: worker
|
||||
version: "1.0.0"
|
||||
resources:
|
||||
skills: []
|
||||
profiles:
|
||||
default:
|
||||
uses:
|
||||
skills: []
|
||||
@@ -1,6 +0,0 @@
|
||||
# testbed-stub (51-04 container stub payload)
|
||||
|
||||
A minimal zero-token stub-runtime rig baked into the openrig-testbed image so the L3
|
||||
daemon-in-container leg can `rig up` a settled topology without a live LLM. The single
|
||||
seat runs the deterministic 51-01 stub harness. Not a product rig — it exists only to
|
||||
prove the container boots a real daemon and settles a real topology headlessly.
|
||||
@@ -1,23 +0,0 @@
|
||||
# 51-04 testbed image — the container-local zero-token stub topology (plan §1 layer 4).
|
||||
#
|
||||
# One pod (dev) with one stub seat (worker). The stub runtime is the deterministic 51-01
|
||||
# node-script harness, so this topology stands up headlessly in real tmux INSIDE the
|
||||
# testbed container without a live LLM (the L3 daemon-in-container leg: `rig up` settles
|
||||
# it, zero tokens by construction). Shape mirrors the proven 51-02 runner fixture
|
||||
# (test/fixtures/scenarios/topo-stub-baton.yaml), which the scenario runner settles
|
||||
# headlessly end-to-end — not a product rig.
|
||||
#
|
||||
# Canonical session of the seat = <pod>-<member>@<name> = dev-worker@testbed-stub.
|
||||
version: "0.2"
|
||||
name: testbed-stub
|
||||
culture_file: culture.md
|
||||
pods:
|
||||
- id: dev
|
||||
label: Dev
|
||||
members:
|
||||
- id: worker
|
||||
agent_ref: "local:agents/worker"
|
||||
profile: default
|
||||
runtime: stub
|
||||
cwd: .
|
||||
edges: []
|
||||
@@ -1,101 +0,0 @@
|
||||
---
|
||||
kind: as-built
|
||||
title: As-Built Docs — Map of Territory + Module Index
|
||||
status: active
|
||||
topics: [knowledge-and-context, observability]
|
||||
domains: [engineering-advisor, operating-advisor, product-advisor]
|
||||
applies-when: |
|
||||
Starting any technical task that needs the shipped OpenRig system as it
|
||||
actually is. Read this first to learn what the as-built tree contains and
|
||||
which module to open; then go to codemap.md for use-case navigation or
|
||||
straight to the named module.
|
||||
siblings: [codemap.md, cli-reference.md, frontmatter-schema.md]
|
||||
prerequisite-reads: []
|
||||
last-verified-against-source: 7eaf524c
|
||||
last-updated: 2026-05-16
|
||||
---
|
||||
|
||||
# OpenRig As-Built Docs
|
||||
|
||||
OpenRig is a local control plane for multi-agent coding topologies — a
|
||||
multi-agent harness that manages your Claude Code and Codex sessions as a
|
||||
single system, with a daemon (`@openrig/daemon`), a CLI (`@openrig/cli`), a UI
|
||||
(`@openrig/ui`), and an MCP server all sitting on one SQLite-backed core. This
|
||||
tree is the **source-verified** description of that system as it actually
|
||||
ships — every load-bearing claim is grounded to `packages/*/src` at a named
|
||||
commit, not to memory, chat, or older docs.
|
||||
|
||||
> Verified against source at HEAD `7eaf524c` (`git describe` →
|
||||
> `v0.3.1-6-g7eaf524c`). Package version is **0.3.1** across all three
|
||||
> packages; HEAD carries 6 commits of unreleased 0.3.2 work, no `v0.3.2` tag.
|
||||
|
||||
## How this tree is organized
|
||||
|
||||
The as-built corpus was modularized (slice 08, `context-architecture-v1`) from
|
||||
two monolithic files into a folder of thematic modules, each independently
|
||||
loadable, each frontmatter-tagged for retrieval, each ≤300 lines (author-mode
|
||||
modules with no prior prose may run to ≤400 — see the slice-08 ACK).
|
||||
|
||||
```
|
||||
docs/as-built/
|
||||
├── README.md ← you are here: map-of-territory + index
|
||||
├── codemap.md ← navigation index (use-case lookup, source-root pointers)
|
||||
├── frontmatter-schema.md← the frontmatter convention these docs follow
|
||||
├── cli-reference.md ← full rig CLI surface (kept whole)
|
||||
├── architecture/ ← 14 backend/runtime modules
|
||||
└── ui/ ← 4 operator-surface modules
|
||||
```
|
||||
|
||||
`docs/DESIGN.md` (the canonical visual / brand / design-system spec) **stays
|
||||
at the repo `docs/` root** by design — it is referenced by many existing
|
||||
`docs/DESIGN.md` paths and carries no source drift. This tree points at it
|
||||
(see `ui/library-specs-and-design-system.md`); it is not copied here.
|
||||
|
||||
## Module index
|
||||
|
||||
### `architecture/` — backend, daemon, runtime
|
||||
|
||||
| Module | What it covers |
|
||||
|---|---|
|
||||
| [daemon-core.md](architecture/daemon-core.md) | How the daemon boots, `createDaemon` wiring, the SQLite schema/40-migration set, the route-mount surface. |
|
||||
| [adapters-and-runtimes.md](architecture/adapters-and-runtimes.md) | The five-method RuntimeAdapter contract, the Claude/Codex/Terminal adapters (launch/resume/fork in tmux), and the resume-honesty layer (honest resumed-vs-fresh assessment). |
|
||||
| [coordination-primitive.md](architecture/coordination-primitive.md) | PL-004 Phase A stream/queue/inbox/outbox; the hot-potato closure contract; where queue closure is enforced. |
|
||||
| [workflow-runtime.md](architecture/workflow-runtime.md) | PL-004 Phase D Workflow Runtime — spec cache, instance state, step trails, transactional-scribe projection, watchdog policies. |
|
||||
| [mission-control.md](architecture/mission-control.md) | PL-005 queue-observability surface — seven views, seven write verbs, action audit, bearer-token middleware. |
|
||||
| [agent-spec-and-startup.md](architecture/agent-spec-and-startup.md) | AgentSpec/RigSpec types, profile resolution, additive startup layering, StartupOrchestrator, whoami/materialize/bind/adopt identity. |
|
||||
| [lifecycle-snapshot-restore.md](architecture/lifecycle-snapshot-restore.md) | Snapshot capture, honest restore (resume vs rebuild vs fresh), restore-honesty enforcement, restore-check / restore-packet probes. |
|
||||
| [transport-and-transcripts.md](architecture/transport-and-transcripts.md) | rig send/capture/broadcast over tmux, pipe-pane transcript capture + search, durable SQLite chat, `rig ask`, MCP-name vs tmux-key distinction. |
|
||||
| [workspace-primitive.md](architecture/workspace-primitive.md) | The PL-007 typed workspace declaration (root/repos/defaultRepo/knowledgeRoot), migrations 038/039, per-item repo-scope gating, file-backed missions/slices indexing. |
|
||||
| [content-surfaces.md](architecture/content-surfaces.md) | The operator-allowlisted file browser, atomic conflict-checked writes + JSONL edit audit, PROGRESS.md tree indexer, the one-screen Steering composer. |
|
||||
| [living-notes-review.md](architecture/living-notes-review.md) | **v0.4.4** — the Living Notes review surface: the ONE `ComposedSliceReview` (intent→plan→delivered) projection, pure composer + gatherer, staged-approval locks, C1-bound `verified`, `/api/review/*` routes, freeze export, ranged media serving, and the SDLC on-disk convention it projects. |
|
||||
| [plugin-agent-image-context-pack.md](architecture/plugin-agent-image-context-pack.md) | The filesystem-canonical content layer — plugin discovery, agent images, context packs, the Claude auto-compaction policy enforcer. |
|
||||
| [packaging-bootstrap-bundles.md](architecture/packaging-bootstrap-bundles.md) | Bundle assembly (schema-v2 pod bundles + legacy v1), bundle create/inspect/install + `/api/up`, the staged BootstrapOrchestrator, legacy install seams. |
|
||||
| [architecture-rules-and-event-system.md](architecture/architecture-rules-and-event-system.md) | The cross-cutting invariants — the 25 architecture rules, the RigEvent union + SSE delivery, intentional compatibility limits. |
|
||||
|
||||
### `ui/` — operator surfaces
|
||||
|
||||
| Module | What it covers |
|
||||
|---|---|
|
||||
| [shell-and-routing.md](ui/shell-and-routing.md) | The UI shell (rail / Explorer / center workspace / drawer / preview stack), the actual route tree the shipped UI mounts, the shared detail drawer + event consumption. |
|
||||
| [topology.md](ui/topology.md) | The topology surface — host hybrid graph, table/terminal views, activity-ring / hot-potato visual language, terminal-preview popovers, navigation/overlay contracts. |
|
||||
| [project-and-for-you.md](ui/project-and-for-you.md) | The operator destination surfaces — the For-You attention feed (5-card classifier + verb actions), the Project workspace/mission/slice scope pages, the Dashboard landing on the vellum brand system. |
|
||||
| [library-specs-and-design-system.md](ui/library-specs-and-design-system.md) | The Library (`/specs`) UI — specs/skills/plugins/agent-images surfaces, the spec-review + spec-library + live-identity flows, the design-system pointer. |
|
||||
|
||||
### Root docs
|
||||
|
||||
| Doc | What it covers |
|
||||
|---|---|
|
||||
| [codemap.md](codemap.md) | Navigation index — module map, structural relationship diagram, fast-lookup-by-use-case, source-root pointer table. Start here when you know *what* you need but not *which module*. |
|
||||
| [cli-reference.md](cli-reference.md) | The full `rig` CLI surface — command groups, subcommands, flags, JSON output, cross-host, coordination primitives. Kept as one doc (slice-08 Q4). |
|
||||
| [frontmatter-schema.md](frontmatter-schema.md) | Which frontmatter convention governs every doc in this tree, plus the one as-built-unique field (`last-verified-against-source`). |
|
||||
| `../DESIGN.md` | The canonical visual / brand / design-system spec (lives at `docs/` root by design; pointer only — not duplicated here). |
|
||||
|
||||
## Source-grounding contract
|
||||
|
||||
Every module declares `last-verified-against-source: <commit-sha>` — the
|
||||
commit its claims were checked against. Load-bearing corrections are recorded
|
||||
inline with an auditable annotation (`> Drift-fix Dx — said X; corrected to Y;
|
||||
slice-00 §z; re-confirmed <file:line> @HEAD`). OPEN items (counts that are
|
||||
definitional or runtime-only) are carried verbatim, never smoothed. The
|
||||
schema is defined in [frontmatter-schema.md](frontmatter-schema.md) and the
|
||||
governing convention is `openrig-work/conventions/frontmatter-for-context/`.
|
||||
+1135
-48
File diff suppressed because it is too large.
Load diff
@@ -1,228 +0,0 @@
|
||||
---
|
||||
kind: as-built
|
||||
title: Adapters and Runtimes — Claude/Codex/Terminal, tmux/cmux, Resume Honesty
|
||||
status: active
|
||||
topics: [agent-runtime, runtime-control]
|
||||
domains: [engineering-advisor, operating-advisor]
|
||||
applies-when: |
|
||||
Need the runtime-adapter contract — how OpenRig launches and resumes a
|
||||
Claude Code, Codex, or terminal harness inside tmux, what the five adapter
|
||||
methods do, or how the daemon honestly assesses whether a harness actually
|
||||
resumed vs fresh-launched (the resume-honesty 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: 7eaf524c
|
||||
last-updated: 2026-05-16
|
||||
---
|
||||
|
||||
# Adapters and Runtimes
|
||||
|
||||
How OpenRig drives the agent harnesses. The daemon never talks to Claude Code,
|
||||
Codex, or a shell directly — it talks to a `RuntimeAdapter`. Three adapters
|
||||
implement one five-method contract; 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 HEAD `7eaf524c` (`git describe` →
|
||||
> `v0.3.1-6-g7eaf524c`). All source in this module is **present at `v0.3.0`**
|
||||
> (`git cat-file -e v0.3.0:<path>` for all 7 files → present) — the adapter
|
||||
> layer is core reboot-era machinery, **not** a 0.3.x feature; do not
|
||||
> back-attribute (§10.8 version-attribution proof technique).
|
||||
|
||||
> Drift-fix (scope) — `architecture.md` §5 "Runtime adapters" carries **no
|
||||
> slice-00 numeric drift** (proposed-structure §4.2: "adapter contract is
|
||||
> current"). The corrections below are *precision* refinements where the source
|
||||
> is more specific than the prose, not stale-count fixes. Each is annotated
|
||||
> inline and re-confirmed at HEAD.
|
||||
|
||||
## 1. The five-method RuntimeAdapter contract
|
||||
|
||||
`RuntimeAdapter` is `packages/daemon/src/domain/runtime-adapter.ts:127`
|
||||
(`interface RuntimeAdapter`). Every adapter declares a `readonly runtime`
|
||||
string and implements exactly five methods (`runtime-adapter.ts:128–153`):
|
||||
|
||||
| Method | Signature (`runtime-adapter.ts`) | Responsibility |
|
||||
|---|---|---|
|
||||
| `listInstalled` | `(binding)` `:131` | List currently installed/projected resources for a node. |
|
||||
| `project` | `(plan, binding)` `:134` | Project resources from a `ProjectionPlan` to the runtime's target locations. |
|
||||
| `deliverStartup` | `(files, binding)` `:137` | Deliver resolved startup files to the runtime. |
|
||||
| `launchHarness` | `(binding, opts)` `:147` | Launch the harness inside the bound tmux session; return a resume token. |
|
||||
| `checkReady` | `(binding)` `:153` | Probe whether the harness is responsive and ready. |
|
||||
|
||||
Startup *action* execution (`slash_command` / `send_text`) is explicitly **not**
|
||||
part of this contract — the contract docstring (`runtime-adapter.ts:121–125`)
|
||||
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:147–150`).
|
||||
|
||||
> Drift-fix (precision) — `architecture.md` §4 said `launchHarness(binding,
|
||||
> opts: { name, resumeToken? })`. Source adds a third, mutually-exclusive
|
||||
> `forkSource` field. Per the contract docstring (`runtime-adapter.ts:142–146`)
|
||||
> `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:116` (`kind: "native_id" |
|
||||
> "artifact_path" | "name" | "last"`; v1 MVP accepts `native_id` only — other
|
||||
> shapes rejected at schema validation, docstring `:106–119`).
|
||||
|
||||
### `HarnessLaunchResult` is a discriminated union with an honest failure arm
|
||||
|
||||
> Drift-fix (precision) — `architecture.md` §4 said `HarnessLaunchResult` is
|
||||
> `{ ok, resumeToken?, resumeType?, error? }` (a single optional-field shape).
|
||||
> Source is a **discriminated union** (`runtime-adapter.ts:81–86`):
|
||||
> `| { ok: true; resumeToken?; resumeType? }`
|
||||
> `| { ok: false; error: string; recovery?: HarnessLaunchRecovery; evidence? }`.
|
||||
> The failure arm carries a typed `recovery` hint
|
||||
> (`HarnessLaunchRecovery = "retry_fresh" | "attention_required"`,
|
||||
> `:79`) and optional `evidence` (last-N pane lines, flowed through to
|
||||
> `RestoreNodeResult.attentionEvidence` for `attention_required` outcomes,
|
||||
> `:83–86`). This is the honest-failure shape, not a smoothed optional `error`.
|
||||
|
||||
## 2. The three adapters
|
||||
|
||||
All three live under `packages/daemon/src/adapters/` and implement
|
||||
`RuntimeAdapter` (Architecture Rule 1: zero Hono in `adapters/`).
|
||||
|
||||
### ClaudeCodeAdapter (`claude-code-adapter.ts:41`)
|
||||
|
||||
- `readonly runtime = "claude-code"` (`:42`).
|
||||
- **Projects** to `.claude/` targets: `guidance_merge` → `<cwd>/CLAUDE.md`
|
||||
(`:127`); `skill_install` → `<cwd>/.claude/skills/<name>/` (`:71,133`);
|
||||
subagents → `.claude/agents`, plugins → `.claude/plugins/<id>`,
|
||||
runtime resources → `.claude/extensions/<id>`, settings fragments merged
|
||||
into `.claude/settings.local.json` (`:388–400`).
|
||||
- **Launches** (`:213–215`): fresh = `claude <permissionMode> --session-id
|
||||
<generatedId> --name <name>`; resume = `claude <permissionMode> --resume
|
||||
<token> --name <name>`; fork = `claude <permissionMode> --resume <parentId>
|
||||
--fork-session --name <seat>` (`:188`).
|
||||
> Drift-fix (precision) — `architecture.md` §5 said only "launches via
|
||||
> `claude --name <name>`, resumes via `claude --resume <token>`". Source
|
||||
> shows fresh launch uses an explicit `--session-id` (so a deterministic
|
||||
> resume token exists immediately) and the fork branch exists. Re-confirmed
|
||||
> `claude-code-adapter.ts:188,213–215` @HEAD.
|
||||
- **Readiness** (`checkReady`, `:239`): verifies tmux session alive, captures
|
||||
40 pane lines + pane command, delegates to `assessNativeResumeProbe` (§3);
|
||||
ready only when probe `status === "resumed"`. The resume-launch verification
|
||||
loop `verifyResumeLaunch` retries up to **16 attempts** (`:273`), failing
|
||||
loudly with `recovery: "retry_fresh"` on `no_conversation_found`
|
||||
(`:284–289`) — no silent fresh fallback.
|
||||
|
||||
### CodexRuntimeAdapter (`codex-runtime-adapter.ts:37`)
|
||||
|
||||
- `readonly runtime = "codex"` (`:38`).
|
||||
- **Projects** to `.agents/` targets: `guidance_merge` → `<cwd>/AGENTS.md`
|
||||
(`:139,330`); `skill_install` → `<cwd>/.agents/skills/<name>/` (`:89,145`);
|
||||
skills resolve under `.agents/skills/<id>` (`:377`).
|
||||
- **Launches/resumes** (`:205,225–226`): fresh launch then capture a fresh
|
||||
thread id; resume = `codex<profileArg> resume<queueStateDirArg> <token>`;
|
||||
fork = `codex<profileArg> fork<queueStateDirArg> <parentId>` (`:205`). On
|
||||
success returns `{ ok: true, resumeToken: threadId, resumeType: "codex_id" }`
|
||||
(`:222,245,250`).
|
||||
> Drift-fix (precision) — `architecture.md` §5 said "launches via `codex`,
|
||||
> resumes via `codex resume <threadId>`". Source confirms the `codex resume
|
||||
> <token>` shape (`:226`) and adds the fork branch + the
|
||||
> `resumeType: "codex_id"` tag. Re-confirmed @HEAD.
|
||||
- Refuses `resumeToken` + `forkSource` together with a clear error
|
||||
(`:180–181`) — honors the mutual-exclusivity contract.
|
||||
|
||||
### TerminalAdapter (`terminal-adapter.ts:19`)
|
||||
|
||||
- `readonly runtime = "terminal"` (`:20`).
|
||||
- **All operations are no-ops** — "the shell IS the harness"
|
||||
(`terminal-adapter.ts:15`): no-op `project`/`deliverStartup`/`launchHarness`
|
||||
(`:34`), and `checkReady` returns ready immediately as soon as the tmux
|
||||
session exists (`:47`). Used for infrastructure nodes — servers, log tails,
|
||||
build watchers. (A terminal node cannot fork; the runtime-adapter docstring
|
||||
notes fork-unsupported adapters refuse with a runtime-mismatch error,
|
||||
`runtime-adapter.ts:113–115`.)
|
||||
|
||||
These three are constructed by `createDaemon` step 4 (`startup.ts`; see
|
||||
`daemon-core.md` §4 "Startup sequence").
|
||||
|
||||
## 3. Resume honesty
|
||||
|
||||
The daemon does not assume a harness resumed just because the launch command
|
||||
ran. Three domain files (`packages/daemon/src/domain/`, all present @v0.3.0)
|
||||
make resume assessment honest:
|
||||
|
||||
### `native-resume-probe.ts`
|
||||
|
||||
`assessNativeResumeProbe(input)` (`native-resume-probe.ts:43`) reads pane
|
||||
command + pane content and returns one of four honest statuses
|
||||
(`NativeResumeProbeStatus`, `:6`):
|
||||
|
||||
- `resumed` — runtime-specific indicators confirm a resumed session.
|
||||
- `failed` — terminal failure (e.g. Claude printed "No conversation found" →
|
||||
code `no_conversation_found`, `:51–57`).
|
||||
- `inconclusive` — we don't know yet (e.g. Claude trust gate, code
|
||||
`trust_gate`, `:65–70`).
|
||||
- `attention_required` — alive and recoverable but **needs operator action**
|
||||
(e.g. Claude resume-selection prompt, code `claude_resume_selection_prompt`,
|
||||
`:58–64`). This is the proxy for "an operator must choose the conversation";
|
||||
it is *distinct* from `inconclusive` and `failed` (docstring `:3–5`).
|
||||
|
||||
`buildNativeResumeCommand` (`:27`) builds the resume command per runtime:
|
||||
claude → `claude --resume <token> [--name <name>]` (`:35`); codex → `codex
|
||||
resume <token>` (`:38`); other runtimes → `null` (`:40`).
|
||||
|
||||
This is Architecture Rule 15 in code: a failed resume is FAILED loudly; there
|
||||
is no automatic fresh fallback (the adapter's `verifyResumeLaunch` returns
|
||||
`ok:false` with a `retry_fresh` recovery hint, never a silent relaunch).
|
||||
|
||||
### `resume-metadata-refresher.ts`
|
||||
|
||||
`ResumeMetadataRefresher` (`resume-metadata-refresher.ts:37`). Post-launch
|
||||
resume-token capture: `refresh(sessions)` (`:62`) skips sessions that already
|
||||
have a `resumeToken` (`:65`), and for `claude-code` sessions with a token runs
|
||||
a `probeClaudeResume` returning `"resumable" | "not_resumable" |
|
||||
"inconclusive"` (`:31,74–75`) — a real launch of the resume command in a
|
||||
throwaway probe tmux session (`:106–111`), not a metadata guess.
|
||||
|
||||
### `codex-thread-id.ts`
|
||||
|
||||
Codex thread-id extraction (`codex-thread-id.ts`). Reads the Codex thread id
|
||||
from the Codex *logs* SQLite databases under `~/.codex/`:
|
||||
`readCodexThreadIdFromCandidateHomes(...)` (`:22`) →
|
||||
`readCodexThreadIdFromLogs(...)` (`:49`) → `resolveCodexLogDbPaths(homeDir)`
|
||||
(`:79`) which globs `<homeDir>/.codex/logs_<N>.sqlite` (`:84–89`,
|
||||
regex `^logs_(\d+)\.sqlite$`) and falls back to `logs_1.sqlite` (`:97`).
|
||||
Uses `better-sqlite3` (`:5`). Resolves the home dir by the harness PID
|
||||
(`defaultResolveHomeDirByPid`, `:9`).
|
||||
|
||||
> Precision note — `architecture.md` §5 "Resume honesty" says codex thread IDs
|
||||
> come from "the Codex SQLite database". Source is more specific: the
|
||||
> per-version Codex *logs* DBs `~/.codex/logs_N.sqlite`. Stated precisely here;
|
||||
> re-confirmed `codex-thread-id.ts:79–97` @HEAD.
|
||||
|
||||
## 4. Relevant Architecture Rules (source-verified at HEAD)
|
||||
|
||||
From `architecture.md` §7 (re-confirmed against the source cited inline):
|
||||
|
||||
- **Rule 5** — Runtime is member-authoritative in the pod-aware model.
|
||||
- **Rule 13** — Readiness checking is a retry loop with exponential backoff and
|
||||
a configurable timeout, using adapter-specific probes (Claude TUI indicator,
|
||||
Codex ready message, terminal immediate). Re-confirmed: `checkReady`
|
||||
delegates to `assessNativeResumeProbe`; the retry loop is
|
||||
`claude-code-adapter.ts:273` (16 attempts).
|
||||
- **Rule 14** — Resume states are locked: `resumed` / `rebuilt` / `fresh`;
|
||||
`rebuilt` = new process assembled from artifacts. (The probe layer adds
|
||||
`inconclusive` / `attention_required` as honest *transient* states, not
|
||||
outcomes — see §3.)
|
||||
- **Rule 15** — Restore honesty: failed resume is FAILED loudly; no automatic
|
||||
fresh fallback; fresh launch is an explicit follow-up only. Enforced in code
|
||||
by §2/§3 (`verifyResumeLaunch` returns `ok:false`, never relaunches).
|
||||
|
||||
## See also
|
||||
|
||||
- `daemon-core.md` — where `createDaemon` constructs the three adapters.
|
||||
- `agent-spec-and-startup.md` — the `StartupOrchestrator` that calls these
|
||||
adapters and owns startup-action execution after `checkReady()`.
|
||||
- `lifecycle-snapshot-restore.md` — how persisted resume tokens flow into
|
||||
snapshot/restore (resume vs rebuild vs fresh).
|
||||
- Source roots: `packages/daemon/src/domain/runtime-adapter.ts`,
|
||||
`packages/daemon/src/adapters/{claude-code-adapter,codex-runtime-adapter,terminal-adapter}.ts`,
|
||||
`packages/daemon/src/domain/{native-resume-probe,resume-metadata-refresher,codex-thread-id}.ts`.
|
||||
@@ -1,232 +0,0 @@
|
||||
---
|
||||
kind: as-built
|
||||
title: Agent/Rig Spec, Resolution, Startup, Identity
|
||||
status: active
|
||||
topics: [specification-and-bundles, agent-runtime]
|
||||
domains: [engineering-advisor, operating-advisor]
|
||||
applies-when: |
|
||||
Need to know the canonical AgentSpec/RigSpec/pod-aware reboot types, how
|
||||
profile resolution and additive startup layering work, the StartupOrchestrator
|
||||
pre-launch-vs-interactive delivery split, or how whoami/materialize/bind/adopt
|
||||
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: 7eaf524c
|
||||
last-updated: 2026-05-16
|
||||
---
|
||||
|
||||
# Agent/Rig Spec, Resolution, Startup, Identity
|
||||
|
||||
How the daemon turns authored YAML specs into a resolved, projected, launched,
|
||||
and identity-addressable topology. The spec-and-startup contract: parse →
|
||||
resolve → project → deliver → launch → wait → persist replay context.
|
||||
|
||||
> Verified against source at HEAD `7eaf524c` (`git describe` →
|
||||
> `v0.3.1-6-g7eaf524c`). Package version is **0.3.1** across all three
|
||||
> packages (slice-00 §1.1). Source feed located by `architecture.md` headings
|
||||
> (§4 Canonical Reboot Types, §5 Domain Services, §6 Execution Flows, §7
|
||||
> Architecture Rules) per slice-08 §10.1 — line numbers are advisory only.
|
||||
|
||||
## 1. Canonical spec and topology types
|
||||
|
||||
(`architecture.md` §4 "Spec and topology")
|
||||
|
||||
- **AgentSpec** — parsed from `agent.yaml`. Owns imports, defaults, startup,
|
||||
resources, and profiles. Canonical parse/normalize/validate is
|
||||
`domain/agent-manifest.ts`.
|
||||
- **RigSpec** — canonical pod-aware rig topology. Uses `version: "0.2"` and
|
||||
`pods[]`; owns cross-pod `edges[]`, rig-level startup overlays, and
|
||||
`cultureFile`.
|
||||
|
||||
> Drift-fix D-spec-version — `architecture.md` §4 says RigSpec
|
||||
> "Uses `version: "0.2"`". This is the **spec-schema version, NOT the
|
||||
> package version** — a different versioning axis from the 0.3.1 package
|
||||
> version. The value is NOT a code constant: `rigspec-schema.ts:52`
|
||||
> validates `version` only as a "required non-empty string"
|
||||
> (`if (!obj["version"] || typeof obj["version"] !== "string")`); `:163`
|
||||
> carries it through as `raw["version"] as string`. `"0.2"` is the
|
||||
> canonical authored value, correctly described as a schema axis. Do NOT
|
||||
> "correct" it toward 0.3.1 (slice-08 §4.6 binding). Re-confirmed
|
||||
> `rigspec-schema.ts:52,163` @HEAD.
|
||||
|
||||
- **RigServicesSpec** — optional `services` block on a pod-aware RigSpec.
|
||||
Shipped kind is Compose-backed env management with `composeFile`,
|
||||
`projectName?`, `profiles?`, `downPolicy?`, `waitFor?`, `surfaces?`,
|
||||
`checkpoints?`.
|
||||
- **RigSpecPod** — pod-local bounded context with `members[]`, pod-local
|
||||
`edges[]`, pod startup, optional continuity policy.
|
||||
- **RigSpecPodMember** — member-level runtime/startup surface: `agentRef`,
|
||||
`profile`, `runtime`, `model?`, `cwd`, `restorePolicy?`, member startup
|
||||
overlays.
|
||||
- **Pod** — persisted DB entity for a pod.
|
||||
- **ContinuityState** — persisted live continuity row keyed by
|
||||
`podId + nodeId`.
|
||||
|
||||
## 2. Execution and projection types
|
||||
|
||||
(`architecture.md` §4 "Execution and restore" — restore/snapshot members are
|
||||
detailed in `lifecycle-snapshot-restore.md`; the spec/projection members live
|
||||
here)
|
||||
|
||||
- **ResolvedNodeConfig** — output of profile resolution. Carries effective
|
||||
runtime/model/cwd, narrowed restore policy, selected resources, layered
|
||||
startup block, resolved spec identity.
|
||||
- **ProjectionPlan** — runtime projection plan for a node: runtime, cwd,
|
||||
projection entries, startup block, diagnostics, conflict/no-op
|
||||
classifications.
|
||||
- **RuntimeAdapter** — the five-method contract (adapter detail in
|
||||
`adapters-and-runtimes.md`): `listInstalled(binding)`
|
||||
(`runtime-adapter.ts:131`), `project(plan, binding)` (`:134`),
|
||||
`deliverStartup(files, binding)` (`:137`), `launchHarness(binding, opts)`
|
||||
(`:147`), `checkReady(binding)` (`:153`). Re-confirmed @HEAD — the contract
|
||||
is current.
|
||||
- **HarnessLaunchResult** — `{ ok, resumeToken?, resumeType?, error? }`
|
||||
returned by `launchHarness`.
|
||||
- **StartupOrchestrator** — drives the full startup sequence (§4 below).
|
||||
|
||||
## 3. Parsing, validation, resolution pipeline
|
||||
|
||||
(`architecture.md` §5 "Parsing and validation" + "Resolution pipeline"; all
|
||||
under `packages/daemon/src/domain/`, zero Hono imports per Architecture Rule 1)
|
||||
|
||||
**Parse / validate:**
|
||||
|
||||
- `agent-manifest.ts` — canonical AgentSpec parse/normalize/validate.
|
||||
- `rigspec-schema.ts` — dual-format RigSpec validation.
|
||||
- `rigspec-codec.ts` — dual-format YAML codec.
|
||||
- `startup-validation.ts` — shared startup-block validation.
|
||||
- `path-safety.ts` — shared relative-path safety checks.
|
||||
- `spec-validation-service.ts` — pure raw-YAML validation helpers.
|
||||
- `spec-review-service.ts` — daemon-owned structured review model for
|
||||
RigSpec/AgentSpec YAML, incl. topology preview, provenance state, managed-app
|
||||
services metadata (`waitFor`, `surfaces`, `composePreview`).
|
||||
|
||||
**Resolve:**
|
||||
|
||||
- `agent-resolver.ts` — resolves `agent_ref`, imports, collision metadata.
|
||||
- `agent-preflight.ts` — single-agent resolution/preflight.
|
||||
- `profile-resolver.ts` — applies defaults, profile uses, resource selection,
|
||||
startup layering, restore-policy narrowing.
|
||||
- `startup-resolver.ts` — additive startup layering.
|
||||
- `projection-planner.ts` — runtime resource projection planning.
|
||||
|
||||
All eleven files re-confirmed present in `packages/daemon/src/domain/` @HEAD.
|
||||
|
||||
## 4. Startup orchestration (the spec-startup contract)
|
||||
|
||||
(`architecture.md` §4 "StartupOrchestrator" + §5 "Startup, runtime, and
|
||||
instantiation" + §7 Architecture Rule 6)
|
||||
|
||||
`StartupOrchestrator` (`domain/startup-orchestrator.ts`) drives:
|
||||
mark pending → project resources → deliver pre-launch files → launch harness
|
||||
→ wait for ready → deliver interactive files → execute actions → persist
|
||||
context → mark ready.
|
||||
|
||||
**Pre-launch vs interactive delivery split** — the load-bearing seam,
|
||||
re-confirmed at source:
|
||||
|
||||
- Pre-launch (filesystem, before harness boot): `guidance_merge`,
|
||||
`skill_install` (`startup-orchestrator.ts:78,167` — "Deliver pre-launch
|
||||
files (guidance_merge, skill_install → filesystem)").
|
||||
- Post-launch (TUI, after harness is ready): `send_text`
|
||||
(`startup-orchestrator.ts:82,160,263` — partition by concrete hint at
|
||||
`:141`, deliver after readiness at `:263`).
|
||||
|
||||
The orchestrator persists replay context including the resume token for future
|
||||
restores (consumed by `lifecycle-snapshot-restore.md`).
|
||||
|
||||
**Architecture Rule 6 — startup layering is additive and ordered** (carried
|
||||
verbatim, `architecture.md` §7): (1) agent base, (2) profile, (3) rig culture
|
||||
file, (4) rig startup, (5) pod startup, (6) member startup, (7) operator debug
|
||||
append. This is the spec-startup contract's invariant; the full 25-rule list
|
||||
lives in `architecture-rules-and-event-system.md`.
|
||||
|
||||
**Startup action constraints** (`architecture.md` §7 "Current startup action
|
||||
constraints"): no shell startup actions; action types are `slash_command` and
|
||||
`send_text` only; non-idempotent actions must not apply on restore; retrying
|
||||
failed startup is handled as restore.
|
||||
|
||||
**Remote import constraints** (§7): the reboot supports `local:...` and
|
||||
`path:/abs/...`. Remote `agent_ref` sources remain unsupported and fail in
|
||||
preflight.
|
||||
|
||||
## 5. Instantiation, preflight, export
|
||||
|
||||
(`architecture.md` §5 "Startup, runtime, and instantiation" + §6 "RigSpec
|
||||
import / validate / preflight / export")
|
||||
|
||||
- `runtime-adapter.ts` — adapter contract + bridge types.
|
||||
- `rigspec-preflight.ts` — dual-stack legacy preflight plus rebooted
|
||||
`rigPreflight(...)`.
|
||||
- `rigspec-instantiator.ts` — dual-stack `RigInstantiator` plus
|
||||
`PodRigInstantiator`.
|
||||
- `rigspec-exporter.ts` — dual-format live rig export to YAML/JSON.
|
||||
- `pod-repository.ts` — pod CRUD plus live continuity-state CRUD.
|
||||
|
||||
`routes/rigspec.ts` is the dual-format seam: validate
|
||||
(pod-aware → `RigSpecSchema.validate`; legacy → `LegacyRigSpecSchema.validate`),
|
||||
preflight (`rigPreflight({ rigSpecYaml, rigRoot, fsOps })` vs
|
||||
`RigSpecPreflight.check(spec)`), import
|
||||
(`podInstantiator.instantiate(yaml, rigRoot)` vs
|
||||
`RigInstantiator.instantiate(spec)`), export (pod-aware exports canonical
|
||||
`version: "0.2"` RigSpec; legacy exports flat-node v1).
|
||||
|
||||
## 6. Identity: whoami, materialize, bind, adopt
|
||||
|
||||
(`architecture.md` §6 "Whoami and adopted-session parity flow" +
|
||||
"Materialize / bind / adopt flow")
|
||||
|
||||
**Whoami resolution** — the daemon owns the truth surface through
|
||||
`/api/whoami` (`routes/whoami.ts`); tmux metadata is an adopted-session
|
||||
anchor, not sovereign truth. `whoami-service.ts:8` declares
|
||||
`resolvedBy: "node_id" | "session_name"`. The route requires `nodeId` or
|
||||
`sessionName` (`routes/whoami.ts:10-15`). Resolution order:
|
||||
explicit `--node-id` → explicit `--session` → env vars → tmux metadata →
|
||||
raw tmux session-name fallback.
|
||||
|
||||
- Managed sessions prefer projected `OPENRIG_NODE_ID` /
|
||||
`OPENRIG_SESSION_NAME`.
|
||||
- Adopted sessions use tmux-owned metadata written at claim/bind time.
|
||||
|
||||
> Drift-nuance D5 (the careful axis — see also `transport-and-transcripts.md`):
|
||||
> the tmux metadata keys `@rigged_node_id` / `@rigged_session_name` /
|
||||
> `@rigged_rig_id` / `@rigged_rig_name` / `@rigged_logical_id` in
|
||||
> `architecture.md` §6 are **CORRECT as-is** and were verified literally at
|
||||
> source — `claim-service.ts:77-81` writes exactly these `@rigged_*` keys;
|
||||
> `claim-service.ts` and `rig-lifecycle-service.ts` read them. This is a
|
||||
> SEPARATE axis from MCP tool names (which are `rig_*`, slice-00 §1.4). Do
|
||||
> NOT blanket-replace `rigged` → `rig` (banked
|
||||
> `feedback_release_prep_three_layer_depersonalization`: the rename was
|
||||
> scoped, not global). The tmux metadata keys were NOT renamed.
|
||||
> Re-confirmed `claim-service.ts:77-81` @HEAD.
|
||||
|
||||
**Materialize / bind / adopt** (`architecture.md` §6): `POST
|
||||
/api/rigs/import/materialize` creates a pod-aware topology without launching
|
||||
sessions; `POST /api/discovery/:id/bind` attaches a discovered live session to
|
||||
an existing logical node; `POST /api/discovery/:id/adopt` is the composite
|
||||
route (bind to existing node, or create a new member in a target pod and bind
|
||||
immediately). CLI mirrors via `rig bind` / `rig adopt`. Authored pod namespace
|
||||
is preserved through adoption so logical ids stay
|
||||
`${podNamespace}.${memberName}` (Architecture Rule 24: adopted-session parity
|
||||
is tmux-metadata parity, not fake env-var parity).
|
||||
|
||||
## OPEN / carried items
|
||||
|
||||
- **D-spec-version (resolved-as-correct):** RigSpec `version: "0.2"` is the
|
||||
spec-schema axis, validated only as a non-empty string in source. Documented,
|
||||
not "corrected".
|
||||
- **D5 (careful, resolved-as-correct for this module):** tmux `@rigged_*`
|
||||
metadata keys are literally still `@rigged_*` at HEAD — architecture.md §6 is
|
||||
accurate. The MCP-tool-name `rigged_*` drift lands in
|
||||
`transport-and-transcripts.md`.
|
||||
|
||||
## See also
|
||||
|
||||
- `daemon-core.md` — createDaemon wiring; the migration/route surface.
|
||||
- `adapters-and-runtimes.md` — the five-method RuntimeAdapter contract detail.
|
||||
- `lifecycle-snapshot-restore.md` — snapshot/restore consumes persisted replay
|
||||
context.
|
||||
- `architecture-rules-and-event-system.md` — the full 25 architecture rules.
|
||||
- Source roots: `packages/daemon/src/domain/{agent-manifest,rigspec-schema,
|
||||
profile-resolver,startup-orchestrator,whoami-service,claim-service}.ts`,
|
||||
`packages/daemon/src/routes/{rigspec,whoami}.ts`.
|
||||
@@ -1,216 +0,0 @@
|
||||
---
|
||||
kind: as-built
|
||||
title: Architecture Invariants, Event System, Compatibility Notes
|
||||
status: active
|
||||
topics: [runtime-control, observability, doctrine]
|
||||
domains: [engineering-advisor, operating-advisor, review]
|
||||
applies-when: |
|
||||
Need the cross-cutting architecture invariants the codebase enforces (the
|
||||
25 architecture rules + startup/import constraints), the shape of the
|
||||
RigEvent union and its SSE delivery surfaces, or the intentional
|
||||
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: 7eaf524c
|
||||
last-updated: 2026-05-16
|
||||
---
|
||||
|
||||
# Architecture Invariants, Event System, Compatibility Notes
|
||||
|
||||
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 HEAD `7eaf524c` (`git describe` →
|
||||
> `v0.3.1-6-g7eaf524c`); package version **0.3.1** across all three packages
|
||||
> (slice-00 §1.1). HEAD carries 6 commits of unreleased 0.3.2 work; no
|
||||
> `v0.3.2` tag exists.
|
||||
|
||||
## 1. Architecture rules
|
||||
|
||||
These are the invariants the codebase is built to preserve (`architecture.md`
|
||||
§7). Rule 6 (startup layering) and rule 7 (restore-policy narrowing) are the
|
||||
spec/startup contract — see `agent-spec-and-startup.md` for their flow detail;
|
||||
they are restated here as system-level invariants.
|
||||
|
||||
1. Zero Hono in `domain/` and `adapters/`.
|
||||
2. Routes depend on the domain; the domain never depends on routes.
|
||||
3. Shared DB-handle invariants are enforced at construction time.
|
||||
4. The reboot is engine-first: domain services land before public-surface
|
||||
rewiring.
|
||||
5. Runtime is member-authoritative in the pod-aware model.
|
||||
6. Startup layering is additive and ordered: agent base → profile → rig
|
||||
culture file → rig startup → pod startup → member startup → operator debug
|
||||
append.
|
||||
7. Restore-policy narrowing is one-way only: `resume_if_possible` →
|
||||
`relaunch_fresh` → `checkpoint_only`.
|
||||
8. Base/import collisions warn; ambiguous import/import unqualified refs fail
|
||||
loudly.
|
||||
9. Bundle assembly and startup-file resolution use containment checks rooted
|
||||
in the owning artifact.
|
||||
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`, `failed`.
|
||||
12. Session recency depends on monotonic ULIDs: `session-registry.ts` uses
|
||||
`monotonicFactory()`; restore selects the newest session by max ULID.
|
||||
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. Resume states are locked: `resumed` / `rebuilt` / `fresh`. `rebuilt` =
|
||||
new process assembled from artifacts.
|
||||
15. Restore honesty: failed resume is FAILED loudly. No automatic fresh
|
||||
fallback. Fresh launch is explicit follow-up only.
|
||||
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,
|
||||
system-validated. No generation, no slugification.
|
||||
18. Communication: tmux is transport, not truth. `send/capture/broadcast`
|
||||
wrap tmux reliably with honest errors.
|
||||
19. Transcripts: raw capture via pipe-pane, ANSI strip on read. `rg`
|
||||
preferred, `grep -E` fallback.
|
||||
20. Config precedence: CLI flag > env var > config file
|
||||
(`~/.openrig/config.json`, with legacy fallback from
|
||||
`~/.rigged/config.json`) > 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
|
||||
external LLM. The agent IS the LLM.
|
||||
23. Spec library truth is YAML on disk; daemon owns the structured
|
||||
review/index/cache layer.
|
||||
24. Adopted-session parity is tmux-metadata parity, not fake env-var parity.
|
||||
25. Human-readable IDs are UI-only presentation helpers. CLI/API/MCP/backend
|
||||
keep full canonical ids.
|
||||
|
||||
### Startup action constraints
|
||||
|
||||
- No shell startup actions.
|
||||
- Action types are `slash_command` and `send_text` only.
|
||||
- Non-idempotent actions must not apply on restore.
|
||||
- Retrying failed startup is handled as restore.
|
||||
|
||||
### Remote import constraints
|
||||
|
||||
The reboot supports `local:...` and `path:/abs/...` agent refs. Remote
|
||||
`agent_ref` sources remain unsupported and fail in preflight
|
||||
(`architecture.md` §7 "Remote import constraints"; restated in compat note 1).
|
||||
|
||||
## 2. Event system
|
||||
|
||||
The daemon's event surface is the single `RigEvent` discriminated union.
|
||||
|
||||
> Drift-fix D8 / OPEN-4 (carried verbatim, slice-00): `architecture.md` §8
|
||||
> says "PL-004 Phase A adds 9 coordination events" and (in §3) "Existing 32
|
||||
> PL-004 events" / "Existing 20 PL-004 events" — internally inconsistent
|
||||
> contested PL-004 sub-counts. **Do NOT carry the 9 / 32 / 20 figures.** The
|
||||
> `architecture.md` §8 "Currently emitted in production code" / "Present in
|
||||
> the union but not yet emitted" lists also predate 0.3.x and are stale. The
|
||||
> union shape below is re-derived from source at HEAD, not migrated.
|
||||
|
||||
`RigEvent` is declared at `packages/daemon/src/domain/types.ts:94`
|
||||
(`export type RigEvent =`) and runs through `types.ts:218`. It has **73
|
||||
union members** (slice-00 §1.8, re-confirmed at HEAD:
|
||||
`grep -cE '^\s*\| \{ type:'` over L94–218 = 73). Every one of the 73
|
||||
declared `type:` literals is also constructed somewhere in
|
||||
`packages/daemon/src/{domain,routes}` (re-verified at HEAD: the set of
|
||||
`type: "<x>"` literals in domain+routes exactly equals the 73 union members
|
||||
— zero union-only-but-never-referenced types).
|
||||
|
||||
### Per-prefix event families (grep-verified at HEAD)
|
||||
|
||||
Each count below is a fresh, primary-source-grep-verified, explicitly-labeled
|
||||
per-prefix family count over the union body
|
||||
(`types.ts:94–218`) — NOT the contested PL-004 sub-count (OPEN-4 ruling:
|
||||
labeled grep-verified family counts are ground truth; the `9`/`32`/`20`
|
||||
figures are forbidden).
|
||||
|
||||
| Prefix | Members | Sample / role |
|
||||
|---|---|---|
|
||||
| `node.*` | 7 | `node.added` (`types.ts:97`) … `node.startup_failed` (`:139`) — lifecycle/startup |
|
||||
| `workflow.*` | 6 | PL-004 Phase D workflow runtime (detail in `workflow-runtime.md`) |
|
||||
| `watchdog.*` | 5 | `watchdog.evaluation_fired` (`:187`) … `watchdog.job_stopped` (`:191`) — PL-004 Phase C |
|
||||
| `rig.*` | 5 | `rig.created` / `rig.deleted` / `rig.imported` / `rig.stopped` / `rig.expanded` (`:151`) |
|
||||
| `queue.*` | 5 | PL-004 Phase A queue lifecycle (`:156`–`:159`, `:169`; detail in `coordination-primitive.md`) |
|
||||
| `package.*` | 5 | legacy package/install engine events |
|
||||
| `mission_control.*` | 5 | PL-005 audit/notification (`:212`–`:218`; detail in `mission-control.md`) |
|
||||
| `bootstrap.*` | 5 | legacy bootstrap-run events |
|
||||
| `session.*` | 4 | session discovery / status / detach / vanish |
|
||||
| `classifier.*` | 4 | PL-004 Phase B classifier-lease lifecycle |
|
||||
| `restore.*` | 3 | restore start/complete/reconcile (detail in `lifecycle-snapshot-restore.md`) |
|
||||
| `qitem.*` | 2 | `qitem.fallback_routed` (`:160`), `qitem.closure_overdue` (`:161`) |
|
||||
| `pod.*` | 2 | `pod.created` (`:135`), `pod.deleted` (`:136`) |
|
||||
| `inbox.*` | 2 | `inbox.absorbed` (`:162`), `inbox.denied` (`:163`) |
|
||||
| `continuity.*` | 2 | `continuity.sync` (`:140`), `continuity.degraded` (`:141`) |
|
||||
| singletons | 11 | one member each: `workflow_spec.*`, `view.*`, `stream.*` (`:155`), `snapshot.*`, `seat.*`, `project.*`, `kernel.*`, `chat.*` (`:149`), `bundle.*`, `binding.*`, `agent.*` |
|
||||
|
||||
Family counts sum to 73 (15 multi-member families totalling 62 + 11
|
||||
singletons), re-confirmed at HEAD.
|
||||
|
||||
### Emission and delivery
|
||||
|
||||
Events are constructed and emitted via `eventBus.emit({ type: ... })` across
|
||||
domain services (`stream-store.ts`, `workflow-runtime.ts`,
|
||||
`restore-orchestrator.ts`, `node-launcher.ts`, etc.) and route handlers. The
|
||||
event log is append-only and SQLite-backed.
|
||||
|
||||
Three SSE delivery surfaces (re-confirmed at HEAD):
|
||||
|
||||
- `GET /api/events` — global stream of all events (`server.ts:457`
|
||||
`app.route("/api/events", eventsRoute)`).
|
||||
- `GET /api/stream/watch` — new stream items (`routes/stream.ts:117`).
|
||||
- `GET /api/queue/watch` — queue/inbox coordination events
|
||||
(`routes/queue.ts:357`).
|
||||
- The chat SSE stream `GET /api/rigs/:rigId/chat/watch` delivers
|
||||
`chat.message` for one rig (rig-scoped; see compat note 6).
|
||||
|
||||
> OPEN-4 (carried verbatim, slice-00): the precise PL-004-only vs PL-005-only
|
||||
> sub-partition is NOT asserted here. `architecture.md`'s `32`/`20`/`9`
|
||||
> figures are internally inconsistent and not reconcilable without
|
||||
> classifying all 73 members by introducing slice — flagged, not smoothed.
|
||||
> The grep-verified per-prefix family counts above are the substituted ground
|
||||
> truth.
|
||||
|
||||
## 3. Remaining compatibility notes
|
||||
|
||||
Intentional limits that still describe the shipped system (`architecture.md`
|
||||
§11), verified as still-current at HEAD:
|
||||
|
||||
1. Remote `agent_ref` imports remain unsupported (see §1 remote import
|
||||
constraints).
|
||||
2. Startup actions remain intentionally constrained (`slash_command`,
|
||||
`send_text`).
|
||||
3. Legacy compatibility seams still ship for pre-reboot data and v1
|
||||
artifacts.
|
||||
4. `rig ask` gathers context only — does not call an external LLM (rule 22).
|
||||
5. Transcript search prefers `rg`, falls back to `grep -E`; quality/perf
|
||||
varies by backend.
|
||||
6. Chat is rig-scoped only — no cross-rig channels or DMs.
|
||||
7. `--verify` on `rig send` checks pane content for message visibility but
|
||||
can produce false positives from pre-existing matching content. Known
|
||||
limitation.
|
||||
8. Terminal node readiness is shell-ready only — no service health probes.
|
||||
9. `rig env down --volumes` exists in the CLI surface, but the explicit
|
||||
daemon-side override is not fully plumbed through yet.
|
||||
10. Managed-app service surfaces are descriptive only — OpenRig does not
|
||||
auto-inject service URLs/tokens into agent prompts beyond authored
|
||||
startup/context files.
|
||||
11. Specialist delegation is conventional, not automatic — addressed by
|
||||
session name or normal communication surfaces.
|
||||
|
||||
## 4. Cross-references
|
||||
|
||||
`architecture.md` §12 names itself the architecture-level source of truth and
|
||||
points at `codemap.md` for file-by-file structure. Under the modular
|
||||
as-built, that role is distributed: this module owns the invariants + event
|
||||
shape; the source-of-truth pointer is the rewritten `../codemap.md`
|
||||
navigation index.
|
||||
|
||||
## See also
|
||||
|
||||
- `daemon-core.md` — wiring, DB, migrations, startup; footprint drift-fixes.
|
||||
- `coordination-primitive.md` — PL-004 Phase A queue/stream/inbox/outbox
|
||||
events.
|
||||
- `workflow-runtime.md` — PL-004 Phase D `workflow.*` events.
|
||||
- `mission-control.md` — PL-005 `mission_control.*` events.
|
||||
- Source roots: `packages/daemon/src/domain/types.ts` (RigEvent union),
|
||||
`packages/daemon/src/routes/{stream,queue}.ts` (SSE watch),
|
||||
`packages/daemon/src/server.ts` (`/api/events`).
|
||||
@@ -1,320 +0,0 @@
|
||||
---
|
||||
kind: as-built
|
||||
title: Content Surfaces — Files Browser, Atomic Write, Progress Tree, Steering Composer
|
||||
status: active
|
||||
topics: [observability, specification-and-bundles]
|
||||
domains: [engineering-advisor, operating-advisor]
|
||||
applies-when: |
|
||||
Need to know how the operator-allowlisted file browser enforces path
|
||||
safety, how atomic conflict-checked writes + the JSONL edit audit work,
|
||||
how the workspace PROGRESS.md tree is indexed, or how the one-screen
|
||||
Steering surface (priority stack + roadmap rail + lane rails + health
|
||||
gates) is composed. Author-mode module — no prior architecture.md prose;
|
||||
every load-bearing claim is sourced to file:line at HEAD.
|
||||
siblings: [workspace-primitive.md, daemon-core.md, ../ui/project-and-for-you.md]
|
||||
prerequisite-reads: [../README.md, workspace-primitive.md]
|
||||
last-verified-against-source: 7eaf524c
|
||||
last-updated: 2026-05-16
|
||||
---
|
||||
|
||||
# Content Surfaces — Files Browser, Atomic Write, Progress Tree, Steering Composer
|
||||
|
||||
> **See also (v0.4.4):** the Living Notes review surface — the composed
|
||||
> intent→plan→delivered projection over this same allowlisted content layer —
|
||||
> is documented in [`living-notes-review.md`](living-notes-review.md).
|
||||
|
||||
|
||||
The **content surfaces** are the operator-allowlisted, filesystem-canonical
|
||||
read/write layer that the Project / Steering UI sits on: a fail-closed file
|
||||
browser, an atomic conflict-checked write service with a JSONL edit audit,
|
||||
the recursive PROGRESS.md tree indexer, and the one-screen Steering composer
|
||||
(+ its compact health-summary gates). None adds SQLite state.
|
||||
|
||||
> **AUTHOR-FROM-SOURCE module.** No prior `architecture.md` prose exists for
|
||||
> this. Every load-bearing claim carries `> Source: <file:line> @HEAD`;
|
||||
> ambiguity is declared as an OPEN item, never smoothed. Paths are relative
|
||||
> to `packages/daemon/src/` unless prefixed `packages/` or `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).
|
||||
>
|
||||
> **SPLIT NOTE (§10.6).** This is the content-surfaces half of the
|
||||
> `workspace-and-content-primitives` SPLIT (sibling `workspace-primitive.md`
|
||||
> carries the workspace primitive + migrations 038/039 +
|
||||
> missions/projects/slices). See `workspace-primitive.md` § header SPLIT
|
||||
> NOTE for the §10.6 rationale and the transparent-noted-deviation
|
||||
> disclosure.
|
||||
|
||||
## 0. Release attribution (forensic proof — read first)
|
||||
|
||||
Per §10.8, re-verified at HEAD via `git cat-file -e <tag>:<path>`:
|
||||
|
||||
| Subsystem | Release | Forensic proof @HEAD |
|
||||
|---|---|---|
|
||||
| `domain/files/{path-safety,file-write-service}.ts` | **≤0.3.0** | `v0.3.0:<path>` → present |
|
||||
| `domain/progress/progress-indexer.ts` | **≤0.3.0** | `v0.3.0:<path>` → present |
|
||||
| `domain/steering/{steering-composer,health-summary}.ts` | **≤0.3.0** | `v0.3.0:<path>` → present |
|
||||
| `routes/{files,progress,steering,health-summary}.ts` | **≤0.3.0** | `v0.3.0:<path>` → present |
|
||||
|
||||
> Source: §10.8 proof re-run at HEAD `7eaf524c` — every listed path
|
||||
> resolves at `v0.3.0` (no failures). All content surfaces are
|
||||
> **≤0.3.0** features (UI Enhancement Pack v0 + Operator Surface
|
||||
> Reconciliation v0; slice-00 0.3.0-GT §1.7 "Files / Markdown /
|
||||
> Progress / Proofs" confirms the cluster shipped 0.3.0). Do **not**
|
||||
> back-attribute any of these to 0.3.1 — the gap is missing
|
||||
> architecture.md prose, not a new feature.
|
||||
|
||||
## 1. Path safety — the fail-closed allowlist (UI Enhancement Pack v0)
|
||||
|
||||
The file browser is gated by a daemon-enforced, **fail-closed** allowlist.
|
||||
Roots are decoded from `OPENRIG_FILES_ALLOWLIST` (env), comma-separated
|
||||
`<name>:<absolute-path>` pairs (legacy fallback `RIGGED_FILES_ALLOWLIST`
|
||||
via `||` so an empty string falls through). Invalid pairs (no colon, empty
|
||||
name, non-absolute path) are **silently skipped**; duplicate names →
|
||||
last-wins. Empty/unset → no roots → routes return an empty list with a
|
||||
structured "configure OPENRIG_FILES_ALLOWLIST" hint. The safe default after
|
||||
a fresh install is **nothing allowlisted**.
|
||||
|
||||
> Source: `domain/files/path-safety.ts:50-51` (env vars),
|
||||
> `:60-93` (`decodeAllowlist` / `readAllowlistFromEnv`; silent-skip
|
||||
> L67-71, last-wins L78, `||` fallback comment L89-91) @HEAD.
|
||||
|
||||
`resolveAllowedPath(allowlist, rootName, relativePath)` is the load-bearing
|
||||
guard. Algorithm: (1) reject unknown root (`root_unknown`); (2) reject
|
||||
expressed-intent `..` segments **before** filesystem resolution
|
||||
(`path_escape`) — segment-split so `foo..bar` is not a false positive;
|
||||
(3) reject an absolute `relativePath` (`path_invalid`); (4) resolve
|
||||
symlinks via `fs.realpathSync` and reject when the realpath does not start
|
||||
with `<canonicalRoot><sep>` (`path_escape`) — a `path.sep` boundary so
|
||||
`/foo/bar` does not match `/foo/bar-other`; (5) `path === ""` resolves to
|
||||
the root itself (so callers can list the root). Symlinks **inside** the
|
||||
tree resolve normally; symlinks pointing **outside** are escape attempts.
|
||||
A non-existent candidate falls back to the unresolved path so the
|
||||
subsequent stat surfaces the absence with a specific code.
|
||||
`resolveAllowedFile` / `resolveAllowedDirectory` add a stat assertion
|
||||
(`not_a_file` / `not_a_directory`).
|
||||
|
||||
> Source: `domain/files/path-safety.ts:95-171` (`resolveAllowedPath`;
|
||||
> `..`-before-fs L124-140, absolute-reject L141-147, sep-boundary
|
||||
> L158-169, empty-path base case in the doc-comment L108-110),
|
||||
> `:173-225` (file/dir convenience asserts) @HEAD.
|
||||
|
||||
## 2. Atomic write + JSONL audit (UI Enhancement Pack v0 item 4)
|
||||
|
||||
`FileWriteService.writeAtomic(req)` is the operator-actionable write surface
|
||||
for `STEERING.md` / `PROGRESS.md` / spec YAML / any allowlisted file.
|
||||
Sequence: (1) resolve target under allowlist (reuses §1 path-safety);
|
||||
(2) re-stat + re-hash the target — if `mtime !== expectedMtime` OR
|
||||
`contentHash !== expectedContentHash`, throw `WriteConflictError` carrying
|
||||
the **current** mtime + hash for the UI to surface (optimistic-concurrency,
|
||||
not a lock); (3) write to a temp file in the **same directory** (PID +
|
||||
random suffix so concurrent writes don't collide); (4) `fsync` the temp fd
|
||||
for durability before the rename; (5) atomic `renameSync` over the target
|
||||
(single inode swap on POSIX — readers see old or new, never partial);
|
||||
(6) recompute mtime + hash + byte delta; (7) append one JSONL audit row.
|
||||
|
||||
> Source: `domain/files/file-write-service.ts:9-25` (documented
|
||||
> atomic-write semantics), `:111-212` (`writeAtomic`; conflict-detect
|
||||
> L129-135, same-dir temp L137-141, fsync L146, atomic rename L161)
|
||||
> @HEAD.
|
||||
|
||||
The audit file is `~/.openrig/file-edit-audit.jsonl` by default
|
||||
(`HOME`/`USERPROFILE` → `/tmp` fallback). **Append-only; never rotates at
|
||||
v0.** A failed audit append throws `FileWriteError("audit_write_failed")`
|
||||
but does **NOT** undo the landed write — the user's edit succeeded; an
|
||||
audit-system flake must not silently revert canon. (The route still
|
||||
surfaces it as a 500 so the failure is honest, not swallowed.)
|
||||
|
||||
> Source: `domain/files/file-write-service.ts:87-91` (default path +
|
||||
> fallback), `:24-25` (never-rotates-at-v0), `:182-204` (audit append;
|
||||
> "does NOT undo the write" comment L183-184) @HEAD.
|
||||
|
||||
## 3. Files routes — browse + read + asset + write
|
||||
|
||||
`filesRoutes()` (mounted `server.ts:507` as `/api/files`). All routes are
|
||||
**literal** (no `/:param` catchall) so order doesn't matter for shadowing
|
||||
(Phase A R1 SSE lesson):
|
||||
|
||||
- `GET /roots` — allowlist root list (or `{roots:[], hint}` when none).
|
||||
- `GET /list?root&path` — directory entries (dirs first, then files,
|
||||
name-sorted; dotfiles always included — allowlisting a root expresses
|
||||
inspection intent).
|
||||
- `GET /read?root&path` — file content + `mtime` + `contentHash` (SHA-256)
|
||||
+ `size`. **Content is capped at `FILE_READ_TRUNCATION_BYTES` (1 MB)** but
|
||||
the hash is computed over the **FULL** file so atomic-write conflict
|
||||
detection stays honest even on a truncated read; response carries
|
||||
`truncated` / `truncatedAtBytes` / `totalBytes`.
|
||||
- `GET /asset?root&path` — raw bytes for embedded images/video/pdf (inferred
|
||||
`Content-Type`, 5-min cache). **v0.4.4 (OPR.0.4.4.20 FR-5):** serves HTTP
|
||||
**byte ranges** — single-range form, `206` + `Content-Range` +
|
||||
`Accept-Ranges: bytes` (malformed/unsatisfiable → `416`) — the
|
||||
iOS-Safari-class media-playback requirement; and `.html` renders as
|
||||
`text/html` ONLY under the explicit `?render=1` opt-in (text/plain stays
|
||||
the default). The slice proof-asset route (`/api/slices/:name/proof-asset/*`)
|
||||
carries the same range semantics (living-notes corrective). See
|
||||
[`living-notes-review.md`](living-notes-review.md) §5.
|
||||
- `POST /write` — atomic write (§2); 503 when no write service
|
||||
(`OPENRIG_FILES_ALLOWLIST` empty); 409 `write_conflict` on stale
|
||||
mtime/hash with the current values for the UI's refresh prompt.
|
||||
|
||||
503 `files_routes_unavailable` when the allowlist dep is unwired.
|
||||
Path-safety errors map to HTTP per code (`root_unknown`/`path_*` → 400,
|
||||
`stat_failed` → 404).
|
||||
|
||||
> Source: `routes/files.ts:51-242` (handlers; route-order comment
|
||||
> L17-19, truncation L139-154, write 503/409 L187-191/L225-231,
|
||||
> path-safety→HTTP `:61-69`); `FILE_READ_TRUNCATION_BYTES = 1_048_576`
|
||||
> `:49`; mounted `server.ts:507`; CLI: no `rig files` verb — files are
|
||||
> a UI-only surface @HEAD.
|
||||
|
||||
> **§10.7 route-reality (source-verified at `packages/ui/src/routes.tsx`):**
|
||||
> `/files` is a **REAL route** (`FilesWorkspace`) the Phase-8.1 survey
|
||||
> MISSED. There is **NO `/markdown` route** — markdown rendering is a
|
||||
> *component* inside file / drawer surfaces, not a navigable destination.
|
||||
>
|
||||
> Source: `packages/ui/src/routes.tsx:192-195` (`path: "/files"` +
|
||||
> `FilesWorkspace`); grep-confirmed no `path: "/markdown"` declaration
|
||||
> anywhere in routes.tsx @HEAD.
|
||||
|
||||
## 4. Progress tree indexer (UI Enhancement Pack v0 item 1B)
|
||||
|
||||
`ProgressIndexer` walks operator-allowlisted scan roots
|
||||
(`OPENRIG_PROGRESS_SCAN_ROOTS`, same `<name>:<abs-path>` shape as the file
|
||||
allowlist; legacy `RIGGED_PROGRESS_SCAN_ROOTS`), finds **`PROGRESS.md` AND
|
||||
`STEERING.md`** files (STEERING.md is anchored as the constraint-frame node
|
||||
per OSR v0 Item 2; the row-machinery is filename-agnostic), and parses each
|
||||
into a checkbox-hierarchy tree. Recursion is depth-bounded (default 6 —
|
||||
enough for mission/lane/slice nesting without descending into
|
||||
`node_modules`/`.git`/`.worktrees`/`dist`/`build`/`.turbo`/`.next` or
|
||||
dotfiles). Checkbox status: `[x]` → `done`, `[~]` → `blocked`, `[ ]` →
|
||||
`active`; headings (`##`–`####`) become hierarchy rows; depth from
|
||||
2-space indent or heading level. Per-file `counts` + a scan-wide
|
||||
`aggregate`. **In-memory walk per request; no caching at v0** (bounded by
|
||||
the operator's allowlist scope).
|
||||
|
||||
> Source: `domain/progress/progress-indexer.ts:79-84` (STEERING anchor +
|
||||
> env vars), `:81` (SKIP_DIRS), `:71` (`DEFAULT_MAX_DEPTH = 6`),
|
||||
> `:218-235` (checkbox status mapping), `:204-215` (heading rows),
|
||||
> `:21-23` (no-caching-at-v0) @HEAD.
|
||||
|
||||
`progressRoutes()` (mounted `server.ts:508` as `/api/progress`):
|
||||
`GET /tree` — the indexed hierarchy; 503 `progress_indexer_unavailable`
|
||||
when unwired; 503 `progress_scan_roots_not_configured` + setup hint when
|
||||
no roots.
|
||||
|
||||
> Source: `routes/progress.ts:18-40` (handler; 503s L29-35); mounted
|
||||
> `server.ts:508` @HEAD.
|
||||
|
||||
> **§10.7 route-reality:** `/progress` is a **`<Navigate to="/project" />`
|
||||
> redirect-stub** — the progress system lives at the daemon
|
||||
> `/api/progress` route, but the UI URL folds into Project tabs (Phase 3).
|
||||
>
|
||||
> Source: `packages/ui/src/routes.tsx:464-468` ("folds into Project tabs
|
||||
> (Phase 3) — redirect to /project") @HEAD.
|
||||
|
||||
## 5. Steering composer (Operator Surface Reconciliation v0 item 1)
|
||||
|
||||
`SteeringComposer.compose()` is the **one-screen composed steering surface**.
|
||||
It is deliberately narrow: it composes only the **filesystem-derived**
|
||||
pieces; the UI fetches PL-005 queue views (in-motion / loop-state) and
|
||||
health gates via their own existing endpoints so the composer stays
|
||||
testable. Three sources, all resolved from a single workspace root
|
||||
(`OPENRIG_STEERING_WORKSPACE`; per-piece overrides
|
||||
`OPENRIG_STEERING_PATH` / `OPENRIG_ROADMAP_PATH` /
|
||||
`OPENRIG_DELIVERY_READY_DIR` trump the root-derived defaults; legacy
|
||||
`RIGGED_STEERING_WORKSPACE`):
|
||||
|
||||
- **priorityStack** — verbatim `STEERING.md` content + mtime + byteCount.
|
||||
- **roadmapRail** — `roadmap/PROGRESS.md` checkbox rows; detects `PL-XXX`
|
||||
rail-item codes; marks the **first unchecked** item as `isNextUnchecked`.
|
||||
- **laneRails** — `delivery-ready/mode-{N}/PROGRESS.md` per-lane: reuses
|
||||
`ProgressIndexer` (maxDepth 3) for identical checkbox semantics to the
|
||||
Progress view; "next pull" = first non-done, non-blocked row (Priority
|
||||
Rail Rule — shelf/queue recency does NOT override); top-N (default 3)
|
||||
prefers active+blocked, falls back to done only to fill N.
|
||||
|
||||
Missing sources are reported in `unavailableSources` (each names the env
|
||||
var that would resolve it) rather than failing the whole payload.
|
||||
`isReady()` is true when **at least one** source resolves.
|
||||
|
||||
> Source: `domain/steering/steering-composer.ts:1-25` (narrow-by-design
|
||||
> rationale + 3-source list), `:103-119` (env vars +
|
||||
> `steeringOptsFromEnv`), `:155-169` (`isReady` / `compose`), `:198-250`
|
||||
> (roadmap rail; next-unchecked L231-235), `:282-316` (lane next-pull
|
||||
> L288-289, top-N L293-296), `RAIL_CODE_REGEX` `:346` @HEAD.
|
||||
|
||||
`steeringRoutes()` (mounted `server.ts:510` as `/api/steering`):
|
||||
`GET /` — the composed payload; 503 `steering_composer_unavailable` when
|
||||
unwired; 503 `steering_workspace_not_configured` + a hint pointing at
|
||||
`rig config init-workspace` / `workspace.steering_path` /
|
||||
`OPENRIG_STEERING_PATH` when no source resolves.
|
||||
|
||||
> Source: `routes/steering.ts:18-34` (handler; 503s L23-29); mounted
|
||||
> `server.ts:510` @HEAD.
|
||||
|
||||
> **§10.7 route-reality:** `/steering` is a **`<Navigate to="/project" />`
|
||||
> redirect-stub** — the composer lives at daemon `/api/steering`; the UI
|
||||
> URL folds into the Project workspace overview tab (Phase 3).
|
||||
>
|
||||
> Source: `packages/ui/src/routes.tsx:470-474` ("folds into Project
|
||||
> workspace overview tab (Phase 3) — redirect to /project") @HEAD.
|
||||
|
||||
## 6. Health-summary aggregator (OSR v0 item 1F)
|
||||
|
||||
`computeNodeHealthSummary` / `computeContextHealthSummary` are the compact
|
||||
health gates on the steering surface — **daemon-side aggregation, not a CLI
|
||||
shell-out** (no per-request subprocess). Node summary: cross-rig roll-up of
|
||||
`sessionStatus` + `lifecycleState` via `getNodeInventory` per rig, with an
|
||||
`attentionRequired` tally. Context summary: reads `context_usage` directly
|
||||
(ContextUsageStore exposes per-node accessors only; listing all rows is a
|
||||
steering-surface concern) and buckets by urgency
|
||||
(`usedPercentage` ≥80 critical / ≥60 warning / else low / null unknown) +
|
||||
freshness (`sampledAt` age vs 300 s → fresh/stale/none). A missing
|
||||
`context_usage` table (test harness without the migration) yields an empty
|
||||
summary, not an error.
|
||||
|
||||
> Source: `domain/steering/health-summary.ts:44-46` (thresholds:
|
||||
> `FRESHNESS_THRESHOLD_S=300`, `URGENCY_CRITICAL_PCT=80`,
|
||||
> `URGENCY_WARNING_PCT=60`), `:48-66` (node roll-up), `:75-117`
|
||||
> (context roll-up; table-absent → empty L81-84) @HEAD.
|
||||
|
||||
`healthSummaryRoutes()` (mounted `server.ts:511` as `/api/health-summary`):
|
||||
`GET /nodes`, `GET /context`; 503 `health_summary_unavailable` when the
|
||||
rigRepo dep is unwired.
|
||||
|
||||
> Source: `routes/health-summary.ts:23-44` (handlers; 503 L33,L40);
|
||||
> mounted `server.ts:511` @HEAD.
|
||||
|
||||
## 7. Cross-cutting properties
|
||||
|
||||
- **Filesystem-canonical, no new SQLite:** all four surfaces read/write the
|
||||
filesystem + the JSONL audit; health-summary reads existing
|
||||
`context_usage` only. No content-surface migration
|
||||
(`progress-indexer.ts:21-23`; `health-summary.ts:81-84`) @HEAD.
|
||||
- **Fail-closed, honest errors:** path-safety rejects every escape attempt
|
||||
before fs resolution; write conflicts surface the current mtime/hash for
|
||||
an explicit refresh; missing config returns 503 + a setup hint naming the
|
||||
exact env var — never a silent empty success
|
||||
(`path-safety.ts:124-169`; `file-write-service.ts:129-135`;
|
||||
`routes/steering.ts:25-29`) @HEAD.
|
||||
- **Atomic-or-nothing writes:** same-directory temp + fsync + atomic rename;
|
||||
a rename failure leaves the target untouched (never a partial write)
|
||||
(`file-write-service.ts:160-172`) @HEAD.
|
||||
- **Composer narrowness is deliberate:** the steering composer owns only
|
||||
filesystem-derived pieces; queue/health come from their own endpoints —
|
||||
keeps it testable (`steering-composer.ts:6-16`) @HEAD.
|
||||
|
||||
## OPEN items (carried, not smoothed)
|
||||
|
||||
- **OPEN-A** — the JSONL edit audit at `~/.openrig/file-edit-audit.jsonl`
|
||||
**never rotates at v0** by explicit design
|
||||
(`file-write-service.ts:24-25`); unbounded growth is a known accepted v0
|
||||
state (PRD § Item 4 defers rotation), stated here rather than smoothed.
|
||||
- **OPEN-B** — `OPENRIG_FILES_ALLOWLIST` vs `OPENRIG_PROGRESS_SCAN_ROOTS`
|
||||
vs `OPENRIG_STEERING_WORKSPACE` are three independent operator-config
|
||||
surfaces with the same encoding but separate resolution; there is no
|
||||
single "workspace allowlist" that unifies them at v0. Source-real;
|
||||
noted, not reconciled.
|
||||
- No slice-00 numeric-drift OPEN (1–5) applies — this module carries no
|
||||
migration-count / route-group / PL-004-event-count claim.
|
||||
@@ -1,242 +0,0 @@
|
||||
---
|
||||
kind: as-built
|
||||
title: Coordination Primitive — Stream/Queue/Inbox/Outbox (PL-004 Phase A)
|
||||
status: active
|
||||
topics: [coordination, observability]
|
||||
domains: [engineering-advisor, operating-advisor, orchestrator]
|
||||
applies-when: |
|
||||
Need to know how the daemon-backed coordination primitive works — the
|
||||
stream/queue/inbox/outbox tables, the hot-potato closure contract, the
|
||||
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: 7eaf524c
|
||||
last-updated: 2026-05-16
|
||||
---
|
||||
|
||||
# Coordination Primitive — Stream/Queue/Inbox/Outbox (PL-004 Phase A)
|
||||
|
||||
The PL-004 Phase A coordination primitive is the SQLite-canonical
|
||||
durable-work layer the daemon exposes through `/api/stream` and `/api/queue`.
|
||||
It replaces the POC filesystem `rigx queue` / `rigx stream` path for
|
||||
daemon-backed work; the POC filesystem path remains untouched and the daemon
|
||||
`rig queue` / `rig stream` write only to SQLite (`architecture.md` §5 L651).
|
||||
|
||||
> Verified against source at HEAD `7eaf524c`.
|
||||
|
||||
## 1. The five host-scoped tables
|
||||
|
||||
Five host-scoped tables back the primitive (`architecture.md` §3 L416–438;
|
||||
migrations re-confirmed at HEAD `packages/daemon/src/db/migrations/`):
|
||||
|
||||
- **`stream_items`** (`023_stream_items.ts`) — L1 append-only intake/audit
|
||||
root. Columns: `stream_item_id` (ULID PK), `ts_emitted`,
|
||||
`stream_sort_key`, `source_session`, `body`, `format` (default `text`),
|
||||
`hint_type`, `hint_urgency`, `hint_destination`, `hint_tags` (JSON),
|
||||
`interrupt`, `archived_at`. Items immutable after emit (only `archived_at`
|
||||
may be set).
|
||||
- **`queue_items`** (`024_queue_items.ts`) — L3 owned-work queue. `qitem_id`
|
||||
is TEXT PK preserving the POC `qitem-YYYYMMDDHHMMSS-<hex>` shape. State
|
||||
enum (8 values): `pending | in-progress | done | blocked | failed |
|
||||
denied | canceled | handed-off`. Carries `closure_reason`,
|
||||
`closure_target`, `closure_required_at`, `chain_of_record` (JSON),
|
||||
`blocked_on`, `handed_off_to`/`handed_off_from`, nudge/heartbeat fields.
|
||||
- **`queue_transitions`** (`025_queue_transitions.ts`) — L3 append-only
|
||||
transition log; authoritative audit trail for state evolution. No
|
||||
UPDATE/DELETE from domain code.
|
||||
- **`inbox_entries`** (`026_inbox_entries.ts`) — mailbox-style asynchronous
|
||||
deposit; idempotent on `inbox_id`. State: `pending | absorbed | denied`.
|
||||
- **`outbox_entries`** (`027_outbox_entries.ts`) — sender-side audit;
|
||||
symmetric to inbox; idempotent on `outbox_id`. Delivery state:
|
||||
`pending | delivered | failed`.
|
||||
|
||||
> Drift-fix D3 — `architecture.md` §3 L243 frames the schema as "27
|
||||
> migrations (22 existing plus 5 added by PL-004 Phase A)". The 5 PL-004
|
||||
> Phase A coordination tables (`023`–`027`) are still correct as a *range*,
|
||||
> but the headline migration count is **40**, not 27 (slice-00 §1.3,
|
||||
> re-confirmed at HEAD: `startup.ts:206` 40-element `migrate()` array; full
|
||||
> drift-fix authority and the correction live in `daemon-core.md`).
|
||||
|
||||
## 2. The six host-scoped services
|
||||
|
||||
Six host-scoped domain services implement the layer (`architecture.md` §5
|
||||
L649–658; files re-confirmed in `packages/daemon/src/domain/` at HEAD).
|
||||
Routes import these; services are Hono-free:
|
||||
|
||||
- **`stream-store.ts`** — L1 stream: idempotent emit (on `stream_item_id`),
|
||||
chronological list with cursor pagination plus source, destination, exact-tag,
|
||||
and inclusive time-window filters, soft archive. `direction=latest` applies
|
||||
every filter before taking the newest bounded page, then returns that page
|
||||
chronologically.
|
||||
- **`queue-repository.ts`** — L3 queue: create, claim/unclaim, update
|
||||
(general state mutator with hot-potato strict-rejection on `done`),
|
||||
transactional handoff (close source as `handed-off` plus create new owned
|
||||
qitem in a single transaction), pod-fallback rerouting, overdue lookup,
|
||||
nudge/heartbeat tracking. Cross-rig validation hook exposed as
|
||||
`validateRig` constructor option.
|
||||
- **`queue-transition-log.ts`** — append-only state-transition log; used by
|
||||
`queue-repository.ts`, exposed read-only on
|
||||
`queue_repository.transitionLog`.
|
||||
- **`hot-potato-enforcer.ts`** — pure validator for the load-bearing API
|
||||
contract (see §3).
|
||||
- **`inbox-handler.ts`** — mailbox handler: authenticated drop (idempotent
|
||||
on `inbox_id`), absorb (promotes a pending entry to a `queue_item`,
|
||||
idempotent), deny (records reason). Auth check is a pluggable constructor
|
||||
hook.
|
||||
- **`outbox-handler.ts`** — sender-side outbox: idempotent record, mark
|
||||
delivered/failed, list. Emits no event-bus events (pure audit).
|
||||
|
||||
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. 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.
|
||||
|
||||
## 3. The hot-potato closure contract (where queue closure is enforced)
|
||||
|
||||
`hot-potato-enforcer.ts` is the pure validator for the load-bearing API
|
||||
contract. Re-confirmed at HEAD (`hot-potato-enforcer.ts:10–24`):
|
||||
|
||||
`state=done` requires `closure_reason ∈ {handed_off_to, blocked_on, denied,
|
||||
canceled, no-follow-on, escalation}`. The reasons
|
||||
`handed_off_to | blocked_on | escalation` additionally require
|
||||
`closure_target`:
|
||||
|
||||
- `handed_off_to` — work continues with a different seat (`closure_target` =
|
||||
new owner).
|
||||
- `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.
|
||||
- `escalation` — kicked up to a higher tier (`closure_target` = escalation
|
||||
target).
|
||||
|
||||
Tier→SLA mapping for `closure_required_at` also lives in
|
||||
`hot-potato-enforcer.ts`. This validator is invoked by
|
||||
`QueueRepository.update()` (and `updateWithinTransaction()`), so closure is
|
||||
enforced at the daemon transaction boundary — the workflow runtime
|
||||
*projects* on closure but does not gate it (see `workflow-runtime.md`).
|
||||
|
||||
## 3b. Cross-host queue routing (v0.4.6 — OPR.0.4.6.MH3)
|
||||
|
||||
The queue's two coordination WRITE verbs — **create + handoff(-and-complete)
|
||||
only** — are host-aware: a write body may carry an out-of-band `hostId`
|
||||
envelope (BR-1 — session strings stay `member@rig` everywhere; the 3-part
|
||||
`agent@rig@host` form is CLI input sugar that never leaves the CLI edge).
|
||||
The mechanism **generalizes the shipped mission-control forward-then-strip
|
||||
WRITE template** (`routes/mission-control.ts` § remote action): one shared
|
||||
route-layer helper (`forwardQueueWrite`, `routes/queue.ts`) resolves the
|
||||
host registry daemon-side (bearers never reach the caller), rejects
|
||||
ssh-declared hosts (`unsupported-transport` — the daemon→daemon path is
|
||||
http-only, because it is what fires the remote nudge), strips `hostId`, and
|
||||
forwards the WHOLE body via `remoteJsonRequest` under a named write-class
|
||||
deadline (`QUEUE_FORWARD_TIMEOUT_MS`). The origin's response returns
|
||||
verbatim; transport failures map to a structured host-named taxonomy
|
||||
(`remote_queue_write_failed`: unknown-host / unsupported-transport /
|
||||
unreachable / auth-failed / remote-error). No local row is ever written on
|
||||
the cross-host path.
|
||||
|
||||
**The model: origin-owns-the-record, at-least-once + idempotent,
|
||||
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's OWN `maybeNudge` fires on ITS local
|
||||
tmux (the forwarded body includes the `nudge` flag) — the sending daemon
|
||||
never reaches across a host boundary.
|
||||
- **Idempotency (arch Q-a).** The forwarding daemon MINTS the `qitemId`
|
||||
before the first forward, so every retry carries the same id; dedup rides
|
||||
the existing `qitem_id TEXT PRIMARY KEY`. On PK conflict the origin
|
||||
returns the stored row when identity fields match (idempotent absorb) and
|
||||
a structured `qitem_id_reuse` error when they differ
|
||||
(`QueueRepository.create()` catch-path + `isQitemPrimaryKeyConflict`).
|
||||
- **Cross-host handoff choreography (arch Q-c).** The local atomic
|
||||
close+create cannot span two DBs, so the route-layer choreography
|
||||
(`crossHostHandoff`, `routes/queue.ts`) runs: successor-create on the
|
||||
target host FIRST (via the one forward helper), local source-close SECOND
|
||||
(`QueueRepository.closeCrossHostHandoffSource`) — 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)` →
|
||||
`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. *(Named residual, inherent to the at-least-once/no-2PC fence: a
|
||||
re-drive naming a DIFFERENT destination derives a different id and cannot
|
||||
absorb the earlier successor — that orphan stays visible via the chain +
|
||||
provenance tags; the source-close conflict check surfaces the
|
||||
disagreement.)*
|
||||
- **Closure across the boundary.** The source closes with
|
||||
`closure_reason=handed_off_to` and `closure_target=member@rig@<host>` —
|
||||
the 3-part form is legal THERE because `closure_target` is OPAQUE
|
||||
audit/display metadata, presence-checked and never parsed for routing
|
||||
(arch R1; any PR parsing it as a session string is a spec violation).
|
||||
The exemption spans exactly the `closure_target` column on `queue_items`
|
||||
and its verbatim mirror on `queue_transitions` — nothing else. In
|
||||
particular the transition log's free-text `transition_note` is a durable
|
||||
carrier too: the minted cross-host close note names the 2-part
|
||||
`toSession` only (rev1-r2 B1). `handed_off_to` and every other
|
||||
session-string carrier stay 2-part.
|
||||
Re-drive semantics: already-terminal + MATCHING `closure_target` = absorb;
|
||||
MISMATCH = structured `cross_host_close_conflict` (409). The successor
|
||||
carries `chain_of_record = [...source.chain, source.qitemId]` — A-side ids
|
||||
are opaque lineage identifiers on B (arch R2b; they do not dereference in
|
||||
B's DB) — plus provenance tags `cross-host` + `from-host:<self-declared
|
||||
name>` (honest best-effort, not authenticated identity).
|
||||
- **Boundary discipline.** Claim / update / inbox stay local-by-principle
|
||||
(after a cross-host handoff the successor lives where its worker lives);
|
||||
sender-side ops on a forwarded item are a named follow-up. The local
|
||||
(no-host) paths are byte-identical to pre-MH-3 behavior; the hot-potato
|
||||
validation contract (§3) is unweakened across the boundary.
|
||||
|
||||
## 4. Coordination events
|
||||
|
||||
> Drift-fix D8 / OPEN-4 (carried verbatim, slice-00): `architecture.md`
|
||||
> §3 L394 says "Existing 32 PL-004 events untouched" and L410 says "Existing
|
||||
> 20 PL-004 events are unchanged" — these two body claims are internally
|
||||
> inconsistent with each other and predate 0.3.x. **Do NOT carry either
|
||||
> number.** The current `RigEvent` union (`packages/daemon/src/domain/types.ts:94`)
|
||||
> has **73 union members** total (slice-00 §1.8, re-confirmed at HEAD:
|
||||
> `grep -cE '^\s*\| \{ type: ' = 73`). A precise PL-004-only vs PL-005-only
|
||||
> sub-partition is not reconcilable from static inspection without
|
||||
> classifying all 73 members by introducing slice; slice-00 OPEN-4 flags
|
||||
> this and it is carried, not smoothed.
|
||||
|
||||
Coordination events emitted by these services (re-confirmed in
|
||||
`domain/types.ts` at HEAD): `stream.emitted` (StreamStore.emit,
|
||||
`types.ts:155`); `queue.created` / `queue.handed_off` / `queue.claimed` /
|
||||
`queue.unclaimed` / `qitem.fallback_routed` / `qitem.closure_overdue`
|
||||
(QueueRepository); `inbox.absorbed` (`types.ts:162`) / `inbox.denied`
|
||||
(InboxHandler). `architecture.md` §8 L987–990 listed these as "9
|
||||
coordination events"; the count of the broader `stream|queue|inbox|qitem`
|
||||
event family at HEAD is 10 (`stream` 1 + `queue` 5 + `inbox` 2 + `qitem` 2)
|
||||
— stated as a re-derived family count, not as a contested PL-004 sub-count
|
||||
(OPEN-4).
|
||||
|
||||
Two SSE surfaces stream coordination events: `/api/stream/watch`
|
||||
(aliased `/api/stream/sse`, `routes/stream.ts:117–118`) for new stream
|
||||
items, and `/api/queue/watch` for queue/inbox events. The event log remains
|
||||
append-only and SQLite-backed. `rig stream watch` is a thin, single-connection
|
||||
consumer of `/api/stream/sse`; it does not add a daemon route or reconnect
|
||||
policy.
|
||||
|
||||
## 5. Route surface
|
||||
|
||||
- `/api/stream` (`server.ts:489`) — `POST /emit` (`routes/stream.ts:24`),
|
||||
`GET /list` (`:56`, including `sourceSession`, `hintDestination`, `hintTag`,
|
||||
`since`, and `until` filters), `GET /watch` + `/sse` SSE (`:117`),
|
||||
`GET /:streamItemId` (`:121`), `POST /:streamItemId/archive` (`:130`).
|
||||
- `/api/queue` (`server.ts:490`) — `POST /create` (`routes/queue.ts:99`),
|
||||
`POST /:qitemId/claim` (`:144`), `POST /:qitemId/unclaim` (`:157`),
|
||||
`POST /:qitemId/update` (`:170`), plus handoff/list/watch surfaces.
|
||||
|
||||
## See also
|
||||
|
||||
- `daemon-core.md` — daemon wiring, the 40-migration set, route surface.
|
||||
- `workflow-runtime.md` — PL-004 Phase D runtime that projects on closure.
|
||||
- `mission-control.md` — PL-005 queue observability over `queue_items`.
|
||||
- Source roots: `packages/daemon/src/domain/{stream-store,queue-repository,
|
||||
queue-transition-log,hot-potato-enforcer,inbox-handler,outbox-handler}.ts`,
|
||||
`packages/daemon/src/routes/{stream,queue}.ts`.
|
||||
@@ -1,260 +0,0 @@
|
||||
---
|
||||
kind: as-built
|
||||
title: Daemon Core — Wiring, DB, Migrations, Startup
|
||||
status: active
|
||||
topics: [runtime-control, observability]
|
||||
domains: [engineering-advisor, operating-advisor]
|
||||
applies-when: |
|
||||
Need to know how the daemon boots, how createDaemon wires the dependency
|
||||
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: 7eaf524c
|
||||
last-updated: 2026-05-16
|
||||
---
|
||||
|
||||
# Daemon Core — Wiring, DB, Migrations, Startup
|
||||
|
||||
OpenRig is a local control plane for multi-agent coding topologies. The daemon
|
||||
(`@openrig/daemon`) is the framework-free SQLite-backed core that the CLI
|
||||
(`@openrig/cli`), UI (`@openrig/ui`), and MCP server all sit on top of.
|
||||
|
||||
> Verified against source at HEAD `7eaf524c` (`git describe` →
|
||||
> `v0.3.1-6-g7eaf524c`). Current package version is **0.3.1** across all three
|
||||
> packages (`package.json` root `"version": "0.3.1"`; slice-00 §1.1). HEAD
|
||||
> carries 6 commits of unreleased release-0.3.2 work; no `v0.3.2` tag exists.
|
||||
|
||||
## 1. System overview
|
||||
|
||||
The system has six architectural layers (`architecture.md` §1 L23–30):
|
||||
|
||||
1. **AgentSpec / pod-aware core** — spec parsing, resolution, precedence,
|
||||
startup orchestration, snapshot/restore, bundles.
|
||||
2. **Operator and topology layer** — harness auto-launch, node inventory,
|
||||
session naming, infrastructure nodes, explorer UI, existing-rig power-on,
|
||||
auto-snapshot, post-command handoff.
|
||||
3. **Communication and history layer** — transcript capture (pipe-pane),
|
||||
communication primitives (send/capture/broadcast), config/preflight,
|
||||
`rig ask` context packs, durable rig chat.
|
||||
4. **Authoring and identity layer** — spec review + spec library, `whoami`,
|
||||
adopted-session tmux-metadata parity, bind/materialize/adopt workflows.
|
||||
5. **Rig environment layer** — rig-scoped services records, Compose-backed
|
||||
service orchestration, readiness gates, env snapshot/restore integration.
|
||||
6. **Agent-managed software layer** — managed-app classification, app-focused
|
||||
browse/review/runtime UI, and the canonical `secrets-manager` example.
|
||||
|
||||
Legacy flat-node/package flows remain for backward compatibility.
|
||||
|
||||
### Verified source footprint at HEAD `7eaf524c`
|
||||
|
||||
> Drift-fix D1/D6 — `architecture.md` L6,11 said `OpenRig v0.2.0` /
|
||||
> "Current v0.2.0 release verification" and L7 said `376` source files. Both
|
||||
> are a frozen pre-v0.2.0-era header (slice-00 §1.9 — last edited `72982bb2`,
|
||||
> 2026-03-30). Corrected to the values below.
|
||||
|
||||
| Metric | Value @ HEAD | Source (independently re-confirmed) |
|
||||
|---|---|---|
|
||||
| Package version | **0.3.1** (HEAD +6 unreleased 0.3.2 commits) | slice-00 §1.1; `package.json:version` |
|
||||
| Total source footprint | **601** files | slice-00 §1.6; `find packages/*/src` non-test = 279+87+235 |
|
||||
| Daemon footprint | **279** total / **173** domain / **49** route mounts (46 route files) / **11** adapters / **40** migrations | slice-00 §1.5/§1.6; `find packages/daemon/src` non-test |
|
||||
| CLI footprint | **87** files | slice-00 §1.6; `find packages/cli/src` non-test |
|
||||
| UI footprint | **235** files | slice-00 §1.6; `find packages/ui/src` `.ts`+`.tsx` non-test |
|
||||
|
||||
> Footprint counts use the `find packages/*/src -type f \( -name '*.ts' -o
|
||||
> -name '*.tsx' \) ! -name '*.test.*'` predicate (tests live in separate
|
||||
> `packages/*/test/` dirs). Counts are reproducible with that predicate; a
|
||||
> different counting convention shifts absolute numbers (slice-00 OPEN-5).
|
||||
|
||||
### The stack
|
||||
|
||||
> Drift-fix D2 — `architecture.md` L37,125 said `CLI (53 command groups)`.
|
||||
> Corrected to **58** at HEAD (slice-00 §1.2: 53 at v0.2.0 tag, 56 at v0.3.0,
|
||||
> 57 at v0.3.1, **58 at HEAD** — the 58th is `scopeCommand()` added post-0.3.1
|
||||
> by `0b77cba4`, re-confirmed `index.ts:20,187`).
|
||||
>
|
||||
> Drift-fix D4 — `architecture.md` L40 said `31 route groups` and L76 said
|
||||
> "`createApp()` now mounts 22 route groups". Corrected to **49 `app.route()`
|
||||
> mounts + 4 dedicated handlers** (slice-00 §1.5; re-confirmed `server.ts`
|
||||
> 49×`app.route(` L450–513, plus `app.get("/healthz")` :446,
|
||||
> `handleExportYaml` :461, `handleExportJson` :462, `app.get("*")` :519).
|
||||
> Carry slice-00 **OPEN-2**: "route-group count is definitional" — there is
|
||||
> no single canonical "route group" definition in source; reported as mount
|
||||
> count + dedicated handlers.
|
||||
>
|
||||
> Drift-fix D3 — `architecture.md` L54 said `SQLite state (36 migrations)`.
|
||||
> Corrected to **40** (slice-00 §1.3; re-confirmed below).
|
||||
|
||||
```text
|
||||
CLI (58 command groups) / UI (explorer + workspace + drawer) / MCP (17 tools)
|
||||
|
|
||||
v
|
||||
Hono daemon routes (49 app.route() mounts + 4 dedicated health/export/static handlers)
|
||||
|
|
||||
+-- dual-format route adapters (legacy v1 + rebooted v0.2)
|
||||
+-- env routes (status / logs / down)
|
||||
+-- transport routes (send/capture/broadcast)
|
||||
+-- transcript routes (tail/grep)
|
||||
+-- ask routes (context evidence packs)
|
||||
+-- chat routes (durable rig messaging + SSE)
|
||||
+-- spec review/library routes (managed-app enrichment + compose preview)
|
||||
+-- whoami identity + context-usage route
|
||||
+-- coordination routes (stream / queue / workflow / mission-control)
|
||||
|
|
||||
v
|
||||
Framework-free domain services (173 daemon domain files)
|
||||
|
|
||||
+-- SQLite state (40 migrations)
|
||||
+-- tmux / cmux / resume adapters
|
||||
+-- runtime adapters (Claude Code / Codex / Terminal)
|
||||
+-- RigEnv substrate (compose adapter, readiness, orchestrator)
|
||||
+-- transport / transcript / chat / ask layers
|
||||
+-- whoami identity service
|
||||
```
|
||||
|
||||
The core product loop: `down (auto-snapshot) → up <rig-name> (auto-restore) →
|
||||
handoff → inspect/attach → work → repeat`.
|
||||
|
||||
> MCP tool count is **17** (`rig_*`) — slice-00 §1.4 confirms the count is
|
||||
> correct and the names are `rig_*` (NOT `rigged_*`; the `rigged_*` text in
|
||||
> `architecture.md` §2 is stale — the rename predates v0.2.0). Per-occurrence
|
||||
> verification of any `rigged_*` reference lands in `transport-and-transcripts.md`
|
||||
> (D5); the tmux `@rigged_*` metadata keys are a separate axis, not blanket-replaced.
|
||||
|
||||
## 2. Database schema
|
||||
|
||||
> Drift-fix D3 — `architecture.md` L243 said "27 migrations (22 existing plus
|
||||
> 5 added by PL-004 Phase A)" and L1002 repeated "27 migrations"; the §1 stack
|
||||
> diagram L54 said "36 migrations". All corrected to **40** migrations
|
||||
> (`001`–`040`). Triangulated (slice-00 §1.3, re-confirmed at HEAD): (1)
|
||||
> filesystem `packages/daemon/src/db/migrations/[0-9][0-9][0-9]_*.ts` → 40
|
||||
> files, `001_core_schema.ts` … `040_workflow_specs_diagnostic.ts`; (2)
|
||||
> `startup.ts:206` `migrate(db, [...])` passes a 40-element schema array
|
||||
> (`coreSchema` … `workflowSpecsDiagnosticSchema`); (3) `migrate.ts:13`
|
||||
> applies them sorted by name, tracked in `schema_migrations`.
|
||||
|
||||
### Core state tables (`001_core_schema.ts`)
|
||||
|
||||
`rigs` (topology container, `001_core_schema.ts:7`), `nodes` (logical node
|
||||
identity, `:17`), `edges` (logical topology relationships, `:30`), plus
|
||||
`bindings` (physical tmux/cmux surface attachment), `sessions` (live execution
|
||||
state), `events` (append-only event log), `snapshots` (serialized rig state),
|
||||
`checkpoints` (per-node recovery state). `architecture.md` §3 L247–289.
|
||||
|
||||
### Reboot-era schema
|
||||
|
||||
- `014_agentspec_reboot.ts` — reboot schema shape; adds `pods`,
|
||||
`continuity_state`, and reboot columns on `nodes`/`sessions`/`checkpoints`
|
||||
(`pod_id`, `agent_ref`, `resolved_spec_*`, `startup_status`,
|
||||
`continuity_source`). `architecture.md` §3 L253–289.
|
||||
- `015_startup_context.ts` — persisted startup replay context for restore.
|
||||
- `016_chat_messages.ts` — durable rig-scoped chat (SQLite-backed; transcripts
|
||||
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.
|
||||
- `020_rig_services.ts` — rig-scoped environment record for service-backed rigs.
|
||||
- `021_seat_handover_observability.ts`, `022_node_codex_config_profile.ts`.
|
||||
|
||||
### Coordination / PL-004 / PL-005 / workspace migrations
|
||||
|
||||
- `023_stream_items.ts` … `027_outbox_entries.ts` — PL-004 Phase A
|
||||
coordination tables (detail in `coordination-primitive.md`).
|
||||
- `028_project_classifications.ts`, `029_classifier_leases.ts`,
|
||||
`030_views_custom.ts` — PL-004 Phase B classifier + view tables. (Note:
|
||||
`architecture.md` L361 said "028 through 030"; the middle migration is
|
||||
literally `029_classifier_leases.ts` — re-confirmed at HEAD.)
|
||||
- `031_watchdog_jobs.ts`, `032_watchdog_history.ts` — PL-004 Phase C watchdog.
|
||||
- `033_workflow_specs.ts`, `034_workflow_instances.ts`,
|
||||
`035_workflow_step_trails.ts` — PL-004 Phase D Workflow Runtime tables
|
||||
(detail in `workflow-runtime.md`). `036_watchdog_policy_enum_extension.ts`
|
||||
is a documenting no-op.
|
||||
- `037_mission_control_actions.ts` — PL-005 Phase A audit table
|
||||
(`037_mission_control_actions.ts:54` `CREATE TABLE … mission_control_actions`;
|
||||
detail in `mission-control.md`).
|
||||
- `038_workspace_primitive.ts`, `039_queue_target_repo.ts` — PL-007 typed
|
||||
workspace primitive (`bab24bf7`).
|
||||
- `040_workflow_specs_diagnostic.ts` — slice-11 (`f68f453a`); an
|
||||
`ALTER TABLE ADD COLUMN` adding parser/validator diagnostic columns to
|
||||
`workflow_specs` (no new table). **Net-new since `architecture.md` was last
|
||||
edited** — slice-00 §1.3 provenance; carried into `workflow-runtime.md`.
|
||||
|
||||
Legacy package/bootstrap/discovery tables (`packages`, `package_installs`,
|
||||
`install_journal`, `bootstrap_runs`, `bootstrap_actions`,
|
||||
`runtime_verifications`, `discovered_sessions`) remain active.
|
||||
|
||||
## 3. Route-mount surface
|
||||
|
||||
`createApp(deps)` (`packages/daemon/src/server.ts:295`) mounts **49**
|
||||
`app.route()` route-group mounts (`server.ts` L450–513) plus 4 dedicated
|
||||
non-route handlers: `GET /healthz` (`:446`), `GET /api/rigs/:rigId/spec`
|
||||
(`handleExportYaml`, `:461`), `GET /api/rigs/:rigId/spec.json`
|
||||
(`handleExportJson`, `:462`), and the static/deep-link `app.get("*")`
|
||||
catch-all (`:519`).
|
||||
|
||||
> OPEN-2 (carried verbatim, slice-00): the route-group "count" is definitional
|
||||
> — "49" is the count of `app.route()` mounts in `server.ts`. The older
|
||||
> "31 route groups" / "createApp now mounts 22 route groups" framing
|
||||
> (`architecture.md` L40,76) used a different, smaller accounting. Independent
|
||||
> corroboration: `packages/daemon/src/routes/` has 46 non-test route `.ts`
|
||||
> files (some groups composed from shared modules; the 49 mounts are the
|
||||
> authoritative count of mounted groups — slice-00 §1.5).
|
||||
|
||||
Mount families include reboot-era rig/session/spec routes plus the coordination
|
||||
routes (`/api/stream` `server.ts:489`, `/api/queue` `:490`,
|
||||
`/api/workflow` `:495`, `missionControlRoutes(...)` `:498`),
|
||||
`/api/health-summary` (`:511`), `/api/rigs/:rigId/env` (`:512`), and
|
||||
`/api/restore-check` (`:513`).
|
||||
|
||||
## 4. Startup sequence (`createDaemon`)
|
||||
|
||||
`createDaemon(opts?)` is `packages/daemon/src/startup.ts:203` (async,
|
||||
returns `DaemonResult`). It returns `{ app, db, deps, contextMonitor }`
|
||||
(`startup.ts:1204`). The sequence (`architecture.md` §9 L1000–1028,
|
||||
corrected against source):
|
||||
|
||||
1. Open SQLite and run **all 40 migrations** (`startup.ts:206`
|
||||
`migrate(db, [coreSchema … workflowSpecsDiagnosticSchema])` — a 40-element
|
||||
array; `architecture.md` L1002 said "27 migrations (22 existing plus the 5
|
||||
PL-004 Phase A coordination tables)" — corrected to 40, drift-fix D3).
|
||||
2. Construct core repositories and legacy services.
|
||||
3. Construct package/bootstrap/discovery services.
|
||||
4. Construct rebooted startup/runtime services: `StartupOrchestrator`,
|
||||
`ClaudeCodeAdapter`, `CodexRuntimeAdapter`, `TerminalAdapter`,
|
||||
`PodRigInstantiator`, `PodBundleSourceResolver`.
|
||||
5. Construct rig environment services: `ComposeServicesAdapter`,
|
||||
`ServiceOrchestrator`.
|
||||
6. Construct operator/transport/history services: `TranscriptStore`,
|
||||
`SessionTransport`, `ChatRepository`, `AskService` (with `HistoryQuery`),
|
||||
`ResumeMetadataRefresher`, `ContextUsageStore`, `ContextMonitor`,
|
||||
`NodeInventory`.
|
||||
7. Construct authoring/identity/managed-app services: `SpecReviewService`,
|
||||
`SpecLibraryService`, `WhoamiService`.
|
||||
8. Construct `BootstrapOrchestrator` with both legacy and rebooted seams.
|
||||
9. Construct PL-004 Phase A coordination services from a shared
|
||||
`QueueRepository` instance (so `InboxHandler.absorb()` and `/api/queue`
|
||||
write to the same repo): `StreamStore`, `QueueRepository`, `InboxHandler`,
|
||||
`OutboxHandler`.
|
||||
10. Build `AppDeps`, enforce shared-DB invariants, and call
|
||||
`createApp(deps)` (`startup.ts:1202`) to mount the full route tree.
|
||||
|
||||
The daemon entrypoint `packages/daemon/src/index.ts:36` calls
|
||||
`createDaemon({ dbPath, bearerToken })`.
|
||||
|
||||
## 5. Test and verification state
|
||||
|
||||
> Drift-fix D7 / OPEN-3 (carried verbatim, slice-00): `architecture.md` L12,13
|
||||
> and §10 L1036–1046 assert daemon `2561/2561` / CLI `794/794` / total
|
||||
> `2422/2422` test pass counts and per-package file counts (`127`/`37`/`37`).
|
||||
> **These are runtime claims and are NOT re-run here** — a read-only static
|
||||
> trace counted `*.test.ts` files only: daemon **255**, cli **234**
|
||||
> (slice-00 §1.7; ui test-file count not separately gathered). Pass tallies
|
||||
> are marked `unverified-runtime-claim`; do not assert them as current. To
|
||||
> assert pass counts, run `pnpm/npm test` and re-verify.
|
||||
|
||||
## See also
|
||||
|
||||
- `coordination-primitive.md` — PL-004 Phase A stream/queue/inbox/outbox.
|
||||
- `agent-spec-and-startup.md` — spec parsing/resolution/startup contract.
|
||||
- `lifecycle-snapshot-restore.md` — snapshot/restore/continuity.
|
||||
- Source roots: `packages/daemon/src/{startup.ts,server.ts,index.ts}`,
|
||||
`packages/daemon/src/db/migrations/`, `packages/cli/src/index.ts`.
|
||||
@@ -1,214 +0,0 @@
|
||||
---
|
||||
kind: as-built
|
||||
title: Lifecycle — Snapshot, Restore, Continuity
|
||||
status: active
|
||||
topics: [continuity, runtime-control]
|
||||
domains: [engineering-advisor, operating-advisor]
|
||||
applies-when: |
|
||||
Need to know how OpenRig captures a snapshot, restores a rig (resume vs
|
||||
rebuild vs fresh), enforces restore honesty, consults live continuity state,
|
||||
or how the daemon-side restore-check / restore-packet readiness probes 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: 7eaf524c
|
||||
last-updated: 2026-05-16
|
||||
---
|
||||
|
||||
# Lifecycle — Snapshot, Restore, Continuity
|
||||
|
||||
The durable-state half of the core product loop:
|
||||
`down (auto-snapshot) → up <rig-name> (auto-restore) → handoff`. Snapshot
|
||||
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 HEAD `7eaf524c` (`git describe` →
|
||||
> `v0.3.1-6-g7eaf524c`). Package version **0.3.1** (slice-00 §1.1). Source
|
||||
> located by `architecture.md` headings (§4 Execution and restore, §5
|
||||
> Snapshot/restore/continuity, §6 Snapshot/restore + Auto-snapshot, §7 rules)
|
||||
> per slice-08 §10.1 — line numbers advisory only. This module is a pure
|
||||
> split EXCEPT §6 (restore-check/restore-packet) which is the D15
|
||||
> author-from-source piece — flagged explicitly there.
|
||||
|
||||
## 1. Snapshot / restore / continuity types
|
||||
|
||||
(`architecture.md` §4 "Execution and restore" — spec/projection members live
|
||||
in `agent-spec-and-startup.md`; the snapshot/restore members live here)
|
||||
|
||||
- **NodeRestoreOutcome** — `"resumed" | "rebuilt" | "fresh" | "failed" |
|
||||
"n-a"` — the locked restore vocabulary. Re-confirmed at source:
|
||||
`restore-orchestrator.ts:725-726` sets `baseStatus = "resumed"` on a
|
||||
resumed harness; `:763` sets `"rebuilt"` when a checkpoint is replayed; the
|
||||
outcome union appears at `:944` (`{ kind: "resumed" }` … ).
|
||||
- **SnapshotData** — current serialized snapshot payload. Reboot extensions
|
||||
are optional for older-snapshot compatibility: `pods?`,
|
||||
`continuityStates?`, `nodeStartupContext?`.
|
||||
- **NodeStartupSnapshot** — persisted restore replay input:
|
||||
classification-free projection entries, resolved startup files, startup
|
||||
actions, runtime.
|
||||
- **PersistedProjectionEntry** — the classification-free restore replay seam:
|
||||
persists only entry identity + source metadata, NOT stale `classification`,
|
||||
`conflicts`, or `noOps` (Architecture Rule 10).
|
||||
|
||||
## 2. Snapshot, restore, continuity domain services
|
||||
|
||||
(`architecture.md` §5 "Snapshot, restore, and continuity")
|
||||
|
||||
- `checkpoint-store.ts` — checkpoint persistence with pod/continuity context.
|
||||
- `snapshot-capture.ts` — captures pods, continuity state, startup replay
|
||||
context, and latest env receipt. Re-confirmed: `snapshot-capture.ts:66-77`
|
||||
pulls `pods`, `continuity_state`, and `node_startup_context` rows per rig.
|
||||
- `snapshot-repository.ts` — snapshot CRUD.
|
||||
- `restore-orchestrator.ts` — resume, checkpoint delivery, startup replay,
|
||||
live continuity consultation, topology ordering, and RigEnv boot gating
|
||||
before agent restore.
|
||||
|
||||
## 3. Restore flow and restore honesty
|
||||
|
||||
(`architecture.md` §6 "Snapshot / restore" + §7 rules 7/14/15/16)
|
||||
|
||||
Restore behavior, each point re-confirmed at `restore-orchestrator.ts`:
|
||||
|
||||
- Reads the newest session by **monotonic ULID**, not timestamp alone
|
||||
(`:700` — "Find the NEWEST session for this node. ULIDs are monotonic, so
|
||||
latest = max id").
|
||||
- Consults live `continuity_state`; preserves state when a node is already
|
||||
`restoring` (`:611-615` — `SELECT status FROM continuity_state …`; if
|
||||
`status === "restoring"` the node is skipped with 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** (`:799` — status `"failed"`, error
|
||||
"Missing required startup files: …").
|
||||
- Writes a **transcript boundary marker before re-launch** (`:652` — "Write
|
||||
transcript boundary marker BEFORE launch (before pipe-pane attaches)").
|
||||
- Refuses to restore over live sessions (`:168` — `rig_not_stopped`: "Rig …
|
||||
has live sessions. Stop the rig with 'rig down' before restoring").
|
||||
- Uses `nativeResumeProbe` to honestly assess whether the harness actually
|
||||
resumed (`:857` continuity-outcome reconciliation).
|
||||
|
||||
**Restore-honesty rules (carried verbatim, `architecture.md` §7):**
|
||||
|
||||
- Rule 7 — restore-policy narrowing is one-way only:
|
||||
`resume_if_possible` → `relaunch_fresh` → `checkpoint_only`.
|
||||
- Rule 14 — resume states are locked: `resumed` / `rebuilt` / `fresh`.
|
||||
`rebuilt` = new process assembled from artifacts.
|
||||
- Rule 15 — failed resume is FAILED loudly. No automatic fresh fallback.
|
||||
Fresh launch is explicit follow-up only.
|
||||
- Rule 16 — post-command handoff required on `up`, `down`, `restore`,
|
||||
`snapshot create`: what happened + current state + next action.
|
||||
|
||||
(The full 25-rule list lives in `architecture-rules-and-event-system.md`.)
|
||||
|
||||
## 4. Auto-snapshot and existing-rig power-on
|
||||
|
||||
(`architecture.md` §6 "Auto-snapshot and existing-rig power-on")
|
||||
|
||||
- `rig down <rigId>` auto-captures an `auto-pre-down` snapshot before
|
||||
teardown.
|
||||
- `rig up <rig-name>` (no file extension) searches for an existing rig by
|
||||
name and restores from the latest `auto-pre-down` snapshot.
|
||||
- If no snapshot: error with guidance ("No saved snapshot for rig 'X'. Boot
|
||||
from a spec or bundle path.").
|
||||
- Post-command handoff: `down` output includes snapshot ID + restore command;
|
||||
`up` output includes node statuses + attach command.
|
||||
|
||||
## 5. Daemon-side restore-check / restore-packet — AUTHORED FROM SOURCE (D15)
|
||||
|
||||
> **D15 author bit (flagged per slice-08 §4.7 binding):** `restore-check` and
|
||||
> `restore-packet` have NO `architecture.md` narrative. This section is the
|
||||
> one author-from-source piece in this otherwise pure-split module — authored
|
||||
> at the slice-00 forensic bar from `routes/restore-check.ts` +
|
||||
> `domain/restore-check-service.ts` + `commands/restore-packet.ts`, file:line
|
||||
> cited, version-attribution forensically checked.
|
||||
>
|
||||
> **Version attribution (forensic):** restore-check is NOT a 0.3.1 feature.
|
||||
> `routes/restore-check.ts` first-created `277e279c` ("feat: native rig
|
||||
> restore-check command", 2026-04-23, pre-0.3.0); present at both `v0.3.0`
|
||||
> and `v0.3.1` git trees (`git ls-tree` confirmed). `restore-packet`
|
||||
> first-created `23f2921e` ("Restore-Packet vertical M2a", 2026-05-01),
|
||||
> likewise present at v0.3.0 and v0.3.1. The gap is missing
|
||||
> architecture.md *prose*, not a version-attribution drift.
|
||||
|
||||
### 5.1 `rig restore-check` — readiness probe
|
||||
|
||||
`GET /api/restore-check?rig=<name>&noQueue=<bool>&noHooks=<bool>`
|
||||
(`routes/restore-check.ts:131`). The route assembles a framework-free
|
||||
`RestoreCheckDeps` (`:138-168`) over existing daemon projections —
|
||||
`listRigs` from `rigRepo`, `getNodeInventory` (joining `node_id` by
|
||||
`logical_id`, `:21-26,143-149`), `getStartupContext` (reads
|
||||
`node_startup_context`, parses `projection_entries_json` /
|
||||
`resolved_files_json` / `startup_actions_json`, `:44-128`), `hasSnapshot`
|
||||
/ `getLatestSnapshot` from `snapshotRepo`, and `probeDaemonHealth`
|
||||
(self-evident: "We're inside the daemon — if this route is responding,
|
||||
daemon is healthy", `:160-163`). It then runs
|
||||
`new RestoreCheckService(deps).check(...)` (`:170-171`).
|
||||
|
||||
`RestoreCheckService.check()` (`restore-check-service.ts:244`) layers:
|
||||
|
||||
1. **Host checks** — `checkDaemonReachable` (probe-throw → `verdict:
|
||||
unknown`, NOT `not_restorable`, `:252-259`), `checkStateDirWritable`
|
||||
(`:261`), `checkHostInfraDeclaration` (`:262`, impl `:406`).
|
||||
2. **Rig enumeration** — `listRigs()` throw → `buildUnknown` (`:267-274`);
|
||||
`--rig` filter; unknown rig → red `rig.<name>.exists` (`:276-284`).
|
||||
3. **Per-rig checks** — `checkSnapshot` (`:290`, impl `:675`),
|
||||
`checkSpecPresent` (`:295`).
|
||||
4. **Per-seat checks** — `checkSeatReadiness` (`:311`), `checkStartupContext`
|
||||
(`:315`, impl `:763`; `unknownChecks` → `buildUnknown`),
|
||||
`checkTranscript` (`:325`), `checkResumePath` (`:329`), and unless opted
|
||||
out: `checkQueueFile` (`:334`, gated by `--no-queue`, impl `:870`) and
|
||||
`checkHooks` (`:339`, gated by `--no-hooks`, impl `:896`).
|
||||
5. **Verdict** — `buildResult` aggregates: any red → `not_restorable`; any
|
||||
yellow → `restorable_with_caveats`; else `restorable`; probe-uninspectable
|
||||
→ `unknown` (`:1074-1085`, `:1362-1379`). Plus a `RecoveryPlan`
|
||||
(`buildRecovery`, `:1186`) and a `RepairStep[]` packet
|
||||
(`buildRepairPacket`, `:1392`; `null` when fully restorable).
|
||||
|
||||
The result shape is `RestoreCheckResult` (`restore-check-service.ts:120-130`):
|
||||
`verdict`, `readiness`, `continuity`, `rigs[]`, `hostInfra`, `recovery`,
|
||||
`counts {red,yellow,green}`, `checks[]`, `repairPacket`.
|
||||
|
||||
**Honest-error design (slice-00 bar):** 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:249-259`). The route's catch-all returns the same
|
||||
`unknown`-shaped body with HTTP 500 + a `probe.error` red check
|
||||
(`routes/restore-check.ts:174-222`). `CheckEntry.remediationSafe` defaults to
|
||||
`false` (conservative — unclassified remediations are NOT
|
||||
auto-execution-safe, `restore-check-service.ts:18-24`).
|
||||
|
||||
CLI surface (`cli-reference.md` `### rig restore-check`):
|
||||
`rig restore-check [--rig <name>] [--no-queue] [--no-hooks] [--json]`. Exit
|
||||
codes: `0` restorable (or with caveats), `1` not restorable (red), `2`
|
||||
unknown / probe error.
|
||||
|
||||
### 5.2 `rig restore-packet` — cross-runtime restore packet
|
||||
|
||||
CLI-side, no daemon route. `commands/restore-packet.ts` (528 lines)
|
||||
implements three subcommands (`cli-reference.md` `### rig restore-packet`):
|
||||
`write [options]` (generate a packet directory from a source session or JSONL
|
||||
file, with `omitted-records` accounting), `read <packet-dir> [--json]`
|
||||
(render contents; non-mutating), `validate <packet-dir> [--json]` (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.
|
||||
|
||||
## OPEN / carried items
|
||||
|
||||
- **D15 (author-from-source, completed):** restore-check / restore-packet
|
||||
authored from source above; flagged as the single author bit in this
|
||||
module. Version attribution forensically resolved (both pre-0.3.0; the gap
|
||||
was missing prose, not drift).
|
||||
- No slice-00 numeric drift applies to this module's split content (the
|
||||
footprint/migration/route counts land in `daemon-core.md`).
|
||||
|
||||
## See also
|
||||
|
||||
- `agent-spec-and-startup.md` — StartupOrchestrator persists the replay
|
||||
context that restore consumes.
|
||||
- `daemon-core.md` — `/api/restore-check` is one of the 49 route mounts
|
||||
(`server.ts:513`).
|
||||
- `transport-and-transcripts.md` — transcript boundary markers written on
|
||||
restore.
|
||||
- Source roots: `packages/daemon/src/domain/{restore-orchestrator,
|
||||
snapshot-capture,snapshot-repository,checkpoint-store,
|
||||
restore-check-service}.ts`, `packages/daemon/src/routes/restore-check.ts`,
|
||||
`packages/cli/src/commands/restore-packet.ts`.
|
||||
@@ -1,205 +0,0 @@
|
||||
---
|
||||
kind: as-built
|
||||
title: Living Notes Review Surface — the intent→plan→delivered projection
|
||||
status: active
|
||||
topics: [knowledge-and-context, observability, sdlc]
|
||||
domains: [engineering-advisor, operating-advisor, product-advisor]
|
||||
applies-when: |
|
||||
Working on or consuming the composed slice/mission review surface — the
|
||||
/api/review/* routes, the ComposedSliceReview contract, the on-disk SDLC
|
||||
convention it projects, staged-approval locks, proof artifacts and the C1
|
||||
header, the freeze export, media serving for review evidence, or the
|
||||
cross-host FLEET aggregate (/api/review/fleet, the fleet composer's
|
||||
union/one-count seam, v0.4.6 MH-5).
|
||||
siblings: [content-surfaces.md, workspace-primitive.md, mission-control.md]
|
||||
prerequisite-reads: [workspace-primitive.md]
|
||||
last-verified-against-source: c8341f72
|
||||
last-updated: 2026-07-08
|
||||
---
|
||||
|
||||
# Living Notes review surface (v0.4.4)
|
||||
|
||||
The review surface is a **pure projection of on-disk markdown into one
|
||||
reviewable structure per slice**: INTENT → PLAN → DELIVERED. Agents change
|
||||
files; the daemon re-projects; nothing here writes product state except the
|
||||
two deliberate approval stamps and the freeze export. Shipped across the
|
||||
0.4.4 living-notes slices (19 signal layer, 20 composer/surfaces, 22 rig
|
||||
agents altitude, 23 SDLC operationalization) and the **corrective rebuild**
|
||||
(2026-07-05/06) that collapsed the surface to the one structure described
|
||||
here. Everything below is verified at `bb5ad219`.
|
||||
|
||||
## 1. The ONE contract — `ComposedSliceReview`
|
||||
|
||||
`packages/daemon/src/domain/review/types.ts` defines the read contract every
|
||||
consumer shares (slice Review tab, mission U5 row expansion, For-You
|
||||
expansion — never a second endpoint per consumer):
|
||||
|
||||
- **identity + phase**: `slice`, `sliceId`, `title`, `missionId`, `phase`
|
||||
(five-way, derived read-time: `locked > review > building > spec > intent`,
|
||||
`derivePhase` in `compose.ts`), `laneLabel` (SS14 vocabulary INTENT / PLAN /
|
||||
BUILD / REVIEW / LOCKED).
|
||||
- **`intent`**: `{text, media[], ssotPath, degrade}` — the slice README's
|
||||
`## Intent` section verbatim (`extractSection`), plus any media it embeds.
|
||||
- **`plan`**: `{concise: {text, media[]}, lockedArtifacts[], lock, ssotPath}` —
|
||||
the PRD's pinned `## Mini-requirements` tier + planned mockups; the pinned
|
||||
artifact set is a **frontmatter READ** (`locked-artifacts:` list on the
|
||||
slice README — no new write machinery); `lock` is the spec-scope
|
||||
staged-approval stamp (§3).
|
||||
- **`delivered`**: `{items[], extraProof[], lock, proofDirPath}` — the
|
||||
redesigned join (§4): each `## Proof contract` deliverable paired with its
|
||||
curated proof media and QA's recorded comparison signal. `lock` is the
|
||||
delivery-scope stamp; `proofDirPath` is the drill-in door to the full
|
||||
fix-loop history.
|
||||
- **KEPT orthogonal bands**: `needsYou` (two sources, one queue: agent-routed
|
||||
items ∪ derived ▲ exceptions with inline evidence), `agents`
|
||||
(scope-parameterized `slice:<id> | mission:<id> | rig` — one contract, all
|
||||
scopes), `lineage` (`VerifyLineage`: candidate/merge/tip facts + the four
|
||||
gate `VerdictCell`s rendering recorded tokens verbatim), `defects`
|
||||
(out-of-slice media refs surfaced, never silently dropped), `composedAt`.
|
||||
|
||||
**Deleted by the corrective (2026-07-05, founder-blocked original):** the
|
||||
four parallel renderable structures (`sections`, `acceptance`, `compare`,
|
||||
`join`) and the coequal `green` field. They do not exist in the types, the
|
||||
composer output, the UI hook, or the fixtures; the daemon route tests assert
|
||||
the keys are ABSENT on the wire (`test/review-composer.test.ts`,
|
||||
`test/review-routes.test.ts`). Recorded-verdict green survives in exactly two
|
||||
places: the per-deliverable `verified` signal (§4) and the mission ledger's
|
||||
completion fact (§6) — never a slice-review structure.
|
||||
|
||||
## 2. Composer + gatherer split
|
||||
|
||||
- `compose.ts` is **PURE**: `(gathered inputs) → composed doc`; identical
|
||||
inputs (including caller-supplied `nowIso`/git facts) produce byte-identical
|
||||
output — idempotence holds by construction and is pinned by tests.
|
||||
- `gather.ts` (`ReviewGatherer`) is the impure shell: reads slice docs +
|
||||
`proof/*.md` artifacts from disk, attention/agent rows from SQLite,
|
||||
approval stamps from frontmatter (cross-checked against the audit log, §3),
|
||||
git lineage facts from the workspace default repo. Every unreadable source
|
||||
degrades honestly (nulls / "unknown") — the composer renders the named
|
||||
degrade, never invented content.
|
||||
|
||||
## 3. The two locks = the shipped staged-approval stamps
|
||||
|
||||
`plan.lock` and `delivered.lock` are projections of the **staged-approval
|
||||
verb** (`rig scope slice|mission approve --scope spec|delivery` — see
|
||||
cli-reference "SDLC control plane verbs"): frontmatter stamps
|
||||
(`approved-spec-by/-at`, `approved-by/-at`) written daemon-side together with
|
||||
an append-only `mission_control_actions` audit row (no half-stamp). The
|
||||
gatherer cross-checks each stamp against the pinned scope-approval
|
||||
`audit_notes_json` shape (`approval_scope` + scope identity); a stamp with no
|
||||
matching row projects `auditVerified: false` and renders as an UNVERIFIED
|
||||
stamp — visible, never a block. Approval is freeze/sign-off, **never**
|
||||
proven-green (BR-6).
|
||||
|
||||
## 4. DELIVERED — promised ↔ curated proof ↔ verified
|
||||
|
||||
`composeDelivered` joins the PRD's `## Proof contract` checkbox items
|
||||
(`extractProofContract`; an optional markdown image on the checkbox line
|
||||
becomes the deliverable's `plannedRef` mockup) to the C1-headed proof
|
||||
artifacts in `<slice>/proof/`:
|
||||
|
||||
- An artifact **covers** a deliverable when its C1 `evidences:` list names the
|
||||
item (exact text or 1-based index).
|
||||
- `verified` binds to the shipped C1 fields, never mere presence:
|
||||
**verified** = a covering `qa|adjudication` artifact records the comparison
|
||||
(`self_check`) AND its recorded verdict is passing; **unverified** = some
|
||||
covering artifact without a passing recorded QA comparison (QA's
|
||||
why-kicked-back `note` still surfaces); **missing** = promised, nothing
|
||||
delivered. All three are render states — fail-open by construction.
|
||||
- The curated proof set is the covering artifacts' body media refs
|
||||
(`ProofArtifact.mediaRefs`, populated by `rig proof add --media` or markdown
|
||||
refs in the artifact body), normalized slice-relative; refs escaping the
|
||||
slice dir become `defects` findings and are never served or inlined.
|
||||
Unmapped-artifact media renders bounded as `extraProof`.
|
||||
- The ▲ insufficient-proof NEEDS-YOU exception fires from the delivered
|
||||
MISSING count (`deriveExceptions`).
|
||||
|
||||
## 5. Routes, freeze, media serving
|
||||
|
||||
- `packages/daemon/src/routes/review.ts`, mounted at `/api/review`
|
||||
(`server.ts` route mounts): `GET /slice/:name`, `GET /mission/:name`,
|
||||
`GET /rig` (the OPR.0.4.4.22 rig-agents altitude root), `GET
|
||||
/agents?scope=slice:<id>|mission:<id>|rig`, `POST /freeze`.
|
||||
- **Freeze** (`freeze.ts`): the ONE synchronous compose-and-freeze path,
|
||||
invoked after the delivery stamp + audit row commit. Renders the composed
|
||||
review to a single self-contained HTML file (`REVIEW-<id>-<date>.html` in
|
||||
the slice dir): CSS inline, images data-URI-inlined under slice-dir
|
||||
containment (resolve-prefix + realpath — a traversal/symlink ref renders
|
||||
the muted outside-slice branch, never inlined), video by link + poster.
|
||||
Exclusive-create through the allowlist-governed atomic write service;
|
||||
re-invocation is an idempotent no-op; a failed render never un-approves.
|
||||
Legacy missions carrying `MISSION_BRIEF.md` may still receive the
|
||||
section-scoped brief-spine fold; new scaffolds do not create that retired
|
||||
web-UI-era file.
|
||||
- **Media serving** for review evidence is ranged on BOTH asset route
|
||||
families (iOS-Safari-class players require `206`): `GET /api/files/asset`
|
||||
(`routes/files.ts` — single-range parse, `206`/`416`, `Accept-Ranges:
|
||||
bytes`; `.html` renders as text/html only under the explicit `?render=1`
|
||||
opt-in) and `GET /api/slices/:name/proof-asset/*` (`routes/slices.ts` —
|
||||
same range semantics via `fileAssetResponse`, added by the corrective QA
|
||||
fixback; immutable-cache posture retained).
|
||||
|
||||
## 6. Mission + rig altitudes
|
||||
|
||||
`composeMissionReview` consumes `{review, green}` entries per slice: the
|
||||
board (stage-specific cells re-bound to the collapsed contract — spec-stamp
|
||||
state, delivered n/m, GREEN·merge pair, stamp), the completion **ledger**
|
||||
(a query over the slice set, never an authored list; `green` here is the
|
||||
recorded-verdict fact from `computeRecordedGreen` — regime 1 = four passing
|
||||
gate verdicts, regime 2 = passing adjudication), `cutComplete` (TRUE only
|
||||
when every in-cut slice is green AND merged AND has zero open needs-human
|
||||
items), and the union NEEDS-YOU (distinct identities — one item seen from N
|
||||
altitudes is one item). `composeRigAgents` serves the standalone rig
|
||||
altitude (roster ∪ recently-holding, park/health/settled from the queue
|
||||
transitions log).
|
||||
|
||||
## 7. The FLEET altitude — the cross-host aggregate SIBLING (v0.4.6, OPR.0.4.6.MH5)
|
||||
|
||||
`GET /api/review/fleet` aggregates every registered host's composed ▲/● set
|
||||
into one manage-by-exception glance. It is a **sibling aggregate endpoint**,
|
||||
never a fourth `AgentsScope` value (arch Q2): the scope grammar stays
|
||||
exactly `slice:* | mission:* | rig`, and the local composer stays a pure
|
||||
function over local state. `domain/review/fleet-compose.ts` is the ONE
|
||||
review-domain module allowed to import hosts transport/registry — a
|
||||
boundary enforced mechanically by the `review-import-audit` static test
|
||||
(the zero-I/O `fanout-contract` types module is the sole allowlisted
|
||||
hosts import elsewhere).
|
||||
|
||||
**Fan-out-the-composed-set (arch Q1):** the ▲ kinds are time-derived on
|
||||
their own host's clock, so the fleet root fans out each host's
|
||||
ALREADY-COMPOSED rig root (`GET /api/review/rig` over `remoteJsonRequest`,
|
||||
concurrent under the named read-class deadline; the local host joins
|
||||
in-process via the same gatherer — zero self-transport) and only **unions +
|
||||
host-dimensions + counts**. It never recomputes exception truth (the
|
||||
composer is clock-free by test pin), so cross-host clock skew can never
|
||||
distort a ▲. Per-host failures degrade to the closed `PerHostStatus`
|
||||
honesty contract; a failed host's counts are ABSENT from its
|
||||
`FleetHostRollup` — absent-not-zero, in the type.
|
||||
|
||||
**One-count across the fleet (arch Q4):** the dedup `Set` lives in the
|
||||
fleet composer — the one place — keyed `hostId|identity` (rendered verbatim
|
||||
on the expanded drawer); within-host multi-altitude visibility collapses to
|
||||
one row with `seenFrom` provenance; an MH-3-forwarded qitem lives only in
|
||||
its origin host's DB, so no double-count by construction.
|
||||
|
||||
**Composition pins the seam (arch Q3, the rule of thumb):** sidedness and
|
||||
caller pick the TRANSPORT seam (MH-4's CLI-direct verbs); when COMPOSITION
|
||||
exists — the fleet union/one-count is a correctness rule — the seam pins
|
||||
daemon-side: ONE composer, one endpoint, every consumer (the `/fleet` route
|
||||
page and the FLEET band today via the shared `useFleet` hook; the TUI/CLI
|
||||
fleet consumers as named follow-ups) reads the same one. UI cadence is the
|
||||
bounded named `FLEET_POLL_INTERVAL_MS` with the feed-cadence-class floor,
|
||||
and the ambient band gates its FETCH on fleet existence (the FS-1 amplifier
|
||||
discipline; enable-at-scale remains the FS-1 release-validation gate). Read
|
||||
+ surface only: acting on a remote host's item rides MH-3/MH-4.
|
||||
|
||||
## 8. The on-disk convention it projects (SDLC control plane)
|
||||
|
||||
The surface projects the markdown-control-plane shapes operationalized by
|
||||
OPR.0.4.4.23 — conventions SSOT `docs/reference/sdlc-conventions.md`:
|
||||
`## Intent` (README) / `## Mini-requirements` + `## Proof contract` (PRD) /
|
||||
`proof/` C1-headed artifacts + `PROOF.md`, scaffolded for every template kind
|
||||
by `rig scope slice create` and checked advisory-only by `rig scope audit`
|
||||
(+ the `rig doctor` SDLC row). The UI half of this surface (the slice Review
|
||||
tab, mission board, For-You approve+chat) is documented in
|
||||
[`../ui/project-and-for-you.md`](../ui/project-and-for-you.md).
|
||||
@@ -1,165 +0,0 @@
|
||||
---
|
||||
kind: as-built
|
||||
title: Mission Control — Queue Observability + 7-Verb Contract (PL-005)
|
||||
status: active
|
||||
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 seven write verbs, the action audit table, the
|
||||
bearer-token middleware, or how queue observability maps to PL-004 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: 7eaf524c
|
||||
last-updated: 2026-05-16
|
||||
---
|
||||
|
||||
# Mission Control — Queue Observability + 7-Verb Contract (PL-005)
|
||||
|
||||
Mission Control (PL-005) is the daemon-backed queue-observability surface: an
|
||||
integrated product UI inside the existing shell (a top-level `/mission-control`
|
||||
route, NOT a new managed app) over the PL-004 Phase A coordination primitive.
|
||||
Per the PRD acceptance criteria: seven views, seven verbs, first-class human
|
||||
seats, recent-ships=10, and a daemon-backed action audit table; no
|
||||
old-dashboard migration/cutover (`architecture.md` §3 L368, L390).
|
||||
|
||||
> Verified against source at HEAD `7eaf524c`. Mission Control is PL-005 (an
|
||||
> early-0.3.0 graft); plugins and Claude auto-compaction are 0.3.1 features
|
||||
> and are NOT back-attributed here (slice-00 0.3.0-ground-truth seams a/row-7).
|
||||
|
||||
## 1. The seven views
|
||||
|
||||
`MISSION_CONTROL_VIEWS` is the canonical view list (re-confirmed at HEAD
|
||||
`packages/daemon/src/domain/mission-control/mission-control-read-layer.ts:32–42`):
|
||||
`my-queue`, `human-gate`, `fleet`, `active-work`, `recent-ships`,
|
||||
`recently-active`, `recent-observations`.
|
||||
|
||||
All seven return rows in the load-bearing 9-field phone-friendly content
|
||||
model (rig/mission name, current phase,
|
||||
active|idle|attention|blocked|degraded, next-action,
|
||||
pending-human-decision, read-cost, last-update timestamp,
|
||||
confidence/freshness, evidence link). The model is non-negotiable across all
|
||||
7 views; UI may render compact, JSON preserves all 9 (`architecture.md` §3
|
||||
L370).
|
||||
|
||||
`MissionControlReadLayer` maps each view to its source-of-truth path
|
||||
(`mission-control-read-layer.ts:4–14`, re-confirmed at HEAD):
|
||||
|
||||
- `my-queue` / `human-gate` / `active-work` / `recent-ships` query PL-004
|
||||
Phase A `queue_items` via `QueueRepository`.
|
||||
- `fleet` consumes the per-rig CLI capability cache + queue summary.
|
||||
- `recently-active` delegates to PL-004 Phase B
|
||||
`ViewProjector.show("recently-active")`.
|
||||
- `recent-observations` reads PL-004 Phase A `stream_items` via
|
||||
`StreamStore`.
|
||||
|
||||
Filesystem fallbacks (`~/.openrig/stream/<date>.jsonl`, raw queue file grep)
|
||||
are graceful-degradation aids, NOT the primary path (`architecture.md` §3
|
||||
L378).
|
||||
|
||||
> Scope note (slice-00 0.3.0-ground-truth OPEN-3, carried): the exact
|
||||
> For-You verb subset is an unresolved velocity slice-01 ruling. This module
|
||||
> describes the **system-level** 7-verb vocabulary (proven, slice-00
|
||||
> §1.6/seam-c). It does NOT enumerate a For-You-surface subset — that
|
||||
> surface is described in `../ui/project-and-for-you.md` when authored.
|
||||
|
||||
## 2. The seven verbs (the write contract)
|
||||
|
||||
The seven verbs execute through the load-bearing
|
||||
`MissionControlWriteContract` (re-confirmed at HEAD
|
||||
`packages/daemon/src/domain/mission-control/mission-control-write-contract.ts:27–36`):
|
||||
|
||||
| Verb | Effect |
|
||||
|---|---|
|
||||
| `approve` | `state="done"`, `closure_reason="no-follow-on"` |
|
||||
| `deny` | `state="done"`, `closure_reason="denied"` |
|
||||
| `route` | `state="done"`, `closure_reason="handed_off_to"`, `closure_target`+`handed_off_to`=route target; creates new qitem at the route target (1-hop) |
|
||||
| `annotate` | no queue mutation; audit record only |
|
||||
| `hold` | `state="blocked"`, `closure_reason="blocked_on"` |
|
||||
| `drop` | `state="done"`, `closure_reason="canceled"` |
|
||||
| `handoff` | the 4-step shape (see below) |
|
||||
|
||||
Each verb is one atomic daemon transaction: queue mutation via
|
||||
`QueueRepository.updateWithinTransaction()` (which preserves Phase A
|
||||
hot-potato closure validation — see `coordination-primitive.md` §3) + an
|
||||
audit row in `mission_control_actions` + a persisted
|
||||
`mission_control.action_executed` event, all in one `db.transaction`. The
|
||||
4-step `handoff` shape (source-update + destination-create + opt-in
|
||||
best-effort notify + audit-record append) is verified atomic; notify failure
|
||||
does NOT roll back durable mutations (PRD invariant). Failure-injection rolls
|
||||
back source closure + audit row + new qitem together (`architecture.md` §3
|
||||
L380; `mission-control-write-contract.ts:5,15`).
|
||||
|
||||
## 3. The action audit table
|
||||
|
||||
`mission_control_actions` (`037_mission_control_actions.ts:54` `CREATE TABLE
|
||||
IF NOT EXISTS mission_control_actions`) is append-only at the API surface:
|
||||
it records every operator action through Mission Control with before/after
|
||||
qitem snapshots for forensic reconstruction. Columns include `action_verb`
|
||||
(TEXT, app-layer enum enforcement, `:56`) and `acted_at` (TEXT NOT NULL ISO
|
||||
timestamp); indexes `(acted_at DESC, action_verb)`,
|
||||
`(qitem_id, acted_at DESC)`, `(actor_session, acted_at DESC)`
|
||||
(`037_mission_control_actions.ts:28–44`). Phase B added NO migrations — this
|
||||
Phase A table is the only data source (`architecture.md` §3 L364, L392).
|
||||
|
||||
## 4. PL-005 Phase B — bearer middleware, notifications, audit browse
|
||||
|
||||
Phase B extends the daemon Mission Control surface:
|
||||
|
||||
- **Bearer-token middleware** —
|
||||
`packages/daemon/src/middleware/auth-bearer-token.ts` (re-confirmed at
|
||||
HEAD: header `auth-bearer-token.ts:1–9` "PL-005 Phase B"). Constant-time
|
||||
bearer comparison via Node `crypto.timingSafeEqual`; the daemon refuses to
|
||||
start with a non-loopback bind interface AND an empty bearer config
|
||||
(startup-side check). Bearer enforced on the write verbs:
|
||||
`app.post("/action", requireAuth)` (`routes/mission-control.ts:294`) and
|
||||
`app.post("/notifications/test", requireAuth)` (`:295`). v0 is bearer-on-write;
|
||||
no OAuth/SSO/per-user model.
|
||||
- **Notification dispatcher** — two adapters
|
||||
(`notification-adapter-ntfy.ts` default + `notification-adapter-webhook.ts`
|
||||
alternate; selected via `OPENRIG_NOTIFICATIONS_MECHANISM` env) plus
|
||||
`notification-dispatcher.ts` (re-confirmed in
|
||||
`domain/mission-control/`). ntfy.sh recommended for the operator's phone
|
||||
via tailnet.
|
||||
- **Read-only audit-history browse** — `audit-browse.ts` over
|
||||
`mission_control_actions`, exposed at `GET /api/mission-control/audit`
|
||||
(`routes/mission-control.ts:346`) with filters and `(limit, before_id)`
|
||||
pagination cursored on SQLite `rowid` (`architecture.md` §3 L392).
|
||||
|
||||
## 5. Mission Control events
|
||||
|
||||
> Drift-fix D8 / OPEN-4 (carried verbatim, slice-00): `architecture.md` §3
|
||||
> L394 says "Existing 32 PL-004 events untouched" — internally inconsistent
|
||||
> with §3 L410's "20" and predates 0.3.x. **Do NOT carry either number.**
|
||||
> The current `RigEvent` union (`packages/daemon/src/domain/types.ts:94`)
|
||||
> has **73 members** total (slice-00 §1.8, re-confirmed at HEAD); the
|
||||
> additive `mission_control.*` events are described below WITHOUT asserting
|
||||
> a contested PL-004 sub-count.
|
||||
|
||||
Re-confirmed `domain/types.ts:212–218`: Phase A added
|
||||
`mission_control.action_executed`, `mission_control.cli_drift_detected`,
|
||||
`mission_control.view_refreshed`; Phase B added
|
||||
`mission_control.notification_sent`, `mission_control.notification_failed`
|
||||
(5 `mission_control.*` members at HEAD).
|
||||
|
||||
## 6. Route surface
|
||||
|
||||
`missionControlRoutes({ bearerToken })` is mounted at `server.ts:498`. Key
|
||||
routes (`routes/mission-control.ts`): `GET /views` (`:245`),
|
||||
`GET /cli-capabilities` (`:250`), `POST /action` (`:298`, auth-gated),
|
||||
`GET /audit` (`:346`), `POST /notifications/test` (auth-gated), plus an SSE
|
||||
surface. The integrated UI is the `/mission-control` top-level route in
|
||||
`packages/ui/src/routes.tsx` mounting `MissionControlSurface`
|
||||
(`architecture.md` §3 L390); UI detail lands in
|
||||
`../ui/project-and-for-you.md`.
|
||||
|
||||
## See also
|
||||
|
||||
- `coordination-primitive.md` — the PL-004 Phase A `queue_items`/`stream_items`
|
||||
sources Mission Control reads, and the hot-potato closure contract verbs honor.
|
||||
- `workflow-runtime.md` — PL-004 Phase D transactional-scribe runtime.
|
||||
- `../ui/project-and-for-you.md` — the UI surface counterpart (authored phase).
|
||||
- Source roots: `packages/daemon/src/domain/mission-control/`,
|
||||
`packages/daemon/src/middleware/auth-bearer-token.ts`,
|
||||
`packages/daemon/src/routes/mission-control.ts`,
|
||||
`packages/daemon/src/db/migrations/037_mission_control_actions.ts`.
|
||||
@@ -1,143 +0,0 @@
|
||||
---
|
||||
kind: as-built
|
||||
title: Packaging, Bootstrap, Bundles, Legacy Install Engine
|
||||
status: active
|
||||
topics: [specification-and-bundles, release-and-versioning]
|
||||
domains: [engineering-advisor, operating-advisor]
|
||||
applies-when: |
|
||||
Need to know how rig/pod bundles are assembled (schema-version-2 vs legacy
|
||||
v1), how bundle create/inspect/install and /api/up route across source kinds,
|
||||
the staged BootstrapOrchestrator plan/apply flow, or which legacy install-
|
||||
engine seams still ship for pre-reboot data.
|
||||
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: 7eaf524c
|
||||
last-updated: 2026-05-16
|
||||
---
|
||||
|
||||
# Packaging, Bootstrap, Bundles, Legacy Install Engine
|
||||
|
||||
How OpenRig packages a topology into a shareable bundle and reconstitutes it
|
||||
on another host. Fully dual-format: schema-version-2 pod bundles plus legacy
|
||||
v1 artifacts, routed deterministically by the bootstrap orchestrator.
|
||||
|
||||
> Verified against source at HEAD `7eaf524c` (`git describe` →
|
||||
> `v0.3.1-6-g7eaf524c`). Package version **0.3.1** (slice-00 §1.1). Source
|
||||
> located by `architecture.md` headings (§5 Bundles/bootstrap/legacy
|
||||
> compatibility, §6 Bundle create/inspect/install + /api/up, §11 Compat
|
||||
> note 3) per slice-08 §10.1 — line numbers advisory only.
|
||||
|
||||
## 1. Bundle, bootstrap, legacy domain services
|
||||
|
||||
(`architecture.md` §5 "Bundles, bootstrap, and legacy compatibility")
|
||||
|
||||
- `pod-bundle-assembler.ts` — schema-version-2 bundle assembler.
|
||||
Re-confirmed: emits `schemaVersion: 2` (`pod-bundle-assembler.ts:167`).
|
||||
- `bundle-types.ts` — v1 and v2 manifest types plus parse/validate/serialize.
|
||||
Re-confirmed: v2 `PodBundleManifest` type carries `schemaVersion: 2`
|
||||
(`:23`); `validatePodBundleManifest` rejects unless `schema_version === 2`
|
||||
(`:38`); `serializePodBundleManifest` writes `schema_version: 2` (`:62`);
|
||||
`parsePodBundleManifest` (`:87`); legacy path
|
||||
`validateLegacyBundleManifest` (`:143`) — both formats live in one file.
|
||||
- `bundle-source-resolver.ts` — `LegacyBundleSourceResolver`
|
||||
(`bundle-source-resolver.ts:25`) plus `PodBundleSourceResolver` (`:132`).
|
||||
- `bootstrap-orchestrator.ts` — staged bootstrap flow with direct pod-aware
|
||||
rig and v2 bundle delegation. `BootstrapMode = "plan" | "apply"`
|
||||
(`bootstrap-orchestrator.ts:26`).
|
||||
- `up-command-router.ts` — spec/bundle source classification for `/api/up`.
|
||||
`SourceKind = "rig_spec" | "rig_bundle" | "rig_name"`
|
||||
(`up-command-router.ts:6`).
|
||||
|
||||
All re-confirmed present in `packages/daemon/src/domain/` @HEAD.
|
||||
|
||||
## 2. Bundle create / inspect / install
|
||||
|
||||
(`architecture.md` §6 "Bundle create / inspect / install")
|
||||
|
||||
`routes/bundles.ts` is fully dual-format:
|
||||
|
||||
- **create** — detects a pod-aware RigSpec and uses `PodBundleAssembler`
|
||||
(accepts an optional `rigRoot`); legacy create still uses
|
||||
`LegacyBundleAssembler`.
|
||||
- **inspect** — safely extracts the archive, detects `schema_version`; v2
|
||||
returns `schemaVersion: 2`, `agents[]`, and integrity data; v1 returns the
|
||||
legacy manifest shape.
|
||||
- **install** — uses the full bootstrap plan/apply; bootstrap peeks the
|
||||
manifest and routes deterministically to `pod_bundle` or `rig_bundle`.
|
||||
Re-confirmed at source: `bootstrap-orchestrator.ts:134-143` — when
|
||||
`sourceKind === "rig_bundle"` it unpacks to a temp peek dir, reads
|
||||
`bundle.yaml`, and calls `parsePodBundleManifest(...)` to detect the
|
||||
schema version before routing.
|
||||
|
||||
## 3. `/api/up` source routing
|
||||
|
||||
(`architecture.md` §6 "`/api/up`")
|
||||
|
||||
`UpCommandRouter` + `BootstrapOrchestrator` own:
|
||||
|
||||
- direct pod-aware rig specs,
|
||||
- legacy rig specs,
|
||||
- v1 bundle installs,
|
||||
- v2 pod-bundle installs.
|
||||
|
||||
Plan mode and apply mode both work across those source kinds.
|
||||
|
||||
> Definitional note (carried, not a numeric drift) — `architecture.md` §6
|
||||
> describes bootstrap routing to `pod_bundle` / `rig_bundle`. The
|
||||
> `UpCommandRouter` *classification* enum is `SourceKind = "rig_spec" |
|
||||
> "rig_bundle" | "rig_name"` (`up-command-router.ts:6`); the
|
||||
> `pod_bundle`-vs-`rig_bundle` distinction is resolved one layer deeper in
|
||||
> `bootstrap-orchestrator.ts` by peeking the manifest schema version
|
||||
> (`:134-143`). Both statements are accurate at different layers; documented
|
||||
> here so the layering is explicit rather than appearing contradictory.
|
||||
|
||||
## 4. Legacy install engine (still ships)
|
||||
|
||||
(`architecture.md` §5 "Legacy systems that still ship" + §11 compat note 3)
|
||||
|
||||
These pre-reboot seams remain active for backward compatibility:
|
||||
|
||||
- package install engine: `package-install-service.ts`,
|
||||
`package-manifest.ts`, `package-repository.ts`, `install-engine.ts`,
|
||||
`conflict-detector.ts`, `role-resolver.ts` (all re-confirmed present
|
||||
@HEAD).
|
||||
- bootstrap and requirement-probe support.
|
||||
- discovery and claim services.
|
||||
- tmux/cmux adapters and resume adapters.
|
||||
|
||||
> Drift-check D-pkg — `architecture.md` §5/§6 carries no slice-00 numeric
|
||||
> drift in this content; the v2 bundle-assembler + dual-format flows were
|
||||
> verified accurate at HEAD (§1–§3 above). The footprint/migration counts
|
||||
> that ARE stale land in `daemon-core.md`, not here.
|
||||
|
||||
Compat note 3 (carried verbatim, `architecture.md` §11): "Legacy
|
||||
compatibility seams still ship for pre-reboot data and v1 artifacts." (The
|
||||
full §11 list lives in `architecture-rules-and-event-system.md`.)
|
||||
|
||||
> Provenance note (carried, not asserted): `bootstrap-orchestrator.ts:3-5`
|
||||
> still imports `LegacyRigSpec` / `LegacyRigSpecCodec` / `LegacyRigSpecSchema`
|
||||
> with in-source `TODO: AS-T08b — migrate to pod-aware RigSpec` markers, and
|
||||
> `:16` `TODO: AS-T12 — migrate to pod-aware bundle source resolver`. The
|
||||
> legacy seam is intentional, in-progress migration scaffolding — recorded
|
||||
> as-is, not smoothed.
|
||||
|
||||
## OPEN / carried items
|
||||
|
||||
- **D-pkg (resolved-as-current):** no slice-00 numeric drift in this
|
||||
module's split content; v2 assembler + dual-format flows verified accurate
|
||||
at HEAD. Bundle-routing layering documented explicitly to pre-empt an
|
||||
apparent §6-vs-source contradiction.
|
||||
- Legacy-migration TODOs carried from source verbatim (AS-T08b / AS-T12).
|
||||
|
||||
## See also
|
||||
|
||||
- `agent-spec-and-startup.md` — `RigInstantiator` / `PodRigInstantiator` and
|
||||
the dual-format spec seam that bundles wrap.
|
||||
- `plugin-agent-image-context-pack.md` — the 0.3.0/0.3.1 reusable
|
||||
starter-state / content-provenance cluster (authored separately in 8.4b).
|
||||
- `daemon-core.md` — `/api/up` + `/api/bundles` are among the 49 route
|
||||
mounts; `BootstrapOrchestrator` is constructed in the createDaemon
|
||||
sequence.
|
||||
- Source roots: `packages/daemon/src/domain/{pod-bundle-assembler,
|
||||
bundle-types,bundle-source-resolver,bootstrap-orchestrator,
|
||||
up-command-router}.ts`, `packages/daemon/src/routes/{bundles,up}.ts`.
|
||||
@@ -1,357 +0,0 @@
|
||||
---
|
||||
kind: as-built
|
||||
title: Content Layer — Plugins, Agent Images, Context Packs, Compaction Policy
|
||||
status: active
|
||||
topics: [extension-and-user-workspace, continuity, skill-management]
|
||||
domains: [engineering-advisor, operating-advisor]
|
||||
applies-when: |
|
||||
Need to know how OpenRig discovers plugins, captures/forks agent images,
|
||||
assembles/sends context packs, or how the Claude auto-compaction enforcer
|
||||
decides to send /compact. Author-mode module — no prior architecture.md
|
||||
prose; every claim is sourced to file:line at HEAD.
|
||||
siblings: [packaging-bootstrap-bundles.md, agent-spec-and-startup.md]
|
||||
prerequisite-reads: [../README.md, agent-spec-and-startup.md]
|
||||
last-verified-against-source: 7eaf524c
|
||||
last-updated: 2026-05-16
|
||||
---
|
||||
|
||||
# Content Layer — Plugins, Agent Images, Context Packs, Compaction Policy
|
||||
|
||||
Four filesystem-canonical content primitives the daemon discovers and
|
||||
serves: **plugins**, **agent images**, **context packs**, and the **Claude
|
||||
auto-compaction policy enforcer**. None adds SQLite state — all are
|
||||
filesystem-canonical with in-memory daemon caches.
|
||||
|
||||
> **AUTHOR-FROM-SOURCE module.** No prior `architecture.md` prose exists
|
||||
> for this. Every load-bearing claim carries `> Source: <file:line>
|
||||
> @HEAD`; ambiguity is declared as an OPEN item, never smoothed. Paths are
|
||||
> relative to `packages/daemon/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 — read first)
|
||||
|
||||
Re-verified at HEAD via `git cat-file -e <tag>:<path>`:
|
||||
|
||||
| Subsystem | Release | Forensic proof @HEAD |
|
||||
|---|---|---|
|
||||
| Context packs | **0.3.0** | `v0.3.0:domain/context-packs/context-pack-library-service.ts` → present (slice-00 0.3.0-GT §1.9) |
|
||||
| Agent images | **0.3.0** | `v0.3.0:domain/agent-images/agent-image-library-service.ts` → present (slice-00 0.3.0-GT §1.9) |
|
||||
| Plugins | **0.3.1, NOT 0.3.0** | `v0.3.0:domain/plugin-discovery-service.ts` → **ABSENT**; `v0.3.1:` → present (slice-00 0.3.0-GT seam (a); map row 5) |
|
||||
| Claude auto-compaction | **0.3.1 headline, no 0.3.0 antecedent** | `v0.3.0:domain/claude-compaction-enforcer.ts` → **ABSENT**; `v0.3.1:` → present (slice-00 0.3.0-GT map row 7) |
|
||||
|
||||
> Source: re-run at HEAD `7eaf524c` —
|
||||
> `git cat-file -e v0.3.0:packages/daemon/src/domain/plugin-discovery-service.ts`
|
||||
> and `...claude-compaction-enforcer.ts` both fail ("exists on disk, but
|
||||
> not in 'v0.3.0'"); the two 0.3.0 library services resolve at `v0.3.0`.
|
||||
> Code present on disk at HEAD does NOT make plugins/compaction a 0.3.0
|
||||
> feature — ancestry is truth; the same-calendar-day commit date is the
|
||||
> forensic trap slice-00 0.3.0-GT seam (a) warns about.
|
||||
|
||||
**Do not back-attribute plugins or compaction to 0.3.0.** The CLI
|
||||
reference already encodes this ("## Plugin Inspection (v0.3.1)").
|
||||
|
||||
> Source: `docs/as-built/cli-reference.md:943` @HEAD.
|
||||
|
||||
## 1. Context packs (PL-014) — 0.3.0
|
||||
|
||||
A **context pack** is a directory of `manifest.yaml` + included markdown /
|
||||
yaml / txt files: operator-authored, library-discoverable, reviewable, and
|
||||
composable. The `rig context` noun is delivery-free. No SQLite tables;
|
||||
in-memory cache at daemon scope.
|
||||
|
||||
> Source: `domain/context-packs/context-pack-types.ts:1-11` @HEAD.
|
||||
|
||||
`ContextPackLibraryService.scan()` walks roots, parses each
|
||||
`manifest.yaml`, replaces the in-memory index; collisions are
|
||||
**last-wins** in discovery order (workspace > user_file > builtin).
|
||||
Startup wires the builtin root (`../context-packs`, first), the configured
|
||||
user-file root (`context.root`, default `$OPENRIG_HOME/context`), its
|
||||
`system/` child as the canonical System World root, and the workspace-local
|
||||
`<workspaceRoot>/.openrig/context-packs` root when present + distinct. A pack is
|
||||
addressed by its path-like **ref** (e.g. `packs/compaction-restore`), which is
|
||||
its unique identity; the opaque entry id is `context-pack:<ref>` (a UI routing
|
||||
key). Colon-id `context-pack:<name>:<version>` addressing and the `/library/:id`
|
||||
routes were removed in Slice-03 Atom 5. Resolution is by ref only through
|
||||
`getByRef` and the read/delete/preview/pieces route family. Startup accepts
|
||||
ordinary files only and rejects context-pack expansion; compose a durable ref
|
||||
first, then use a dedicated delivery verb when delivery is intended.
|
||||
|
||||
> Source: `domain/context-packs/context-pack-library-service.ts:59-94`
|
||||
> (scan; last-wins L79-81), `:31-33` (id); `startup.ts`
|
||||
> (`contextPackLibrary` construction) @HEAD.
|
||||
|
||||
The parser is pure (no fs; caller passes raw YAML). It rejects malformed
|
||||
YAML, missing `name`/`version`, non-array `files`, per-file path traversal
|
||||
(`..`/leading `/`), and unsupported suffixes (`.md .markdown .yaml .yml
|
||||
.txt`); `version` coerced to string. Per-file token estimate is
|
||||
`ceil(bytes/4)`.
|
||||
|
||||
> Source: `domain/context-packs/manifest-parser.ts:11` (suffixes),
|
||||
> `:13-121` (rejects; traversal `:83-89`); token estimate
|
||||
> `context-pack-library-service.ts:46-48` @HEAD.
|
||||
|
||||
`assembleBundle` concatenates files into one paste-ready string framed
|
||||
`# OpenRig Context Pack: <name> v<version>` + optional purpose + `## File:
|
||||
<path> (role: <role>)` headers. Missing files are **skipped and surfaced
|
||||
in `missingFiles`** (operator repair), not a hard fail; a present-but-
|
||||
unreadable file throws `file_read_failed`.
|
||||
|
||||
> Source: `domain/context-packs/bundle-assembler.ts:38-39` (prefixes),
|
||||
> `:73-100` (missing skip L74-76; read-fail throw L81-87) @HEAD.
|
||||
|
||||
`contextPacksRoutes()` exposes a ref-primary, delivery-free library surface:
|
||||
`GET /library`, `POST /library/sync`, `POST /library/compose`,
|
||||
`GET/DELETE /library/by-ref`, `GET /library/by-ref/preview`, and
|
||||
`GET /library/by-ref/pieces`. Preview returns the assembled review shape;
|
||||
pieces returns ordered member contents plus the whole plain text and byte size.
|
||||
There is no pack-owned delivery route. CLI library verbs are
|
||||
`rig context compose|list|show|preview|sync|add|rm`; delivery belongs to
|
||||
`rig send --context`, `rig broadcast --context`, `rig walk --through`, and
|
||||
`rig queue create --body-context`.
|
||||
|
||||
> Source: `routes/context-packs.ts` (complete route table);
|
||||
> `domain/startup-validation.ts` (file-only startup contract);
|
||||
> `packages/cli/src/commands/context.ts`, `send.ts`, `broadcast.ts`,
|
||||
> `walk.ts`, and `queue.ts` @HEAD.
|
||||
|
||||
## 2. Agent images (PL-016) — 0.3.0
|
||||
|
||||
An **agent image** is a snapshot bundle of a productive seat's resumable
|
||||
state: runtime-specific resume token (Claude `resume_token` / Codex
|
||||
`thread_id`), source-seat lineage, optional cwd-deltas + notes. Consumable
|
||||
by AgentSpec `session_source: mode: agent_image`. Filesystem-canonical at
|
||||
`~/.openrig/agent-images/<name>/` + workspace-local; **no SQLite tables**.
|
||||
|
||||
> Source: `domain/agent-images/agent-image-types.ts:1-13` @HEAD.
|
||||
|
||||
`AgentImageLibraryService` mirrors `ContextPackLibraryService` (scan / list
|
||||
/ get / last-wins) with three source-stated differences: `sourceResumeToken`
|
||||
passes through to consumers (instantiator consumes; operator surfaces
|
||||
redact); `stats.json` is a separate mutable file updated atomically on
|
||||
fork-count increment; a `.pinned` sentinel pins from prune. Id
|
||||
`agent-image:<name>:<version>`.
|
||||
|
||||
> Source: `domain/agent-images/agent-image-library-service.ts:5-14`
|
||||
> (3-difference comment), `:38-41` (id) @HEAD.
|
||||
|
||||
`discoverResumeToken(db, sourceSession)` queries `sessions` then `nodes`
|
||||
and returns a typed failure (`session_not_found`/`runtime_unsupported`)
|
||||
rather than fabricating a token; only `claude-code`/`codex` have a native
|
||||
fork primitive. Claude prefers `context_usage.session_id` over persisted
|
||||
`sessions.resume_token`; Codex uses `resume_token`, falling back to a
|
||||
binding's `external_session_name` for `external_cli` seats; returns
|
||||
`nativeId: null` honestly when none.
|
||||
|
||||
> Source: `domain/agent-images/resume-token-discovery.ts:37-85` (honest
|
||||
> null L84; Claude pref L64-69; external_cli L78-83); honesty comment
|
||||
> `:9-10` @HEAD.
|
||||
|
||||
`SnapshotCapturer.capture()` routes through `discoverResumeToken`, throws
|
||||
`AgentImageError` on failure or missing native id (no fabricated token, no
|
||||
auto-fallback to fresh), writes manifest + empty `stats.json` via
|
||||
`install()`, re-scans. Captured `nodeCwd` → manifest `source_cwd` so the
|
||||
Use-as-starter snippet emits `cwd:` (fork starts in the parent's directory
|
||||
where Claude's project-dir-scoped jsonl lives); the daemon does NOT
|
||||
override cwd at fork dispatch.
|
||||
|
||||
> Source: `domain/agent-images/snapshot-capturer.ts:60-104` (throw
|
||||
> L65-79; source_cwd L88-93; install+scan L101-102);
|
||||
> `routes/agent-images.ts:256-265` (no-cwd-override contract) @HEAD.
|
||||
|
||||
**Evidence guard (CATASTROPHIC-bounce; fails closed).**
|
||||
`evaluateProtection()` protects an image from deletion if ANY: pinned;
|
||||
referenced by an active `agent.yaml`; referenced by a rig spec; or a
|
||||
lineage descendant of a protected image (transitive, fixed-point
|
||||
iteration). Spec-root scanning parses YAML structure (not string-grep)
|
||||
and is deliberately conservative — false positives (over-protection)
|
||||
acceptable; false negatives = catastrophic data loss. `--force` /
|
||||
`?force=true` overrides.
|
||||
|
||||
> Source: `domain/agent-images/evidence-guard.ts:1-16` (bounce +
|
||||
> fail-closed), `:53-115` (direct + transitive; fixed point L92-112),
|
||||
> `:117-122` (conservative) @HEAD.
|
||||
|
||||
**Resume-token redaction at route boundary (LOAD-BEARING).**
|
||||
`/api/agent-images` redacts `sourceResumeToken` → `"(redacted)"` on every
|
||||
operator-facing path; tokens are **never returned over the wire**; only
|
||||
the in-process rigspec-instantiator consumes the real token.
|
||||
|
||||
> Source: `routes/agent-images.ts:15-17` + `:44-46` (`redactResumeToken`),
|
||||
> applied `:60`,`:67`,`:94`,`:161`; slice-00 0.3.0-GT §1.9 flags this
|
||||
> LOAD-BEARING @HEAD.
|
||||
|
||||
`agentImagesRoutes()` (mounted `server.ts:483-485`): `GET /library`,
|
||||
`POST /library/sync`, `GET /library/:id`, `GET /library/:id/preview`,
|
||||
`POST /library/:id/pin`, `POST /library/:id/unpin`,
|
||||
`DELETE /library/:id` (evidence-guarded unless `force=true`),
|
||||
`POST /snapshot`, `POST /prune` (**dry-run by default**,
|
||||
`dryRun !== false`); guard `specRoots` injected via
|
||||
`deps.agentImageSpecRoots`. CLI: `rig agent-image
|
||||
list|show|preview|create|delete|pin|unpin|prune|sync`.
|
||||
|
||||
> Source: `routes/agent-images.ts:54-250` (table; prune default L112;
|
||||
> delete-guard L224-239); `server.ts:483-485`;
|
||||
> `docs/as-built/cli-reference.md:895-912` @HEAD.
|
||||
|
||||
## 3. Plugins (plugin-primitive Phase 3a) — **0.3.1, NOT 0.3.0**
|
||||
|
||||
> **Forensic trap (slice-00 0.3.0-GT seam (a)):** the plugin-discovery
|
||||
> file's first-creating commit is dated the same day as the 0.3.0 release
|
||||
> commit but is NOT an ancestor of `v0.3.0`. Plugins are **0.3.1**.
|
||||
> Re-confirmed at HEAD by the §0 tag-presence test.
|
||||
|
||||
`PluginDiscoveryService` is a read-only filesystem aggregator — no SQLite,
|
||||
no mutation routes (SC-29 EXCEPTION #8, declared verbatim in the source
|
||||
header). It scans four source kinds, unioned with provenance labels:
|
||||
vendored (`~/.openrig/plugins/<id>/`), Claude cache
|
||||
(`~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/`), Codex cache
|
||||
(same under `~/.codex`), and rig-cwd (`<cwd>/.claude/plugins/*` +
|
||||
`<cwd>/.codex/plugins/*`). Detection = presence of
|
||||
`.claude-plugin/plugin.json` and/or `.codex-plugin/plugin.json` (declares
|
||||
`runtimes`). Slice 28 added `skillCount` (readdir of `<plugin>/skills/`)
|
||||
to the list response so the index page avoids an N+1 detail fetch
|
||||
(SC-29 EXCEPTION #11, verbatim).
|
||||
|
||||
> Source: `domain/plugin-discovery-service.ts:1-29` (SC-29 #8 + scan
|
||||
> desc), `:39` (4-kind `PluginSourceKind`), `listPlugins` `:205-276`
|
||||
> (4 scan blocks), `scanCwdBundledPlugins` `:283-307`, `detectPlugin`
|
||||
> `:393-453` (marker rule L399-404; `skillCount` L433-451 + #11
|
||||
> L75-80) @HEAD.
|
||||
|
||||
`getPlugin(id)` returns detail (manifests + skills + hooks + MCP servers);
|
||||
`rig-cwd:` ids are self-resolvable (parses the cwd out of the id prefix
|
||||
and re-scans so `/api/plugins/:id` does not 404 on an id `?cwd=`
|
||||
returned). `findUsedBy(id)` walks `agent.yaml` files parsing YAML
|
||||
structure (not string-grep — comments don't false-positive) to collect
|
||||
`resources.plugins[].id` + referencing profiles.
|
||||
|
||||
> Source: `domain/plugin-discovery-service.ts:309-369` (getPlugin;
|
||||
> rig-cwd self-resolve L310-321), `extractCwdFromRigCwdId` `:466-479`,
|
||||
> `findUsedBy` `:371-389`, `readResourcesPlugins` `:599-615`,
|
||||
> `readProfilesUsingPlugin` `:617-633` (structure-not-grep `:20-23`)
|
||||
> @HEAD.
|
||||
|
||||
`PluginVendorService.ensureLatest()` runs `ensureVendored` (hash-skip
|
||||
idempotent copy from `packages/daemon/assets/plugins/<name>/` to
|
||||
`~/.openrig/plugins/<name>/`) then `attemptAutoFetch`
|
||||
(`github.com/mvschwarz/openrig-plugins`, 5s timeout,
|
||||
**404/network/timeout tolerated silently** — vendored is ALWAYS the
|
||||
fallback; upstream repo intentionally empty at v0 so 404 is normal-state;
|
||||
NO tarball extraction at v0). Wired at startup for `openrig-core`.
|
||||
|
||||
> Source: `domain/plugin-vendor-service.ts:1-24`, `ensureVendored`
|
||||
> `:80-103` (hash-skip L97-99), `attemptAutoFetch` `:111-131`
|
||||
> (404-tolerant L116-117; no-extract L123-125), `ensureLatest`
|
||||
> `:138-141`; `startup.ts:434-472` @HEAD.
|
||||
|
||||
`pluginsRoutes()` (mounted `server.ts:478`, read-only): `GET /` (filters
|
||||
`?runtime=`, `?source=`, `?cwd=`), `GET /:id/used-by`,
|
||||
`GET /:id/files/list?path=`, `GET /:id/files/read?path=` (slice 28
|
||||
docs-browser), `GET /:id`. Literal sub-paths are mounted **before** the
|
||||
bare `/:id` catchall (route-order discipline). The files endpoints reuse
|
||||
the path-safety machinery with the discovered plugin's absolute path as a
|
||||
synthetic single-root allowlist (operator need not declare plugin paths
|
||||
in `OPENRIG_FILES_ALLOWLIST`; plugin folders read-only at v0 so the
|
||||
content hash is informational). CLI: `rig plugin
|
||||
list|show|used-by|validate`; no `install` verb at v0 (deferred to 0.3.2).
|
||||
|
||||
> Source: `routes/plugins.ts:29-39` + `:107-231` (table; before-catchall
|
||||
> L128-130/L141-142; `pluginRootAllowlist` :74-92; read-only-hash
|
||||
> L182-184); `server.ts:478`;
|
||||
> `docs/as-built/cli-reference.md:943-963` @HEAD.
|
||||
|
||||
> **OPEN-A** — `parseSourceFilter` (`routes/plugins.ts:69-72`) accepts
|
||||
> only `vendored|claude-cache|codex-cache`; it does NOT accept `rig-cwd`
|
||||
> though `PluginSourceKind` (`domain/plugin-discovery-service.ts:39`) and
|
||||
> `ListPluginsOpts.sourceFilter` include it. `?source=rig-cwd` is
|
||||
> silently dropped at the route while `?cwd=` still surfaces rig-cwd
|
||||
> entries unfiltered. Stated as-is; intent (rig-cwd reachable only via
|
||||
> `?cwd=`) vs filter-gap is not resolvable from source alone.
|
||||
|
||||
## 4. Claude auto-compaction enforcer (slice 27) — **0.3.1 headline**
|
||||
|
||||
> **No 0.3.0 antecedent (slice-00 0.3.0-GT map row 7).** The enforcer
|
||||
> file is absent at `v0.3.0`, present at `v0.3.1` (§0).
|
||||
|
||||
`ClaudeCompactionEnforcer.maybeAutoCompact()` decides per seat whether
|
||||
`ContextMonitor` should send `/compact`, driven by operator
|
||||
`policies.claude_compaction.*` settings. Decoupled from `ContextMonitor`
|
||||
scheduling; `ContextMonitor` is constructed with the enforcer at startup.
|
||||
|
||||
> Source: `domain/claude-compaction-enforcer.ts:7-12`, `maybeAutoCompact`
|
||||
> `:205-331`; `startup.ts:1191-1199` (enforcer →
|
||||
> `new ContextMonitor(db, contextUsageStore, claudeAdapter,
|
||||
> compactionEnforcer)`) @HEAD.
|
||||
|
||||
**Defensive contract** (source classifies compaction lifecycle as
|
||||
load-bearing per the banked permission-layer foot-gun rule):
|
||||
|
||||
- **Opt-in, default-off:** `enabled=false` → never triggers.
|
||||
- **Runtime filter:** triggers only when `runtime === "claude-code"`.
|
||||
- **Invalid-policy = disabled:** a hand-edited non-integer / out-of-
|
||||
`[1,100]` `thresholdPercent` is treated as disabled (safer-failure).
|
||||
- **Re-arm via threshold crossing:** session must drop below threshold
|
||||
before another auto-compact fires; window state NOT persisted (restart
|
||||
resets — safer-failure direction).
|
||||
- **Send-failure graceful-degrade:** returns `{ triggered: false,
|
||||
reason: "send_failed" }`, never throws; dedup timestamp set only on
|
||||
successful send so a transient failure retries next tick.
|
||||
|
||||
> Source: `domain/claude-compaction-enforcer.ts:14-44` (risk-class +
|
||||
> contract), runtime `:206-208`, invalid-policy `:224-232`,
|
||||
> dedup/threshold `:285-300`, send-fail `:312-314`/`:323-325` @HEAD.
|
||||
|
||||
**Active handshake state machine** (Claude hooks can supply context but
|
||||
do not create a new assistant turn): (1) **pre-compact prep** — first
|
||||
eligible above-threshold tick sends a normal user-channel prep prompt;
|
||||
state → `prep_prompt_sent`. (2) **/compact** — next eligible tick sends
|
||||
`/compact <instruction> + trust-channel bridge note`; sets dedup
|
||||
timestamp + `triggeredAboveThreshold`; queues post stage
|
||||
`turn_boundary`. (3) **post-compact, below threshold** — staged sends
|
||||
`turn_boundary` (ack-only) → `restore_prompt` (points at the pending
|
||||
marker `<openrigHome>/compaction/restore-pending/<key>.json`, transcript
|
||||
/ session-id fallbacks) → `compliance_prompt` (read-depth audit); final
|
||||
stage sets post-restore cooldown + clears the above-threshold latch.
|
||||
|
||||
> Source: `domain/claude-compaction-enforcer.ts:71-77` (compact+bridge),
|
||||
> `:79-98` (prep), `:108-145` (restore + marker path), `:147-163`
|
||||
> (compliance), `:165-171` (turn boundary), state machine `:233-330`
|
||||
> (below-threshold L233-283; above-threshold L302-330) @HEAD.
|
||||
|
||||
Policy fields via `SettingsStore.resolveClaudeCompactionPolicy()`:
|
||||
`enabled`, `thresholdPercent`, `preCompactInstruction`,
|
||||
`compactInstruction`, `messageInline`, `messageFilePath`,
|
||||
`postRestoreAuditInstruction` — each backed by a
|
||||
`policies.claude_compaction.*` key + `OPENRIG_POLICIES_CLAUDE_COMPACTION_*`
|
||||
env override. Defaults: dedup `60_000` ms; post-compact restore cooldown
|
||||
`10 * 60_000` ms.
|
||||
|
||||
> Source: `domain/user-settings/settings-store.ts:553-565` (resolver),
|
||||
> keys `:97-103`, env `:145-151`;
|
||||
> `domain/claude-compaction-enforcer.ts:45-46` (default windows) @HEAD.
|
||||
|
||||
## 5. Cross-cutting properties
|
||||
|
||||
- **Filesystem-canonical, no new SQLite** across all four; daemon caches
|
||||
in-memory; compaction window state intentionally not persisted
|
||||
(context-pack-types.ts:8-11; agent-image-types.ts:12-13;
|
||||
routes/plugins.ts:6; claude-compaction-enforcer.ts:26-29) @HEAD.
|
||||
- **Honest failure, no fabrication** — discovery returns null; capturer
|
||||
throws; enforcer degrades + never throws; evidence guard fails closed
|
||||
(resume-token-discovery.ts:9-10; snapshot-capturer.ts:11-12;
|
||||
claude-compaction-enforcer.ts:30-33; evidence-guard.ts:16) @HEAD.
|
||||
- **503-when-unprovisioned** is the uniform route pattern when the
|
||||
backing service is absent from context (routes/context-packs.ts:31;
|
||||
routes/agent-images.ts:59; routes/plugins.ts:113) @HEAD.
|
||||
|
||||
## OPEN items (carried, not smoothed)
|
||||
|
||||
- **OPEN-A** — plugin `?source=` filter omits `rig-cwd` (§3); intent vs
|
||||
filter-gap unresolvable from source.
|
||||
- No slice-00 numeric-drift OPEN (1–5) applies — this module carries no
|
||||
migration / route-group / PL-004-event counts. Slice-00 0.3.0-GT
|
||||
OPEN-3 (For-You verb subset) is out of scope (UI surface, not
|
||||
content-layer).
|
||||
@@ -1,242 +0,0 @@
|
||||
---
|
||||
kind: as-built
|
||||
title: Transport, Transcripts, Chat, Ask
|
||||
status: active
|
||||
topics: [coordination, observability]
|
||||
domains: [engineering-advisor, operating-advisor]
|
||||
applies-when: |
|
||||
Need to know how rig send/capture/broadcast works, how pipe-pane transcript
|
||||
capture and rg/grep search behave, how durable rig chat (SQLite + SSE) is
|
||||
modeled, what rig ask gathers, or the exact MCP-tool-name 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: 7eaf524c
|
||||
last-updated: 2026-05-16
|
||||
---
|
||||
|
||||
# Transport, Transcripts, Chat, Ask
|
||||
|
||||
The communication-and-history layer: tmux is transport, not truth. Send/
|
||||
capture/broadcast wrap tmux with honest errors; transcripts are raw pipe-pane
|
||||
captures; chat is daemon-backed SQLite; `rig ask` gathers evidence but never
|
||||
calls an LLM.
|
||||
|
||||
> Verified against source at HEAD `7eaf524c` (`git describe` →
|
||||
> `v0.3.1-6-g7eaf524c`). Package version **0.3.1** (slice-00 §1.1). Source
|
||||
> located by `architecture.md` headings (§5 Transport and communication, §6
|
||||
> Communication/Transcript/Chat flows, §11 Compat notes) per slice-08 §10.1
|
||||
> — line numbers advisory only.
|
||||
|
||||
## 1. The naming axes (D5 — read this first)
|
||||
|
||||
This module carries the D5 drift, which has **two independent axes** that
|
||||
must NOT be conflated or blanket-replaced (banked
|
||||
`feedback_release_prep_three_layer_depersonalization`: the rename was scoped,
|
||||
not global). Per-occurrence source verification:
|
||||
|
||||
**Axis 1 — MCP tool names: `rig_*` (architecture.md is STALE → corrected).**
|
||||
slice-00 §1.4 confirms all 17 MCP tools are `rig_*`. The `rigged_*`
|
||||
references in `architecture.md` are stale text from a rename that predates
|
||||
v0.2.0:
|
||||
|
||||
> Drift-fix D5 (MCP-tool-name axis) — `architecture.md` §5 `node-inventory.ts`
|
||||
> description says MCP `rigged_rig_nodes`; §6 chat flow says MCP
|
||||
> `rigged_chatroom_send` + `rigged_chatroom_watch`. Corrected to **`rig_*`**.
|
||||
> Re-confirmed at source: `mcp-server.ts:288` registers `"rig_rig_nodes"`,
|
||||
> `:305` `"rig_send"`, `:339` `"rig_capture"`, `:364` `"rig_chatroom_send"`,
|
||||
> `"rig_chatroom_watch"` (tool #17). Zero `rigged_chatroom_send` /
|
||||
> `rigged_send` / `rigged_rig_nodes` in non-test product source (grep clean
|
||||
> @HEAD). slice-00 §1.4; the rename landed in `b183c50c` pre-v0.2.0.
|
||||
|
||||
**Axis 2 — tmux metadata keys: `@rigged_*` (architecture.md is CORRECT → do
|
||||
NOT change).** The tmux metadata keys written at claim/bind time are a
|
||||
SEPARATE thing from MCP tool names and were NOT renamed:
|
||||
|
||||
> Drift-nuance D5 (tmux-metadata-key axis) — `architecture.md` §6 "Whoami
|
||||
> and adopted-session parity flow" lists `@rigged_node_id`,
|
||||
> `@rigged_session_name`, `@rigged_rig_id`, `@rigged_rig_name`,
|
||||
> `@rigged_logical_id`. These are **CORRECT as-is** — verified literally at
|
||||
> source: `claim-service.ts:77-81` writes exactly these five `@rigged_*`
|
||||
> keys. Do NOT blanket-sed `rigged` → `rig`; this is a per-occurrence
|
||||
> verify, not a global substitution. (The metadata-key axis is detailed in
|
||||
> `agent-spec-and-startup.md` §6.) Re-confirmed `claim-service.ts:77-81`
|
||||
> @HEAD.
|
||||
|
||||
## 2. Transport and communication domain services
|
||||
|
||||
(`architecture.md` §5 "Transport and communication")
|
||||
|
||||
- `session-transport.ts` — communication primitives: send/capture/broadcast
|
||||
with session resolution (canonical + legacy names), mid-work detection,
|
||||
honest error reporting, pod/rig/global targeting.
|
||||
- `transcript-store.ts` — pipe-pane transcript management: ANSI stripping on
|
||||
read, boundary markers, readTail, grep. Filesystem-backed, NOT SQLite.
|
||||
- `history-query.ts` — transcript + chat search. Prefers `rg` when
|
||||
available, falls back to `grep -E`, surfaces which backend was used.
|
||||
Re-confirmed: `history-query.ts:7` `backend: "rg" | "grep" | "none"`;
|
||||
`:103` execs `rg -i --no-filename -e <pattern>`; `:108` returns
|
||||
`backend: "rg"`.
|
||||
- `ask-service.ts` — context-engineering evidence pack: gathers rig summary
|
||||
plus transcript excerpts, chat excerpts, insufficiency state, guidance.
|
||||
Does NOT call an external LLM.
|
||||
- `chat-repository.ts` — durable rig-scoped chat: CRUD for `chat_messages`
|
||||
table, SSE-compatible event emission.
|
||||
|
||||
Routes: `routes/{transport,transcripts,ask,chat,whoami}.ts` — all confirmed
|
||||
present @HEAD.
|
||||
|
||||
## 3. Communication flow
|
||||
|
||||
(`architecture.md` §6 "Communication flow")
|
||||
|
||||
`rig send <session> "message"` → CLI → `POST /api/transport/send` →
|
||||
`SessionTransport`:
|
||||
|
||||
1. Resolve session name (canonical or legacy; by session/rig/pod/global).
|
||||
2. Check mid-work state (unless `--force`) — re-confirmed
|
||||
`session-transport.ts:136-141` (`findPatternEvidence(recentLines,
|
||||
MID_WORK_PATTERNS)`); legacy mid-work check at `:666`.
|
||||
3. Two-step tmux send: a unique file/buffer pasted with `paste-buffer -d -r -p` at every payload size → ~200ms delay → separate `C-m`. Bracketed paste preserves multiline input in supporting TUIs; the payload never enters a shell argument. A successful paste proves transport execution, not runtime consumption.
|
||||
(`session-transport.ts:717` submits `C-m`).
|
||||
4. Optional `--verify`: capture post-send pane, check message visibility
|
||||
(`session-transport.ts:305` `verify?`; `:694` `if (opts?.verify)`).
|
||||
5. Honest result with reason on failure.
|
||||
|
||||
Architecture Rule 18 (carried, `architecture.md` §7): tmux is transport, not
|
||||
truth — `send/capture/broadcast` wrap tmux reliably with honest errors.
|
||||
|
||||
### 3b. Cross-host coordination verbs (v0.4.6 — OPR.0.4.6.MH4)
|
||||
|
||||
`rig send/capture/transcript/broadcast --host <id>` (and the `agent@rig@host`
|
||||
target sugar on the session-target verbs) cross the host boundary with **zero
|
||||
daemon-side changes** — the remote daemon's existing local routes do all the
|
||||
work; the only net-new is the CLI transport branch.
|
||||
|
||||
- **The seam principle (arch-ruled): SIDEDNESS + CALLER pick the seam.**
|
||||
ONE-SIDED remote ops from a BEARER-CAPABLE caller (the CLI resolves the
|
||||
registry bearer locally) go **CLI-DIRECT** via the shipped
|
||||
`runRemoteHttpOp` — one hop, no local-daemon involvement (the
|
||||
`ps --all-hosts` precedent). TWO-SIDED ops (MH-3's queue handoff closes the
|
||||
local source and creates the remote successor — the local daemon owns half
|
||||
the transaction) or BEARER-INCAPABLE callers (the browser: MC-action,
|
||||
MH-2's read-through) use the **daemon-side forward-then-strip**. MH-4's
|
||||
four verbs are pure one-sided remote ops from the CLI.
|
||||
- **Transport is dictated by the host entry (ssh XOR http), never a
|
||||
per-call choice:** ssh hosts keep the shipped shell-out byte-verbatim for
|
||||
send/capture; http hosts (the `pair` front door's kind) take the
|
||||
CLI-direct branch to `POST /api/transport/send|capture|broadcast` /
|
||||
`GET /api/transcripts/*` with the SAME bodies/paths the local CLI builds
|
||||
(one route, two callers = wrap parity by construction). transcript and
|
||||
broadcast are http-only (no ssh path exists for them); a wrong-transport
|
||||
verb dies with the structured requirement error — never a fallback.
|
||||
- **Terminal-bearer posture (named limitation, v0 — `/api/transport/*`
|
||||
ONLY):** the remote's transport routes (send/capture/broadcast) gate on
|
||||
ITS TERMINAL bearer class (`OPENRIG_TERMINAL_BEARER_TOKEN`, default null →
|
||||
pass-through; the tailnet is the auth boundary by design), while 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 surfaces as the structured `permission-gate`
|
||||
step (never a hang, never silent). 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 (arch n2):**
|
||||
`/api/transcripts/*` mounts UNGATED (`server.ts` — the shipped open-route
|
||||
posture; daemon-local trust boundary with route-level credential
|
||||
redaction as the protective primitive), so a wrong terminal bearer that
|
||||
permission-gates `send --host` does NOT gate `transcript --host` — the
|
||||
read keeps succeeding, and the proof matrix must not treat the auth-fail
|
||||
class as uniform across the four verbs. A coherent transcript-read auth
|
||||
policy across tail/grep/full is a named future slice per
|
||||
`routes/transcripts.ts`'s own comment (orch approved-option-a).
|
||||
Bearer-class unification is likewise a NAMED follow-up, not v0 (no
|
||||
un-asked auth machinery).
|
||||
- **BR-1 holds:** the 3-part form is CLI-edge sugar only (suffix must match
|
||||
a REGISTERED host id, else passthrough + 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 MH-3's queue — MH-4
|
||||
adds no queue surface.
|
||||
|
||||
## 4. Transcript flow
|
||||
|
||||
(`architecture.md` §6 "Transcript flow")
|
||||
|
||||
1. `NodeLauncher` starts `pipe-pane` immediately after tmux session creation
|
||||
(before harness boot).
|
||||
2. Raw terminal output streams to
|
||||
`~/.openrig/transcripts/{rig-name}/{session-name}.log`.
|
||||
3. `TranscriptStore` owns path convention, ANSI stripping on read, boundary
|
||||
markers, `readTail`, `grep`.
|
||||
4. `rig transcript <session> --tail N / --grep "pattern"` provides
|
||||
agent-facing access.
|
||||
5. On restore: a boundary marker is written before re-launch; pipe-pane
|
||||
reconnects to the same file (append). (Restore-side detail in
|
||||
`lifecycle-snapshot-restore.md` §3.)
|
||||
6. `rig ask` gathers rig summary plus transcript excerpts, chat excerpts,
|
||||
insufficiency state, and guidance.
|
||||
|
||||
Architecture Rule 19 (carried): transcripts are raw capture via pipe-pane,
|
||||
ANSI strip on read; `rg` preferred, `grep -E` fallback. Rule 22: `rig ask`
|
||||
is context engineering — gathers evidence, does NOT call an external LLM;
|
||||
the agent IS the LLM.
|
||||
|
||||
## 5. Chat flow
|
||||
|
||||
(`architecture.md` §6 "Chat flow")
|
||||
|
||||
1. `rig chatroom send <rig> "message"` → `POST
|
||||
/api/rigs/:rigId/chat/send` → `ChatRepository.addMessage()`.
|
||||
2. SSE: `GET /api/rigs/:rigId/chat/watch` delivers real-time messages.
|
||||
3. History: `GET /api/rigs/:rigId/chat/history` returns full channel
|
||||
history; `POST /api/rigs/:rigId/chat/topic` persists topic markers.
|
||||
4. UI: chat-room tab in the rig drawer.
|
||||
5. MCP: **`rig_chatroom_send` + `rig_chatroom_watch`** (D5 axis-1 correction
|
||||
— `architecture.md` §6 said `rigged_*`; source `mcp-server.ts:364` +
|
||||
tool #17).
|
||||
6. Source of truth: daemon-backed SQLite (`chat_messages` table), NOT tmux
|
||||
scrollback.
|
||||
|
||||
**ChatMessage** type (`architecture.md` §4): durable rig-scoped message —
|
||||
`id`, `rigId`, `sender`, `kind`, `body`, `topic`, `createdAt`.
|
||||
|
||||
## 6. Compatibility notes (carried verbatim, `architecture.md` §11)
|
||||
|
||||
The intentional limits in this layer:
|
||||
|
||||
- Note 4 — `rig ask` gathers context only; does not call an external LLM.
|
||||
The agent reasons about the gathered evidence.
|
||||
- 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` checks pane content for message
|
||||
visibility but can produce false positives from pre-existing matching
|
||||
content. Known limitation.
|
||||
|
||||
(The full §11 compatibility-notes list lives in
|
||||
`architecture-rules-and-event-system.md`.)
|
||||
|
||||
## OPEN / carried items
|
||||
|
||||
- **D5 (the careful one — resolved per-occurrence, NOT blanket-replaced):**
|
||||
Axis 1 (MCP tool names) corrected `rigged_*` → `rig_*` (3 sites: §5
|
||||
node-inventory, §6 chat flow ×2). Axis 2 (tmux `@rigged_*` metadata keys)
|
||||
verified literally correct at `claim-service.ts:77-81` and left unchanged.
|
||||
No slice-00 numeric drift applies to this module's split content.
|
||||
|
||||
## See also
|
||||
|
||||
- `daemon-core.md` — transport/transcript/chat/ask are among the 49 route
|
||||
mounts; MCP tool count (17, `rig_*`) is anchored there.
|
||||
- `agent-spec-and-startup.md` §6 — the tmux `@rigged_*` metadata-key axis
|
||||
detail (whoami/adopt).
|
||||
- `lifecycle-snapshot-restore.md` §3 — restore-side transcript boundary
|
||||
markers.
|
||||
- `coordination-primitive.md` §3b — MH-3's cross-host QUEUE routing (the
|
||||
two-sided daemon-forward twin of §3b's one-sided CLI-direct verbs).
|
||||
- `cli-reference.md` § Cross-host execution — the per-verb transport
|
||||
capability table, parse rules, and http failure taxonomy (MH-3 + MH-4).
|
||||
- Source roots: `packages/daemon/src/domain/{session-transport,
|
||||
transcript-store,history-query,ask-service,chat-repository}.ts`,
|
||||
`packages/daemon/src/routes/{transport,transcripts,ask,chat}.ts`,
|
||||
`packages/cli/src/mcp-server.ts`,
|
||||
`packages/cli/src/{remote-host-ops,cross-host-target,cross-host-executor}.ts` (v0.4.6 MH-4).
|
||||
@@ -1,509 +0,0 @@
|
||||
---
|
||||
kind: as-built
|
||||
title: Workflow Runtime + Watchdog Policies (PL-004 Phase C/D)
|
||||
status: active
|
||||
topics: [coordination, runtime-control]
|
||||
domains: [engineering-advisor, operating-advisor]
|
||||
applies-when: |
|
||||
Need to know how the daemon-native Workflow Runtime works — workflow specs
|
||||
cache, instance state, step trails, the transactional-scribe projection
|
||||
contract, or the watchdog policy set including workflow-keepalive.
|
||||
siblings: [coordination-primitive.md, mission-control.md]
|
||||
prerequisite-reads: [../README.md, coordination-primitive.md]
|
||||
last-verified-against-source: slice/opr-0.4.6.wf2-spec-language tip (base d18907ed — WF-1 merged)
|
||||
last-updated: 2026-07-06
|
||||
---
|
||||
|
||||
# Workflow Runtime + Watchdog Policies (PL-004 Phase C/D)
|
||||
|
||||
The daemon-native Workflow Runtime (PL-004 Phase D) turns an intended
|
||||
sequence of work into durable SQLite state: declarative workflow specs, live
|
||||
instance state, append-only step trails, and the load-bearing
|
||||
transactional-scribe contract. The PRD §L4 operating model is
|
||||
owner-as-author semantically plus workflow-as-transactional-scribe
|
||||
mechanically (`architecture.md` §3 L398).
|
||||
|
||||
> Verified against source at HEAD `7eaf524c`.
|
||||
|
||||
## 1. The three Phase D tables (+ the diagnostic addition)
|
||||
|
||||
Re-confirmed at HEAD in `packages/daemon/src/db/migrations/`:
|
||||
|
||||
- **`workflow_specs`** (`033_workflow_specs.ts:33` `CREATE TABLE … workflow_specs`)
|
||||
— a read-through cache of human-authored markdown/YAML spec files. Sources
|
||||
are workspace-surface; the daemon caches by `(name, version)` with a
|
||||
content `source_hash` so valid operator edits to the spec file win at next
|
||||
read (workspace-surface reconciliation). Spec authoring stays
|
||||
markdown-authoritative; the cache exists for fast lookup and runtime
|
||||
resolution (`architecture.md` §3 L400).
|
||||
- **`workflow_instances`** (`034_workflow_instances.ts:45` `CREATE TABLE …
|
||||
workflow_instances`) — live state per running workflow: `status`
|
||||
(`active|waiting|completed|failed`), `current_frontier_json` (active qitem
|
||||
ids), `hop_count` (loop-guard counter), `last_continuation_decision_json`.
|
||||
Instances survive daemon restart from SQLite — no filesystem
|
||||
reconciliation (`architecture.md` §3 L402).
|
||||
- **`workflow_step_trails`** (`035_workflow_step_trails.ts:32` `CREATE TABLE …
|
||||
workflow_step_trails`) — append-only history of meaningful step
|
||||
transitions. Every closure produces one trail row pairing the prior qitem
|
||||
with the next qitem (null on terminal). `WorkflowStepTrailLog.record()` is
|
||||
the only writer (`architecture.md` §3 L404).
|
||||
- **`040_workflow_specs_diagnostic.ts`** — slice-11 (`f68f453a`,
|
||||
slice-00 §1.3 provenance). An `ALTER TABLE ADD COLUMN` adding
|
||||
parser/validator diagnostic columns to `workflow_specs` (**no new table,
|
||||
no constraint changes beyond a DEFAULT**; the cache carries the
|
||||
parse/validation diagnostic for the UI to render — `040_..._diagnostic.ts:5–25`).
|
||||
**This migration is net-new since `architecture.md` was last edited** and
|
||||
is not described in any prior as-built doc (slice-00 §1.3 — `f68f453a`
|
||||
postdates the §3 body) — authored here from source per the slice-08
|
||||
drift-to-fix register.
|
||||
|
||||
`036_watchdog_policy_enum_extension.ts` is a documenting no-op that records
|
||||
the Phase D watchdog enum extension (Phase C uses application-layer
|
||||
enforcement via the `PHASE_D_POLICIES` array, so no DDL is needed —
|
||||
`architecture.md` §3 L363).
|
||||
|
||||
## 2. The transactional-scribe contract
|
||||
|
||||
The load-bearing Phase D guarantee is implemented in
|
||||
`WorkflowProjector.project()` (`packages/daemon/src/domain/workflow-projector.ts`).
|
||||
Re-confirmed at HEAD: the projector header (`workflow-projector.ts:1–20`)
|
||||
declares "transactional-scribe contract" and `project()` runs a single
|
||||
`db.transaction` (`workflow-projector.ts:184` `const txn = this.db.transaction(...)`).
|
||||
Inside that one transaction:
|
||||
|
||||
1. Close the current packet (state mutation on `queue_items`).
|
||||
2. Create the next-step packet (`QueueRepository.createWithinTransaction()`,
|
||||
`workflow-projector.ts:230`).
|
||||
3. Record the trail entry.
|
||||
4. Update the instance frontier + status.
|
||||
5. Persist workflow events.
|
||||
|
||||
Either everything commits or everything rolls back; lost handoffs are
|
||||
impossible by design. Post-commit, subscribers are notified and the next
|
||||
owner is nudged (`architecture.md` §3 L406).
|
||||
|
||||
`WorkflowRuntime` (`packages/daemon/src/domain/workflow-runtime.ts:61`
|
||||
`export class WorkflowRuntime`) is the orchestration class above the
|
||||
projector.
|
||||
|
||||
**Phase D scope boundary** (`architecture.md` §3 L412): excludes multi-hop
|
||||
chaining, gate-return-sweep, and the closure-enforcement path. The daemon's
|
||||
transactional state remains the closure authority via Phase A's hot-potato
|
||||
strict-rejection (see `coordination-primitive.md` §3); the workflow runtime
|
||||
**projects on closure, it does not gate closure**.
|
||||
|
||||
## 3. The workflow-keepalive watchdog policy
|
||||
|
||||
`workflow-keepalive` is the Phase C-deferred watchdog policy, a TypeScript
|
||||
port of the POC `lib/policies/workflow-keepalive.mjs` adapted to read SQLite
|
||||
(`packages/daemon/src/domain/policies/workflow-keepalive.ts:1–5`).
|
||||
Re-confirmed at HEAD (`workflow-keepalive.ts:5–16`):
|
||||
|
||||
- **LOAD-BEARING:** it MUST read `workflow_instances` directly via SQLite —
|
||||
never the markdown source.
|
||||
- Eligibility: `status === "active" || status === "waiting"`. Else
|
||||
`action=terminal, reason="workflow_not_active"`.
|
||||
- Frontier empty + no fallback target: skip with `reason="empty_frontier"`.
|
||||
- Resolves frontier qitem owners by querying `queue_items`; combines with
|
||||
explicit observer/created-by targets; sends to the first resolved target.
|
||||
|
||||
The watchdog supervision tree itself (PL-004 Phase C, `031_watchdog_jobs.ts` /
|
||||
`032_watchdog_history.ts`) records only meaningful evaluations; quiet skip
|
||||
reasons (`not_due`, `no_actionable_artifacts`, `active_wake_not_due`) are
|
||||
NOT recorded and do NOT emit `watchdog.*` events — POC parity so agents are
|
||||
not woken about scheduler polls (`architecture.md` §3 L362). The Phase D
|
||||
policy enum extends Phase C's three values with `workflow-keepalive`.
|
||||
|
||||
## 4. Workflow events
|
||||
|
||||
> Drift-fix D8 / OPEN-4 (carried verbatim, slice-00): `architecture.md` §3
|
||||
> L410 says "Existing 20 PL-004 events are unchanged" — internally
|
||||
> inconsistent with L394's "32 PL-004 events untouched". **Do NOT carry
|
||||
> either number.** The current `RigEvent` union
|
||||
> (`packages/daemon/src/domain/types.ts:94`) has **73 members** total
|
||||
> (slice-00 §1.8, re-confirmed at HEAD). The additive Phase D `workflow.*`
|
||||
> events are described below WITHOUT asserting a contested PL-004 sub-count.
|
||||
|
||||
Phase D extends `RigEvent` with the additive `workflow.*` events
|
||||
(re-confirmed `domain/types.ts:196–201`): `workflow.instantiated`,
|
||||
`workflow.step_closed`, `workflow.next_qitem_projected`,
|
||||
`workflow.completed`, `workflow.failed`, `workflow.routing_table_changed`
|
||||
(6 members; a separate `workflow_spec` event also exists in the union).
|
||||
|
||||
## 5. Route surface
|
||||
|
||||
`/api/workflow` (`server.ts:495`) — `POST /validate`
|
||||
(`routes/workflow.ts:82`), `POST /instantiate` (`:93`,
|
||||
`getRuntime(c).instantiate(...)`), `POST /project` (`:118`,
|
||||
`getRuntime(c).project(...)` — the transactional-scribe entry),
|
||||
`GET /:instance_id/trace` (instance + trail), `POST /:instance_id/continue`
|
||||
(idempotent inspect). Surface enumerated `routes/workflow.ts:21–28`.
|
||||
Cross-ref: the `rig workflow` CLI surface — see `../cli-reference.md`.
|
||||
|
||||
## 6. The WF-1 failure envelope (OPR.0.4.6.WF1)
|
||||
|
||||
Added on top of the kept Phase D core (nothing above was re-specced;
|
||||
FR-1 regression tests pin it):
|
||||
|
||||
- **Step deadlines (FR-2, derived — never stored):**
|
||||
`workflow-deadline.ts` classifies every active|waiting instance's
|
||||
frontier packet by anchor — claimed w/ `closure_required_at` ·
|
||||
claimed w/ NULL deadline (`claimed_at` + threshold; workflow packets
|
||||
ship tier `mode2`, which has no SLA entry) · never-claimed
|
||||
(`created_at` + threshold) · unclaimed-after-claim (`created_at`;
|
||||
unclaim NULLs `claimed_at`). `WORKFLOW_STEP_STUCK_THRESHOLD_SECONDS`
|
||||
(4h, = the routine-tier SLA) is THE single threshold home; WF-5
|
||||
binds to it. Stuck self-clears on normal re-projection.
|
||||
- **Keepalive auto-arm (FR-3):** instantiate + every handoff ensure
|
||||
ONE per-instance `workflow-keepalive` watchdog job INSIDE the scribe
|
||||
transaction; terminal exits disarm it. Auto-armed jobs carry
|
||||
`context.deadline_gated: true` — quiet while healthy, and their
|
||||
overdue send targets the stuck packet's owner with re-project
|
||||
steering. Operator-registered jobs keep exact POC always-send parity.
|
||||
- **Boot sweep (FR-4):** `workflow-boot-sweep.ts` at daemon startup —
|
||||
re-arms missing keepalives, reissues LOST post-commit nudges
|
||||
(pending frontier packet with `last_nudge_attempt` NULL = the
|
||||
commit-then-crash window, detected from the nudge ledger), surfaces
|
||||
stuck instances; one summary log line.
|
||||
- **Real idempotency (FR-5):** waiting-replay ABSORPTION under the
|
||||
full closure-intent identity (exit/packet/step/actor/resultNote/
|
||||
effective-blocker/evidence deep-equal) — exact replay = zero writes;
|
||||
any mismatch = a new decision via the normal path. Migration 049
|
||||
adds `workflow_instances.version`: every guarded advance bumps it
|
||||
`WHERE version = ?`; a stale writer gets structured
|
||||
`instance_version_conflict` and its whole transaction rolls back.
|
||||
- **max_hops enforced (FR-6):** compared at projection via
|
||||
`exceedsMaxHops(hopCount, baseline, maxHops)` (v1 baseline = 0; the
|
||||
baseline is WF-5's resume seam). Exceeding converts the handoff to
|
||||
an honest structured failure (packet closed, instance failed, guard
|
||||
evidence in trail + `workflow.failed`). Migration 050 adds
|
||||
`workflow_specs.spec_json` — before it, `loop_guards`/`invariants`/
|
||||
`closure`/`entry` were silently DROPPED at projection-time
|
||||
rehydration (column-only rebuild); legacy rows self-heal on
|
||||
readThrough and degrade VISIBLY (named once-per-spec advisory).
|
||||
- **Validation (FR-7):** `parseWorkflowSpec` rejects unknown keys loud
|
||||
at every level against EXPORTED closed keysets (WF-2 extends them);
|
||||
the validator walks reachability/cycles over the projector's own
|
||||
exported `resolveNextStep` — unreachable steps fail; a cycle without
|
||||
`max_hops` fails naming the fix; with it, sanctioned.
|
||||
- **`continue` honesty (FR-8):** relabeled to its real read-only
|
||||
inspector semantics everywhere (CLI description/outcome, route
|
||||
comment); `project` remains the sole advance write path.
|
||||
- **The v2 dispositions (FR-9):** every declared-but-unenforced key —
|
||||
`invariants.{continuation_required,preserve_lineage,closure_required}`,
|
||||
`closure.*`, step `gates[]`, role `skill_refs`, `next_hop.mode:
|
||||
prefer`, `loop_guards.spawn_budget` — produces the fail-open
|
||||
`declared_not_enforced_v1` validator advisory (warning; never
|
||||
blocks). `spawn_budget`'s advisory names its WF-2/WF-6
|
||||
parallel-frontier acceptance pointer (arch ruling 2026-07-06).
|
||||
`fallbackSynthesis` (instance column, never written) is dispositioned
|
||||
in the `workflow-types.ts` JSDoc.
|
||||
|
||||
## 7. The WF-2 spec language (OPR.0.4.6.WF2)
|
||||
|
||||
WF-2 grows the language the ratified WF-1 engine speaks. ONE named
|
||||
engine extension (branch execution); everything else is language +
|
||||
compilation onto shipped seams.
|
||||
|
||||
**Conditional-on-outcome branching (FR-1).** A step may declare
|
||||
`next_hop.on: {<exit>: <step-id>}` — branch keys are the recorded exit
|
||||
enum ONLY (`handoff|waiting|done|failed`; closed set, enforced at
|
||||
parse — `spec_branch_key_invalid`). A MAPPED exit routes to its target
|
||||
INSIDE the same scribe transaction: next qitem created in-txn, instance
|
||||
stays ACTIVE bound to the target, hop count + version guard bumped
|
||||
identically to a linear advance, and the taken branch recorded
|
||||
ADDITIVELY (`lastContinuationDecision.branchTaken` + the trail row's
|
||||
`closure_evidence.branch_taken`) — never in `closure_reason` (closed
|
||||
Phase-A enum). An UNMAPPED `failed`/`done` stays terminal exactly as
|
||||
before; unmapped `waiting` stays a park. The `max_hops` guard fires on
|
||||
ANY route (branch routes create the canonical remediation cycles);
|
||||
cycle detection at validation runs over the structural ∪ branch edge
|
||||
union and requires a declared `max_hops` to sanction any cycle.
|
||||
Routing seam: `resolveNextStep(spec, step, recordedExit?)` — one
|
||||
exported function, structural default when no exit supplied (the
|
||||
validator's path).
|
||||
|
||||
**Per-step `harness:` pin (FR-2).** `claude-code | codex` (agent
|
||||
harnesses only — `terminal` rejected at parse with a teaching error; Pi
|
||||
joins in 0.4.7). Owner resolution picks the first `preferred_target`
|
||||
whose node `runtime` column matches (`nodeRuntimeOf`: latest session →
|
||||
node join); no match = structured `harness_pin_unsatisfied` naming the
|
||||
pin + every candidate's runtime. Explicit owner overrides are
|
||||
reconciled too — an override can never silently defeat a pin. Static
|
||||
check at instantiate for every pinned step; re-checked at each route.
|
||||
|
||||
**Per-step `host:` pin (FR-3).** `local`/absent = full execution today.
|
||||
A registry id validates against `~/.openrig/hosts.yaml` (daemon
|
||||
read-only twin; unknown id = `host_not_registered` naming registered
|
||||
ids) but a remote pin fails loud at INSTANTIATE with
|
||||
`host_pin_remote_unsupported` naming the MH-3 boundary + workaround —
|
||||
the queue is local-only until MH-3; no qitem is ever minted into a
|
||||
queue that cannot route it, and there is no silent local fallback.
|
||||
|
||||
**Structured step-level `gate:` (FR-5 — the socket; WF-5 owns
|
||||
semantics).** Singular per step, closed keyset `{target, summary,
|
||||
evidence_ref}`. HUMAN target (the shipped human-seat predicate) →
|
||||
compiles to a human-routed item (tier `human-gate` + summary +
|
||||
evidence_ref — the shipped 0.4.4 write path), resolved by the shipped
|
||||
`resolve` verb; HANDLER-ROLE target → an ordinary agent item to the
|
||||
role's resolved seat. Routing INTO a gated step creates the gate item
|
||||
as the frontier packet and parks the instance `waiting`; resolve/close
|
||||
continues the flow from that step (the WF-1 unpark — no restart). A
|
||||
gated ENTRY step parks from birth.
|
||||
|
||||
**Dispositions (FR-4) — the inert third state is dead.** The legacy
|
||||
step `gates: [...]` string list is REMOVED at parse
|
||||
(`spec_gates_removed`, what/why/fix naming the new `gate:` object);
|
||||
`next_hop.mode: prefer` is REMOVED at parse
|
||||
(`spec_prefer_mode_removed` — it never had distinct behavior).
|
||||
`skill_refs` / `closure.*` / `invariants.{continuation_required,
|
||||
preserve_lineage,closure_required}` keep their WF-1 FR-9 explicitly-v2
|
||||
advisories; `spawn_budget` stays explicitly-v2 (WF-6/parallel-frontier
|
||||
acceptance pointer). Every key is consumed, removed, or
|
||||
machine-readably advisory — zero silently-inert keys.
|
||||
|
||||
**Versioning honesty (FR-6).** New strictness lands at
|
||||
`parseWorkflowSpec` (the only seam that sees raw keys; the WF-1
|
||||
exported closed keysets extended with `harness`/`host`/`gate` +
|
||||
`next_hop.on`) and applies at validate/instantiate/re-parse. A LIVE
|
||||
instance pinned to a pre-WF-2 spec version keeps executing un-failed
|
||||
(project() has no validation gate, by design; stored `spec_json` blobs
|
||||
missing the new optional fields read fine); the same spec FILE
|
||||
re-validated fails under the new rules.
|
||||
|
||||
**Hand-authorability (FR-6).** Three shipped example shapes at
|
||||
`packages/daemon/src/builtins/workflow-specs/`: `linear-build.yaml`
|
||||
(zero WF-2 features — the zero-regression reference),
|
||||
`gated-release.yaml` (human gate + harness pins),
|
||||
`branched-remediation.yaml` (bounded failed-path remediation loop).
|
||||
|
||||
**The composed RSI example (OPR.0.4.6.FAC2).** `factory-rsi.yaml` is the
|
||||
single-rig recursive-self-improvement factory MVP: it composes the branch +
|
||||
gate + guard primitives into the inner loop — `plan → implement → qa_check →
|
||||
review → release_prep` — where `qa_check`/`review` branch `failed` back to
|
||||
`implement` (bounded remediation) and `release_prep` (the release-manager
|
||||
prepares artifacts, un-gated) hands off to a human-gated `release_signoff`.
|
||||
Dogfood is decoupled from this gated loop: the dogfood seat runs out-of-band
|
||||
against the shipped product and feeds its findings into the next plan (the RSI
|
||||
edge, ungated). The remediation loops are sanctioned only by the enforceable
|
||||
`loop_guards.max_hops`; a trip is a WF-5 exception (orchestrator-first via
|
||||
`exception_routing`). It targets the shipped `factory-rsi` launch starter
|
||||
(`specs/rigs/launch/factory-rsi/`) whose seats pin 1:1 to its roles via
|
||||
`preferred_targets` — the v0 hardcode seam, no binding layer.
|
||||
|
||||
## The CLI surface (OPR.0.4.6.WF3)
|
||||
|
||||
WF-3 made the CLI the primary human/agent driving surface. Render-side
|
||||
by rule (BR-2): `run`/`watch` consume the shipped SSE endpoints
|
||||
(snapshot-first-then-stream, priorQitemId dedup, reconnect → announced
|
||||
poll fallback, outcome-as-exit-code: 0 completed / 3 failed);
|
||||
`trace`/`list`/`show` human modes are formatted (argo-shape tree, ps-
|
||||
mechanics columns, ATTN markers) while `--json` stays byte-stable;
|
||||
`status` composes the needs-attention rollup CLI-SIDE from the
|
||||
API-carried `instance.deadline` classification (one threshold home —
|
||||
the CLI never recomputes a class). The two daemon additions:
|
||||
|
||||
- **`route`** (`POST /api/workflow/:id/route`, runtime `route()`):
|
||||
close+recreate+rebind in ONE scribe transaction — honest
|
||||
`handed_off_to` closure with provenance, successor recreate (same
|
||||
step; `current_step_id` unchanged; no hop bump — route is not an
|
||||
advance), frontier rebind under the version guard, keepalive
|
||||
re-target in-txn. Advance-authority revocation is STRUCTURAL: the
|
||||
old packet leaves the frontier in the transaction, so a zombie
|
||||
owner's stale `project` hits the shipped `packet_not_on_frontier`
|
||||
409.
|
||||
- **The frontier close-path guard** (`workflow-frontier-guard.ts` →
|
||||
INJECTED into `QueueRepository` at startup; the queue never imports
|
||||
the workflow domain): terminal closure of a live frontier packet
|
||||
from non-workflow verbs rejects `workflow_frontier_packet` with a
|
||||
what/why/fix naming `rig workflow project` / `route`. Workflow
|
||||
writers pass `viaWorkflowVerb`; non-workflow qitems see zero new
|
||||
behavior.
|
||||
|
||||
## The exception + human-gate model (OPR.0.4.6.WF5)
|
||||
|
||||
The deterministic engine's exception layer: the happy path stays
|
||||
orchestrator-free and PROVEN so; every exception becomes exactly one
|
||||
durable attention item the moment it exists; the responder resolves it
|
||||
and the flow resumes from where it stopped.
|
||||
|
||||
- **The taxonomy** (`workflow-exception.ts`): three closed classes as
|
||||
pure predicates over recorded state — `unmapped_failed` (recorded
|
||||
`status=failed`; a WF-2-mapped `failed` routes to remediation and is
|
||||
NOT an exception), `stuck_overdue` (the WF-1 deadline evaluator's
|
||||
verdict consumed verbatim — the single threshold home), and
|
||||
`human_gate_trip` (WF-2 HUMAN gates; the compiled park IS the item).
|
||||
Handler-role gate-trips are deterministic handoffs, not exceptions —
|
||||
classes (a)/(b) backstop the handler's own step. The occurrence key
|
||||
is the recorded packet id of the episode: re-detections dedupe,
|
||||
resolve+resume closes, a fresh packet is a NEW occurrence.
|
||||
- **The maturity dial** (`workflow-exception-router.ts` + the
|
||||
`exception_routing` spec grammar + the `workflow.exception_routing`
|
||||
settings key): target resolution = spec per-class → spec default →
|
||||
host dynamic key → ORCHESTRATOR-FIRST (the declared orchestrator
|
||||
role via the same `preferred_targets` pick step owners use) →
|
||||
registered-human selection (`workflow-human-destination.ts`). THE TIER SPLIT: `human-gate` rides
|
||||
ONLY human-routed positions — an orchestrator-routed item carries
|
||||
the ordinary tier so the shipped attention union (which matches on
|
||||
tier regardless of destination) never leaks it into NEEDS-YOU. The
|
||||
shipped attention predicate is untouched.
|
||||
- **Class (a) born-in-txn**: serial failure and unhandled dependency-branch
|
||||
failure share exception admission. The failed packet, dependency occurrence,
|
||||
owning item and staged wake commit together, even while an unrelated frontier
|
||||
keeps the instance active. Mapped remediation remains ordinary workflow work;
|
||||
an unmapped or max-hop failure requires an owner. An agent destination rejected
|
||||
as an unknown rig tries registered-human selection. Selection, admission,
|
||||
or storage failure rolls back the close; it never commits a phantom
|
||||
human alert. Other errors retain their original diagnosis. **Class (b) at detection**: the boot sweep and the keepalive
|
||||
evaluation call the injected ensurer (`workflow-exception-
|
||||
escalation.ts`) — occurrence-deduped against OPEN items by tag
|
||||
query, scoped to the exact workflow, instance and packet; the crash-surviving
|
||||
sweep re-creates a missed item. Normal projection, keepalive (including
|
||||
healthy/terminal returns), and boot (including completed instances) reconcile
|
||||
each overdue item's own packet. A resolved wait, completion or obsolete
|
||||
frontier packet closes only that occurrence with a retained transition;
|
||||
an overdue sibling stays open. Unknown provenance is retained. A later
|
||||
overdue episode can create a fresh item even when it reuses the same packet.
|
||||
- **Human selection and failure**: the existing `workspace.operator_seat_name`
|
||||
setting selects a registered human; when unset, exactly one registered human
|
||||
is required. No `human@host` alias is invented and no arbitrary choice is made
|
||||
among several humans. The setting and registry are read at fallback time,
|
||||
so a valid configured agent route needs no human registry. Missing, ambiguous,
|
||||
invalid or unavailable selection produces `workflow_human_destination_unavailable`
|
||||
(HTTP 409 for failed projection). Fix the registration/selection and retry.
|
||||
Detection-time admission failures are logged by boot and included in the
|
||||
keepalive's existing owner nudge and evaluation notes; later detection retries.
|
||||
A registered destination still uses the gateway's ordinary delivery rules and
|
||||
receipt ledger. Admission is not proof of posting or readership.
|
||||
A capability inventory or detector instance-binding read failure propagates
|
||||
instead of becoming a no-match:
|
||||
failed projection returns HTTP 500 and rolls back its packet, instance and
|
||||
history writes; overdue detection surfaces the read error without an exception
|
||||
item. An evidenced no-match still uses registered-human selection.
|
||||
- **`resume`** (`POST /api/workflow/:id/resume`, runtime `resume()`,
|
||||
`rig workflow resume`): redrive semantics in ONE scribe transaction —
|
||||
failed→active REBOUND to the recorded failed step; the owner is
|
||||
RE-RESOLVED through the projection resolver (never copied from the
|
||||
stale destination — resume is the one sanctioned re-resolution
|
||||
point); `--decision` lands durably in the redrive packet; the
|
||||
occurrence's open items close with provenance; the trail is
|
||||
preserved, never rewritten. For a dependency graph, `--occurrence <failed-qitem-id>`
|
||||
selects the episode (required with several unresolved failures). Its resolution,
|
||||
redrive packet/wake and exact instance/occurrence exception closure share one
|
||||
transaction; siblings remain intact. An identical occurrence/decision retry
|
||||
returns the existing redrive; changed decision bytes conflict without mutation.
|
||||
THE LIVELOCK RAIL (migration 051):
|
||||
`hops_baseline` re-anchors the max_hops guard at resume so each
|
||||
redrive gets exactly one bounded window; `resume_count` is the
|
||||
recorded redrive fact; re-exceeding raises an honest NEW occurrence.
|
||||
- **The workflow-aware ▲ band** (`review/compose.ts
|
||||
deriveWorkflowExceptions` + the gatherer source): the missing-item
|
||||
backstop row, the stuck row with evaluator evidence, the
|
||||
frontier-non-open ANOMALY row (detection behind WF-3 FR-6's
|
||||
prevention), and THE AWARENESS ROW — an orchestrator-routed
|
||||
exception renders holder + age in the human band (one identity, two
|
||||
projections, count = 1); human-routed items render nothing there
|
||||
(the ● item is the row). Recomposition clears on state-exit.
|
||||
|
||||
## The workflow ↔ rig binding layer (OPR.0.4.6.FAC1)
|
||||
|
||||
Run any workflow on any rig that can support it, without editing the
|
||||
spec — the self-driving factory's binding substrate. Three seams:
|
||||
|
||||
- **A1 — bind at instantiation** (migration 052,
|
||||
`workflow_instances.bound_rig`): the effective binding =
|
||||
`--rig`/`targetRig` override `?? spec.target.rig ?? null`; the spec
|
||||
field stays a DEFAULT (no routing path reads it — display only). The
|
||||
rig NAME persists (the durable operator-space coordinate); name→id
|
||||
re-resolves fresh at each resolution site — a vanished rig fails loud
|
||||
(`bound_rig_not_found`), never silently. NULL = unbound =
|
||||
byte-identical pre-FAC-1 behavior. **Unknown-rig validation SPLITS by
|
||||
PROVENANCE** (arch ruling 2026-07-07, target-rig zero-regression):
|
||||
an explicit operator `--rig`/`targetRig` is AUTHORITATIVE — unknown →
|
||||
`bound_rig_unknown` HARD-FAIL before any mutation; a spec-default
|
||||
`target.rig` is ADVISORY (authored under the pre-FAC-1 regime where the
|
||||
field was ignored at runtime) — unknown → DEGRADE to unbound + a LOUD
|
||||
`advisories` notice on the instantiate result (surfaced by route + CLI
|
||||
stderr), never a hard-fail. This preserves AC-1 zero-regression for
|
||||
shipped/example specs that declare a descriptive `target.rig` AND route
|
||||
via `preferred_targets` (e.g. `conveyor`): they instantiate exactly as
|
||||
pre-FAC-1. A spec that genuinely needs a bound rig still fails loudly,
|
||||
per-step (entry at instantiate, later role-only steps at projection) —
|
||||
the degrade is to honest per-step failure with a heads-up, never to
|
||||
silence.
|
||||
- **A2 — role→seat capability resolution**
|
||||
(`workflow-role-resolver.ts` pure policy +
|
||||
`workflow-role-context.ts` lazy sync snapshot): TIER 3 inside
|
||||
`resolveDefaultOwner`, activating ONLY when a role declares zero
|
||||
`preferred_targets` AND the instance is bound. Tier order is sacred:
|
||||
explicit owner → gate compile → declared `preferred_targets`
|
||||
(byte-identical, never inventory-filtered) → capability → loud null.
|
||||
The CLOSED fact set: role (`nodes.role`, declared per pod member —
|
||||
seat-side, opt-in) · nodeKind · lifecycleState (`running` only) ·
|
||||
runtime (harness-pin aware) · sync `pendingWorkCount` (pending-only
|
||||
backlog) · the derived canonical coordinate. Async
|
||||
`attachAgentActivity`/tmux probes are structurally absent from the
|
||||
transaction. Managed seats only: adopted seats are excluded LOUDLY
|
||||
(`adopted_seat_not_role_resolvable_v1`). Selection = least backlog,
|
||||
plain-codepoint coordinate tiebreak (`driver10@rig < driver2@rig`).
|
||||
Resolution runs ONCE at step-close (after the frontier + absorption
|
||||
guards — replays perform zero inventory reads) and records as the
|
||||
packet destination; the WF-5 resume is the one re-resolution point,
|
||||
now capability-aware. All SIX owner-resolution sites carry the
|
||||
context: projector next-step, human-gate parked-packet owner,
|
||||
handler-role gate destination (no-targets + bound → capability),
|
||||
runtime entry (live + recorded), the eager instantiate loop
|
||||
(STRUCTURAL zero-role-coverage check only — `bound_rig_role_uncovered`;
|
||||
no live resolution of future steps; a warming rig instantiates), and
|
||||
resume. The WF-5 exception dial's orchestrator-role position resolves
|
||||
capability-aware on the bound rig at both homes (in-txn class-(a) +
|
||||
detection-time class-(b)), then uses registered-human selection if no
|
||||
agent resolves. Failures are loud-with-candidates: structured
|
||||
per-candidate disqualifiers + a named zero-candidate message; never a
|
||||
spawn, never auto-`add_member`, never a dead-seat route. Additive
|
||||
`owner_resolution` trail evidence records `{mode, role, boundRig?,
|
||||
seat}` per routing decision.
|
||||
- **A3 — roles bind to SEATS, never occupants**: the ONE string rule —
|
||||
the derived canonical coordinate `{pod}-{member}@{rig}` is both the
|
||||
tiebreak key and the recorded destination, so an agent handover
|
||||
behind the seat never strands the workflow (raw occupant-era session
|
||||
names are never recorded as role-resolution destinations).
|
||||
|
||||
## The member-exists instantiate advisory (OPR.0.4.6.FAC3 — engine bit)
|
||||
|
||||
The queue transport validates the RIG of a destination, never the member
|
||||
(`topologyValidateRig` is rig-exists-only by design — hardening it would
|
||||
gate every queue write and break legitimate non-managed destinations),
|
||||
so a declared `preferred_target` naming a registered rig but a typo'd or
|
||||
stale MEMBER would mint an orphan packet, visible only later as a WF-5
|
||||
stuck exception. FAC-3 catches it at the earliest knowable moment: at
|
||||
instantiate, for every step-referenced role (each step's `actor_role`
|
||||
plus a handler gate's target role — the same reference set the
|
||||
structural coverage check walks), each declared `preferred_target` that
|
||||
parses CANONICAL and names a rig registered on this daemon is probed
|
||||
for member existence (`rigMemberExists` beside `rigDeclaresRole` —
|
||||
sync SQL, the derived canonical coordinate per the FAC-1 Q5 one-string
|
||||
rule, existence at ANY lifecycle state and node kind; liveness stays
|
||||
projection's business). An unknown member yields ONE aggregated
|
||||
advisory per unique target — naming every declaring step/role pair, the
|
||||
consequence (the work will not be claimed; it will surface as a stuck
|
||||
exception), and the fix hint — pushed into the shipped
|
||||
`InstantiateResult.advisories` list (the FAC-1 `target.rig`-degrade
|
||||
surface: one list, now two producers; rendered by the route body + CLI
|
||||
stderr, zero new surface). ADVISORY-NEVER-DENY: instantiate always
|
||||
proceeds. Skips (in order): human-seat refs (classified BEFORE parse,
|
||||
the queue-gate archetype), non-canonical raw/adopted destinations (the
|
||||
inventory cannot vouch for them), unregistered rigs (the transport
|
||||
already rejects those loudly at queue-write — no double advisory).
|
||||
|
||||
## See also
|
||||
|
||||
- `coordination-primitive.md` — PL-004 Phase A; the closure authority the
|
||||
runtime projects against.
|
||||
- `mission-control.md` — PL-005 queue observability + 7-verb contract.
|
||||
- Source roots: `packages/daemon/src/domain/{workflow-projector,
|
||||
workflow-runtime,workflow-instance-store,workflow-spec-cache,
|
||||
workflow-step-trail-log,workflow-validator}.ts`,
|
||||
`packages/daemon/src/domain/policies/workflow-keepalive.ts`,
|
||||
`packages/daemon/src/domain/{workflow-exception,workflow-exception-router,
|
||||
workflow-exception-escalation}.ts`, `packages/daemon/src/routes/workflow.ts`.
|
||||
@@ -1,414 +0,0 @@
|
||||
---
|
||||
kind: as-built
|
||||
title: Workspace Primitive — RigSpec.workspace, Migrations 038/039, Missions/Projects/Slices
|
||||
status: active
|
||||
topics: [specification-and-bundles, observability]
|
||||
domains: [engineering-advisor, operating-advisor]
|
||||
applies-when: |
|
||||
Need to know how a rig declares a typed workspace (workspaceRoot / repos /
|
||||
defaultRepo / knowledgeRoot), how that block is persisted and resolved into
|
||||
whoami / node-inventory, how per-item target_repo scope is validated, or how
|
||||
the file-backed missions/slices tree is indexed and projected into the
|
||||
Project UI. Author-mode module — no prior architecture.md prose; every
|
||||
load-bearing claim is sourced to file:line at HEAD.
|
||||
siblings: [content-surfaces.md, daemon-core.md, ../ui/project-and-for-you.md]
|
||||
prerequisite-reads: [../README.md, daemon-core.md]
|
||||
last-verified-against-source: 7eaf524c
|
||||
last-updated: 2026-05-16
|
||||
---
|
||||
|
||||
# Workspace Primitive — RigSpec.workspace, Migrations 038/039, Missions/Projects/Slices
|
||||
|
||||
The **workspace primitive (PL-007)** is the typed declaration that lets a rig
|
||||
name *where its work lives* — a workspace root, a set of named repos with
|
||||
kinds, an optional default repo, and an optional knowledge root — and have
|
||||
that surface through `whoami` / node-inventory and gate per-item repo scope.
|
||||
Alongside it, a **file-backed missions/slices tree** is indexed read-only and
|
||||
projected into the Project UI's mission / slice surfaces.
|
||||
|
||||
> **AUTHOR-FROM-SOURCE module.** No prior `architecture.md` prose exists for
|
||||
> this. Every load-bearing claim carries `> Source: <file:line> @HEAD`;
|
||||
> ambiguity is declared as an OPEN item, never smoothed. Paths are relative to
|
||||
> `packages/daemon/src/` unless prefixed `packages/` or `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).
|
||||
>
|
||||
> **SPLIT NOTE (§10.6).** The honest source-grounded scope of
|
||||
> `workspace-and-content-primitives` (proposed-structure.md §4.9 / D13)
|
||||
> exceeds ~400 lines across two distinct subsystem clusters with distinct
|
||||
> source roots. Per the §10.6 SPLIT DIRECTIVE it is split by subsystem
|
||||
> cluster into this module (workspace primitive + migrations 038/039 +
|
||||
> missions/projects/slices) and the sibling `content-surfaces.md`
|
||||
> (files/markdown/progress/steering). This is a transparent noted deviation
|
||||
> from ratified Q7 "18", a faithful application of the founder's own
|
||||
> ratified Q3 principle ("distinct primitive / distinct source root →
|
||||
> split"); surfaced at the slice-08 review gate, not a mid-execution
|
||||
> interrupt.
|
||||
|
||||
## 0. Release attribution (forensic proof — read first)
|
||||
|
||||
Per §10.8, re-verified at HEAD via `git cat-file -e <tag>:<path>`:
|
||||
|
||||
| Subsystem | Release | Forensic proof @HEAD |
|
||||
|---|---|---|
|
||||
| `domain/workspace/{workspace-resolver,frontmatter-validator,default-workspace-scaffold}.ts` | **≤0.3.0** | `v0.3.0:<path>` → present |
|
||||
| migrations `038_workspace_primitive.ts`, `039_queue_target_repo.ts` | **≤0.3.0** | `v0.3.0:<path>` → present |
|
||||
| `domain/slices/{slice-indexer,slice-detail-projector}.ts` | **≤0.3.0** | `v0.3.0:<path>` → present |
|
||||
| `routes/{workspace,slices,projects}.ts` | **≤0.3.0** | `v0.3.0:<path>` → present |
|
||||
| `domain/workspace/getting-started-narrative.ts` | **0.3.1** | `v0.3.0:` → **ABSENT**; `v0.3.1:` → present |
|
||||
| `routes/missions.ts` | **0.3.1** | `v0.3.0:` → **ABSENT**; `v0.3.1:` → present |
|
||||
|
||||
> Source: §10.8 proof re-run at HEAD `7eaf524c` —
|
||||
> `git cat-file -e v0.3.0:packages/daemon/src/domain/workspace/getting-started-narrative.ts`
|
||||
> and `...routes/missions.ts` both fail ("exists on disk, but not in
|
||||
> 'v0.3.0'"); all other listed paths resolve at `v0.3.0`. The workspace
|
||||
> primitive itself is a **0.3.0** feature (slice-00 0.3.0-GT §1.4, PL-007,
|
||||
> migrations 038/039) — do not back-attribute it to 0.3.1. The
|
||||
> `missions` route + the getting-started narrative scaffold are the
|
||||
> **0.3.1** additions layered on top (slice 12 mission scope; slice 21
|
||||
> onboarding-conveyor).
|
||||
|
||||
slice-00 0.3.0-GT §1.4 independently confirms the primitive shipped 0.3.0:
|
||||
workspace-primitive merge `2ce54abc` (PL-007) with migrations
|
||||
`038_workspace_primitive` + `039_queue_target_repo`, "fresh databases apply
|
||||
migrations through `039_queue_target_repo`".
|
||||
|
||||
## 1. The typed workspace declaration (PL-007) — 0.3.0
|
||||
|
||||
`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:762-770` (`WorkspaceSpec`), `:751-758`
|
||||
> (`WorkspaceRepoSpec`), `:780` (`RigSpec.workspace?`) @HEAD.
|
||||
|
||||
| Field | Shape | Notes |
|
||||
|---|---|---|
|
||||
| `workspaceRoot` | string | Verbatim from spec |
|
||||
| `repos[]` | `{ name, path, kind }[]` | `path` resolved to absolute at parse time; authors may declare relative to `workspaceRoot` in YAML |
|
||||
| `defaultRepo?` | string | active repo when no env override / cwd match |
|
||||
| `knowledgeRoot?` | string | treated as `kind=knowledge` when surfaced |
|
||||
|
||||
`WorkspaceKind` is a closed 5-member union: `user`, `project`, `knowledge`,
|
||||
`lab`, `delivery`.
|
||||
|
||||
> Source: `domain/types.ts:748-749` (`WORKSPACE_KINDS` /
|
||||
> `WorkspaceKind`) @HEAD.
|
||||
|
||||
### 1.1 Persistence — migration 038 + RigRepository
|
||||
|
||||
Migration **038** adds `workspace_json TEXT` to the `rigs` table. It holds the
|
||||
typed `RigSpec.workspace` block as JSON when a rig declares one; NULL for rigs
|
||||
without a workspace block.
|
||||
|
||||
> Source: `db/migrations/038_workspace_primitive.ts:16-21`
|
||||
> (`ALTER TABLE rigs ADD COLUMN workspace_json TEXT`); doc-comment
|
||||
> `:3-14` @HEAD.
|
||||
|
||||
`RigRepository.setRigWorkspace(rigId, workspace)` persists it (UPDATE
|
||||
`workspace_json` + `updated_at`); `getRigWorkspace(rigId)` reads it back,
|
||||
JSON-parsing to `WorkspaceSpec` and returning `null` on parse failure. Both
|
||||
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:98-105` (setter, column probe
|
||||
> L99), `:106-117` (getter; parse-fail → null L114-116) @HEAD.
|
||||
|
||||
The instantiator persists the block at rig-create time **only when declared**:
|
||||
|
||||
> Source: `domain/rigspec-instantiator.ts:653-655` (`if
|
||||
> (rigSpec.workspace) … setRigWorkspace(rigId, rigSpec.workspace)`) @HEAD.
|
||||
|
||||
### 1.2 Runtime resolution — workspace-resolver
|
||||
|
||||
`resolveWorkspaceContext({ spec, cwd, envOverride })` (consumed by
|
||||
`whoami-service`) returns the `WhoamiWorkspaceBlock` or `null` when no spec.
|
||||
`activeRepo` resolution: an `envOverride` (non-empty, trimmed) wins
|
||||
**verbatim** — even an unknown repo name is honored, because operators set
|
||||
`OPENRIG_TARGET_REPO` consciously (PL-007 PRD § Item 3); otherwise
|
||||
`defaultRepo` is used **only if it names a declared repo**. `knowledgeKind`
|
||||
is `"knowledge"` when `knowledgeRoot` is declared, else `null`.
|
||||
|
||||
> Source: `domain/workspace/workspace-resolver.ts:26-52` (resolver;
|
||||
> env-override-verbatim L34-43, including the "honored verbatim"
|
||||
> comment L35-36) @HEAD.
|
||||
|
||||
`whoami-service` reads the persisted spec and resolves with the query's
|
||||
`targetRepoOverride`, falling back to `process.env["OPENRIG_TARGET_REPO"]`:
|
||||
|
||||
> Source: `domain/whoami-service.ts:319-324` (`getRigWorkspace` +
|
||||
> `resolveWorkspaceContext`, env fallback L323); `whoami` returns
|
||||
> `workspace` in its payload `:335` @HEAD.
|
||||
|
||||
`resolveNodeWorkspace({ spec, cwd })` (consumed by `node-inventory`) derives a
|
||||
per-node `NodeWorkspaceInfo` by walking the node's `cwd` up the directory
|
||||
tree for the **longest-prefix repo path** that contains it; falls back to
|
||||
`knowledge` when cwd is under `knowledgeRoot`, then to the rig's
|
||||
`defaultRepo` when cwd doesn't resolve. Containment uses a `path.relative`
|
||||
boundary check (not a string `startsWith`) so `/foo/bar` does not match
|
||||
`/foo/bar-other`.
|
||||
|
||||
> Source: `domain/workspace/workspace-resolver.ts:57-95`
|
||||
> (longest-prefix L67-73; knowledge fallback L77-79; default-repo
|
||||
> fallback L82-88), `isInside` `:97-103`;
|
||||
> `domain/node-inventory.ts:397` (`workspace: resolveNodeWorkspace(...)`),
|
||||
> `:434-437` (`NodeWorkspaceInfo`) @HEAD.
|
||||
|
||||
### 1.3 Per-item repo scope — migration 039 + queue validation
|
||||
|
||||
Migration **039** adds `target_repo TEXT` to `queue_items` plus
|
||||
`idx_queue_items_target_repo`. It carries the per-item typed repo scope when
|
||||
an operator passes `--target-repo <name>`; NULL when the qitem is
|
||||
unambiguous against the rig's `default_repo` or no workspace is declared.
|
||||
Mission Control views surface the field for cross-rig handoff clarity.
|
||||
|
||||
> Source: `db/migrations/039_queue_target_repo.ts:16-22`
|
||||
> (`ALTER TABLE queue_items ADD COLUMN target_repo TEXT` +
|
||||
> `CREATE INDEX … idx_queue_items_target_repo`); doc-comment
|
||||
> `:3-14` @HEAD.
|
||||
|
||||
The queue route validates `target_repo` at the route layer against the
|
||||
**source rig's** `RigSpec.workspace.repos[]`: it parses the rig name out of
|
||||
`source_session` (`<member>@<rig>`), looks up the rig, reads
|
||||
`getRigWorkspace`, and rejects an unknown repo with `unknown_target_repo` +
|
||||
the known-repo list. It **fails open** (`{ ok: true }`) when there is no
|
||||
rigRepo, no parseable rig, the rig is unknown, or no workspace is declared —
|
||||
validation only bites when a workspace actively declares repos.
|
||||
|
||||
> Source: `routes/queue.ts:49-57` (fail-open guards), `:55`
|
||||
> (`getRigWorkspace`), `:58-66` (`unknown_target_repo` +
|
||||
> `knownRepos`) @HEAD.
|
||||
|
||||
## 2. Workspace HTTP route — frontmatter validator (0.3.0)
|
||||
|
||||
`workspaceRoutes()` (mounted `server.ts:491` as `/api/workspace`) exposes a
|
||||
**single read-only endpoint** at v0:
|
||||
|
||||
`POST /api/workspace/validate` — body `{ root, workspaceKind?, recursive?,
|
||||
requireFrontmatter?, maxFiles? }`; returns a `FrontmatterValidationReport`.
|
||||
`root` is required (400 `root_required`); an out-of-vocabulary
|
||||
`workspaceKind` is rejected 400 `invalid_workspace_kind`; validator throws
|
||||
→ 500 `validate_failed`. **No filesystem mutation.**
|
||||
|
||||
> Source: `routes/workspace.ts:23-65` (handler; root-required L35-37;
|
||||
> kind-enum L39-47; 500 L59-62); mounted `server.ts:491` @HEAD.
|
||||
|
||||
`validateWorkspaceFrontmatter()` walks a root, parses each `.md` file's
|
||||
YAML frontmatter (delimited `---` on the first line), and emits a structured
|
||||
gap report — **advisory only, never modifies files**. Gap kinds:
|
||||
`missing-required-field`, `unrecognized-status-value`, `parse-error`,
|
||||
`missing-frontmatter`. Per-kind required fields: `user`/`project` →
|
||||
`["doc"]`; `knowledge`/`lab`/`delivery` → `["doc","status","created","owner"]`.
|
||||
Valid `status` enum: `active|draft|archived|superseded`. Default behavior
|
||||
skips files without `---` silently (informal notes) unless
|
||||
`requireFrontmatter`; recurses by default; skips `node_modules` / `.git` /
|
||||
`.worktrees` / `dist` / `build`; hard cap `maxFiles` default 10000.
|
||||
|
||||
> Source: `domain/workspace/frontmatter-validator.ts:53` (status enum),
|
||||
> `:56-62` (per-kind required), `:23-27` (gap kinds), `:90-122` (walk;
|
||||
> skip-dirs L105-111), `:160-172` (missing-frontmatter behavior),
|
||||
> `:201-226` (required + status check) @HEAD.
|
||||
|
||||
CLI surface: `rig workspace validate [root]` — v0 is intentionally narrow
|
||||
(`validate` only); future versions add typed-kind authoring on the same
|
||||
walker.
|
||||
|
||||
> Source: `docs/as-built/cli-reference.md:931-941` @HEAD.
|
||||
|
||||
## 3. Default project-workspace scaffold
|
||||
|
||||
`workspaceScaffoldDirs()` / `workspaceScaffoldFiles()` produce the
|
||||
repo-ready default workspace (`~/.openrig/workspace/` or `--root`). The same
|
||||
scaffold is used **idempotently by daemon startup**. It emits exactly two
|
||||
directories (`missions/`, `exhaust/`) and four files (`SPEC.md`,
|
||||
`project.yaml`, `workspace.yaml`, `.gitignore`). The catalog points its
|
||||
single default project at `.`; `project.yaml` owns project intent and mission
|
||||
discovery and exposes empty `install.context` / `install.skills` selectors.
|
||||
The ignore file excludes `exhaust/` and local `.openrig/` projection state
|
||||
while keeping authored project context versionable.
|
||||
|
||||
The workspace owner is called by the shared instance initializer used by CLI
|
||||
daemon start and direct daemon first start. The initializer is additive. It
|
||||
never deletes or overwrites an existing file;
|
||||
the retained `--force` spelling is a compatibility no-op for overwrite
|
||||
behavior. CLI and daemon scaffolds are byte-parity pinned. Mission and slice
|
||||
content is created explicitly through `rig scope`, not seeded by workspace
|
||||
initialization. Instance context, System World, skill source, runtime state,
|
||||
and the retired `artifacts/`, `evidence/`, `progress/`, `field-notes/`,
|
||||
`dogfood-evidence/`, `README.md`, and `STEERING.md` entries are not emitted.
|
||||
|
||||
> Source: `domain/workspace/default-workspace-scaffold.ts`
|
||||
> (`workspaceScaffoldDirs`, `workspaceScaffoldFiles`); CLI
|
||||
> `domain/instance-initialization.ts`; daemon `index.ts`; CLI
|
||||
> `packages/cli/src/daemon-lifecycle.ts` and
|
||||
> `packages/cli/src/commands/config-init-workspace.ts` (`runInitWorkspace`);
|
||||
> parity: `packages/daemon/test/getting-started-narrative-parity.test.ts`
|
||||
> @HEAD.
|
||||
|
||||
## 4. File-backed missions / slices tree
|
||||
|
||||
### 4.1 SliceIndexer (Slice Story View v0) — 0.3.0
|
||||
|
||||
`SliceIndexer` reads slice folders from a configured filesystem root. The
|
||||
**default workspace contract** is
|
||||
`workspace/missions/<mission>/slices/<slice>`; explicitly configured flat
|
||||
roots (`workspace/slices/<slice>`) remain supported for compatibility.
|
||||
A nested `slices/` child folder makes the parent a mission
|
||||
(`missionId = <mission-folder>`); a bare folder is a flat slice
|
||||
(`missionId = null`). NO new SQLite migration, NO new event type: read-only
|
||||
projection over existing tables (`queue_items`, `queue_transitions`,
|
||||
`mission_control_actions`) + dogfood-evidence directories. Time-bounded
|
||||
listing + detail caches (`invalidate()` drops both). `isReady()` is true
|
||||
when any configured slice root exists on disk.
|
||||
|
||||
> Source: `domain/slices/slice-indexer.ts:1-14` (contract + no-new-state),
|
||||
> `:174-176` (`isReady`), `:179-182` (`invalidate`), `:212-256`
|
||||
> (`readSliceLocations`; nested-vs-flat L233-253), `:62-89`
|
||||
> (`SliceListEntry` shape: `missionId` / `slicePath` / `qitemIds` /
|
||||
> `proofPacket`) @HEAD.
|
||||
|
||||
### 4.2 SliceDetailProjector (Slice Story View v0 + v1) — 0.3.0
|
||||
|
||||
Given a `SliceRecord`, the projector assembles the full per-slice payload
|
||||
across six tabs (Story, Acceptance, Decisions, Docs, Tests/Verification,
|
||||
Topology). Read-only; composes already-shipped tables +
|
||||
`workflow_specs`/`workflow_instances`/`workflow_step_trails` + slice docs on
|
||||
disk + dogfood-evidence. **v1 removed the v0 hardcoded legacy phase enum**
|
||||
(`discovery`/`product-lab`/`delivery`/…): `StoryEvent.phase` is now an
|
||||
open-ended string-or-null — the spec-defined `step.id` when bound to a
|
||||
`workflow_instance`, else `null` (UI groups under "Untagged"). When no
|
||||
workflow runtime is constructed the projector silently degrades to v0
|
||||
behavior (`workflowBinding=null`, `specGraph=null`).
|
||||
|
||||
> Source: `domain/slices/slice-detail-projector.ts:1-21` (six-tab
|
||||
> contract + v1 enrichment), `:18-21` (v0 phase enum REMOVED at v1);
|
||||
> startup degrade-path `startup.ts:1063-1076` (projector built with
|
||||
> `workflowRuntime?.specCache`; comment L1064-1071) @HEAD.
|
||||
|
||||
### 4.3 Slices routes — 0.3.0
|
||||
|
||||
`slicesRoutes()` (mounted `server.ts:501` as `/api/slices`):
|
||||
`GET /` (filter `all|active|done|blocked`, default `all`; `?refresh=1`
|
||||
invalidates; optional `?boundToWorkflow=<name>:<version>` lens narrows to
|
||||
slices bound to a workflow instance), `POST /refresh` (drops both indexer
|
||||
caches — no daemon restart), `GET /:name/proof-asset/*` (path-traversal
|
||||
guarded; immutable 1-day cache), `GET /:name/doc/*` (markdown for the Docs
|
||||
tab; traversal guarded), `GET /:name` (full per-tab payload). 503
|
||||
`slices_indexer_unavailable` when unwired; 503 `slices_root_not_configured`
|
||||
+ setup hint when not ready. **Route-order discipline:** literal `/` /
|
||||
`/refresh` / `/:name/proof-asset/*` / `/:name/doc/*` are registered BEFORE
|
||||
the dynamic `/:name` so they are not shadowed.
|
||||
|
||||
> Source: `routes/slices.ts:31-177` (handlers; route-order L34-35,
|
||||
> L101-102, L109-113, L166-167; 503s L38-44; `boundToWorkflow`
|
||||
> L60-86); mounted `server.ts:501` @HEAD.
|
||||
|
||||
### 4.4 Missions route — **0.3.1** (slice 12 + slice 13 + slice 18)
|
||||
|
||||
`missionsRoutes()` (mounted `server.ts:505` as `/api/missions`) is the
|
||||
mission scope data layer. `GET /:missionId` returns
|
||||
`{ missionId, missionPath, slices, workflow_spec, topology, status }` —
|
||||
slices filtered from the SliceIndexer by `missionId`; `missionPath` derived
|
||||
by going up two levels from any slice's `slicePath`; `workflow_spec` parsed
|
||||
lazily from `<missionPath>/README.md` frontmatter (same `parseWorkflowSpecRef`
|
||||
helper the slice-indexer uses); `topology.specGraph` projected via
|
||||
`projectSpecGraph(spec, null)` when the spec is cached, `{ specGraph: null }`
|
||||
when declared-but-not-cached, `null` when nothing declared; `status` read
|
||||
from README frontmatter. `POST /:missionId/complete` writes
|
||||
`status: complete` to the mission README frontmatter (idempotent; preserves
|
||||
unrelated fields) — the daemon is the audit-trail surface, the UI keeps an
|
||||
optimistic localStorage mirror. 404 `mission_not_found` when no slices match.
|
||||
|
||||
> Source: `routes/missions.ts:39-118` (handlers), `:124-142`
|
||||
> (`writeMissionStatusComplete`), `:148-150` (`computeMissionPath`
|
||||
> up-two-levels), `:171-177` (`readMissionWorkflowSpec`), `:205-215`
|
||||
> (`computeMissionTopology`); mounted `server.ts:505`; §0 proof:
|
||||
> `routes/missions.ts` [email protected] ⇒ **0.3.1** @HEAD.
|
||||
|
||||
### 4.5 Projects route — Coordination L2 classifier (PL-004 Phase B) — 0.3.0
|
||||
|
||||
`projectsRoutes()` (mounted `server.ts:492` as `/api/projects`) backs the
|
||||
`rig project` CLI verb — this is the **PL-004 Phase B project *classifier***
|
||||
(lease lifecycle + idempotent classify + operator-verb reclaim + SSE), NOT
|
||||
the Project *workspace UI* (that is the slices/missions surface above; the
|
||||
naming overlap is a documented seam). Endpoints: `POST /lease/acquire`
|
||||
(optional `evaluateDeadnessFirst` clears stale/dead leases first),
|
||||
`POST /lease/heartbeat`, `POST /reclaim-classifier`, `POST /project`
|
||||
(idempotent on `stream_item_id`), `GET /lease`, `GET /list`,
|
||||
`GET /sse` + `GET /watch` (SSE), `GET /:projectId`. **Route-order
|
||||
discipline:** literal `/lease`, `/list`, `/sse`, `/watch` are registered
|
||||
BEFORE the bare `/:projectId` catchall (Phase A R1 SSE lesson).
|
||||
|
||||
> Source: `routes/projects.ts:18-194` (handlers; route-order note
|
||||
> L15-17, L140-141, L158-159, L185); error-code → HTTP mapping
|
||||
> `:31-52`; mounted `server.ts:492` @HEAD.
|
||||
|
||||
## 5. UI route-reality (§10.7 — source-verified at routes.tsx@HEAD)
|
||||
|
||||
`packages/ui/src/routes.tsx` is **542 lines** and uses TanStack Router
|
||||
(`createRoute({ path, component })` objects), NOT JSX `<Route>`. The
|
||||
Phase-8.1 survey's grep-derived missions/projects expectations are
|
||||
corrected here against routes.tsx reality:
|
||||
|
||||
| Survey expectation | routes.tsx@HEAD reality | routes.tsx:NN |
|
||||
|---|---|---|
|
||||
| `/project` (workspace) | **REAL route** — `WorkspaceScopePage` | `:128-131` |
|
||||
| `/project/mission/$missionId` | **REAL route** — `MissionScopePage` | `:134-137` |
|
||||
| `/project/slice/$sliceId` | **REAL route** — `SliceScopePage` | `:140-143` |
|
||||
| `/files` | **REAL route** — `FilesWorkspace` (see content-surfaces.md) | `:192-195` |
|
||||
| `/mission-control` | **`<Navigate to="/for-you" />`** redirect-stub (DELETED per SC-18; the Mission Control *system* lives at daemon/PL-005, not a UI destination) | `:440-444` |
|
||||
| `/slices` | **`<Navigate to="/project" />`** redirect-stub (DELETED per project-tree.md) | `:447-451` |
|
||||
| `/slices/$name` | **`<Navigate to="/project/slice/$sliceId" />`** redirect-stub | `:453-460` |
|
||||
| `/progress` | **`<Navigate to="/project" />`** redirect-stub (folds into Project tabs, Phase 3) | `:464-468` |
|
||||
| `/steering` | **`<Navigate to="/project" />`** redirect-stub (folds into Project workspace overview tab, Phase 3) | `:470-474` |
|
||||
| `/missions` (top-level) | **NO route** — missions are reached only via `/project/mission/$missionId` | (absent) |
|
||||
| `/markdown` | **NO route** — markdown is a component in file/drawer surfaces, not a destination (see content-surfaces.md §4) | (absent) |
|
||||
|
||||
> Source: `packages/ui/src/routes.tsx:90-195` (real routes),
|
||||
> `:435-474` (redirect-stub block; each `<Navigate>` + DELETED/folds
|
||||
> comment), `:476-490` (route tree) @HEAD. Grep-confirmed absent:
|
||||
> no `path: "/missions"` / `path: "/markdown"` declaration anywhere
|
||||
> in routes.tsx @HEAD.
|
||||
|
||||
Net §10.7 ruling: the daemon `/api/missions` + `/api/slices` +
|
||||
`/api/projects` routes are real and load-bearing; the **operator-facing UI**
|
||||
consumes them through `/project*` destinations only. `/mission-control`,
|
||||
`/slices`, `/progress`, `/steering` are redirect-stubs (the systems exist at
|
||||
the daemon layer, the URLs were collapsed into `/project` / `/for-you`).
|
||||
|
||||
## 6. Cross-cutting properties
|
||||
|
||||
- **Optional + valid-without:** rigs without a `workspace` block stay valid;
|
||||
whoami / node-inventory / queue-target-repo all return null / fail-open
|
||||
(`workspace-resolver.ts:32`; `rig-repository.ts:99,107`;
|
||||
`routes/queue.ts:55`) @HEAD.
|
||||
- **Defensive column probes:** every `workspace_json` / `target_repo` access
|
||||
guards on column presence so partial test fixtures don't crash
|
||||
(`rig-repository.ts:99,107`; migrations 038/039 ship separately so a
|
||||
fixture can apply only the half it needs — `038.ts:11-14`) @HEAD.
|
||||
- **Read-only projection, no new state for the tree:** SliceIndexer /
|
||||
SliceDetailProjector add NO migration / event type; only the workspace
|
||||
declaration (038) + per-item scope (039) touch SQLite
|
||||
(`slice-indexer.ts:12-14`) @HEAD.
|
||||
- **Advisory, never mutates:** the frontmatter validator and the
|
||||
init-workspace scaffold never delete operator content
|
||||
(`frontmatter-validator.ts:12-13`; `config-init-workspace.ts:12-16`) @HEAD.
|
||||
|
||||
## OPEN items (carried, not smoothed)
|
||||
|
||||
- **OPEN-A** — `resolveWorkspaceContext` honors an `envOverride`
|
||||
**verbatim even when it names no declared repo** (`workspace-resolver.ts:34-43`,
|
||||
by explicit PL-007 PRD § Item 3 design), whereas the queue route
|
||||
**rejects** an unknown `target_repo` against the same `repos[]`
|
||||
(`routes/queue.ts:58-66`). These two surfaces apply opposite policies to
|
||||
an unknown repo name (whoami trusts the operator; queue validates). Stated
|
||||
as-is — the asymmetry is source-real and intentional per the cited
|
||||
comments, but the divergence is not reconciled in source.
|
||||
- **OPEN-B** — the `/api/projects` *classifier* (PL-004 Phase B) and the
|
||||
`/project*` *workspace UI* (slices/missions) share the word "project" but
|
||||
are unrelated subsystems. Documented as a naming seam; no source defect.
|
||||
- No slice-00 numeric-drift OPEN (1–5) applies — this module carries no
|
||||
migration-count / route-group / PL-004-event-count claim (those land in
|
||||
daemon-core / coordination-primitive / architecture-rules).
|
||||
+84
-1085
File diff suppressed because it is too large.
Load diff
+399
-171
@@ -1,197 +1,425 @@
|
||||
---
|
||||
kind: as-built
|
||||
title: OpenRig Codemap — Navigation Index / Map of Territory
|
||||
status: active
|
||||
topics: [knowledge-and-context, observability]
|
||||
domains: [engineering-advisor, operating-advisor]
|
||||
applies-when: |
|
||||
You know what you need to learn about the shipped OpenRig system but not
|
||||
which as-built module holds it. Use the module map, the use-case lookup,
|
||||
or the source-root table to route to the right doc — or jump straight to
|
||||
the source root the codemap points at.
|
||||
siblings: [README.md, cli-reference.md]
|
||||
prerequisite-reads: [README.md]
|
||||
last-verified-against-source: 7eaf524c
|
||||
last-updated: 2026-05-16
|
||||
---
|
||||
# OpenRig Source Codemap
|
||||
|
||||
# OpenRig Codemap — Navigation Index
|
||||
Source-driven map of every file under `packages/daemon/src`, `packages/cli/src`, and `packages/ui/src` at current `HEAD`.
|
||||
|
||||
This is a **map of territory**, not a content dump. It tells you which
|
||||
as-built module answers a question and which `packages/*/src` root that
|
||||
module is grounded in. The deep content lives in the modules; the code lives
|
||||
in the source roots; this file points at both.
|
||||
Current footprint:
|
||||
- daemon: 211 source files (126 domain, 31 routes, 11 adapters, 36 migrations, 7 other)
|
||||
- CLI: 78 source files
|
||||
- UI: 87 source files
|
||||
- total: 376 source files
|
||||
|
||||
> The old codemap was a 425-line file-by-file `Exports:`/`Related:` flat dump
|
||||
> that drifted fastest (its own header carried a stale v0.2.0 footprint and an
|
||||
> internally-contradictory command-group count) and never fit a context
|
||||
> window. That anti-pattern is retired (slice-08 Q5, founder-ratified). The
|
||||
> genuinely-useful part — the source-root index — is preserved below as the
|
||||
> source-root pointer table; the per-file transcription is not.
|
||||
How to use this doc:
|
||||
- `Exports` lists the public symbols defined by the file.
|
||||
- `Related` lists the file's primary local outgoing dependencies so you can follow the code path quickly.
|
||||
- The package/area groupings are structural, not ownership metadata.
|
||||
|
||||
## (a) Product frame
|
||||
Fast lookup:
|
||||
- Daemon app wiring and mounted HTTP surface: `packages/daemon/src/startup.ts`, `packages/daemon/src/server.ts`, `packages/daemon/src/routes/*`
|
||||
- AgentSpec / pod-aware engine: `packages/daemon/src/domain/agent-*`, `profile-resolver.ts`, `projection-planner.ts`, `startup-*`, `rigspec-*`, `pod-repository.ts`
|
||||
- Rig environment / managed-app substrate: `packages/daemon/src/adapters/compose-services-adapter.ts`, `packages/daemon/src/domain/service-orchestrator.ts`, `packages/daemon/src/domain/services-readiness.ts`, `packages/daemon/src/routes/env.ts`
|
||||
- Snapshot / restore / continuity: `packages/daemon/src/domain/snapshot-*`, `checkpoint-store.ts`, `restore-orchestrator.ts`
|
||||
- Transport / communication: `packages/daemon/src/domain/session-transport.ts`, `packages/daemon/src/routes/transport.ts`
|
||||
- Transcripts / persistence: `packages/daemon/src/domain/transcript-store.ts`, `packages/daemon/src/domain/history-query.ts`, `packages/daemon/src/routes/transcripts.ts`
|
||||
- Ask / context packs: `packages/daemon/src/domain/ask-service.ts`, `packages/daemon/src/routes/ask.ts`
|
||||
- Chat: `packages/daemon/src/domain/chat-repository.ts`, `packages/daemon/src/routes/chat.ts`
|
||||
- Spec review / library / identity: `packages/daemon/src/domain/spec-review-service.ts`, `packages/daemon/src/domain/spec-library-service.ts`, `packages/daemon/src/domain/whoami-service.ts`, `packages/daemon/src/routes/spec-review.ts`, `packages/daemon/src/routes/spec-library.ts`, `packages/daemon/src/routes/whoami.ts`
|
||||
- Node inventory: `packages/daemon/src/domain/node-inventory.ts`
|
||||
- Context usage: `packages/daemon/src/domain/context-usage-store.ts`, `packages/daemon/src/domain/context-monitor.ts`
|
||||
- Resume honesty: `packages/daemon/src/domain/native-resume-probe.ts`, `resume-metadata-refresher.ts`, `codex-thread-id.ts`
|
||||
- Package / bootstrap / bundle flows: `packages/daemon/src/domain/package-*`, `install-*`, `bootstrap-*`, `bundle-*`
|
||||
- CLI command surface: `packages/cli/src/index.ts`, `packages/cli/src/commands/*` (53 groups)
|
||||
- CLI infrastructure: `packages/cli/src/config-store.ts`, `packages/cli/src/system-preflight.ts`
|
||||
- UI workspace and navigation: `packages/ui/src/components/Explorer.tsx`, `packages/ui/src/components/WorkspaceHome.tsx`, `packages/ui/src/components/AppShell.tsx`
|
||||
- UI shared drawer: `packages/ui/src/components/SharedDetailDrawer.tsx`, `RigDetailPanel.tsx`, `NodeDetailPanel.tsx`, `DiscoveryPanel.tsx`, `SpecsPanel.tsx`, `RigChatPanel.tsx`, `SystemPanel.tsx`
|
||||
- UI spec/library surfaces: `packages/ui/src/components/RigSpecDisplay.tsx`, `packages/ui/src/components/AgentSpecDisplay.tsx`, `packages/ui/src/components/LibraryReview.tsx`, `packages/ui/src/components/SpecsWorkspace.tsx`
|
||||
- UI managed-app runtime surfaces: `packages/ui/src/components/RigEnvPanel.tsx`, `packages/ui/src/hooks/useRigEnv.ts`, `packages/ui/src/lib/build-setup-prompt.ts`
|
||||
- UI live identity surfaces: `packages/ui/src/components/LiveIdentityDisplay.tsx`, `packages/ui/src/components/LiveNodeDetails.tsx`
|
||||
- UI data layer: `packages/ui/src/hooks/*`
|
||||
|
||||
OpenRig is a local control plane for multi-agent coding topologies — a
|
||||
multi-agent harness that manages your Claude Code and Codex sessions as a
|
||||
single system. The daemon (`@openrig/daemon`) is the framework-free
|
||||
SQLite-backed core; the CLI (`@openrig/cli`), UI (`@openrig/ui`), and MCP
|
||||
server all sit on top of it.
|
||||
## Daemon
|
||||
|
||||
> Source-verified at HEAD `7eaf524c` (`v0.3.1-6-g7eaf524c`); package version
|
||||
> **0.3.1**, 6 unreleased 0.3.2 commits on HEAD, no `v0.3.2` tag. Frame
|
||||
> sentence triangulated against `architecture/daemon-core.md` §1 +
|
||||
> `openrig-internal/product/positioning.md` ("a multi-agent harness, a local
|
||||
> control plane that manages your Claude Code and Codex sessions as a single
|
||||
> system").
|
||||
### Entrypoints And Wiring
|
||||
- `packages/daemon/src/index.ts`: CLI entrypoint for starting the daemon HTTP server. Exports: startServer. Related: `packages/daemon/src/startup.js`.
|
||||
- `packages/daemon/src/seed.ts`: Development/test seed entrypoint for populating sample daemon state. Exports: none. Related: `packages/daemon/src/db/connection.js`, `packages/daemon/src/db/migrate.js`, `packages/daemon/src/db/migrations/001_core_schema.js`, `packages/daemon/src/db/migrations/002_bindings_sessions.js`, +3 more.
|
||||
- `packages/daemon/src/server.ts`: Defines `AppDeps`, enforces shared-DB invariants, and mounts the full public Hono route tree including dual-format rigspec import/export/materialize, bundles, transport/transcripts/ask/chat, env status/logs/down, specs review/library, and `whoami`. Exports: AppDeps, createApp. Related: `packages/daemon/src/adapters/cmux.js`, `packages/daemon/src/adapters/tmux.js`, `packages/daemon/src/domain/bootstrap-orchestrator.js`, `packages/daemon/src/domain/bootstrap-repository.js`, +36 more.
|
||||
- `packages/daemon/src/startup.ts`: Constructs the daemon dependency graph, runs all 36 migrations, wires legacy, reboot, North Star, Post-North-Star, Phase 5 RigEnv, context-usage, Final Stretch 3 managed-app services, and PL-004 coordination services together, and returns `{ app, db, deps }`. Exports: createDaemon. Related: `packages/daemon/src/adapters/claude-resume.js`, `packages/daemon/src/adapters/cmux-transport.js`, `packages/daemon/src/adapters/cmux.js`, `packages/daemon/src/adapters/codex-resume.js`, +58 more.
|
||||
|
||||
## (b) Module map
|
||||
### Adapters
|
||||
- `packages/daemon/src/adapters/claude-code-adapter.ts`: Adapter implementation for claude code integration. Exports: ClaudeAdapterFsOps, ClaudeCodeAdapter. Related: `packages/daemon/src/adapters/tmux.js`, `packages/daemon/src/domain/projection-planner.js`, `packages/daemon/src/domain/runtime-adapter.js`.
|
||||
- `packages/daemon/src/adapters/claude-resume.ts`: Resume adapter for claude sessions. Exports: ClaudeResumeAdapter, ResumeResult. Related: `packages/daemon/src/adapters/shell-quote.js`, `packages/daemon/src/adapters/tmux.js`.
|
||||
- `packages/daemon/src/adapters/cmux-transport.ts`: Adapter/util module for cmux transport integration. Exports: createCmuxCliTransport. Related: `packages/daemon/src/adapters/cmux.js`, `packages/daemon/src/adapters/tmux.js`.
|
||||
- `packages/daemon/src/adapters/cmux.ts`: Adapter/util module for cmux integration. Exports: CmuxAdapter, CmuxResult, CmuxStatus, CmuxSurface, CmuxTransport, CmuxTransportFactory, CmuxWorkspace. Related: none.
|
||||
- `packages/daemon/src/adapters/compose-services-adapter.ts`: Compose-backed rig-environment adapter for `up`, `ps`, `logs`, and teardown. Exports: ComposePsService, ComposeServicesAdapter, ComposeServicesUpParams, ComposeServicesUpResult, ComposeServicesLogsParams, ComposeServicesLogsResult, ComposeServicesDownParams, ComposeServicesDownResult. Related: `packages/daemon/src/adapters/tmux-exec.js`.
|
||||
- `packages/daemon/src/adapters/codex-resume.ts`: Resume adapter for codex sessions. Exports: CodexResumeAdapter, ResumeResult. Related: `packages/daemon/src/adapters/claude-resume.js`, `packages/daemon/src/adapters/shell-quote.js`, `packages/daemon/src/adapters/tmux.js`.
|
||||
- `packages/daemon/src/adapters/codex-runtime-adapter.ts`: Adapter implementation for codex runtime integration. Exports: CodexAdapterFsOps, CodexRuntimeAdapter. Related: `packages/daemon/src/adapters/tmux.js`, `packages/daemon/src/domain/projection-planner.js`, `packages/daemon/src/domain/runtime-adapter.js`.
|
||||
- `packages/daemon/src/adapters/terminal-adapter.ts`: Infrastructure runtime adapter for terminal/shell nodes. No-op project/deliver/launch, immediate readiness. Exports: TerminalAdapter. Related: `packages/daemon/src/domain/runtime-adapter.js`.
|
||||
- `packages/daemon/src/adapters/shell-quote.ts`: Adapter/util module for shell quote integration. Exports: shellQuote. Related: none.
|
||||
- `packages/daemon/src/adapters/tmux-exec.ts`: Adapter/util module for tmux exec integration. Exports: execCommand. Related: `packages/daemon/src/adapters/tmux.js`.
|
||||
- `packages/daemon/src/adapters/tmux.ts`: Adapter/util module for tmux integration. Exports: ExecFn, TmuxAdapter, TmuxPane, TmuxResult, TmuxSession, TmuxWindow. Related: none.
|
||||
|
||||
One row per module. "Reach for this when…" mirrors each module's actual
|
||||
`applies-when` frontmatter.
|
||||
### DB Core
|
||||
- `packages/daemon/src/db/connection.ts`: Creates the SQLite connection with daemon-wide pragmas. Exports: createDb. Related: none.
|
||||
- `packages/daemon/src/db/migrate.ts`: Migration runner and `Migration` type shared by all schema files. Exports: Migration, migrate. Related: none.
|
||||
|
||||
### architecture/
|
||||
### DB Migrations
|
||||
- `packages/daemon/src/db/migrations/001_core_schema.ts`: Database migration for core schema. Exports: coreSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/002_bindings_sessions.ts`: Database migration for bindings sessions. Exports: bindingsSessionsSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/003_events.ts`: Database migration for events. Exports: eventsSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/004_snapshots.ts`: Database migration for snapshots. Exports: snapshotsSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/005_checkpoints.ts`: Database migration for checkpoints. Exports: checkpointsSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/006_resume_metadata.ts`: Database migration for resume metadata. Exports: resumeMetadataSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/007_node_spec_fields.ts`: Database migration for node spec fields. Exports: nodeSpecFieldsSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/008_packages.ts`: Database migration for packages. Exports: packagesSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/009_install_journal.ts`: Database migration for install journal. Exports: installJournalSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/010_journal_seq.ts`: Database migration for journal seq. Exports: journalSeqSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/011_bootstrap.ts`: Database migration for bootstrap. Exports: bootstrapSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/012_discovery.ts`: Database migration for discovery. Exports: discoverySchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/013_discovery_fk_fix.ts`: Database migration for discovery fk fix. Exports: discoveryFkFix. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/014_agentspec_reboot.ts`: Database migration for agentspec reboot. Exports: agentspecRebootSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/015_startup_context.ts`: Database migration for startup context. Exports: startupContextSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/016_chat_messages.ts`: Database migration for durable rig-scoped chat messages. Exports: chatMessagesSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/017_pod_namespace.ts`: Database migration that persists authored pod namespace separately from pod DB id for export, adoption, and identity parity. Exports: podNamespaceSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/018_context_usage.ts`: Database migration for per-node context-usage persistence. Exports: contextUsageSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/019_external_cli_attachment.ts`: Database migration extending bindings for external CLI attachment metadata. Exports: externalCliAttachmentSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/020_rig_services.ts`: Database migration for rig-scoped services records and persisted env receipts. Exports: rigServicesSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/021_seat_handover_observability.ts`: Database migration for seat-handover observability fields. Exports: seatHandoverObservabilitySchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/022_node_codex_config_profile.ts`: Database migration adding Codex config-profile field on nodes. Exports: nodeCodexConfigProfileSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/023_stream_items.ts`: PL-004 Phase A — L1 stream items table (append-only intake/audit root). Exports: streamItemsSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/024_queue_items.ts`: PL-004 Phase A — L3 queue items table (owned-work queue with closure obligation). Exports: queueItemsSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/025_queue_transitions.ts`: PL-004 Phase A — append-only queue state transition log. Exports: queueTransitionsSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/026_inbox_entries.ts`: PL-004 Phase A — mailbox-style inbox for asynchronous deposit. Exports: inboxEntriesSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/027_outbox_entries.ts`: PL-004 Phase A — sender-side outbox audit. Exports: outboxEntriesSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/028_project_classifications.ts`: PL-004 Phase B — L2 project classifications table (idempotent on stream_item_id; FK to stream_items). Exports: projectClassificationsSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/029_classifier_leases.ts`: PL-004 Phase B — single-writer classifier lease table (partial UNIQUE INDEX on state='active'). Exports: classifierLeasesSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/030_views_custom.ts`: PL-004 Phase B — custom view registry. Exports: viewsCustomSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/031_watchdog_jobs.ts`: PL-004 Phase C — watchdog jobs (canonical scheduler state; policy enum + intervals + lifecycle). Exports: watchdogJobsSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/032_watchdog_history.ts`: PL-004 Phase C — append-only watchdog evaluation history (sent/skipped/terminal; not_due polls not recorded). Exports: watchdogHistorySchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/033_workflow_specs.ts`: PL-004 Phase D — workflow specs (cached read-through from markdown/YAML; UNIQUE on name+version; source_hash invalidation). Exports: workflowSpecsSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/034_workflow_instances.ts`: PL-004 Phase D — workflow instances (live state; status enum; current_frontier_json; hop_count). Exports: workflowInstancesSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/035_workflow_step_trails.ts`: PL-004 Phase D — append-only workflow step trail history (FK to workflow_instances and queue_items). Exports: workflowStepTrailsSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/036_watchdog_policy_enum_extension.ts`: PL-004 Phase D — documenting no-op migration; Phase C uses application-layer enforcement so the enum extension to include workflow-keepalive is implemented in PHASE_D_POLICIES (watchdog-jobs-repository.ts), not in DDL. Exports: watchdogPolicyEnumExtensionSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
- `packages/daemon/src/db/migrations/037_mission_control_actions.ts`: PL-005 Phase A — Mission Control action audit table (append-only; 7-verb enum at app layer; before/after qitem snapshots; FK to queue_items). Exports: missionControlActionsSchema. Related: `packages/daemon/src/db/migrate.js`.
|
||||
|
||||
| Module | One-sentence summary | Reach for this when… |
|
||||
|---|---|---|
|
||||
| `daemon-core.md` | The framework-free SQLite-backed core the CLI/UI/MCP all sit on. | You need to know how the daemon boots, how `createDaemon` wires the dependency graph, the SQLite schema/migration set, or the route-mount surface. |
|
||||
| `adapters-and-runtimes.md` | The five-method runtime-adapter contract + the resume-honesty layer. | You need the runtime-adapter contract, how OpenRig launches/resumes a Claude Code, Codex, or terminal harness inside tmux, or how the daemon honestly assesses whether a harness actually resumed vs fresh-launched. |
|
||||
| `coordination-primitive.md` | PL-004 Phase A: the SQLite-canonical durable-work layer (`/api/stream`, `/api/queue`). | You need the stream/queue/inbox/outbox tables, the hot-potato closure contract, the transactional handoff guarantee, or where queue closure is enforced. |
|
||||
| `workflow-runtime.md` | PL-004 Phase D: turns an intended sequence of work into durable SQLite state. | You need workflow specs cache, instance state, step trails, the transactional-scribe projection contract, or the watchdog policy set including workflow-keepalive. |
|
||||
| `mission-control.md` | PL-005: the daemon-backed queue-observability surface inside the existing shell. | You need the seven views, the seven write verbs, the action audit table, the bearer-token middleware, or how queue observability maps to PL-004 sources. |
|
||||
| `agent-spec-and-startup.md` | How authored YAML specs become a resolved, launched, identity-addressable topology. | You need the AgentSpec/RigSpec/pod-aware reboot types, profile resolution + additive startup layering, the StartupOrchestrator delivery split, or how whoami/materialize/bind/adopt resolve identity. |
|
||||
| `lifecycle-snapshot-restore.md` | The durable-state half of `down → up → handoff`. | You need how OpenRig captures a snapshot, restores a rig (resume vs rebuild vs fresh), enforces restore honesty, consults live continuity, or how restore-check / restore-packet readiness probes work. |
|
||||
| `transport-and-transcripts.md` | The communication-and-history layer; tmux is transport, not truth. | You need how rig send/capture/broadcast works, pipe-pane transcript capture + search, durable SQLite chat, what `rig ask` gathers, or the MCP-tool-name vs tmux-metadata-key distinction. |
|
||||
| `workspace-primitive.md` | PL-007: the typed declaration of where a rig's work lives. | You need how a rig declares a typed workspace (root/repos/defaultRepo/knowledgeRoot), how it persists/resolves into whoami / node-inventory, how per-item `target_repo` scope is validated, or how the file-backed missions/slices tree is indexed and projected into Project. |
|
||||
| `content-surfaces.md` | The operator-allowlisted, filesystem-canonical read/write layer Project/Steering sits on. | You need how the file browser enforces path safety, how atomic conflict-checked writes + the JSONL edit audit work, how the PROGRESS.md tree is indexed, or how the one-screen Steering surface is composed. |
|
||||
| `plugin-agent-image-context-pack.md` | Four filesystem-canonical content primitives the daemon discovers and serves. | You need how OpenRig discovers plugins, captures/forks agent images, assembles/sends context packs, or how the Claude auto-compaction enforcer decides to send `/compact`. |
|
||||
| `packaging-bootstrap-bundles.md` | How a topology is packaged into a shareable bundle and reconstituted elsewhere. | You need how rig/pod bundles are assembled (schema-v2 vs legacy v1), how bundle create/inspect/install + `/api/up` route across source kinds, the staged BootstrapOrchestrator flow, or which legacy install-engine seams still ship. |
|
||||
| `architecture-rules-and-event-system.md` | The cross-cutting invariants that belong to no single subsystem. | You need the 25 architecture rules + startup/import constraints, the shape of the RigEvent union and its SSE delivery, or the intentional compatibility limits that still describe the shipped system. |
|
||||
| `living-notes-review.md` | **v0.4.4** — the one intent→plan→delivered review projection over on-disk SDLC markdown. | You need the `ComposedSliceReview` contract, the `/api/review/*` routes, staged-approval locks (`--scope spec|delivery`), the `## Proof contract` ↔ proof-artifact join and C1-bound `verified`, the freeze export, or ranged media serving for review evidence. |
|
||||
### Domain: Mission Control / Queue Observability (PL-005 Phase A)
|
||||
- `packages/daemon/src/domain/mission-control/mission-control-action-log.ts`: Append-only writer for mission_control_actions. API surface lacks update/delete/remove (contract enforcement). Validates verb-specific required fields (annotate→annotation, hold/drop→reason). Exports: MissionControlActionLog, MissionControlActionLogError, MissionControlVerb, MISSION_CONTROL_VERBS. Related: `packages/daemon/src/db/migrations/037_mission_control_actions.js`.
|
||||
- `packages/daemon/src/domain/mission-control/mission-control-write-contract.ts`: LOAD-BEARING. Atomic 7-verb action coordinator. Each verb is one db.transaction: queue mutation via Phase D's QueueRepository.updateWithinTransaction (preserves Phase A hot-potato closure validation; emits queue.updated) + audit row + persisted mission_control.action_executed event. The 4-step handoff shape (source-update + destination-create + opt-in best-effort notify + audit append) is verified atomic; notify failure does NOT roll back durable state. Exports: MissionControlWriteContract, MissionControlWriteContractError, MissionControlActionInput, MissionControlActionResult. Related: `packages/daemon/src/domain/queue-repository.js`, `packages/daemon/src/domain/mission-control/mission-control-action-log.js`.
|
||||
- `packages/daemon/src/domain/mission-control/mission-control-read-layer.ts`: Maps 7 Mission Control views to source-of-truth paths. my-queue/human-gate/active-work/recent-ships query queue_items via QueueRepository; fleet uses fleetCliCapability roll-up; recently-active delegates to PL-004 Phase B ViewProjector.show("recently-active"); recent-observations reads stream_items via StreamStore. All rows return the 9-field phone-friendly content model (PRD non-negotiable). Exports: MissionControlReadLayer, MissionControlViewName, CompactStatusRow, MISSION_CONTROL_VIEWS. Related: `packages/daemon/src/domain/queue-repository.js`, `packages/daemon/src/domain/view-projector.js`, `packages/daemon/src/domain/stream-store.js`, `packages/daemon/src/domain/mission-control/mission-control-fleet-cli-capability.js`.
|
||||
- `packages/daemon/src/domain/mission-control/mission-control-fleet-cli-capability.ts`: Per-rig CLI capability cache + fleet roll-up. Implements 4 sub-clauses of PRD § Runtime/Source Drift Acceptance: per-field availability check, per-rig honesty, once-per-session-per-rig logging, "rigs running stale CLI" indicator. Synthesizes per-rig activity state (active|idle|attention|blocked|degraded) from queue_items aggregation. Exports: MissionControlFleetCliCapability, FleetRollupRow, FleetRollup, MISSION_CONTROL_DESIRED_FIELDS. Related: `packages/daemon/src/domain/rig-repository.js`, `packages/daemon/src/db/migrations/024_queue_items.js`.
|
||||
- `packages/daemon/src/routes/mission-control.ts`: Hono route module for `/api/mission-control` (`GET /views` literal list; `GET /views/:view-name` view fetch; `POST /action` 7-verb atomic execute; `GET /sse` + `GET /watch` SSE; `GET /cli-capabilities` fleet drift cache). SSE/literal paths mounted before /views/:view-name catchall per PL-004 Phase A R1 route-order discipline. Exports: missionControlRoutes. Related: `packages/daemon/src/domain/mission-control/*`, `packages/daemon/src/domain/event-bus.js`.
|
||||
|
||||
### ui/
|
||||
### Product UI: Mission Control / Queue Observability (PL-005 Phase A)
|
||||
- `packages/ui/src/components/mission-control/MissionControlSurface.tsx`: Top-level Mission Control surface inside the existing product UI shell. Tab navigation across the 7 view names. Mounted at the `/mission-control` route. Exports: MissionControlSurface.
|
||||
- `packages/ui/src/components/mission-control/views/{MyQueueView,HumanGateView,FleetView,ActiveWorkView,RecentShipsView,RecentlyActiveView,RecentObservationsView}.tsx`: 7 view components. Most wrap a shared GenericListView; FleetView combines CliDriftIndicator + per-row MissingFieldPlaceholder; MyQueueView combines HumanSeatCard + GenericListView with verb actions enabled.
|
||||
- `packages/ui/src/components/mission-control/components/CompactStatusRow.tsx`: 9-field phone-friendly content-model atom (PRD non-negotiable). Renders compact / expanded density modes; UI may collapse but JSON preserves all 9 fields.
|
||||
- `packages/ui/src/components/mission-control/components/VerbActions.tsx`: Shared 7-verb action sub-component. Renders verb buttons + per-verb required-field input (destination for route/handoff, annotation for annotate, reason for hold/drop). Submits to `POST /api/mission-control/action`. Invalidates Mission Control view queries on success.
|
||||
- `packages/ui/src/components/mission-control/components/HumanSeatCard.tsx`: First-class human-seat rendering. Shows session identity, pending load, blocked count, verb capabilities. NOT invisible config-layer convention.
|
||||
- `packages/ui/src/components/mission-control/components/CliDriftIndicator.tsx`: Cross-CLI-version drift indicator (PRD sub-clause 4). Shows fleet-level "rigs running stale CLI" badge + per-row "field unavailable on this rig's daemon version" placeholders via the MissingFieldPlaceholder export.
|
||||
- `packages/ui/src/components/mission-control/hooks/{useMissionControlView,useMissionControlAction,useMissionControlCliCapabilities}.ts`: TanStack Query hooks fetching from `/api/mission-control/{views/:name,action,cli-capabilities}`.
|
||||
|
||||
| Module | One-sentence summary | Reach for this when… |
|
||||
|---|---|---|
|
||||
| `shell-and-routing.md` | The shell-first, route-first, primitive-driven operator surface. | You need how the UI shell (rail / Explorer / center workspace / drawer / preview stack) is assembled, the actual route tree the shipped UI mounts, or how the shared detail drawer and event consumption work. |
|
||||
| `topology.md` | The operator's live picture of host → rig → pod → seat. | You need how the topology surface is built — the host hybrid graph, the table/terminal views, the activity-ring / hot-potato visual language, terminal-preview popovers, and the navigation/overlay contracts. |
|
||||
| `project-and-for-you.md` | The three operator-facing destination surfaces (For You / Project / Dashboard). | You need how the For-You attention feed (5-card classifier + verb actions), the Project workspace/mission/slice scope pages, and the Dashboard landing on the vellum brand system are built. |
|
||||
| `library-specs-and-design-system.md` | The Library (`/specs`) destination + the design-system pointer. | You need how the Library UI is assembled — the spec/skills/plugins surfaces, the spec-review + spec-library + live-identity flows that feed it — or where the canonical visual/design-system spec lives. |
|
||||
### Domain: Coordination Watchdog (PL-004 Phase C; extended in Phase D)
|
||||
- `packages/daemon/src/domain/watchdog-jobs-repository.ts`: Persistence for watchdog_jobs. Phase D extension: enforces four-policy enum (periodic-reminder, artifact-pool-ready, edge-artifact-required, workflow-keepalive) at register-time. Phase C's policy_deferred_to_phase_d rejection has been replaced with positive registration-accept. Exports: WatchdogJobsRepository, WatchdogJobsError, WatchdogJob, PHASE_D_POLICIES, PHASE_C_POLICIES (alias). Related: `packages/daemon/src/db/migrations/031_watchdog_jobs.js`.
|
||||
- `packages/daemon/src/domain/watchdog-history-log.ts`: Append-only writer for watchdog_history. Records meaningful evaluations only (sent/skipped/terminal). API surface intentionally lacks update/delete. Exports: WatchdogHistoryLog, WatchdogHistoryEntry, WatchdogOutcome. Related: `packages/daemon/src/db/migrations/032_watchdog_history.js`.
|
||||
- `packages/daemon/src/domain/watchdog-policy-engine.ts`: Resolves policy by name, parses spec_yaml context, dispatches policy.evaluate(), records meaningful outcomes via history-log, emits watchdog.* events, calls injected delivery callback for action=send. Exports: WatchdogPolicyEngine, DeliveryFn, DeliveryRequest, DeliveryOutcome. Related: `packages/daemon/src/domain/watchdog-jobs-repository.js`, `packages/daemon/src/domain/watchdog-history-log.js`, `packages/daemon/src/domain/event-bus.js`.
|
||||
- `packages/daemon/src/domain/watchdog-scheduler.ts`: Tick-driven daemon-native scheduler that joins the supervision tree. Filters listActive() through isDue(), evaluates due jobs sequentially, supports start/stop with graceful in-flight await. Exports: WatchdogScheduler, isDue. Related: `packages/daemon/src/domain/watchdog-policy-engine.js`, `packages/daemon/src/domain/watchdog-jobs-repository.js`.
|
||||
- `packages/daemon/src/domain/policies/types.ts`: Policy contract (Policy, PolicyJob, PolicyEvaluation). Exports: Policy, PolicyJob, PolicyEvaluation. Related: none.
|
||||
- `packages/daemon/src/domain/policies/periodic-reminder.ts`: Policy that returns send {target, message} unconditionally; throws policy_spec_invalid if context.target.session or context.message missing. Translated from POC `lib/policies/periodic-reminder.mjs`. Exports: periodicReminderPolicy. Related: `packages/daemon/src/domain/policies/types.js`.
|
||||
- `packages/daemon/src/domain/policies/artifact-pool-ready.ts`: Policy that scans context.pools and skips with no_actionable_artifacts when empty; otherwise sends a formatted message capped at max_items. Translated from POC `lib/policies/artifact-pool-ready.mjs`. Exports: artifactPoolReadyPolicy. Related: `packages/daemon/src/domain/policies/artifact-pool-helpers.js`, `packages/daemon/src/domain/policies/types.js`.
|
||||
- `packages/daemon/src/domain/policies/edge-artifact-required.ts`: Policy that scans source_pools and target_pools, computes source-key per artifact, and sends an edge-repair message for sources lacking matching downstream artifacts. Skips with no_missing_edge_artifacts when all sources matched. Translated from POC `lib/policies/edge-artifact-required.mjs`. Exports: edgeArtifactRequiredPolicy. Related: `packages/daemon/src/domain/policies/artifact-pool-helpers.js`, `packages/daemon/src/domain/policies/types.js`.
|
||||
- `packages/daemon/src/domain/policies/artifact-pool-helpers.ts`: Shared filesystem scanner + formatter for artifact-pool-ready and edge-artifact-required. Translated from POC `lib/policies/artifact-pool.js`. Exports: scanArtifactPools, formatArtifactList, sourceKeyFor, ArtifactPoolSpec, ScannedArtifact. Related: none.
|
||||
- `packages/daemon/src/routes/watchdog.ts`: Hono route module for `/api/watchdog` (`POST /register`, `GET /list`, `GET /sse`, `GET /watch`, `GET /:job_id`, `GET /:job_id/status`, `POST /:job_id/stop`). SSE/literal paths mounted before /:job_id catchall per Phase A R1 route-order discipline. Exports: watchdogRoutes. Related: `packages/daemon/src/domain/watchdog-jobs-repository.js`, `packages/daemon/src/domain/watchdog-history-log.js`, `packages/daemon/src/domain/event-bus.js`.
|
||||
- `packages/daemon/src/domain/policies/workflow-keepalive.ts`: PL-004 Phase D — workflow-keepalive policy (carry-forward from Phase C deferral). Reads workflow_instances directly via SQLite (audit row 18 LOAD-BEARING); requires status active|waiting; resolves frontier qitem owners via queue_items. Translated from POC `lib/policies/workflow-keepalive.mjs`; source-of-truth switched from markdown to SQLite. Exports: makeWorkflowKeepalivePolicy. Related: `packages/daemon/src/domain/policies/types.js`, `packages/daemon/src/db/migrations/034_workflow_instances.js`.
|
||||
|
||||
### root
|
||||
### Domain: Workflow Runtime (PL-004 Phase D)
|
||||
- `packages/daemon/src/domain/workflow-types.ts`: Shared types (WorkflowSpec, WorkflowInstance, WorkflowStepTrailEntry, WorkflowExitKind). Reverse-engineered from POC `workflow-runtime-v0/lib/workflow-runtime.rb` + fixture YAMLs. Exports: WorkflowSpec, WorkflowStepSpec, WorkflowRoleSpec, WorkflowInvariants, WorkflowClosureMessages, WorkflowLoopGuards, WorkflowInstance, WorkflowInstanceStatus, WorkflowStepTrailEntry, WorkflowExitKind, WorkflowSpecRow. Related: none.
|
||||
- `packages/daemon/src/domain/workflow-spec-cache.ts`: Read-through cache from markdown/YAML spec files into workflow_specs table. Workspace-surface reconciliation: source_hash invalidates the cache on next read; valid operator edits to spec files win. Uses the `yaml` package for parsing. Exports: WorkflowSpecCache, WorkflowSpecError, parseWorkflowSpec. Related: `packages/daemon/src/db/migrations/033_workflow_specs.js`.
|
||||
- `packages/daemon/src/domain/workflow-validator.ts`: Validates a workflow spec against role resolution, step uniqueness, allowed-exits consistency, and (optional via injected callback) seat liveness. Returns structured ValidationResult with severity-tagged issues. Exports: WorkflowValidator, ValidationIssue, ValidationResult, SeatLivenessCheckFn. Related: `packages/daemon/src/domain/workflow-types.js`.
|
||||
- `packages/daemon/src/domain/workflow-instance-store.ts`: CRUD on workflow_instances + frontier tracking. Survives daemon restart (queries SQLite directly). Exports: WorkflowInstanceStore, WorkflowInstanceError, CreateWorkflowInstanceInput. Related: `packages/daemon/src/db/migrations/034_workflow_instances.js`.
|
||||
- `packages/daemon/src/domain/workflow-step-trail-log.ts`: Append-only writer/reader for workflow_step_trails. API surface lacks update/delete (contract enforcement). Mirrors Phase A's queue-transition-log + Phase C's watchdog-history-log shape. Exports: WorkflowStepTrailLog, WorkflowStepTrailRecordInput. Related: `packages/daemon/src/db/migrations/035_workflow_step_trails.js`.
|
||||
- `packages/daemon/src/domain/workflow-projector.ts`: LOAD-BEARING. Implements the transactional-scribe contract: closing a workflow_instances frontier qitem AND creating the next-step queue_items row AND appending the workflow_step_trails entry AND updating instance frontier+status all happen in the SAME daemon transaction (db.transaction). If any side throws, all roll back. Lost handoffs are impossible by design. Post-commit, fans out persisted events + nudges next owner. Uses Phase A QueueRepository.createWithinTransaction() (Phase D extension point). Exports: WorkflowProjector, WorkflowProjectorError, ProjectStepInput, ProjectStepResult. Related: `packages/daemon/src/domain/queue-repository.js`, `packages/daemon/src/domain/workflow-instance-store.js`, `packages/daemon/src/domain/workflow-step-trail-log.js`.
|
||||
- `packages/daemon/src/domain/workflow-runtime.ts`: Facade over spec-cache + validator + instance-store + projector + step-trail-log. Operations: validate, instantiate (creates instance + entry qitem in same transaction), project (delegates to projector), continue (idempotent inspector). Exports: WorkflowRuntime, WorkflowRuntimeDeps, InstantiateInput, InstantiateResult, WorkflowInstanceError, WorkflowProjectorError, WorkflowSpecError. Related: `packages/daemon/src/domain/workflow-projector.js`, `packages/daemon/src/domain/workflow-spec-cache.js`.
|
||||
- `packages/daemon/src/routes/workflow.ts`: Hono route module for `/api/workflow` (`POST /validate`, `POST /instantiate`, `POST /project`, `GET /list`, `GET /sse`, `GET /watch`, `GET /:instance_id`, `GET /:instance_id/trace`, `POST /:instance_id/continue`). SSE/literal paths mounted before /:instance_id catchall per Phase A R1 route-order discipline. Exports: workflowRoutes. Related: `packages/daemon/src/domain/workflow-runtime.js`, `packages/daemon/src/domain/event-bus.js`.
|
||||
|
||||
| Doc | One-sentence summary | Reach for this when… |
|
||||
|---|---|---|
|
||||
| `cli-reference.md` | The full `rig` CLI surface, kept as one doc. | You need the exact rig CLI surface — command groups, subcommands, flags, JSON output, cross-host, coordination primitives. |
|
||||
| `frontmatter-schema.md` | The frontmatter convention these docs follow + the as-built-unique field. | You are authoring or updating a doc under `docs/as-built/`. |
|
||||
| `../DESIGN.md` | The canonical visual / brand / design-system spec (repo `docs/` root). | You need the visual system, brand identity, or design-system tokens. (Stays at root by design; pointer only.) |
|
||||
### Domain: Core Runtime
|
||||
- `packages/daemon/src/domain/errors.ts`: Domain-specific error types, currently including `RigNotFoundError`. Exports: RigNotFoundError. Related: none.
|
||||
- `packages/daemon/src/domain/event-bus.ts`: Persistent event log plus in-process pub/sub for routes, SSE, and domain emitters. Exports: EventBus. Related: `packages/daemon/src/domain/types.js`.
|
||||
- `packages/daemon/src/domain/graph-projection.ts`: Pure projection from persisted rig/session state to React Flow graph nodes and edges. Exports: ReactFlowGraph, RigGraphInput, projectRigToGraph. Related: `packages/daemon/src/domain/types.js`.
|
||||
- `packages/daemon/src/domain/context-monitor.ts`: Daemon-owned context-usage recorder that samples live runtime state and updates persistent usage summaries. Exports: ContextMonitor. Related: `packages/daemon/src/domain/context-usage-store.js`.
|
||||
- `packages/daemon/src/domain/context-usage-store.ts`: SQLite-backed store for per-node context usage snapshots used by whoami/node inventory surfaces. Exports: ContextUsageStore, ContextUsageSnapshot, ContextUsageStoreOpts. Related: none.
|
||||
- `packages/daemon/src/domain/node-launcher.ts`: Atomic node launch service that creates tmux, session rows, bindings, and launch events together. Exports: LaunchResult, NodeLauncher. Related: `packages/daemon/src/adapters/tmux.js`, `packages/daemon/src/domain/event-bus.js`, `packages/daemon/src/domain/rig-repository.js`, `packages/daemon/src/domain/session-name.js`, +2 more.
|
||||
- `packages/daemon/src/domain/ps-projection.ts`: Builds the `/api/ps` summary view over rigs, nodes, sessions, and latest snapshots. Exports: PsEntry, PsProjectionService. Related: none.
|
||||
- `packages/daemon/src/domain/reconciler.ts`: Marks missing tmux sessions as detached and keeps persisted session state aligned with reality. Exports: ReconcileResult, Reconciler. Related: `packages/daemon/src/adapters/tmux.js`, `packages/daemon/src/domain/event-bus.js`, `packages/daemon/src/domain/session-registry.js`.
|
||||
- `packages/daemon/src/domain/rig-repository.ts`: SQLite-backed repository for rig, node, edge, and rig-services state. Also projects `hasServices` into rig summaries for runtime/UI gating. Exports: RigRepository. Related: `packages/daemon/src/domain/types.js`.
|
||||
- `packages/daemon/src/domain/rig-teardown.ts`: Graceful rig shutdown/delete orchestrator used by `/api/down`. Exports: RigTeardownOrchestrator, TeardownResult. Related: `packages/daemon/src/adapters/tmux.js`, `packages/daemon/src/domain/errors.js`, `packages/daemon/src/domain/event-bus.js`, `packages/daemon/src/domain/rig-repository.js`, +2 more.
|
||||
- `packages/daemon/src/domain/service-orchestrator.ts`: Rig-scoped services orchestrator for env boot, readiness gating, receipt capture, and teardown. Exports: ServiceBootResult, ServiceOrchestrator, ServiceTeardownResult. Related: `packages/daemon/src/adapters/compose-services-adapter.js`, `packages/daemon/src/domain/rig-repository.js`, `packages/daemon/src/domain/services-readiness.js`.
|
||||
- `packages/daemon/src/domain/session-name.ts`: Tmux session-name derivation and validation helpers. Exports: deriveSessionName, validateSessionName. Related: none.
|
||||
- `packages/daemon/src/domain/session-registry.ts`: Session and binding lifecycle repository, including claimed-session registration and startup-status updates. Exports: SessionRegistry. Related: `packages/daemon/src/domain/session-name.js`, `packages/daemon/src/domain/types.js`.
|
||||
- `packages/daemon/src/domain/services-readiness.ts`: Shared readiness evaluator for RigEnv wait targets (`url`, `tcp`, `service + condition`). Exports: WaitTargetFailure, WaitTargetSuccess, evaluateWaitTargets. Related: none.
|
||||
- `packages/daemon/src/domain/types.ts`: Canonical daemon type layer for entities, events, legacy rig specs, rebooted RigSpec/AgentSpec topology, RigEnv/service contracts, startup, snapshots, and restore. Exports: AgentResources, AgentSpec, Binding, Checkpoint, ContinuityPolicySpec, ContinuityState, Edge, EnvCheckpoint, EnvReceipt, GuidanceResource, HookResource, ImportSpec, InstantiateOutcome, InstantiateResult, LegacyRigSpec, LegacyRigSpecEdge, LegacyRigSpecNode, LifecycleDefaults, Node, NodeStartupSnapshot, NodeWithBinding, PersistedEvent, PersistedProjectionEntry, Pod, PreflightResult, ProfileSpec, RestoreNodeResult, RestoreOutcome, RestoreResult, Rig, RigEvent, RigServicesRecord, RigServicesSpec, RigSpec, RigSpecCrossPodEdge, RigSpecPod, RigSpecPodEdge, RigSpecPodMember, RigWithRelations, RuntimeResource, Session, SkillResource, Snapshot, SnapshotData, StartupAction, StartupBlock, StartupFile, SubagentResource, ValidationResult. Related: none.
|
||||
- `packages/daemon/src/domain/up-command-router.ts`: Source router that classifies a path as a rig spec or rig bundle before bootstrap. Exports: RouteResult, SourceKind, UpCommandRouter. Related: `packages/daemon/src/domain/rigspec-codec.js`, `packages/daemon/src/domain/rigspec-schema.js`.
|
||||
|
||||
## (c) Structural relationship diagram
|
||||
### Domain: Specs, Resolution, Startup
|
||||
- `packages/daemon/src/domain/agent-manifest.ts`: Canonical `agent.yaml` parser, validator, and normalizer for AgentSpec files. Exports: normalizeAgentSpec, parseAgentSpec, validateAgentSpec. Related: `packages/daemon/src/domain/path-safety.js`, `packages/daemon/src/domain/startup-validation.js`, `packages/daemon/src/domain/types.js`.
|
||||
- `packages/daemon/src/domain/agent-preflight.ts`: Lightweight preflight for a single `agent_ref`, used before full rig instantiation. Exports: agentPreflight. Related: `packages/daemon/src/domain/agent-resolver.js`, `packages/daemon/src/domain/types.js`.
|
||||
- `packages/daemon/src/domain/agent-resolver.ts`: Resolves `agent_ref` roots, imported AgentSpecs, and cross-spec resource-collision metadata. Exports: AgentResolverFsOps, ResolveResult, ResolvedAgentSpec, ResourceCollision, resolveAgentRef, resolveImports. Related: `packages/daemon/src/domain/agent-manifest.js`, `packages/daemon/src/domain/types.js`.
|
||||
- `packages/daemon/src/domain/pod-repository.ts`: SQLite-backed repository for pods and live continuity-state rows. Exports: PodRepository. Related: `packages/daemon/src/domain/types.js`.
|
||||
- `packages/daemon/src/domain/profile-resolver.ts`: Applies AgentSpec defaults, profile uses, startup layering, and restore-policy narrowing to produce a `ResolvedNodeConfig`. Exports: QualifiedResource, ResolutionContext, ResolutionResult, ResolvedNodeConfig, ResolvedResources, resolveNodeConfig. Related: `packages/daemon/src/domain/agent-resolver.js`, `packages/daemon/src/domain/startup-resolver.js`, `packages/daemon/src/domain/types.js`.
|
||||
- `packages/daemon/src/domain/projection-planner.ts`: Converts resolved node config plus collision data into runtime projection entries, diagnostics, conflicts, and no-ops. Exports: PlanResult, ProjectionClassification, ProjectionEntry, ProjectionFsOps, ProjectionInput, ProjectionPlan, planProjection. Related: `packages/daemon/src/domain/agent-resolver.js`, `packages/daemon/src/domain/conflict-detector.js`, `packages/daemon/src/domain/profile-resolver.js`, `packages/daemon/src/domain/types.js`.
|
||||
- `packages/daemon/src/domain/rigspec-codec.ts`: YAML codec layer for both legacy flat-node RigSpec and rebooted pod-aware RigSpec shapes. Exports: LegacyRigSpecCodec, RigSpecCodec. Related: `packages/daemon/src/domain/types.js`.
|
||||
- `packages/daemon/src/domain/rigspec-exporter.ts`: Exports live rigs back into RigSpec YAML/JSON. Dual-format: detects pod-aware rigs (podId non-null) and exports canonical v0.2 RigSpec with pods/members/edges; legacy rigs export as flat-node v1. Exports: RigSpecExporter. Related: `packages/daemon/src/domain/errors.js`, `packages/daemon/src/domain/pod-repository.js`, `packages/daemon/src/domain/rig-repository.js`, `packages/daemon/src/domain/session-registry.js`, `packages/daemon/src/domain/types.js`.
|
||||
- `packages/daemon/src/domain/rigspec-instantiator.ts`: Dual-stack instantiation layer containing both legacy `RigInstantiator` and rebooted `PodRigInstantiator`. Exports: PodRigInstantiator, RigInstantiator. Related: `packages/daemon/src/domain/agent-resolver.js`, `packages/daemon/src/domain/event-bus.js`, `packages/daemon/src/domain/node-launcher.js`, `packages/daemon/src/domain/pod-repository.js`, +10 more.
|
||||
- `packages/daemon/src/domain/rigspec-preflight.ts`: Dual-stack preflight layer: legacy `RigSpecPreflight` plus rebooted pure `rigPreflight`. Exports: RigPreflightInput, RigSpecPreflight, rigPreflight. Related: `packages/daemon/src/adapters/tmux.js`, `packages/daemon/src/domain/agent-resolver.js`, `packages/daemon/src/domain/profile-resolver.js`, `packages/daemon/src/domain/rig-repository.js`, +4 more.
|
||||
- `packages/daemon/src/domain/rigspec-schema.ts`: Validation and normalization for both legacy and rebooted RigSpec schemas. Exports: LegacyRigSpecSchema, RigSpecSchema. Related: `packages/daemon/src/domain/path-safety.js`, `packages/daemon/src/domain/startup-validation.js`, `packages/daemon/src/domain/types.js`.
|
||||
- `packages/daemon/src/domain/runtime-adapter.ts`: Runtime-adapter contract plus bridge types used by startup orchestration and runtime-specific adapters. Exports: InstalledResource, NodeBinding, ProjectionResult, ReadinessResult, ResolvedStartupFile, RuntimeAdapter, StartupDeliveryResult. Related: `packages/daemon/src/domain/projection-planner.js`, `packages/daemon/src/domain/types.js`.
|
||||
- `packages/daemon/src/domain/spec-validation-service.ts`: Pure validation helpers for raw AgentSpec and RigSpec YAML strings. Exports: validateAgentSpecFromYaml, validateRigSpecFromYaml. Related: `packages/daemon/src/domain/agent-manifest.js`, `packages/daemon/src/domain/rigspec-codec.js`, `packages/daemon/src/domain/rigspec-schema.js`.
|
||||
- `packages/daemon/src/domain/spec-review-service.ts`: Structured review-model builder for RigSpec and AgentSpec YAML. Produces topology preview data, normalized summaries, provenance/source-state, and managed-app services metadata used by preview, library, and live display surfaces. Exports: AgentSpecReview, LegacyRigSpecReview, PodAwareRigSpecReview, RigSpecReview, RigSpecServicesReview, SourceState, SpecGraphData, SpecReviewError, SpecReviewService. Related: `packages/daemon/src/domain/agent-manifest.js`, `packages/daemon/src/domain/rigspec-codec.js`, `packages/daemon/src/domain/rigspec-schema.js`.
|
||||
- `packages/daemon/src/domain/spec-library-service.ts`: Filesystem-backed spec library index over builtin and user roots. Classifies YAML through `SpecReviewService`, assigns stable ids, marks service-backed rigs with `hasServices`, and serves metadata/YAML lookup. Exports: SpecLibraryEntry, SpecLibraryOpts, SpecLibraryService. Related: `packages/daemon/src/domain/spec-review-service.js`.
|
||||
- `packages/daemon/src/domain/whoami-service.ts`: Daemon-side runtime identity projector used by `/api/whoami`. Resolves by node or session, expands peers/edges/transcript helpers, and surfaces ambiguity honestly. Exports: WhoamiResult, WhoamiAmbiguousError, WhoamiService. Related: `packages/daemon/src/domain/rig-repository.js`, `packages/daemon/src/domain/session-registry.js`, `packages/daemon/src/domain/transcript-store.js`.
|
||||
- `packages/daemon/src/domain/startup-orchestrator.ts`: Startup execution engine for projection, startup-file delivery, action execution, readiness, and persisted replay context. Exports: StartupInput, StartupOrchestrator, StartupResult. Related: `packages/daemon/src/adapters/tmux.js`, `packages/daemon/src/domain/event-bus.js`, `packages/daemon/src/domain/projection-planner.js`, `packages/daemon/src/domain/runtime-adapter.js`, +2 more.
|
||||
- `packages/daemon/src/domain/startup-resolver.ts`: Pure additive startup-layer merge function across agent, profile, rig, pod, member, and operator layers. Exports: StartupLayerInputs, resolveStartup. Related: `packages/daemon/src/domain/types.js`.
|
||||
- `packages/daemon/src/domain/startup-validation.ts`: Shared validation and normalization for startup files and startup actions. Exports: normalizeStartupBlock, validateStartupAction, validateStartupBlock, validateStartupFile. Related: `packages/daemon/src/domain/path-safety.js`, `packages/daemon/src/domain/types.js`.
|
||||
|
||||
Built from each module's `siblings` / `prerequisite-reads` frontmatter.
|
||||
`daemon-core.md` is the spine (prerequisite for almost every architecture
|
||||
module); `shell-and-routing.md` is the UI spine.
|
||||
### Domain: Snapshots And Restore
|
||||
- `packages/daemon/src/domain/checkpoint-store.ts`: Checkpoint persistence, lookup, and rig-wide checkpoint aggregation. Exports: CheckpointStore. Related: `packages/daemon/src/domain/types.js`.
|
||||
- `packages/daemon/src/domain/restore-orchestrator.ts`: Restore pipeline for relaunch, resume, checkpoint delivery, startup replay, topology ordering, and RigEnv boot gating before agent restore. Exports: RestoreOrchestrator. Related: `packages/daemon/src/adapters/claude-resume.js`, `packages/daemon/src/adapters/codex-resume.js`, `packages/daemon/src/adapters/tmux.js`, `packages/daemon/src/domain/checkpoint-store.js`, +7 more.
|
||||
- `packages/daemon/src/domain/snapshot-capture.ts`: Captures a consistent snapshot of rig topology, sessions, checkpoints, pods, continuity state, startup context, and the latest rig-env receipt. Exports: SnapshotCapture. Related: `packages/daemon/src/domain/checkpoint-store.js`, `packages/daemon/src/domain/errors.js`, `packages/daemon/src/domain/event-bus.js`, `packages/daemon/src/domain/rig-repository.js`, +3 more.
|
||||
- `packages/daemon/src/domain/snapshot-repository.ts`: SQLite-backed repository for snapshot CRUD and listing. Exports: SnapshotRepository. Related: `packages/daemon/src/domain/types.js`.
|
||||
|
||||
```
|
||||
README.md (entry — prerequisite for all)
|
||||
│
|
||||
┌───────────────┴───────────────┐
|
||||
▼ ▼
|
||||
architecture/ ui/
|
||||
│ │
|
||||
daemon-core.md ◀── (prerequisite spine for the column below)
|
||||
│ │ │ │
|
||||
│ │ │ └──▶ adapters-and-runtimes.md
|
||||
│ │ │ (five-method contract + resume honesty;
|
||||
│ │ │ consumed by agent-spec startup orchestration)
|
||||
│ │ └────────────────────────────┐
|
||||
│ └──────────────┐ │
|
||||
▼ ▼ ▼
|
||||
coordination- agent-spec-and- transport-and-
|
||||
primitive.md startup.md transcripts.md
|
||||
│ │ │ │
|
||||
▼ ▼ │ ▼
|
||||
workflow- mission- │ lifecycle-snapshot-restore.md
|
||||
runtime.md control.md │ ▲ (consumes persisted replay context)
|
||||
│ │ │
|
||||
└────┬─────┘ ├──▶ packaging-bootstrap-bundles.md
|
||||
▼ │ ▲
|
||||
architecture-rules- │ │ (0.3.x reusable starter-state cluster)
|
||||
and-event-system.md │ ▼
|
||||
(consumes all └──▶ plugin-agent-image-context-pack.md
|
||||
PL-004/005 events)
|
||||
### Domain: Packages And Install Engine
|
||||
- `packages/daemon/src/domain/conflict-detector.ts`: Content-aware conflict classification shared by package installs and rebooted projection planning. Exports: GuidanceConflictMeta, RefinedInstallPlan, classifyResourceProjection, detectConflicts. Related: `packages/daemon/src/domain/install-planner.js`, `packages/daemon/src/domain/package-resolver.js`, `packages/daemon/src/domain/projection-planner.js`.
|
||||
- `packages/daemon/src/domain/install-engine.ts`: Journaled apply/rollback engine for package installs. Exports: EngineFsOps, InstallEngine, InstallResult, RollbackResult. Related: `packages/daemon/src/domain/conflict-detector.js`, `packages/daemon/src/domain/install-planner.js`, `packages/daemon/src/domain/install-policy.js`, `packages/daemon/src/domain/install-repository.js`.
|
||||
- `packages/daemon/src/domain/install-planner.ts`: Computes classified package install entries and target paths. Exports: ActionClassification, ConflictInfo, InstallPlan, InstallPlanEntry, InstallPlanner, PlanOptions. Related: `packages/daemon/src/domain/package-resolver.js`, `packages/daemon/src/domain/role-resolver.js`.
|
||||
- `packages/daemon/src/domain/install-policy.ts`: Approval-policy gate for package install plans. Exports: PolicyRejection, PolicyResult, applyPolicy. Related: `packages/daemon/src/domain/conflict-detector.js`, `packages/daemon/src/domain/install-planner.js`.
|
||||
- `packages/daemon/src/domain/install-repository.ts`: SQLite-backed repository for package install records and journal entries. Exports: Install, InstallRepository, InstallSummary, JournalEntry. Related: none.
|
||||
- `packages/daemon/src/domain/install-verifier.ts`: Post-apply verification for install records and filesystem targets. Exports: Check, EntryVerification, InstallVerifier, VerificationResult, VerifierFsOps. Related: `packages/daemon/src/domain/install-repository.js`, `packages/daemon/src/domain/package-repository.js`.
|
||||
- `packages/daemon/src/domain/package-install-service.ts`: Top-level package validate/plan/install/rollback service used by routes and bootstrap. Exports: PackageInstallOutcome, PackageInstallService. Related: `packages/daemon/src/domain/conflict-detector.js`, `packages/daemon/src/domain/install-engine.js`, `packages/daemon/src/domain/install-planner.js`, `packages/daemon/src/domain/install-policy.js`, +4 more.
|
||||
- `packages/daemon/src/domain/package-manifest.ts`: Parser and validator for `package.yaml` manifests. Exports: AgentExport, GuidanceExport, HookExport, InstallPolicy, McpExport, PackageExports, PackageManifest, PackageRequirements, RoleDefinition, SkillExport, ValidationResult, VerificationCheck, VerificationConfig, normalizeManifest, parseManifest, serializeManifest, validateManifest. Related: none.
|
||||
- `packages/daemon/src/domain/package-repository.ts`: SQLite-backed repository for package metadata and install summaries. Exports: Package, PackageRepository, PackageSummary. Related: none.
|
||||
- `packages/daemon/src/domain/package-resolve-helper.ts`: Shared helper that wraps package resolution for routes and orchestrators. Exports: ResolveResult, resolvePackage. Related: `packages/daemon/src/domain/package-manifest.js`, `packages/daemon/src/domain/package-resolver.js`.
|
||||
- `packages/daemon/src/domain/package-resolver.ts`: Resolves local package sources and computes manifest hashes. Exports: FsOps, PackageResolver, ResolvedPackage. Related: `packages/daemon/src/domain/package-manifest.js`.
|
||||
- `packages/daemon/src/domain/path-safety.ts`: Shared safe-path validator used by manifests and startup config. Exports: validateSafePath. Related: none.
|
||||
- `packages/daemon/src/domain/role-resolver.ts`: Filters package exports according to selected roles/runtime scope. Exports: DeferredExport, ResolvedExports, resolveExports. Related: `packages/daemon/src/domain/package-manifest.js`.
|
||||
|
||||
workspace-primitive.md ──▶ content-surfaces.md
|
||||
(PL-007 declaration) (filesystem read/write layer on top)
|
||||
│ │
|
||||
└──────────┬───────────────┘
|
||||
▼ (UI counterpart)
|
||||
ui/project-and-for-you.md
|
||||
### Domain: Bootstrap, Discovery, Bundles
|
||||
- `packages/daemon/src/domain/bootstrap-orchestrator.ts`: Staged bootstrap workflow that composes runtime verification, requirement probes, external installs, package installs, legacy rig instantiation, direct pod-aware rig handling, and schema-version-2 pod-bundle delegation. Exports: BootstrapMode, BootstrapOptions, BootstrapOrchestrator, BootstrapResult, BootstrapStageResult. Related: `packages/daemon/src/domain/bootstrap-repository.js`, `packages/daemon/src/domain/bootstrap-types.js`, `packages/daemon/src/domain/bundle-source-resolver.js`, `packages/daemon/src/domain/external-install-executor.js`, +10 more.
|
||||
- `packages/daemon/src/domain/bootstrap-repository.ts`: SQLite-backed repository for bootstrap runs and action journals. Exports: BootstrapRepository. Related: `packages/daemon/src/domain/bootstrap-types.js`.
|
||||
- `packages/daemon/src/domain/bootstrap-types.ts`: Shared type definitions for bootstrap data. Exports: ActionKind, ActionStatus, BootstrapAction, BootstrapRun, BootstrapStatus, RuntimeStatus, RuntimeVerification. Related: none.
|
||||
- `packages/daemon/src/domain/bundle-archive.ts`: Archive pack/unpack and digest verification for `.rigbundle` files. Exports: pack, unpack, verifyArchiveDigest. Related: `packages/daemon/src/domain/bundle-integrity.js`, `packages/daemon/src/domain/bundle-types.js`.
|
||||
- `packages/daemon/src/domain/bundle-assembler.ts`: Legacy rig-bundle assembler for package-based bundles. Exports: AssembleOptions, AssemblerFsOps, LegacyBundleAssembler, PackageInput. Related: `packages/daemon/src/domain/bundle-types.js`, `packages/daemon/src/domain/rigspec-codec.js`, `packages/daemon/src/domain/rigspec-schema.js`.
|
||||
- `packages/daemon/src/domain/bundle-integrity.ts`: Per-file integrity manifest generation and verification for bundles. Exports: IntegrityFsOps, VerifyResult, computeIntegrity, verifyIntegrity, writeIntegrity. Related: `packages/daemon/src/domain/bundle-types.js`.
|
||||
- `packages/daemon/src/domain/bundle-source-resolver.ts`: Dual-stack bundle resolver containing legacy package-bundle and rebooted pod-bundle extraction flows. Exports: BundleResolvedSource, LegacyBundleSourceResolver, PodBundleResolvedSource, PodBundleSourceResolver. Related: `packages/daemon/src/domain/bundle-archive.js`, `packages/daemon/src/domain/bundle-types.js`, `packages/daemon/src/domain/package-resolve-helper.js`, `packages/daemon/src/domain/package-resolver.js`.
|
||||
- `packages/daemon/src/domain/bundle-types.ts`: Bundle manifest types plus parse/validate/serialize helpers for schema v1 and schema v2 bundles. Exports: BundleIntegrity, LegacyBundleManifest, LegacyBundlePackageEntry, PodBundleAgentEntry, PodBundleAgentImportEntry, PodBundleManifest, isRelativeSafePath, normalizeLegacyBundleManifest, parseLegacyBundleManifest, parsePodBundleManifest, serializeLegacyBundleManifest, serializePodBundleManifest, validateLegacyBundleManifest, validatePodBundleManifest. Related: none.
|
||||
- `packages/daemon/src/domain/claim-service.ts`: Claims discovered sessions into managed rig/node state. Exports: ClaimResult, ClaimService. Related: `packages/daemon/src/domain/discovery-repository.js`, `packages/daemon/src/domain/event-bus.js`, `packages/daemon/src/domain/rig-repository.js`, `packages/daemon/src/domain/session-registry.js`.
|
||||
- `packages/daemon/src/domain/discovery-coordinator.ts`: Coordinates tmux scans, fingerprinting, enrichment, persistence, and event emission for discovery. Exports: DiscoveryCoordinator. Related: `packages/daemon/src/domain/discovery-repository.js`, `packages/daemon/src/domain/discovery-types.js`, `packages/daemon/src/domain/event-bus.js`, `packages/daemon/src/domain/session-enricher.js`, +3 more.
|
||||
- `packages/daemon/src/domain/discovery-repository.ts`: SQLite-backed repository for discovered session records. Exports: DiscoveryRepository, UpsertData. Related: `packages/daemon/src/domain/discovery-types.js`.
|
||||
- `packages/daemon/src/domain/discovery-types.ts`: Shared type definitions for discovery data. Exports: Confidence, DiscoveredSession, DiscoveryStatus, RuntimeHint, SessionOrigin. Related: none.
|
||||
- `packages/daemon/src/domain/external-install-executor.ts`: Runs approved external install actions and journals execution results. Exports: ExecutionResult, ExecutionSummary, ExternalInstallExecutor, TaggedAction. Related: `packages/daemon/src/adapters/tmux.js`, `packages/daemon/src/domain/external-install-planner.js`.
|
||||
- `packages/daemon/src/domain/external-install-planner.ts`: Turns requirement-probe results into auto-approvable or manual external install actions. Exports: ApprovalClassification, ExternalInstallAction, ExternalInstallPlan, ExternalInstallPlanner. Related: `packages/daemon/src/adapters/shell-quote.js`, `packages/daemon/src/domain/requirements-probe.js`.
|
||||
- `packages/daemon/src/domain/pod-bundle-assembler.ts`: Rebooted bundle assembler that vendors AgentSpecs, imports, rig startup files, and rewritten `agent_ref`s. Exports: PodAssembleOptions, PodAssembleResult, PodAssemblerFsOps, PodBundleAssembler. Related: `packages/daemon/src/domain/agent-resolver.js`, `packages/daemon/src/domain/bundle-types.js`, `packages/daemon/src/domain/rigspec-codec.js`, `packages/daemon/src/domain/rigspec-schema.js`, +1 more.
|
||||
- `packages/daemon/src/domain/requirements-probe.ts`: Requirement-probe registry and probe result types used during bootstrap. Exports: ProbeResult, ProbeStatus, RequirementSpec, RequirementsProbeRegistry. Related: `packages/daemon/src/adapters/shell-quote.js`, `packages/daemon/src/adapters/tmux.js`.
|
||||
- `packages/daemon/src/domain/runtime-verifier.ts`: Verifies runtime/tool availability and persists verification results. Exports: RuntimeVerifier. Related: `packages/daemon/src/adapters/tmux.js`, `packages/daemon/src/domain/bootstrap-types.js`.
|
||||
- `packages/daemon/src/domain/session-enricher.ts`: Adds repository/config hints to discovered sessions based on filesystem inspection. Exports: EnrichmentResult, SessionEnricher. Related: none.
|
||||
- `packages/daemon/src/domain/session-fingerprinter.ts`: Infers runtime/session identity from tmux, cmux, process, and pane evidence. Exports: FingerprintEvidence, FingerprintResult, SessionFingerprinter. Related: `packages/daemon/src/adapters/cmux.js`, `packages/daemon/src/adapters/tmux.js`, `packages/daemon/src/domain/discovery-types.js`, `packages/daemon/src/domain/tmux-discovery-scanner.js`.
|
||||
- `packages/daemon/src/domain/tmux-discovery-scanner.ts`: Low-level tmux scanner that enumerates panes/sessions for discovery. Exports: ScanResult, ScannedPane, TmuxDiscoveryScanner. Related: `packages/daemon/src/adapters/tmux.js`.
|
||||
|
||||
shell-and-routing.md ──▶ topology.md
|
||||
│ └──▶ project-and-for-you.md ◀──▶ architecture/mission-control.md
|
||||
└──────────────▶ library-specs-and-design-system.md ──▶ ../DESIGN.md (pointer)
|
||||
```
|
||||
### Domain: North Star Operator Layer
|
||||
- `packages/daemon/src/domain/node-inventory.ts`: Universal node-level projection consumed by CLI, UI, and MCP. Core fields (session name, status, startup status, restore outcome, attach command) plus extended fields (model, agent ref, startup files, installed resources). Exports: NodeInventoryService. Related: `packages/daemon/src/domain/types.js`, `packages/daemon/src/domain/runtime-adapter.js`.
|
||||
- `packages/daemon/src/domain/demo-rig-selector.ts`: Helper for existing-rig power-on — finds the right rig by name from ps summary entries. Exports: selectCurrentRigSummary. Related: none.
|
||||
- `packages/daemon/src/domain/draft-rig-generator.ts`: Synthesizes a candidate RigSpec YAML from discovered sessions — groups by CWD, suggests pods, sanitizes IDs. Exports: generateDraftRig. Related: `packages/daemon/src/domain/discovery-types.js`, `packages/daemon/src/domain/rigspec-codec.js`, `packages/daemon/src/domain/types.js`.
|
||||
- `packages/daemon/src/domain/native-resume-probe.ts`: Honest assessment of whether a harness actually resumed vs fresh-launched — probes pane command and content for runtime-specific indicators. Exports: NativeResumeProbeResult, assessNativeResumeProbe, buildNativeResumeCommand, isProbeShellReady. Related: `packages/daemon/src/adapters/shell-quote.js`.
|
||||
- `packages/daemon/src/domain/resume-metadata-refresher.ts`: Post-launch resume token capture — reads Claude conversation IDs from state files and Codex thread IDs from SQLite. Exports: ResumeMetadataRefresher. Related: `packages/daemon/src/domain/codex-thread-id.js`, `packages/daemon/src/domain/native-resume-probe.js`, `packages/daemon/src/domain/session-registry.js`, `packages/daemon/src/adapters/tmux.js`.
|
||||
- `packages/daemon/src/domain/codex-thread-id.ts`: Codex-specific thread ID extraction from the Codex SQLite state database. Exports: defaultResolveHomeDirByPid, readCodexThreadIdFromCandidateHomes, ResolveHomeDirByPid. Related: none.
|
||||
|
||||
Reading-order rule: open a module's `prerequisite-reads` first
|
||||
(`README.md`, then `daemon-core.md` for most architecture modules;
|
||||
`README.md` then `shell-and-routing.md` for most ui modules).
|
||||
### Domain: Post-North-Star Transport and History
|
||||
- `packages/daemon/src/domain/session-transport.ts`: Communication primitives — send/capture/broadcast with session resolution (canonical + legacy names), mid-work detection via pane content heuristics, honest error reporting, pod/rig/global targeting. Exports: SessionTransport, TargetSpec, SendResult, CaptureResult, BroadcastResult, SendOpts. Related: `packages/daemon/src/domain/rig-repository.js`, `packages/daemon/src/domain/session-registry.js`, `packages/daemon/src/adapters/tmux.js`.
|
||||
- `packages/daemon/src/domain/transcript-store.ts`: Pipe-pane transcript management — ANSI stripping on read (preserves raw on disk), boundary markers for session lifecycle events, readTail, grep. Filesystem-backed, not SQLite. Exports: TranscriptStore, TranscriptStoreOpts. Related: none (filesystem-only).
|
||||
- `packages/daemon/src/domain/history-query.ts`: Unified transcript + chat search — prefers `rg` when available, falls back to `grep -E`, surfaces which backend was used. Exports: HistoryQuery, SearchResult, ChatSearchResult, ExecDep. Related: `packages/daemon/src/domain/transcript-store.js`.
|
||||
- `packages/daemon/src/domain/ask-service.ts`: Context engineering evidence pack — gathers topology snapshot, transcript excerpts, chat history excerpts, restore metadata. Returns structured context for the agent to reason about. Does NOT call an external LLM. Exports: AskService, AskDeps. Related: `packages/daemon/src/domain/ps-projection.js`, `packages/daemon/src/domain/rig-repository.js`, `packages/daemon/src/domain/history-query.js`.
|
||||
- `packages/daemon/src/domain/chat-repository.ts`: Durable rig-scoped chat messages — CRUD for chat_messages table, monotonic ULID IDs, rig-scoped queries. Exports: ChatRepository, ChatMessage. Related: none (SQLite-only).
|
||||
|
||||
## (d) Fast lookup by use-case
|
||||
### Domain: Coordination Primitive (PL-004 Phase A)
|
||||
- `packages/daemon/src/domain/stream-store.ts`: L1 coordination stream — append-only intake/audit root. Idempotent emit on stream_item_id, chronological list with cursor pagination, soft archive. Exports: StreamStore, StreamItem, StreamEmitInput, StreamListOptions. Related: `packages/daemon/src/domain/event-bus.js`.
|
||||
- `packages/daemon/src/domain/queue-repository.ts`: L3 coordination queue — create, claim/unclaim, update with hot-potato strict-rejection, transactional handoff (close source + create new in one transaction), pod-fallback rerouting, overdue lookup. POC qitem_id format preserved. Exports: QueueRepository, QueueRepositoryError, QueueItem, QueueState, QueuePriority, QueueCreateInput, QueueUpdateInput, QueueHandoffInput. Related: `packages/daemon/src/domain/event-bus.js`, `packages/daemon/src/domain/queue-transition-log.js`, `packages/daemon/src/domain/hot-potato-enforcer.js`.
|
||||
- `packages/daemon/src/domain/queue-transition-log.ts`: Append-only state transition log for queue_items. No UPDATE / DELETE from domain code. Exports: QueueTransitionLog, QueueTransition, QueueTransitionInput. Related: `packages/daemon/src/domain/hot-potato-enforcer.js`.
|
||||
- `packages/daemon/src/domain/hot-potato-enforcer.ts`: Pure validator for the load-bearing hot-potato API contract — state=done requires closure_reason from the 6-value enum. Tier→SLA mapping for closure_required_at. Exports: CLOSURE_REASONS, ClosureReason, validateClosure, isClosureReason, computeClosureRequiredAt. Related: none.
|
||||
- `packages/daemon/src/domain/inbox-handler.ts`: Mailbox handler — authenticated drop (idempotent on inbox_id), absorb (promote pending entry to a queue_item), deny (record reason). Authentication is a pluggable constructor hook. Exports: InboxHandler, InboxHandlerError, InboxEntry, InboxState, InboxDropInput. Related: `packages/daemon/src/domain/event-bus.js`, `packages/daemon/src/domain/queue-repository.js`.
|
||||
- `packages/daemon/src/domain/outbox-handler.ts`: Sender-side outbox — symmetric to inbox; idempotent record, mark delivered/failed, list. No event-bus events emitted. Exports: OutboxHandler, OutboxHandlerError, OutboxEntry, OutboxDeliveryState, OutboxRecordInput. Related: none (SQLite-only).
|
||||
|
||||
| I need to know… | → see |
|
||||
|---|---|
|
||||
| How the daemon boots / `createDaemon` wiring / migration set / route mounts | `architecture/daemon-core.md` |
|
||||
| The runtime-adapter contract / how a harness is launched or resumed in tmux | `architecture/adapters-and-runtimes.md` |
|
||||
| Where Claude resume honesty lives / resumed-vs-fresh assessment | `architecture/adapters-and-runtimes.md` |
|
||||
| Where queue closure is enforced / hot-potato contract / durable handoff | `architecture/coordination-primitive.md` |
|
||||
| How workflow specs project on closure / transactional-scribe / watchdog policies | `architecture/workflow-runtime.md` |
|
||||
| The Mission Control views/verbs / queue-observability / action audit | `architecture/mission-control.md` |
|
||||
| AgentSpec/RigSpec types, profile resolution, startup layering, whoami/bind/adopt | `architecture/agent-spec-and-startup.md` |
|
||||
| Snapshot/restore, restore honesty, restore-check / restore-packet probes | `architecture/lifecycle-snapshot-restore.md` |
|
||||
| rig send/capture/broadcast, transcripts, durable chat, `rig ask`, MCP-name vs tmux-key | `architecture/transport-and-transcripts.md` |
|
||||
| The workspace primitive (root/repos), `target_repo` scope gating, missions/slices indexing | `architecture/workspace-primitive.md` |
|
||||
| The file browser path safety, atomic writes + edit audit, PROGRESS tree, Steering composer | `architecture/content-surfaces.md` |
|
||||
| The composed slice/mission review (`/api/review/*`), staged-approval locks, proof artifacts + `verified`, freeze export, ranged media | `architecture/living-notes-review.md` |
|
||||
| Plugin discovery / agent images / context packs / Claude auto-compaction enforcer | `architecture/plugin-agent-image-context-pack.md` |
|
||||
| Bundle assembly, bundle install / `/api/up`, BootstrapOrchestrator, legacy install seams | `architecture/packaging-bootstrap-bundles.md` |
|
||||
| The 25 architecture rules / RigEvent union / SSE delivery / compatibility limits | `architecture/architecture-rules-and-event-system.md` |
|
||||
| The UI shell, the real route tree, the shared detail drawer | `ui/shell-and-routing.md` |
|
||||
| The topology graph/table/terminal views, activity-ring / hot-potato visuals | `ui/topology.md` |
|
||||
| The For-You attention feed, Project scope pages, the Dashboard landing | `ui/project-and-for-you.md` |
|
||||
| The vellum brand system on the destination surfaces (0.3.1 brand identity) | `ui/project-and-for-you.md` (vellum brand = **0.3.1** per slice-00 0.3.0-GT seam (b); slice-00 §2 row 1 = vellum-primitives → brand-identity, row 2 = destination-model → polished-destinations) |
|
||||
| The Library `/specs` UI + spec-review/spec-library/live-identity flows | `ui/library-specs-and-design-system.md` |
|
||||
| The full `rig` CLI surface | `cli-reference.md` |
|
||||
| The visual / brand / design-system spec | `../DESIGN.md` (repo `docs/` root) |
|
||||
| Which frontmatter these docs use + the as-built-unique field | `frontmatter-schema.md` |
|
||||
### Routes
|
||||
- `packages/daemon/src/routes/adapters.ts`: Hono route module for adapters API endpoints. Exports: adaptersRoutes. Related: `packages/daemon/src/adapters/cmux.js`, `packages/daemon/src/adapters/tmux.js`.
|
||||
- `packages/daemon/src/routes/agents.ts`: Hono route module for AgentSpec validation. POST `/api/agents/validate` using `validateAgentSpecFromYaml`. Exports: agentsRoutes. Related: `packages/daemon/src/domain/spec-validation-service.js`.
|
||||
- `packages/daemon/src/routes/bootstrap.ts`: Hono route module for bootstrap API endpoints. Exports: bootstrapRoutes. Related: `packages/daemon/src/domain/bootstrap-orchestrator.js`, `packages/daemon/src/domain/bootstrap-repository.js`, `packages/daemon/src/domain/event-bus.js`.
|
||||
- `packages/daemon/src/routes/bundles.ts`: Hono route module for dual-format bundle create/inspect/install. Supports legacy v1 package bundles and schema-version-2 pod bundles, including v2 inspect responses with `agents[]` and integrity data. Exports: bundleRoutes. Related: `packages/daemon/src/domain/bootstrap-orchestrator.js`, `packages/daemon/src/domain/bootstrap-repository.js`, `packages/daemon/src/domain/bundle-archive.js`, `packages/daemon/src/domain/bundle-assembler.js`, +7 more.
|
||||
- `packages/daemon/src/routes/discovery.ts`: Hono route module for discovery scan/list/detail plus Final Stretch flows: `draft-rig`, `bind`, and composite `adopt`. Exports: discoveryRoutes. Related: `packages/daemon/src/domain/claim-service.js`, `packages/daemon/src/domain/discovery-coordinator.js`, `packages/daemon/src/domain/discovery-repository.js`, `packages/daemon/src/domain/draft-rig-generator.js`.
|
||||
- `packages/daemon/src/routes/down.ts`: Hono route module for down API endpoints. Exports: downRoutes. Related: `packages/daemon/src/domain/errors.js`, `packages/daemon/src/domain/rig-teardown.js`.
|
||||
- `packages/daemon/src/routes/env.ts`: Hono route module for rig-environment status, logs, and teardown. Refreshes env receipts best-effort and returns additive managed-app/runtime metadata (`hasServices`, `surfaces`, `receipt`). Exports: envRoutes. Related: `packages/daemon/src/adapters/compose-services-adapter.js`, `packages/daemon/src/domain/rig-repository.js`, `packages/daemon/src/domain/service-orchestrator.js`.
|
||||
- `packages/daemon/src/routes/events.ts`: Hono route module for events API endpoints. Exports: eventsRoute. Related: `packages/daemon/src/domain/event-bus.js`, `packages/daemon/src/domain/types.js`.
|
||||
- `packages/daemon/src/routes/packages.ts`: Hono route module for the legacy package-install surface (`/validate`, `/plan`, `/install`, history, rollback). AgentSpec validation no longer lives here. Exports: packagesRoutes. Related: `packages/daemon/src/domain/conflict-detector.js`, `packages/daemon/src/domain/event-bus.js`, `packages/daemon/src/domain/install-engine.js`, `packages/daemon/src/domain/install-planner.js`, +6 more.
|
||||
- `packages/daemon/src/routes/ps.ts`: Hono route module for ps API endpoints. Exports: psRoutes. Related: `packages/daemon/src/domain/ps-projection.js`.
|
||||
- `packages/daemon/src/routes/rigs.ts`: Hono route module for rig CRUD, graph projection, summary, delete, and existing-rig power-on by rig id. Exports: rigsRoutes. Related: `packages/daemon/src/domain/event-bus.js`, `packages/daemon/src/domain/graph-projection.js`, `packages/daemon/src/domain/node-inventory.js`, `packages/daemon/src/domain/rig-repository.js`, `packages/daemon/src/domain/session-registry.js`.
|
||||
- `packages/daemon/src/routes/rigspec.ts`: Hono route module for dual-format RigSpec import, validate, preflight, materialize, and export. Pod-aware import/preflight/materialize require `X-Rig-Root`; export emits v0.2 pod-aware YAML/JSON when the live rig has pods. Exports: handleExportJson, handleExportYaml, rigspecImportRoutes. Related: `packages/daemon/src/domain/errors.js`, `packages/daemon/src/domain/rigspec-codec.js`, `packages/daemon/src/domain/rigspec-exporter.js`, `packages/daemon/src/domain/rigspec-instantiator.js`, +2 more.
|
||||
- `packages/daemon/src/routes/sessions.ts`: Hono route module for rig sessions and node inventory/detail/launch/focus. `GET /api/rigs/:rigId/nodes/:logicalId` is the backend contract for the live node drawer and full-details workspace. Exports: nodesRoutes, sessionsRoutes. Related: `packages/daemon/src/adapters/cmux.js`, `packages/daemon/src/domain/node-inventory.js`, `packages/daemon/src/domain/node-launcher.js`, `packages/daemon/src/domain/rig-repository.js`, `packages/daemon/src/domain/session-registry.js`.
|
||||
- `packages/daemon/src/routes/snapshots.ts`: Hono route module for snapshots API endpoints. Exports: restoreRoutes, snapshotsRoutes. Related: `packages/daemon/src/domain/errors.js`, `packages/daemon/src/domain/restore-orchestrator.js`, `packages/daemon/src/domain/snapshot-capture.js`, `packages/daemon/src/domain/snapshot-repository.js`.
|
||||
- `packages/daemon/src/routes/transport.ts`: Hono route module for communication primitives (`POST /send`, `/capture`, `/broadcast`). Resolves session targets, delegates to SessionTransport. Exports: transportRoutes. Related: `packages/daemon/src/domain/session-transport.js`.
|
||||
- `packages/daemon/src/routes/transcripts.ts`: Hono route module for transcript access (`GET /:session/tail`, `/:session/grep`). Resolves session to rig/node, delegates to TranscriptStore. Exports: transcriptRoutes. Related: `packages/daemon/src/domain/transcript-store.js`, `packages/daemon/src/domain/rig-repository.js`.
|
||||
- `packages/daemon/src/routes/ask.ts`: Hono route module for context evidence packs (`POST /`). Delegates to AskService. Exports: askRoutes. Related: `packages/daemon/src/domain/ask-service.js`.
|
||||
- `packages/daemon/src/routes/chat.ts`: Hono route module for durable rig chat (`GET /watch` SSE stream, `POST /send`, `GET /history`, `POST /topic`). Delegates to ChatRepository, streams via SSE. Exports: chatRoutes. Related: `packages/daemon/src/domain/chat-repository.js`, `packages/daemon/src/domain/event-bus.js`.
|
||||
- `packages/daemon/src/routes/stream.ts`: Hono route module for the PL-004 Phase A coordination L1 stream (`POST /emit`, `GET /list`, `GET /:id`, `POST /:id/archive`, `GET /watch` SSE). Host-scoped (no rigId). Exports: streamRoutes. Related: `packages/daemon/src/domain/stream-store.js`, `packages/daemon/src/domain/event-bus.js`.
|
||||
- `packages/daemon/src/routes/queue.ts`: Hono route module for the PL-004 Phase A coordination L3 queue plus inbox/outbox (`POST /create`, `POST /:id/{claim,unclaim,update,handoff,fallback}`, `GET /list`, `GET /overdue`, `GET /:id`, `GET /:id/transitions`, inbox/outbox subroutes, `GET /watch` SSE). Surfaces hot-potato strict-rejection structured errors with validReasons enum. Exports: queueRoutes. Related: `packages/daemon/src/domain/queue-repository.js`, `packages/daemon/src/domain/inbox-handler.js`, `packages/daemon/src/domain/outbox-handler.js`, `packages/daemon/src/domain/event-bus.js`.
|
||||
- `packages/daemon/src/routes/spec-review.ts`: Hono route module for structured review over raw RigSpec / AgentSpec YAML. Accepts `sourceState` and returns review models or validation errors. Exports: specReviewRoutes. Related: `packages/daemon/src/domain/spec-review-service.js`.
|
||||
- `packages/daemon/src/routes/spec-library.ts`: Hono route module for the filesystem-backed spec library (`list`, `get`, `review`, `sync`). Enriches service-backed reviews with best-effort compose preview data for managed-app UI surfaces. Exports: specLibraryRoutes. Related: `packages/daemon/src/domain/spec-library-service.js`, `packages/daemon/src/domain/spec-review-service.js`.
|
||||
- `packages/daemon/src/routes/whoami.ts`: Hono route module for daemon-backed runtime identity lookup by `nodeId` or `sessionName`. Exports: whoamiRoutes. Related: `packages/daemon/src/domain/whoami-service.js`.
|
||||
- `packages/daemon/src/routes/up.ts`: Hono route module for `/api/up`, routing direct rig specs, bundles, and rig-name restore into the staged bootstrap flow. Exports: upRoutes. Related: `packages/daemon/src/domain/bootstrap-orchestrator.js`, `packages/daemon/src/domain/bootstrap-repository.js`, `packages/daemon/src/domain/event-bus.js`, `packages/daemon/src/domain/up-command-router.js`.
|
||||
|
||||
## (e) Source-root pointer table
|
||||
## CLI
|
||||
|
||||
Module → primary `packages/*/src/...` roots. This replaces the old per-file
|
||||
`Exports:`/`Related:` dump: it points at the code, it does not transcribe it.
|
||||
Source-grounding for each claim lives inside the module with file:line cites.
|
||||
### Entrypoints And Infrastructure
|
||||
- `packages/cli/src/client.ts`: Shared HTTP client for talking to the daemon API, including raw JSON posts and text-body posts with optional extra headers such as `X-Rig-Root`. Exports: DaemonClient, DaemonConnectionError, DaemonResponse. Related: none.
|
||||
- `packages/cli/src/daemon-lifecycle.ts`: Starts, stops, inspects, and tails the local daemon process. Spawns the daemon with `process.execPath` and bypasses local `daemon.json` gating when `OPENRIG_URL` is set by probing remote `/healthz` directly. Exports: DaemonState, DaemonStatus, LOG_FILE, LifecycleDeps, OPENRIG_DIR, STATE_FILE, StartOptions, getDaemonPath, getDaemonStatus, readLogs, startDaemon, stopDaemon, tailLogs. Related: none.
|
||||
- `packages/cli/src/index.ts`: Commander entrypoint that assembles the full `rig` CLI program (40 mounted command groups, including env status/logs/down, `destroy`, and Final Stretch 1 `specs`, `whoami`, `bind`, and `adopt`). Exports: ProgramDeps, createProgram. Related: `packages/cli/src/commands/bootstrap.js`, `packages/cli/src/commands/bundle.js`, `packages/cli/src/commands/claim.js`, `packages/cli/src/commands/daemon.js`, +19 more.
|
||||
- `packages/cli/src/mcp-server.ts`: Implements the CLI-hosted MCP server over stdio, wrapping 17 daemon-backed tools including node inventory, send/capture, bundle/spec validation, and chatroom. Exports: createMcpServer. Related: `packages/cli/src/client.js`.
|
||||
|
||||
| Module | Primary source roots |
|
||||
|---|---|
|
||||
| `architecture/daemon-core.md` | `packages/daemon/src/{startup.ts,server.ts,index.ts}`, `packages/daemon/src/db/migrations/`, `packages/cli/src/index.ts` |
|
||||
| `architecture/adapters-and-runtimes.md` | `packages/daemon/src/domain/runtime-adapter.ts`, `packages/daemon/src/adapters/{claude-code-adapter,codex-runtime-adapter,terminal-adapter}.ts`, `packages/daemon/src/domain/{native-resume-probe,resume-metadata-refresher,codex-thread-id}.ts` |
|
||||
| `architecture/coordination-primitive.md` | `packages/daemon/src/domain/{stream-store,queue-repository,queue-transition-log,hot-potato-enforcer,inbox-handler,outbox-handler}.ts`, `packages/daemon/src/routes/{stream,queue}.ts` |
|
||||
| `architecture/workflow-runtime.md` | `packages/daemon/src/domain/{workflow-projector,workflow-runtime,workflow-instance-store,workflow-spec-cache,workflow-step-trail-log,workflow-validator}.ts`, `packages/daemon/src/domain/policies/workflow-keepalive.ts`, `packages/daemon/src/routes/workflow.ts` |
|
||||
| `architecture/mission-control.md` | `packages/daemon/src/domain/mission-control/`, `packages/daemon/src/middleware/auth-bearer-token.ts`, `packages/daemon/src/routes/mission-control.ts`, `packages/daemon/src/db/migrations/037_mission_control_actions.ts` |
|
||||
| `architecture/agent-spec-and-startup.md` | `packages/daemon/src/domain/{agent-manifest,rigspec-schema,profile-resolver,startup-orchestrator,whoami-service,claim-service}.ts`, `packages/daemon/src/routes/{rigspec,whoami}.ts` |
|
||||
| `architecture/lifecycle-snapshot-restore.md` | `packages/daemon/src/domain/{restore-orchestrator,snapshot-capture,snapshot-repository,checkpoint-store}.ts`, `packages/daemon/src/routes/restore-check.ts`, `packages/cli/src/commands/restore-packet.ts` |
|
||||
| `architecture/transport-and-transcripts.md` | `packages/daemon/src/domain/{session-transport,transcript-store,history-query,ask-service,chat-repository}.ts`, `packages/daemon/src/routes/{transport,transcripts,ask,chat}.ts`, `packages/cli/src/mcp-server.ts` |
|
||||
| `architecture/workspace-primitive.md` | `packages/daemon/src/domain/workspace/`, `packages/cli/src/commands/config-init-workspace.ts`, `packages/daemon/src/db/migrations/{038,039}*`, `packages/ui/src/routes.tsx` |
|
||||
| `architecture/content-surfaces.md` | `packages/daemon/src/domain/{files,progress,steering}*`, `packages/daemon/src/routes/{files,progress,steering}.ts`, `packages/ui/src/routes.tsx` |
|
||||
| `architecture/living-notes-review.md` | `packages/daemon/src/domain/review/{types,compose,gather,freeze,brief-spine}.ts`, `packages/daemon/src/routes/{review,files,slices}.ts`, `packages/cli/src/commands/{scope,proof}.ts`, `packages/ui/src/components/review/` |
|
||||
| `architecture/plugin-agent-image-context-pack.md` | `packages/daemon/src/domain/plugin-discovery-service.ts`, `packages/daemon/src/domain/{agent-images,context-packs}/`, `packages/daemon/src/domain/claude-compaction-enforcer.ts` |
|
||||
| `architecture/packaging-bootstrap-bundles.md` | `packages/daemon/src/domain/{pod-bundle-assembler,bootstrap-orchestrator,bundle-*,package-*,install-*}.ts`, `packages/daemon/src/routes/{bundles,up}.ts` |
|
||||
| `architecture/architecture-rules-and-event-system.md` | `packages/daemon/src/domain/types.ts` (RigEvent union), `packages/daemon/src/routes/{stream,queue}.ts` (SSE watch), `packages/daemon/src/server.ts` (`/api/events`) |
|
||||
| `ui/shell-and-routing.md` | `packages/ui/src/routes.tsx`, `packages/ui/src/components/AppShell.tsx` |
|
||||
| `ui/topology.md` | `packages/ui/src/components/topology/`, `packages/ui/src/lib/{graph,hybrid,multi-rig}-layout.ts` |
|
||||
| `ui/project-and-for-you.md` | `packages/ui/src/routes.tsx`, `packages/ui/src/components/dashboard/vellum/` |
|
||||
| `ui/library-specs-and-design-system.md` | `packages/ui/src/components/specs/`, `packages/daemon/src/domain/{spec-review-service,spec-library-service}.ts`, `../DESIGN.md` (pointer) |
|
||||
| `cli-reference.md` | `packages/cli/src/index.ts`, `packages/cli/src/commands/*` |
|
||||
### Commands
|
||||
- `packages/cli/src/commands/agent.ts`: Commander command module for `agent`. Subcommands: `validate` (POST `/api/agents/validate`). Supports `--json`. Exports: AgentDeps, agentCommand. Related: `packages/cli/src/client.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
- `packages/cli/src/commands/bootstrap.ts`: Commander command module for `bootstrap`. Supports library-name resolution before falling back to raw source refs. Exports: bootstrapCommand. Related: `packages/cli/src/client.js`, `packages/cli/src/commands/daemon.js`, `packages/cli/src/commands/specs.js`, `packages/cli/src/commands/status.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
- `packages/cli/src/commands/bind.ts`: Commander command module for `bind` — bind a discovered session to an existing logical node. Exports: bindCommand. Related: `packages/cli/src/client.js`, `packages/cli/src/commands/daemon.js`, `packages/cli/src/commands/status.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
- `packages/cli/src/commands/bundle.ts`: Commander command module for `bundle`. Supports dual-format bundle create/inspect/install, `--json`, and pod-aware `--rig-root` on create. Exports: bundleCommand. Related: `packages/cli/src/client.js`, `packages/cli/src/commands/daemon.js`, `packages/cli/src/commands/status.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
- `packages/cli/src/commands/claim.ts`: Commander command module for `claim`. Exports: claimCommand. Related: `packages/cli/src/client.js`, `packages/cli/src/commands/daemon.js`, `packages/cli/src/commands/status.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
- `packages/cli/src/commands/daemon.ts`: Commander command module for `daemon`. Exports: daemonCommand, realDeps. Related: `packages/cli/src/daemon-lifecycle.js`.
|
||||
- `packages/cli/src/commands/discover.ts`: Commander command module for `discover`. Exports: discoverCommand. Related: `packages/cli/src/client.js`, `packages/cli/src/commands/daemon.js`, `packages/cli/src/commands/status.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
- `packages/cli/src/commands/down.ts`: Commander command module for `down`. Exports: downCommand. Related: `packages/cli/src/client.js`, `packages/cli/src/commands/daemon.js`, `packages/cli/src/commands/status.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
- `packages/cli/src/commands/env.ts`: Commander command module for `env` — rig environment status/logs/down for service-backed rigs and managed apps. Exports: envCommand. Related: `packages/cli/src/client.js`, `packages/cli/src/commands/daemon.js`, `packages/cli/src/daemon-lifecycle.js`, `packages/cli/src/commands/status.js`.
|
||||
- `packages/cli/src/commands/export.ts`: Commander command module for `export`. Exports: ExportDeps, exportCommand. Related: `packages/cli/src/client.js`, `packages/cli/src/commands/daemon.js`, `packages/cli/src/commands/status.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
- `packages/cli/src/commands/import.ts`: Commander command module for `import`. Locally parses YAML to detect pod-aware rigs, sends `X-Rig-Root` for pod-aware preflight/instantiate flows, and supports `--rig-root`. Exports: ImportDeps, importCommand. Related: `packages/cli/src/client.js`, `packages/cli/src/commands/daemon.js`, `packages/cli/src/commands/status.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
- `packages/cli/src/commands/mcp.ts`: Commander command module for `mcp`. Exports: mcpCommand. Related: `packages/cli/src/client.js`, `packages/cli/src/commands/daemon.js`, `packages/cli/src/commands/status.js`, `packages/cli/src/daemon-lifecycle.js`, +1 more.
|
||||
- `packages/cli/src/commands/package.ts`: Commander command module for the legacy package-management surface. Exports: packageCommand. Related: `packages/cli/src/client.js`, `packages/cli/src/commands/daemon.js`, `packages/cli/src/commands/status.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
- `packages/cli/src/commands/ps.ts`: Commander command module for `ps`. Exports: psCommand. Related: `packages/cli/src/client.js`, `packages/cli/src/commands/daemon.js`, `packages/cli/src/commands/status.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
- `packages/cli/src/commands/requirements.ts`: Commander command module for `requirements`. Exports: requirementsCommand. Related: `packages/cli/src/client.js`, `packages/cli/src/commands/daemon.js`, `packages/cli/src/commands/status.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
- `packages/cli/src/commands/restore.ts`: Commander command module for `restore`. Exports: restoreCommand. Related: `packages/cli/src/client.js`, `packages/cli/src/commands/daemon.js`, `packages/cli/src/commands/status.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
- `packages/cli/src/commands/rig.ts`: Commander command module for `rig`. Subcommands: `validate` (POST `/api/rigs/import/validate`), `preflight` (POST `/api/rigs/import/preflight` with `X-Rig-Root` header). Both support `--json`. Exports: RigDeps, rigCommand. Related: `packages/cli/src/client.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
- `packages/cli/src/commands/snapshot.ts`: Commander command module for `snapshot`. Exports: snapshotCommand. Related: `packages/cli/src/client.js`, `packages/cli/src/commands/daemon.js`, `packages/cli/src/commands/status.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
- `packages/cli/src/commands/status.ts`: Commander command module for `status`. Exports: StatusDeps, statusCommand. Related: `packages/cli/src/client.js`, `packages/cli/src/commands/daemon.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
- `packages/cli/src/commands/specs.ts`: Commander command module for the agent-facing spec library workflow. Subcommands: `ls`, `show`, `preview`, `add`, `sync`, plus shared name resolution used by `up` and `bootstrap`. `add` accepts single YAML files and full spec directories containing `rig.yaml` or `agent.yaml`. Help/examples and not-found guidance explicitly call out managed apps. Exports: resolveLibrarySpec, specsCommand. Related: `packages/cli/src/client.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
- `packages/cli/src/commands/ui.ts`: Commander command module for `ui`. Exports: UiDeps, uiCommand. Related: `packages/cli/src/commands/daemon.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
- `packages/cli/src/commands/up.ts`: Commander command module for `up`. Supports spec paths, bundle paths, rig-name restore, and library-name resolution; fails loudly on rig-name vs library-name ambiguity. Help/examples now treat managed apps like `secrets-manager` as first-class launch targets. Auto-preflight, auto-daemon-start, post-command handoff with attach commands. Exports: upCommand. Related: `packages/cli/src/client.js`, `packages/cli/src/commands/daemon.js`, `packages/cli/src/commands/specs.js`, `packages/cli/src/daemon-lifecycle.js`, `packages/cli/src/system-preflight.js`.
|
||||
- `packages/cli/src/commands/whoami.ts`: Commander command module for `whoami`. Resolves identity from explicit args, env vars, tmux metadata, and session-name fallback, then delegates to daemon `/api/whoami`. Exports: resolveIdentitySource, whoamiCommand. Related: `packages/cli/src/client.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
- `packages/cli/src/commands/adopt.ts`: Commander command module for `adopt` — materialize topology from a pod-aware RigSpec, then bind discovered live sessions according to `--bind` mappings. Exports: AdoptDeps, adoptCommand. Related: `packages/cli/src/client.js`, `packages/cli/src/commands/import.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
|
||||
> No per-file flat dump. File-level detail belongs in the code; this codemap
|
||||
> points at the source root and the module that explains it. The per-file
|
||||
> index anti-pattern (old codemap) is retired, not relocated.
|
||||
### Commands: Post-North-Star Additions
|
||||
- `packages/cli/src/commands/send.ts`: Commander command module for `send` — send message to agent terminal via reliable tmux two-step. Supports `--verify` and `--force`. Exports: sendCommand. Related: `packages/cli/src/client.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
- `packages/cli/src/commands/capture.ts`: Commander command module for `capture` — capture agent pane content. Supports `--lines N` and `--json`. Exports: captureCommand. Related: `packages/cli/src/client.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
- `packages/cli/src/commands/broadcast.ts`: Commander command module for `broadcast` — send to all agents in a rig or pod. Reports per-session delivery status. Exports: broadcastCommand. Related: `packages/cli/src/client.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
- `packages/cli/src/commands/transcript.ts`: Commander command module for `transcript` — composable transcript access via `--tail N` and `--grep "pattern"`. Exports: transcriptCommand. Related: `packages/cli/src/client.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
- `packages/cli/src/commands/stream.ts`: Commander command module for `rig stream` (PL-004 Phase A) — coordination L1 intake stream. Subcommands: `emit`, `list`, `show`, `archive`. Speaks only to the daemon HTTP API; does not touch POC filesystem state. Exports: streamCommand, StreamDeps. Related: `packages/cli/src/client.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
- `packages/cli/src/commands/queue.ts`: Commander command module for `rig queue` (PL-004 Phase A) — coordination L3 queue plus inbox/outbox. Subcommands: `create`, `claim`, `unclaim`, `update`, `handoff`, `fallback`, `show`, `transitions`, `list`, `overdue`, `inbox-drop`, `inbox-absorb`, `inbox-deny`, `inbox-pending`, `outbox-record`, `outbox-list`. Hot-potato strict-rejection enforced at daemon. Exports: queueCommand, QueueDeps. Related: `packages/cli/src/client.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
- `packages/cli/src/commands/config.ts`: Commander command module for `config` — read/write/reset config keys. Supports `--json`. Exports: configCommand. Related: `packages/cli/src/config-store.js`.
|
||||
- `packages/cli/src/commands/preflight.ts`: Commander command module for `preflight` — system readiness checks. Supports `--json`. Exports: preflightCommand. Related: `packages/cli/src/system-preflight.js`, `packages/cli/src/config-store.js`.
|
||||
- `packages/cli/src/commands/ask.ts`: Commander command module for `ask` — context evidence pack over transcripts + topology + chat. Supports `--json`. Exports: askCommand. Related: `packages/cli/src/client.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
- `packages/cli/src/commands/chatroom.ts`: Commander command module for `chatroom` — durable group chat with subcommands `send`, `watch`, `history`, and `topic`. Exports: chatroomCommand. Related: `packages/cli/src/client.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
|
||||
### CLI Infrastructure: Post-North-Star Additions
|
||||
- `packages/cli/src/config-store.ts`: Config file management at `~/.openrig/config.json` with legacy fallback from `~/.rigged/config.json`. 5 locked keys with env var overrides. Precedence: CLI flag > env var > config file > default. Exports: ConfigStore and config helpers. Related: none (filesystem-only).
|
||||
- `packages/cli/src/system-preflight.ts`: System readiness checks: Node.js version, tmux availability, writable directories, port availability. Every error follows the 3-part pattern (what + why + fix). Exports: SystemPreflight, PreflightCheck, PreflightResult. Related: `packages/cli/src/config-store.js`, `packages/cli/src/daemon-lifecycle.js`.
|
||||
|
||||
## UI
|
||||
|
||||
### App Entry And Routing
|
||||
- `packages/ui/src/App.tsx`: Thin app wrapper that renders the TanStack Router provider. Exports: App. Related: `packages/ui/src/routes.js`.
|
||||
- `packages/ui/src/globals.css`: Tailwind/theme tokens and global UI styling. Exports: none. Related: none.
|
||||
- `packages/ui/src/main.tsx`: Bootstraps the React app, fonts, and global styles. Exports: none. Related: `packages/ui/src/App.js`, `packages/ui/src/globals.css`.
|
||||
- `packages/ui/src/routes.tsx`: Declares the explorer-first route tree and root shell composition, including specs review/library routes, discovery/specs drawer bridges, and live-node full-details route `/rigs/$rigId/nodes/$logicalId`. Exports: router. Related: `packages/ui/src/components/AppShell.js`, `packages/ui/src/components/BootstrapWizard.js`, `packages/ui/src/components/BundleInspector.js`, `packages/ui/src/components/BundleInstallFlow.js`, +13 more.
|
||||
|
||||
### Components: Application Surfaces
|
||||
- `packages/ui/src/components/ActivityFeed.tsx`: Rolling global activity/event overlay driven by SSE. Exports: ActivityFeed. Related: `packages/ui/src/hooks/useActivityFeed.js`.
|
||||
- `packages/ui/src/components/AppShell.tsx`: Persistent explorer/workspace/drawer shell. Owns drawer selection context, discovery placement state, specs workspace provider, explorer visibility, and top-level discovery/specs/system toggles. Exports: DrawerSelectionContext, DrawerSelectionContextValue, DiscoveryPlacementContext, DiscoveryPlacementContextValue, ExplorerVisibilityContext, ExplorerVisibilityContextValue, NodeSelectionContext, AppShell, useDiscoveryPlacement, useDrawerSelection, useExplorerVisibility, useNodeSelection. Related: `packages/ui/src/components/ActivityFeed.js`, `packages/ui/src/components/Explorer.js`, `packages/ui/src/components/SharedDetailDrawer.js`, `packages/ui/src/components/SpecsWorkspace.js`, `packages/ui/src/hooks/useActivityFeed.js`, `packages/ui/src/hooks/useGlobalEvents.js`, `packages/ui/src/hooks/useRigSummary.js`.
|
||||
- `packages/ui/src/components/BootstrapWizard.tsx`: Multi-step bootstrap planning/apply flow UI for both rig specs and `.rigbundle` archives. Includes the spec-or-bundle entry field and bundle-inspector handoff link. Exports: BootstrapWizard. Related: `packages/ui/src/components/RequirementsPanel.js`, `packages/ui/src/hooks/useBootstrap.js`.
|
||||
- `packages/ui/src/components/BundleInspector.tsx`: Bundle inspection screen for manifest and integrity results. Renders `agents[]` plus schema-version badge for v2 pod bundles and legacy package content for v1 bundles. Exports: BundleInspector. Related: `packages/ui/src/hooks/useBundles.js`.
|
||||
- `packages/ui/src/components/BundleInstallFlow.tsx`: Bundle install plan/apply screen. Labels the install as pod-aware or legacy from bootstrap `resolve_spec.detail.source`. Exports: BundleInstallFlow. Related: `packages/ui/src/hooks/useBundles.js`.
|
||||
- `packages/ui/src/components/Dashboard.tsx`: Home dashboard that renders rig cards and high-level rig actions. Exports: Dashboard. Related: `packages/ui/src/components/RigCard.js`, `packages/ui/src/hooks/mutations.js`, `packages/ui/src/hooks/usePsEntries.js`, `packages/ui/src/hooks/useRigSummary.js`.
|
||||
- `packages/ui/src/components/DiscoveryOverlay.tsx`: Session discovery and claim surface. Exports: DiscoveryOverlay. Related: `packages/ui/src/hooks/useDiscovery.js`, `packages/ui/src/hooks/useRigSummary.js`.
|
||||
- `packages/ui/src/components/ImportFlow.tsx`: RigSpec validate/preflight/instantiate flow UI. Supports pod-aware `X-Rig-Root`, structured preflight diagnostics, and rebooted RigSpec terminology. Exports: ImportFlow. Related: `packages/ui/src/hooks/mutations.js`.
|
||||
- `packages/ui/src/components/AgentSpecValidateFlow.tsx`: Standalone validate surface for one AgentSpec YAML, backed by `/api/agents/validate`. Exports: AgentSpecValidateFlow. Related: none.
|
||||
- `packages/ui/src/components/WorkflowScaffold.tsx`: Shared page-shell primitives for multi-step/spec-review flows (`WorkflowHeader`, `WorkflowStepIndicator`, `WorkflowSection`, summary cards, code preview). Exports: WorkflowHeader, WorkflowStepIndicator, WorkflowSection, WorkflowSummaryGrid, WorkflowSummaryCard, WorkflowCodePreview. Related: none.
|
||||
- `packages/ui/src/components/WorkspacePage.tsx`: Shared center-workspace page shell used by specs/library/live-details surfaces. Exports: WorkspacePage. Related: none.
|
||||
- `packages/ui/src/components/SpecsWorkspace.tsx`: Local persisted workspace state for spec authoring/review tasks, drafts, and active task list. Exports: SpecsDraft, SpecsTask, SPECS_WORKSPACE_STORAGE_KEYS, SpecsWorkspaceProvider, useSpecsWorkspace. Related: none.
|
||||
- `packages/ui/src/components/PackageDetail.tsx`: Package detail screen with install history, journal, and rollback actions. Exports: PackageDetail. Related: `packages/ui/src/hooks/usePackageDetail.js`.
|
||||
- `packages/ui/src/components/PackageInstallFlow.tsx`: Legacy package validate/configure/plan/apply flow UI, explicitly labeled `(Legacy)`. Exports: PackageInstallFlow. Related: none.
|
||||
- `packages/ui/src/components/PackageList.tsx`: Legacy package summary list/grid screen presented under the rebooted `SPECS` navigation, with an empty-state handoff into RigSpec import. Exports: PackageList. Related: `packages/ui/src/hooks/usePackages.js`.
|
||||
- `packages/ui/src/components/RequirementsPanel.tsx`: Visualizes requirement probe results inside bootstrap flows. Exports: RequirementResult, RequirementsPanel. Related: none.
|
||||
- `packages/ui/src/components/RigCard.tsx`: Dashboard card for one rig with counts, status, and primary actions. Exports: RigCard, RigSummary. Related: `packages/ui/src/hooks/useCountUp.js`, `packages/ui/src/hooks/usePsEntries.js`.
|
||||
- `packages/ui/src/components/RigGraph.tsx`: Rig graph view that renders topology, discovery overlays, and focus interactions. Exports: RigGraph. Related: `packages/ui/src/components/RigNode.js`, `packages/ui/src/hooks/useDiscovery.js`, `packages/ui/src/hooks/useRigEvents.js`, `packages/ui/src/hooks/useRigGraph.js`.
|
||||
- `packages/ui/src/components/RigNode.tsx`: Custom graph-node renderer for React Flow topology cards. Exports: RigNode. Related: none.
|
||||
- `packages/ui/src/components/Sidebar.tsx`: App navigation sidebar. Exports: Sidebar. Related: none.
|
||||
- `packages/ui/src/components/SnapshotPanel.tsx`: Snapshot list/create/restore panel shown beside rig graphs. Exports: SnapshotPanel. Related: `packages/ui/src/hooks/mutations.js`, `packages/ui/src/hooks/useSnapshots.js`.
|
||||
|
||||
### Components: North Star + Post-North-Star Additions
|
||||
- `packages/ui/src/components/Explorer.tsx`: Hierarchical tree navigator — rigs → pods → agents with status indicators. Primary navigation surface. Click rig loads graph, click node opens detail drawer. Exports: Explorer. Related: `packages/ui/src/hooks/useRigSummary.js`, `packages/ui/src/hooks/usePsEntries.js`, `packages/ui/src/hooks/useNodeInventory.js`.
|
||||
- `packages/ui/src/components/SharedDetailDrawer.tsx`: Unified drawer surface keyed by `DrawerSelection`. Routes to rig, node, system, discovery, or specs panels without leaving the current workspace. Exports: DrawerSelection, SharedDetailDrawer. Related: `packages/ui/src/components/DiscoveryPanel.js`, `packages/ui/src/components/NodeDetailPanel.js`, `packages/ui/src/components/RigDetailPanel.js`, `packages/ui/src/components/SpecsPanel.js`, `packages/ui/src/components/SystemPanel.js`.
|
||||
- `packages/ui/src/components/RigDetailPanel.tsx`: Rig detail: identity, node summary, snapshots/actions, and runtime drawer tabs (`Info`, conditional `Env`, `Chat Room`). Exports: RigDetailPanel. Related: `packages/ui/src/hooks/useRigSummary.js`, `packages/ui/src/hooks/useSnapshots.js`, `packages/ui/src/hooks/useNodeInventory.js`.
|
||||
- `packages/ui/src/components/RigEnvPanel.tsx`: Runtime env surface for service-backed rigs. Shows overall env state, per-service health, health gates, surfaces, logs, and teardown action. Exports: RigEnvPanel. Related: `packages/ui/src/hooks/useRigEnv.js`.
|
||||
- `packages/ui/src/components/NodeDetailPanel.tsx`: Runtime-first node drawer. Shows rig/session/runtime identity, peers, directional edges, transcript helpers, compact spec summary, status, actions (tmux/cmux/resume/full-details), startup files, and recent events. Exports: NodeDetailPanel. Related: `packages/ui/src/components/LiveIdentityDisplay.js`, `packages/ui/src/hooks/useNodeDetail.js`, `packages/ui/src/lib/copy-text.js`, `packages/ui/src/lib/display-name.js`.
|
||||
- `packages/ui/src/components/NodeDetailPlaceholder.tsx`: Empty state for node detail when no node is selected. Exports: NodeDetailPlaceholder. Related: none.
|
||||
- `packages/ui/src/components/DiscoveryPanel.tsx`: Drawer-native discovery/adoption surface. Supports scan/list, draft-rig generation, placement-first bind/adopt, and pod/member targeting inside the shared drawer. Exports: DiscoveryPlacementTarget, DiscoveryPanel. Related: `packages/ui/src/hooks/useDiscovery.js`.
|
||||
- `packages/ui/src/components/SpecsPanel.tsx`: Drawer-native spec library and authoring launcher. Presents a unified library list with `All / Apps / Rigs / Agents`, type/stability badges, richer managed-app rows, and review-route handoff. Exports: SpecsPanel. Related: `packages/ui/src/components/SpecsWorkspace.js`, `packages/ui/src/hooks/useSpecLibrary.js`.
|
||||
- `packages/ui/src/components/RigChatPanel.tsx`: Chat room tab in rig drawer — send messages, watch live stream, view history. Exports: RigChatPanel. Related: `packages/ui/src/hooks/useRigChat.js`.
|
||||
- `packages/ui/src/components/LiveIdentityDisplay.tsx`: Reusable runtime-identity subsection for peers, edges, transcript helpers, and compact spec summary. Used by the node drawer and full-details route. Exports: LiveIdentityDisplay. Related: none.
|
||||
- `packages/ui/src/components/LiveNodeDetails.tsx`: Explicit center-workspace route for deep inspection of one live node. Composes runtime identity plus reusable spec display components. Exports: LiveNodeDetails. Related: `packages/ui/src/components/AgentSpecDisplay.js`, `packages/ui/src/components/LiveIdentityDisplay.js`, `packages/ui/src/hooks/useNodeDetail.js`.
|
||||
- `packages/ui/src/components/RigSpecDisplay.tsx`: Canonical RigSpec display primitive used by draft review, library review, and live/workspace inspection flows. Supports a library-only managed-app Environment tab with compose preview, health gates, and surfaces. Exports: RigSpecDisplay. Related: `packages/ui/src/components/SpecTopologyPreview.js`.
|
||||
- `packages/ui/src/components/AgentSpecDisplay.tsx`: Canonical AgentSpec display primitive used by preview, library, and live-details flows. Exports: AgentSpecDisplay. Related: none.
|
||||
- `packages/ui/src/components/RigSpecReview.tsx`: Route-level rig review page that consumes `RigSpecDisplay` and specs workspace state. Exports: RigSpecReview. Related: `packages/ui/src/components/RigSpecDisplay.js`, `packages/ui/src/components/SpecsWorkspace.js`, `packages/ui/src/hooks/useSpecReview.js`.
|
||||
- `packages/ui/src/components/AgentSpecReview.tsx`: Route-level agent review page that consumes `AgentSpecDisplay` and specs workspace state. Exports: AgentSpecReview. Related: `packages/ui/src/components/AgentSpecDisplay.js`, `packages/ui/src/components/SpecsWorkspace.js`, `packages/ui/src/hooks/useSpecReview.js`.
|
||||
- `packages/ui/src/components/LibraryReview.tsx`: Library-entry review page that renders reusable display components plus provenance/source-state. Service-backed rigs surface managed-app copy, specialist identity, setup-prompt copy, and env-aware review details. Exports: LibraryReview. Related: `packages/ui/src/components/AgentSpecDisplay.js`, `packages/ui/src/components/RigSpecDisplay.js`, `packages/ui/src/hooks/useSpecLibrary.js`.
|
||||
- `packages/ui/src/components/SpecTopologyPreview.tsx`: Lightweight topology preview for structured rig review models. Exports: SpecTopologyPreview. Related: none.
|
||||
- `packages/ui/src/components/SystemPanel.tsx`: Drawer surface for system-wide event log/status tabs. Replaces the old status-bar role with a richer right-drawer system surface. Exports: SystemPanel. Related: `packages/ui/src/hooks/useActivityFeed.js`.
|
||||
- `packages/ui/src/components/WorkspaceHome.tsx`: Landing page when no rig is selected. Entry point for explorer-first workflow. Exports: WorkspaceHome. Related: `packages/ui/src/components/AppShell.js`.
|
||||
|
||||
### Components: UI Primitives
|
||||
- `packages/ui/src/components/ui/alert.tsx`: Wrapped/customized shadcn-style UI primitive for alert. Exports: Alert, AlertDescription, AlertTitle. Related: none.
|
||||
- `packages/ui/src/components/ui/badge.tsx`: Wrapped/customized shadcn-style UI primitive for badge. Exports: Badge, BadgeProps, badgeVariants. Related: none.
|
||||
- `packages/ui/src/components/ui/button.tsx`: Wrapped/customized shadcn-style UI primitive for button. Exports: Button, ButtonProps, buttonVariants. Related: none.
|
||||
- `packages/ui/src/components/ui/card.tsx`: Wrapped/customized shadcn-style UI primitive for card. Exports: Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle. Related: none.
|
||||
- `packages/ui/src/components/ui/dialog.tsx`: Wrapped/customized shadcn-style UI primitive for dialog. Exports: Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger. Related: none.
|
||||
- `packages/ui/src/components/ui/input.tsx`: Wrapped/customized shadcn-style UI primitive for input. Exports: Input. Related: none.
|
||||
- `packages/ui/src/components/ui/separator.tsx`: Wrapped/customized shadcn-style UI primitive for separator. Exports: Separator. Related: none.
|
||||
- `packages/ui/src/components/ui/table.tsx`: Wrapped/customized shadcn-style UI primitive for table. Exports: Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow. Related: none.
|
||||
- `packages/ui/src/components/ui/tabs.tsx`: Wrapped/customized shadcn-style UI primitive for tabs. Exports: Tabs, TabsContent, TabsList, TabsTrigger. Related: none.
|
||||
- `packages/ui/src/components/ui/textarea.tsx`: Wrapped/customized shadcn-style UI primitive for textarea. Exports: Textarea. Related: none.
|
||||
- `packages/ui/src/components/ui/tooltip.tsx`: Wrapped/customized shadcn-style UI primitive for tooltip. Exports: Tooltip, TooltipContent, TooltipProvider, TooltipTrigger. Related: none.
|
||||
|
||||
### Hooks
|
||||
- `packages/ui/src/hooks/mutations.ts`: Shared mutation hooks for rig import, teardown, snapshot creation, and restore. `useImportRig` supports optional `rigRoot` and sends `X-Rig-Root` for pod-aware import. Exports: ImportError, useCreateSnapshot, useImportRig, useRestoreSnapshot, useTeardownRig. Related: none.
|
||||
- `packages/ui/src/hooks/useActivityFeed.ts`: SSE-backed activity-feed model and event-formatting helpers. Exports: ActivityEvent, UseActivityFeedResult, eventColor, eventRoute, eventSummary, formatRelativeTime, useActivityFeed. Related: none.
|
||||
- `packages/ui/src/hooks/useBootstrap.ts`: Bootstrap plan/apply hooks. Exports: BootstrapApplyResult, BootstrapPlanResult, useBootstrapApply, useBootstrapPlan. Related: none.
|
||||
- `packages/ui/src/hooks/useBundles.ts`: Bundle inspect/install hooks. Typed for v2 inspect responses (`schemaVersion`, `agents`, integrity) and install-stage `detail.source` labeling. Exports: BundleInstallResult, InspectResult, useBundleInspect, useBundleInstall. Related: none.
|
||||
- `packages/ui/src/hooks/useCountUp.ts`: Small animation helper for count-up telemetry. Exports: useCountUp. Related: none.
|
||||
- `packages/ui/src/hooks/useDiscovery.ts`: Discovery polling plus claim/bind/adopt mutations and draft-rig generation helpers. Exports: DiscoveredSession, useAdoptSession, useBindSession, useClaimSession, useDiscoveredSessions, useDiscoveredSessionsConditional, useDiscoveryPoll, useDiscoveryScan. Related: none.
|
||||
- `packages/ui/src/hooks/usePackageDetail.ts`: Package detail, journal, history, and rollback hooks. Exports: InstallSummary, JournalEntry, PackageInfo, useInstallHistory, useJournalEntries, usePackageInfo, useRollbackInstall. Related: none.
|
||||
- `packages/ui/src/hooks/usePackages.ts`: Package summary list hook. Exports: PackageSummary, usePackages. Related: none.
|
||||
- `packages/ui/src/hooks/usePsEntries.ts`: `/api/ps` summary hook. Exports: PsEntry, usePsEntries. Related: none.
|
||||
- `packages/ui/src/hooks/useRigEvents.ts`: Rig-scoped SSE subscription and invalidation hook. Exports: UseRigEventsResult, useRigEvents. Related: none.
|
||||
- `packages/ui/src/hooks/useRigGraph.ts`: Rig graph fetch/transformation hook. Exports: useRigGraph. Related: none.
|
||||
- `packages/ui/src/hooks/useRigSummary.ts`: Rig summary list hook used across dashboard and shell surfaces. Includes `hasServices` so runtime/UI can gate managed-app env surfaces. Exports: RigSummary, useRigSummary. Related: none.
|
||||
- `packages/ui/src/hooks/useSnapshots.ts`: Snapshot list hook for one rig. Exports: Snapshot, useSnapshots. Related: none.
|
||||
|
||||
### Hooks: North Star + Post-North-Star Additions
|
||||
- `packages/ui/src/hooks/useNodeInventory.ts`: Fetches node inventory for a rig from the canonical `GET /api/rigs/:rigId/nodes` endpoint. Exports: useNodeInventory. Related: none.
|
||||
- `packages/ui/src/hooks/useNodeDetail.ts`: Fetches extended node detail from `GET /api/rigs/:rigId/nodes/:logicalId`, including peers, edges, transcript helpers, and compact spec summary for the adopted-parity/live-identity drawer. Exports: NodeDetailData, useNodeDetail. Related: none.
|
||||
- `packages/ui/src/hooks/useRigEnv.ts`: Fetches `GET /api/rigs/:rigId/env` for service-backed rig status, surfaces, and receipt data, with runtime-friendly refetch behavior. Exports: RigEnvData, useRigEnv. Related: none.
|
||||
- `packages/ui/src/hooks/useRigChat.ts`: Chat send/watch/history hooks for the rig chat panel. Exports: useRigChat. Related: none.
|
||||
- `packages/ui/src/hooks/useGlobalEvents.ts`: Global SSE subscription for explorer status updates. Exports: useGlobalEvents. Related: none.
|
||||
- `packages/ui/src/hooks/useSpecLibrary.ts`: Spec library list and library-review fetch hooks. Typed for `sourceState: "library_item"` review results and `hasServices`-aware managed-app classification. Exports: SpecLibraryEntry, LibraryReview, LibraryRigReview, LibraryAgentReview, useSpecLibrary, useLibraryReview. Related: none.
|
||||
- `packages/ui/src/hooks/useSpecReview.ts`: Structured spec-review hooks for raw YAML preview (`rig` and `agent`) over `/api/specs/review/*`. The rig review type now carries managed-app services metadata and compose preview. Exports: SpecGraphData, RigSpecReview, AgentSpecReview, useRigSpecReview, useAgentSpecReview. Related: none.
|
||||
|
||||
### Lib Utilities
|
||||
- `packages/ui/src/lib/edge-styles.ts`: Edge-style resolver for graph links. Exports: EdgeStyleResult, getEdgeStyle. Related: none.
|
||||
- `packages/ui/src/lib/graph-layout.ts`: Tree-layout helper for rig graph positioning. Exports: applyTreeLayout. Related: none.
|
||||
- `packages/ui/src/lib/instantiate-status-colors.ts`: Color-class lookup for instantiation states. Exports: getInstantiateStatusColorClass. Related: none.
|
||||
- `packages/ui/src/lib/query-client.ts`: Shared TanStack Query client singleton. Exports: queryClient. Related: none.
|
||||
- `packages/ui/src/lib/restore-status-colors.ts`: Color-class lookup for restore states. Exports: getRestoreStatusColorClass. Related: none.
|
||||
- `packages/ui/src/lib/status-colors.ts`: Generic rig/session status color mapping. Exports: getStatusColorClass. Related: none.
|
||||
- `packages/ui/src/lib/utils.ts`: Shared UI utility helpers, currently `cn` class merging. Exports: cn. Related: none.
|
||||
|
||||
### Lib Utilities: North Star + Post-North-Star Additions
|
||||
- `packages/ui/src/lib/display-id.ts`: Short ULID display utility — uses ULID tail (not head) for better uniqueness in same-view contexts. UI-only, no backend changes. Exports: shortId. Related: none.
|
||||
- `packages/ui/src/lib/display-name.ts`: Pod name extraction from qualified logical IDs (e.g., "dev1" from "dev1.impl"). Exports: displayPodName, inferPodName. Related: none.
|
||||
- `packages/ui/src/lib/build-setup-prompt.ts`: Managed-app setup-prompt generator used by library review copy surfaces. Exports: buildSetupPrompt. Related: none.
|
||||
- `packages/ui/src/lib/copy-text.ts`: Clipboard copy utility for the "Copy tmux attach" and "Copy resume command" buttons. Exports: copyText. Related: none.
|
||||
@@ -1,65 +0,0 @@
|
||||
---
|
||||
kind: as-built
|
||||
title: As-Built Frontmatter — Pointer + As-Built-Unique Field
|
||||
status: active
|
||||
topics: [knowledge-and-context, frontmatter]
|
||||
domains: [engineering-advisor, operating-advisor]
|
||||
applies-when: |
|
||||
Authoring or updating a doc under docs/as-built/. Tells you which
|
||||
frontmatter convention governs these docs and the one field that is
|
||||
unique to as-built docs.
|
||||
siblings: [README.md]
|
||||
prerequisite-reads: [README.md]
|
||||
last-verified-against-source: 7eaf524c
|
||||
last-updated: 2026-05-16
|
||||
---
|
||||
|
||||
# As-Built Frontmatter — Pointer + As-Built-Unique Field
|
||||
|
||||
Every doc under `docs/as-built/` carries YAML frontmatter. The shape is
|
||||
**not** defined here. It is the substrate-wide context-frontmatter
|
||||
convention; this doc only points to it and documents the one field that
|
||||
is unique to as-built docs.
|
||||
|
||||
## Canonical convention (do not duplicate — read it)
|
||||
|
||||
`openrig-work/conventions/frontmatter-for-context/README.md` is the
|
||||
authoritative schema: required floor (`kind` + `title` + `status` +
|
||||
`applies-when`), recommended fields (`topics`, `domains`, `siblings`,
|
||||
`prerequisite-reads`), and the controlled vocabularies for `kind:`,
|
||||
`topics:`, and `domains:`. Author against that convention. This doc adds
|
||||
nothing to it except the field below.
|
||||
|
||||
## `kind: as-built`
|
||||
|
||||
These docs use `kind: as-built`. That value is in the convention's
|
||||
controlled `kind:` vocabulary (first row of its "Controlled vocabulary —
|
||||
`kind:`" table, source `openrig/docs/as-built/*`). Using it is conformant,
|
||||
not an extension.
|
||||
|
||||
## `last-verified-against-source: <sha>` (as-built-unique)
|
||||
|
||||
As-built docs describe the running system. They drift when the source
|
||||
drifts. The as-built-unique field records the exact commit the doc was
|
||||
last verified against:
|
||||
|
||||
```yaml
|
||||
last-verified-against-source: 7eaf524c
|
||||
```
|
||||
|
||||
- **Value:** the short SHA of the source HEAD the doc was verified
|
||||
against at its last edit. Pair with `last-updated: <iso-date>`.
|
||||
- **Why it is here and not in the convention:** the convention is
|
||||
substrate-wide; most context docs do not track a source SHA. This
|
||||
field is meaningful only for docs that mirror code, i.e. as-built
|
||||
docs. It is the per-module drift-detection anchor the
|
||||
context-architecture-v1 mission dogfoods on its own production.
|
||||
- **Discipline:** when re-verifying a module against a newer HEAD,
|
||||
bump this field (and `last-updated`) and carry an inline
|
||||
`re-confirmed <file:line> @HEAD` annotation on each load-bearing
|
||||
claim that was re-checked.
|
||||
|
||||
## See also
|
||||
|
||||
- `openrig-work/conventions/frontmatter-for-context/README.md` — the canonical schema
|
||||
- `README.md` — the as-built corpus map of territory
|
||||
+230
-36
@@ -1,44 +1,238 @@
|
||||
---
|
||||
kind: as-built
|
||||
title: ui.md — Reorganized into the Modular As-Built Tree (Redirect Stub)
|
||||
status: superseded
|
||||
topics: [knowledge-and-context]
|
||||
domains: [engineering-advisor, operating-advisor, product-advisor]
|
||||
applies-when: |
|
||||
You followed an old reference to docs/as-built/ui.md. The monolith was
|
||||
reorganized (slice-08, context-architecture-v1) into the ui/ module folder.
|
||||
Go to README.md (map of territory) or codemap.md (use-case lookup), then the
|
||||
named ui/ module.
|
||||
siblings: [README.md, codemap.md, architecture.md]
|
||||
prerequisite-reads: []
|
||||
last-verified-against-source: 7eaf524c
|
||||
last-updated: 2026-05-16
|
||||
---
|
||||
# OpenRig UI As-Built
|
||||
|
||||
# ui.md was reorganized into the modular as-built tree
|
||||
This document describes the current UI architecture and component system. The
|
||||
brand/design rules live in `docs/DESIGN.md`; this file focuses on how the shipped UI
|
||||
is assembled.
|
||||
|
||||
This single-file UI monolith was split into a folder of independently-loadable,
|
||||
frontmatter-tagged thematic modules (slice-08, `context-architecture-v1`). The
|
||||
canonical as-built description of the shipped operator UI now lives in `ui/`.
|
||||
This stub is a forwarding pointer so old references still resolve.
|
||||
## Package Shape
|
||||
|
||||
**Start here:**
|
||||
UI package: `packages/ui`
|
||||
|
||||
- [`./README.md`](./README.md) — the map of territory and full module index.
|
||||
- [`./codemap.md`](./codemap.md) — navigation index: use-case lookup table and
|
||||
source-root pointers. Use this when you know *what* you need but not *which*
|
||||
module.
|
||||
Primary implementation areas:
|
||||
|
||||
## Where the major content went
|
||||
- `src/routes.tsx` - TanStack Router route tree
|
||||
- `src/components/AppShell.tsx` - global shell, rail, Explorer, drawer, preview stack
|
||||
- `src/components/ui/` - reusable vellum and base UI primitives
|
||||
- `src/components/graphics/` - runtime, tool, and actor marks
|
||||
- `src/components/topology/` - host/rig/pod/seat graph, table, terminal, activity
|
||||
- `src/components/project/` - workspace/mission/slice observability and project metadata primitives
|
||||
- `src/components/for-you/` - attention feed and actionable queue cards
|
||||
- `src/components/specs/` - Library and skill file viewing
|
||||
- `src/components/preview/` - terminal/session preview panes
|
||||
- `src/hooks/` - route data hooks and event consumption
|
||||
- `src/lib/` - classifiers, formatters, layout helpers, brand helpers, activity logic
|
||||
|
||||
The UI content is now the **4 modules under `ui/`**:
|
||||
## Shell Model
|
||||
|
||||
| Module | What moved here |
|
||||
|---|---|
|
||||
| [`ui/shell-and-routing.md`](ui/shell-and-routing.md) | Package shape, the `AppShell` shell model (rail / Explorer / center workspace / drawer / preview stack), the route tree, design primitives, the shared detail-drawer/viewer system, event/activity consumption. |
|
||||
| [`ui/topology.md`](ui/topology.md) | The topology surface — host hybrid graph, table/terminal views, the activity-ring / hot-potato visual language, terminal-preview popovers, navigation/overlay contracts. |
|
||||
| [`ui/project-and-for-you.md`](ui/project-and-for-you.md) | The operator destination surfaces — Project observability (workspace/mission/slice scope tabs), the For-You attention feed (5-card classifier + queue actions), the Dashboard landing on the vellum brand system. |
|
||||
| [`ui/library-specs-and-design-system.md`](ui/library-specs-and-design-system.md) | The Library (`/specs`) UI — specs/applications/skills surfaces, the graphics layer, the current design constraints, and the design-system pointer to `../DESIGN.md`. |
|
||||
`AppShell` wraps every route with:
|
||||
|
||||
The brand/design rules still live at `docs/DESIGN.md` (repo `docs/` root, by
|
||||
design — see `ui/library-specs-and-design-system.md`).
|
||||
- Desktop rail
|
||||
- Route-aware Explorer sidebar
|
||||
- Center workspace
|
||||
- Shared detail drawer
|
||||
- Preview stack
|
||||
- Topology overlay state provider
|
||||
- Shared drawer selection context
|
||||
- Shared discovery placement context
|
||||
|
||||
The rail destinations are:
|
||||
|
||||
- Dashboard: `/`
|
||||
- Topology: `/topology`
|
||||
- For You: `/for-you`
|
||||
- Project: `/project`
|
||||
- Library: `/specs`
|
||||
- Settings: `/settings`
|
||||
- Advisor and Operator placeholders/settings links
|
||||
|
||||
The Explorer is contextual. It changes its tree based on the current destination
|
||||
rather than behaving as a generic file browser.
|
||||
|
||||
## Route Model
|
||||
|
||||
Main routes:
|
||||
|
||||
- `/` - Dashboard
|
||||
- `/topology` - host topology scope
|
||||
- `/topology/rig/$rigId` - rig scope
|
||||
- `/topology/pod/$rigId/$podName` - pod scope
|
||||
- `/topology/seat/$rigId/$logicalId` - seat scope with live node details
|
||||
- `/for-you` - attention feed
|
||||
- `/project` - workspace project scope
|
||||
- `/project/mission/$missionId` - mission scope
|
||||
- `/project/slice/$sliceId` - slice scope
|
||||
- `/specs` - Library
|
||||
- `/specs/applications` - application section
|
||||
- `/specs/skills/$skillToken` - skill viewer defaulting to `skill.md`
|
||||
- `/specs/skills/$skillToken/file/$fileToken` - specific skill file viewer
|
||||
- `/settings` - settings center
|
||||
- `/search` - audit/history view
|
||||
- `/lab/project-graphics-preview` - graphics preview lab route
|
||||
|
||||
Legacy routes remain for compatibility where needed, including package flows,
|
||||
bootstrap flows, validation flows, and `/rigs/$rigId`.
|
||||
|
||||
## Design Primitives
|
||||
|
||||
The UI moved from route-specific one-off panels toward reusable primitives.
|
||||
|
||||
Base primitives:
|
||||
|
||||
- `VellumCard` - paper card with optional dark header, hard shadow, registration marks
|
||||
- `VellumSheet` - side sheet/drawer with vellum-heavy surface and registration marks
|
||||
- `RegistrationMarks` - corner registration marks
|
||||
- `StatusPip` - semantic status only
|
||||
- `SectionHeader`, `EmptyState`, `Button`, `Tabs`, `Table`, and form controls
|
||||
|
||||
Graphics primitives:
|
||||
|
||||
- `RuntimeMark` and `RuntimeBadge`
|
||||
- `ToolMark` and `ToolBadge`
|
||||
- `ActorMark` and `OperatorMoodMark`
|
||||
- Runtime and tool normalization in `runtime-brand.ts` and `tool-brand.ts`
|
||||
|
||||
Project metadata primitives:
|
||||
|
||||
- `EventBadge`
|
||||
- `QueueStateBadge`
|
||||
- `TagPill`
|
||||
- `ActorChip`
|
||||
- `DateChip`
|
||||
- `FlowChips`
|
||||
- `ProofThumbnailGrid`
|
||||
- `ProofPacketHeader`
|
||||
|
||||
These primitives centralize visual language for runtime identity, queue state,
|
||||
actor flow, event labels, dates, tags, and proof images.
|
||||
|
||||
## Topology
|
||||
|
||||
Topology is a scoped workspace with graph, table, and terminal views.
|
||||
|
||||
Current topology pieces:
|
||||
|
||||
- `HostMultiRigGraph` renders the host-level hybrid React Flow graph.
|
||||
- `HybridAgentNode` renders compact agent cards with runtime badges, context
|
||||
percentage, token totals, activity state, terminal preview, and CMUX actions.
|
||||
- `HybridPodGroupNode` renders soft dashed pod frames.
|
||||
- `RigGroupNode` renders soft rig frames with registration marks and aggregate
|
||||
activity.
|
||||
- `ActivityRing` and card activity classes show active, needs-input, and blocked
|
||||
states.
|
||||
- `HotPotatoEdge` visualizes directional queue movement through the graph.
|
||||
- `TopologyTableView` mirrors topology data in a dense table.
|
||||
- `TopologyTerminalView` shows terminal-oriented topology state.
|
||||
- `TerminalPreviewPopover` provides black-glass quick terminal preview above the
|
||||
graph via a portal.
|
||||
|
||||
Important topology contracts:
|
||||
|
||||
- Graph/table/tree navigation resolves to seat URLs.
|
||||
- Host-level graph uses cross-rig node ID prefixing.
|
||||
- Expanded rig state is managed by `TopologyOverlayProvider`.
|
||||
- Graph data is lazy-fetched for expanded rigs.
|
||||
- Terminal preview actions are hover/focus visible.
|
||||
- The terminal popover must escape React Flow stacking contexts and stay within
|
||||
the viewport.
|
||||
|
||||
## Project Observability
|
||||
|
||||
Project is organized as a hierarchy:
|
||||
|
||||
- Workspace
|
||||
- Mission
|
||||
- Slice
|
||||
|
||||
The current route scope acts as a filter. Higher scopes show broader rollups;
|
||||
lower scopes show more specific story, queue, proof, artifact, test, and topology
|
||||
data.
|
||||
|
||||
Current project tabs:
|
||||
|
||||
- Story - narrative progress and queue body content
|
||||
- Progress - status and activity rollup
|
||||
- Artifacts - files, commits, proof, and outputs
|
||||
- Tests - proof material, screenshots, and verification detail
|
||||
- Queue - operational qitems with actions and drawer detail
|
||||
- Topology - workflow/agent diagram where available
|
||||
|
||||
Project primitives translate raw queue and event data into readable badges,
|
||||
chips, dates, flows, proof thumbnails, and action outcome panels.
|
||||
|
||||
## For You
|
||||
|
||||
For You is the attention-routing surface. It uses live event feed data plus queue
|
||||
details to classify cards into:
|
||||
|
||||
- Action Required
|
||||
- Approval
|
||||
- Shipped
|
||||
- Progress
|
||||
- Observation
|
||||
|
||||
The card renderer prioritizes readable body content, proof thumbnails, actor
|
||||
flow, friendly dates, and action affordances. Queue actions reuse existing
|
||||
mission-control action endpoints.
|
||||
|
||||
## Library And Skills
|
||||
|
||||
`/specs` is the Library route. It contains specs, applications, context packs,
|
||||
agent specs, agent images, and skills.
|
||||
|
||||
Skills are folder-based. The skill tree in Explorer treats each skill as a
|
||||
folder. Clicking a skill opens a skill detail route that defaults to `skill.md`
|
||||
case-insensitively. The skill detail page uses the existing `FileViewer` and
|
||||
does not add a second in-page file browser; file navigation belongs in the
|
||||
Explorer tree.
|
||||
|
||||
## Drawer And Viewer System
|
||||
|
||||
The shared detail drawer is used for transient focused detail:
|
||||
|
||||
- Queue item viewer
|
||||
- File viewer
|
||||
- Subspec preview
|
||||
- Other detail selections
|
||||
|
||||
Drawer triggers carry root/path provenance so the viewer can fetch and render the
|
||||
correct content. The drawer supports outside-click dismissal.
|
||||
|
||||
Image proof viewing is handled by `ProofImageViewer`, which respects the shell
|
||||
layout and uses black-glass styling.
|
||||
|
||||
## Event And Activity Consumption
|
||||
|
||||
UI event consumption is centralized through shared event hooks so the app avoids
|
||||
spawning duplicate SSE connections for related surfaces.
|
||||
|
||||
Current activity consumers include:
|
||||
|
||||
- For You feed hydration
|
||||
- Topology activity rings and hot-potato movement
|
||||
- Activity feed/system surfaces
|
||||
- Rig event surfaces where appropriate
|
||||
|
||||
Reduced-motion preference is honored for pulse and packet animations.
|
||||
|
||||
## Graphics Layer
|
||||
|
||||
The graphics package is intentionally centralized:
|
||||
|
||||
- Runtime identity: Claude, Codex, Terminal, Unknown
|
||||
- Tool identity: CMUX, tmux, VS Code, Terminal, file, markdown, config, code,
|
||||
screenshot, proof, transcript, commit, folder, skill, video, trace
|
||||
- Actor identity: human/operator, runtime agents, terminal fallback
|
||||
|
||||
The goal is to make dense operator surfaces scannable without adding more raw
|
||||
metadata text.
|
||||
|
||||
## Current Design Constraints
|
||||
|
||||
- Use the shared primitives before creating new card styles.
|
||||
- Keep vellum and black-glass separate.
|
||||
- Keep status semantics separate from activity animation.
|
||||
- Do not duplicate runtime/tool brand detection outside the central helpers.
|
||||
- Do not add new daemon shape for UI polish unless the slice explicitly declares
|
||||
and verifies that boundary.
|
||||
- Do not make page-level content look like a raw terminal log unless the content
|
||||
is actually terminal output.
|
||||
@@ -1,129 +0,0 @@
|
||||
---
|
||||
kind: as-built
|
||||
title: UI Library/Specs Surfaces + Design-System Pointer
|
||||
status: active
|
||||
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 + 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: 7eaf524c
|
||||
last-updated: 2026-05-16
|
||||
---
|
||||
|
||||
# UI Library/Specs Surfaces + Design-System Pointer
|
||||
|
||||
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 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/` (re-confirmed at HEAD):
|
||||
|
||||
- `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.
|
||||
|
||||
> 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.
|
||||
|
||||
## 2. Spec review / library / live-identity flows
|
||||
|
||||
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 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`; `/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`) — 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`.
|
||||
- **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`, `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, 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: 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
|
||||
|
||||
- `docs/DESIGN.md` — the canonical visual/design-system spec (pointer; do
|
||||
not copy).
|
||||
- `shell-and-routing.md` — the `/specs` route family + shell + drawer.
|
||||
- `../architecture/agent-spec-and-startup.md` — the spec parsing/resolution
|
||||
contract behind the review flows.
|
||||
- `../architecture/plugin-agent-image-context-pack.md` — the 0.3.1 content
|
||||
layer behind the plugins/agent-image/context-pack Library surfaces.
|
||||
- Source roots: `packages/ui/src/components/specs/`,
|
||||
`packages/daemon/src/domain/{spec-review-service,spec-library-service}*`.
|
||||
@@ -1,433 +0,0 @@
|
||||
---
|
||||
kind: as-built
|
||||
title: UI Project Observability, For You, Dashboard
|
||||
status: active
|
||||
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 + 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: 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 landing surface on the
|
||||
vellum brand system). All read live daemon state; none adds UI-local
|
||||
persistence beyond per-event soft-dismiss.
|
||||
|
||||
> **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 — read first)
|
||||
|
||||
Re-verified at HEAD via `git cat-file -e <tag>:<path>`:
|
||||
|
||||
| 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` (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) |
|
||||
|
||||
> 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 (source-verified at `routes.tsx`@HEAD — BINDING)
|
||||
|
||||
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 @HEAD | Component | Source |
|
||||
|---|---|---|---|
|
||||
| `/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: `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.
|
||||
|
||||
> **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: 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: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 exactly one of five
|
||||
`FeedCardKind` values — `action-required`, `approval`, `shipped`,
|
||||
`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: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.
|
||||
|
||||
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.
|
||||
|
||||
> 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.
|
||||
|
||||
### 2.2 Queue-item hydration + proof previews
|
||||
|
||||
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.
|
||||
|
||||
> 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.
|
||||
|
||||
### 2.3 Verb actions on action/approval cards (the 7-verb system; OPEN-3)
|
||||
|
||||
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]` — 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`
|
||||
> (`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).
|
||||
|
||||
> **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 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: `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.4 Card surface — vellum-coherent (0.3.1 brand layer)
|
||||
|
||||
`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: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.
|
||||
|
||||
### 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, 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).
|
||||
|
||||
> 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 (`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: `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`)
|
||||
|
||||
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: `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`)
|
||||
|
||||
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: `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`,
|
||||
`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: `components/project/ScopePages.tsx:198-217`
|
||||
> (`useProjectScopeRollup`; `rowsForScope` `:193-196`),
|
||||
> rollup components `:219-532`; gate `:679`,`:754` (`active !== "overview"`)
|
||||
> @HEAD.
|
||||
|
||||
### 3.5 Review tabs (v0.4.4 — the Living Notes surface)
|
||||
|
||||
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 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 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 + composition: see
|
||||
[`../architecture/living-notes-review.md`](../architecture/living-notes-review.md).
|
||||
|
||||
> Source @`bb5ad219`: `components/review/{SliceReviewTab,MissionReviewTab,
|
||||
> NeedsYouAccordion,AgentsBandView,VerifyLineageCard,EvidenceOpener,
|
||||
> RigAgentsPage}.tsx`, `review/vellum.ts`, `hooks/useReview.ts`,
|
||||
> `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 landing surface (`/` → `Dashboard`)
|
||||
|
||||
`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).
|
||||
|
||||
> 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, 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* (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). 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.
|
||||
@@ -1,163 +0,0 @@
|
||||
---
|
||||
kind: as-built
|
||||
title: UI Shell, Routing, Drawer System
|
||||
status: active
|
||||
topics: [observability]
|
||||
domains: [engineering-advisor, product-advisor]
|
||||
applies-when: |
|
||||
Need to know how the UI shell (AppShell rail / Explorer / center workspace /
|
||||
drawer / preview stack) is assembled, the actual route tree the shipped UI
|
||||
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: 7eaf524c
|
||||
last-updated: 2026-05-16
|
||||
---
|
||||
|
||||
# UI Shell, Routing, Drawer System
|
||||
|
||||
The `@openrig/ui` package is the shell-first, route-first, primitive-driven
|
||||
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 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/components/AppShell.tsx` — global shell: rail, Explorer, drawer,
|
||||
preview stack.
|
||||
- `src/components/ui/` — reusable vellum + base UI primitives.
|
||||
- `src/components/graphics/RuntimeMark.tsx` — runtime/tool/actor marks.
|
||||
- `src/components/topology/` — graph/table/terminal topology surfaces.
|
||||
- `src/components/project/`, `for-you/`, `dashboard/`, `feed/` —
|
||||
observability surfaces.
|
||||
- `src/components/specs/` — Library / skills / plugins surfaces.
|
||||
- `src/components/{preview,markdown,drawer-viewers}/` — viewers.
|
||||
- `src/hooks/`, `src/lib/` — route data hooks, classifiers, formatters,
|
||||
layout/brand helpers.
|
||||
|
||||
## 2. Shell model
|
||||
|
||||
`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.
|
||||
|
||||
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`)
|
||||
- For You `/for-you` (`rail-for-you`)
|
||||
- Project `/project` (`rail-project`)
|
||||
- Library `/specs` (`rail-specs`)
|
||||
- Settings `/settings` (`rail-settings`)
|
||||
|
||||
The Explorer is contextual: its tree changes with the current destination
|
||||
rather than acting as a generic file browser.
|
||||
|
||||
## 3. Route model
|
||||
|
||||
> 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([...])`).
|
||||
>
|
||||
> 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: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` (`: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` (`: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:432`–`:474` mount `<Navigate>` redirects for removed routes —
|
||||
NOT destination pages: `/context` → `/topology`; `/mission-control` →
|
||||
`/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, 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 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
|
||||
|
||||
- `topology.md` — graph/table/terminal topology surface.
|
||||
- `project-and-for-you.md` — project observability + For-You feed.
|
||||
- `library-specs-and-design-system.md` — Library/specs + DESIGN.md pointer.
|
||||
- Source roots: `packages/ui/src/routes.tsx`,
|
||||
`packages/ui/src/components/AppShell.tsx`.
|
||||
@@ -1,109 +0,0 @@
|
||||
---
|
||||
kind: as-built
|
||||
title: UI Topology — Graph/Table/Terminal, HotPotato, ActivityRing
|
||||
status: active
|
||||
topics: [observability, coordination]
|
||||
domains: [engineering-advisor, operating-advisor]
|
||||
applies-when: |
|
||||
Need to know how the topology surface is built — the host hybrid graph,
|
||||
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: 7eaf524c
|
||||
last-updated: 2026-05-16
|
||||
---
|
||||
|
||||
# UI Topology — Graph/Table/Terminal, HotPotato, ActivityRing
|
||||
|
||||
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 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
|
||||
|
||||
> 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/` (re-confirmed at HEAD):
|
||||
|
||||
- `HostMultiRigGraph.tsx` — host-level hybrid React Flow graph (multi-rig
|
||||
single canvas).
|
||||
- `HybridTopologyNodes.tsx` — exports `HybridAgentNode` (compact agent cards:
|
||||
runtime badges, context %, token totals, activity state, terminal preview,
|
||||
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.
|
||||
- `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).
|
||||
|
||||
> 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
|
||||
|
||||
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 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 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` must escape React Flow stacking contexts (portaled
|
||||
above the canvas) and stay within the viewport.
|
||||
|
||||
## 3. Layout helpers
|
||||
|
||||
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
|
||||
|
||||
- `shell-and-routing.md` — the `/topology` route family and shell.
|
||||
- `project-and-for-you.md` — sibling observability surface.
|
||||
- `../architecture/coordination-primitive.md` — the queue movement the
|
||||
hot-potato edge visualizes.
|
||||
- Source root: `packages/ui/src/components/topology/`,
|
||||
`packages/ui/src/lib/{graph,hybrid,multi-rig}-layout.ts`.
|
||||
@@ -46,7 +46,7 @@ imports:
|
||||
profiles:
|
||||
default:
|
||||
uses:
|
||||
skills: [openrig-user, development-team, test-driven-development, systematic-debugging]
|
||||
skills: [using-superpowers, openrig-user, development-team, test-driven-development, systematic-debugging]
|
||||
guidance: []
|
||||
subagents: []
|
||||
hooks: []
|
||||
@@ -77,7 +77,7 @@ defaults:
|
||||
model: claude-opus-4-6
|
||||
lifecycle:
|
||||
execution_mode: interactive_resident
|
||||
compaction_strategy: default-compaction
|
||||
compaction_strategy: harness_native
|
||||
restore_policy: resume_if_possible
|
||||
|
||||
imports:
|
||||
@@ -165,7 +165,7 @@ defaults:
|
||||
model: claude-opus-4-6
|
||||
lifecycle:
|
||||
execution_mode: interactive_resident
|
||||
compaction_strategy: default-compaction
|
||||
compaction_strategy: harness_native
|
||||
restore_policy: resume_if_possible
|
||||
```
|
||||
|
||||
@@ -180,7 +180,7 @@ 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) |
|
||||
| `compaction_strategy` | string | `harness_native` | `harness_native`, `pod_continuity` (`custom_prompt` is explicitly rejected in v1) |
|
||||
| `restore_policy` | string | `resume_if_possible` | `resume_if_possible`, `relaunch_fresh`, `checkpoint_only` |
|
||||
|
||||
---
|
||||
@@ -318,39 +318,6 @@ Recognized runtime resource types:
|
||||
|
||||
Unknown runtime resource types are still copied to the runtime extension directory for agent-visible context.
|
||||
|
||||
#### Writing a `codex_config_fragment`
|
||||
|
||||
**Begin the fragment with a table header.** A fragment must be a valid TOML
|
||||
document on its own, and every key it sets must sit under a table it declares.
|
||||
A fragment that puts keys ahead of its first table header is refused at
|
||||
projection time, and nothing is written.
|
||||
|
||||
The reason is TOML's grammar rather than a policy choice. The managed block is
|
||||
appended to the end of the user's `config.toml`, and TOML has no syntax for
|
||||
returning to document root once a table has been opened. So if the user's file
|
||||
ends inside any table, an appended root-level key does not land at root — it
|
||||
silently becomes a member of *their* table. Refusal is deterministic and never
|
||||
inspects the user's file: a fragment author cannot see user state, and a rule
|
||||
that passed or failed depending on it would be impossible to reproduce.
|
||||
|
||||
```toml
|
||||
# refused — `model` would bind into whatever table the user's file ends inside
|
||||
model = "gpt-5"
|
||||
|
||||
[mcp_servers.exa]
|
||||
url = "https://mcp.exa.ai/mcp"
|
||||
```
|
||||
|
||||
```toml
|
||||
# accepted — every key sits under a table this fragment declares
|
||||
[mcp_servers.exa]
|
||||
url = "https://mcp.exa.ai/mcp"
|
||||
```
|
||||
|
||||
Where a fragment's table is one the user already declares, the user's table
|
||||
wins: the managed table is dropped, their values are never merged, rewritten or
|
||||
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)
|
||||
@@ -383,12 +350,6 @@ The startup block follows the same format as in the RigSpec (see `docs/reference
|
||||
|
||||
Agent-level startup is applied to all profiles. Profile-level startup is applied only when that profile is active. Both merge additively via the startup layering model.
|
||||
|
||||
An additional orientation challenge requires an explicit `startup_proof` action
|
||||
with `value: authenticated` and `idempotent: true`. Omission adds no exercise;
|
||||
a later applicable `value: none` overrides an earlier selection. See
|
||||
[startup proof selection](rig-spec.md#startup-proof-selection) for precedence,
|
||||
restore behavior, and the distinction between readiness and verified proof.
|
||||
|
||||
### Delivery Hint Quick Reference
|
||||
|
||||
| Hint | When Delivered | Mechanism |
|
||||
@@ -414,7 +375,7 @@ restore behavior, and the distinction between readiness and verified proof.
|
||||
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).
|
||||
13. Lifecycle `compaction_strategy` must be `harness_native` or `pod_continuity`.
|
||||
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.
|
||||
|
||||
@@ -452,6 +413,6 @@ The only required file is `agent.yaml`. Everything else is referenced by paths i
|
||||
| `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 |
|
||||
| `reviewer` | `specs/agents/review/reviewer/` | `shared` | openrig-user, review-team, etc. | 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 |
|
||||
@@ -225,7 +225,7 @@ Commands sent to the agent's terminal after it's ready. Can install MCPs, run se
|
||||
| `send_text` delivery after ready | **Supported** | Reliable. Requires harness to be ready. |
|
||||
| Hook projection | **Experimental** | Files are copied but execution/integration varies by runtime. |
|
||||
| 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. 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. |
|
||||
| Permission allowlisting | **Supported via harness config** | Core OpenRig boot adds the minimal Claude `Bash(rig:*)` baseline. Additional policy should be supplied through spec-selected runtime resource fragments or native Codex config profiles, not adapter hard-code. |
|
||||
| MCP installation | **Experimental** | Claude Code: `/mcp` interactive command or `claude mcp add` from CLI. Can also be described in startup files for agent self-configuration. Reliability depends on runtime TUI state. |
|
||||
| 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. |
|
||||
@@ -246,8 +246,7 @@ This way, when deterministic support becomes fully reliable, the agent will boot
|
||||
OpenRig performs best-effort deterministic runtime configuration for managed sessions. Core bootstrap stays minimal; user/custom policy belongs in spec-selected runtime resources. These writes are intentionally invasive and should be disclosed plainly:
|
||||
|
||||
- Claude global config: `~/.claude/settings.json`
|
||||
OpenRig no longer writes a core `Bash(rig:*)` permission allowance here. Older
|
||||
installations may retain one; existing user settings are not removed.
|
||||
Purpose: allow core `rig` commands without repeated Claude permission prompts.
|
||||
- Claude global state: `~/.claude.json`
|
||||
Purpose: pre-trust managed workspaces and mark onboarding complete for fresh managed sessions.
|
||||
- Claude project-local config: `.claude/settings.local.json`
|
||||
@@ -261,11 +260,6 @@ 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
|
||||
- already-running adopted sessions may need restart before they pick up newly written config
|
||||
|
||||
Permission mode and runtime resource projection are separate. A selected fragment
|
||||
can affect native configuration, but OpenRig's launch flags can override those
|
||||
values. Recording a config-surface `permission_policy` is not proof that its
|
||||
rules were translated or applied. See [permission precedence and limits](getting-started.md#custom-settings-and-precedence).
|
||||
|
||||
### Runtime Differences
|
||||
|
||||
**Claude Code:**
|
||||
@@ -280,9 +274,7 @@ rules were translated or applied. See [permission precedence and limits](getting
|
||||
- Reads from `AGENTS.md` and `.agents/` directory
|
||||
- Recurring task support is limited — no confirmed equivalent of Claude Code's `/loop` command
|
||||
- MCP configuration mechanism differs from Claude Code
|
||||
- Approval policy and sandbox access are separate controls. OpenRig's default
|
||||
`-s workspace-write` selects the sandbox; it does not force `-a`. A member's
|
||||
`codex_config_profile` selects native `-p`, distinct from the AgentSpec `profile`.
|
||||
- Approval mode controlled via launch flags (`-a`, `-s`, `--full-auto`)
|
||||
- Can self-install dependencies from instructions but timer/recurring behavior is not reliably available
|
||||
|
||||
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."
|
||||
@@ -319,7 +311,7 @@ This prompts the agent to actually invoke the skills, not just have them as pass
|
||||
## System Check
|
||||
|
||||
After identity recovery, verify:
|
||||
1. `rig ps --nodes` shows your rig running (scoped to your session's rig by default; outside a managed session name it explicitly: `rig ps --nodes --rig <name>`)
|
||||
1. `rig ps --nodes` shows your rig running
|
||||
2. `rig env status` shows services healthy (if applicable)
|
||||
3. Your working directory is correct
|
||||
4. Required tools are available (node, npm, git, etc.)
|
||||
@@ -363,5 +355,4 @@ When creating a new agent's startup experience:
|
||||
- [ ] Include a system check in the startup context
|
||||
- [ ] Verify the agent spec validates: `rig agent validate agent.yaml`
|
||||
- [ ] Verify the rig spec validates: `rig spec validate rig.yaml`
|
||||
- [ ] Run the advisory authoring check: `rig spec audit rig.yaml`
|
||||
- [ ] Test by launching the rig and checking that the agent received the expected content
|
||||
@@ -1,101 +0,0 @@
|
||||
# Agent state taxonomy
|
||||
|
||||
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
|
||||
truth is `packages/daemon/src/domain/activity-taxonomy.ts`.
|
||||
|
||||
## The three orthogonal axes
|
||||
|
||||
| axis | values | question it answers |
|
||||
|---|---|---|
|
||||
| session | `present` · `detached` · `exited` · `absent` | does a process exist |
|
||||
| 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 |
|
||||
|
||||
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.
|
||||
|
||||
### needs-input is a count + reason, never a status value
|
||||
|
||||
Blocked-on-input rides as `{ count, reason }` — the number of outstanding prompts plus a
|
||||
short phrase naming why nothing is moving ("permission prompt", "usage limit",
|
||||
"classifier hold" — provider chrome and usage limits are explicitly in-axis: they are
|
||||
the second cause of production-observed parks). Human surfaces may *display* "needs-input"
|
||||
(the four-value human list) via the one bridge `deriveDisplayActivity`, which
|
||||
renders needs-input whenever `count > 0`; no store or transition ever holds it as a
|
||||
state. Attention/alarm values likewise stay in their own machinery (`attentionCount`).
|
||||
Both herdr and omnigent converged on this exclusion, with warning comments on the
|
||||
collision in both codebases.
|
||||
|
||||
## Derived diagnoses — computed at read time, never stored
|
||||
|
||||
- **PARKED** — the disease: `(activity = idle-at-prompt OR needs-input pending) ×
|
||||
(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 **not** parked.
|
||||
- **DONE-UNSEEN** — finished work whose completion nobody consumed (herdr derives it as
|
||||
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
|
||||
|
||||
| ours | herdr (`src/detect/mod.rs:11`) | omnigent (`schemas.py:2767`) |
|
||||
|---|---|---|
|
||||
| `working` | `Working` | `running` |
|
||||
| `idle-at-prompt` | `Idle` | `idle` |
|
||||
| needs-input count+reason | `Blocked` + `visible_blocker` override | `pending_elicitations_count` + `blocked_on` phrase — **not** a status |
|
||||
| `unknown` | `Unknown` ("plain shell or unrecognized program") | — |
|
||||
| derived DONE-UNSEEN | derived `Done` = idle ∧ unseen (`src/ui/sidebar.rs:186`) | — |
|
||||
| session axis | server owns the PTY (presence direct) | `runner_online` × `host_online` × `host_resumable` |
|
||||
| — (rejected) | — | `waiting` (turn parked on async drain — collides with Claude's dialog `waiting`; both codebases carry warning comments) |
|
||||
|
||||
## The evidence ladder (rung inventory and retirement conditions)
|
||||
|
||||
State is computed by ONE arbitration point (`SeatActivityService`) from ranked,
|
||||
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 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
|
||||
rung-health event.
|
||||
- **r4 — visible needs-input chrome**: standing; outranks self-report for the
|
||||
needs-input signal only (a dialog you can see beats a hook that said working).
|
||||
- **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; production agreement promotes it; identity-only until
|
||||
promoted).
|
||||
|
||||
Partial-coverage honesty: a source with partial lifecycle coverage gets identity-only
|
||||
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
|
||||
generation swap is its own visible event — never an activity transition — and triggers
|
||||
rung-inventory re-declaration: a successor never inherits its predecessor's rung
|
||||
authority (hooks live in occupant config while the pane is seat-persistent).
|
||||
|
||||
## 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
|
||||
oscillated on mid-turn lulls and idempotently locked out real completions; its
|
||||
surviving 5-second variant is annotated a stopgap awaiting a hook replacement.
|
||||
Distinction held: transcript growth remains FINE as the refocus hook's cadence
|
||||
trigger — a different purpose, and the one permitted consumer.
|
||||
- **pane-scraping as primary truth: REJECTED.** herdr — whose TOML screen manifests are
|
||||
the state of that art — subordinates them to hooks wherever hooks cover the lifecycle,
|
||||
and marks viewer screens `skip_state_update` because scrollback lies. Pane reading
|
||||
stays fallback-tier only.
|
||||
@@ -1,120 +0,0 @@
|
||||
# The Chain-File Convention (CE-v2)
|
||||
|
||||
**This document is the SSOT for chain files**: what they are named, what each
|
||||
altitude carries, and how the leaf-to-root trace resolves. Both trees' walkers
|
||||
consume the paths defined here. If a walker and this document disagree, one of
|
||||
them has a defect — report it; do not fork the convention.
|
||||
|
||||
## The one rule
|
||||
|
||||
**One filename, identical at every altitude of a tree.** A reader orients by
|
||||
walking from where they stand toward the root, reading the same-named file at
|
||||
each level. No pointers to follow, no branching, no per-level names. Inventing
|
||||
a level-specific name breaks every walker.
|
||||
|
||||
Chain files sit on **nodes** (an instance, a rig, a pod, a seat; a mission, a slice)
|
||||
— never on shelves (`rigs/`, `seats/`, `missions/` are containment, not
|
||||
nodes, and carry no chain file).
|
||||
|
||||
## Two trees, two questions
|
||||
|
||||
| tree | path shape | carries | ships? |
|
||||
|---|---|---|---|
|
||||
| **Topology** | instance → rig → pod → seat | how work is done here | **yes** — generally applicable defaults ship in source |
|
||||
| **Project** | project → mission → slice | what is being built | **no** — depends on what the user builds; see below |
|
||||
|
||||
### The topology tree
|
||||
|
||||
Rooted at the typed config key **`topology.root`** (resolution
|
||||
`env OPENRIG_TOPOLOGY_ROOT > config file > derived default
|
||||
$OPENRIG_HOME/topology`). Never hardcode the path — `rig config get
|
||||
topology.root` is the answer on any machine. The instance altitude **is the
|
||||
top of the root** (there is no instance directory to find; the root is the
|
||||
instance):
|
||||
|
||||
```
|
||||
<topology.root>/<NAME>.md # instance altitude
|
||||
<topology.root>/rigs/<rig>/<NAME>.md # rig altitude
|
||||
<topology.root>/rigs/<rig>/pods/<pod>/<NAME>.md # pod altitude
|
||||
<topology.root>/rigs/<rig>/seats/<seat>/<NAME>.md # seat altitude
|
||||
```
|
||||
|
||||
The engine creates the instance root, rig directory, and each declared pod
|
||||
directory when it materializes topology, even when no authored chain default
|
||||
exists. Pod context remains optional: use that altitude only for knowledge
|
||||
shared within one context domain. Cross-pod guidance still belongs at the rig
|
||||
altitude.
|
||||
|
||||
Established chain names on the topology tree:
|
||||
|
||||
- `LEARNED.md` — what a POSITION has learned; never shared or shipped as-is.
|
||||
A seat's LEARNED is identified by its PATH: the same seat name in two rigs
|
||||
is two different files.
|
||||
- `CULTURE.md` — norms layered into members at startup.
|
||||
|
||||
### 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`.
|
||||
|
||||
**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. 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.)
|
||||
|
||||
## Legacy location and the advisory
|
||||
|
||||
Before this convention the topology tree lived at `~/.openrig/shared-docs/rigs/`
|
||||
(design decision 2026-08-14: an arbitrary folder on one machine, not a product
|
||||
path). That location **stays readable** as a per-level fallback so existing
|
||||
rigs migrate instead of breaking — but every read that resolves there emits a
|
||||
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
|
||||
settings twin (`resolveLegacyTopologyRigsRoot`); walkers import it and carry
|
||||
no path literal.
|
||||
|
||||
## The trace
|
||||
|
||||
`rig context trace --rig <rig> [--pod <pod>] [--seat <seat>] --name <NAME>.md`
|
||||
performs the walk: it prints each selected altitude root-first (general →
|
||||
specific), marks whether content came from `topology.root`, the legacy tree
|
||||
(with the advisory on stderr), or is absent, and needs no running daemon —
|
||||
orientation is exactly when the daemon may be down. Existing rig/seat traces
|
||||
remain valid; selecting `--pod` adds that context domain between them. `--json`
|
||||
returns the structured result.
|
||||
|
||||
Your reads ARE the walk: a trace assembled from memory is a recitation that
|
||||
reproduces the drift it was meant to catch. Run it; do not recall it.
|
||||
|
||||
## Shipped defaults and the curation path
|
||||
|
||||
Included rigs (product-team first) ship sensible-default chain files at the
|
||||
applicable instance, rig, pod, and seat altitudes, installed under
|
||||
`topology.root` at rig-up.
|
||||
A shipped default is a **starting point** the occupying team appends to — it
|
||||
is never overwritten by a later rig-up (existing files win).
|
||||
|
||||
Adding a discovered best practice to the shipped defaults is deliberately
|
||||
lightweight:
|
||||
|
||||
1. **Discovery** — the practice appears where it was earned: a seat's
|
||||
`LEARNED.md`, a field note, a review observation.
|
||||
2. **Curation** — someone judges it *generally applicable* (would it hold on a
|
||||
stranger's machine, in a different project?). If it is project-specific it
|
||||
stays at the altitude that earned it.
|
||||
3. **Ship** — add it to the rig's default chain files in source
|
||||
(`packages/daemon/specs/rigs/…/topology/`), with the motivating incident in
|
||||
one line. It reaches new installs at the next release; running rigs pick it
|
||||
up only via explicit delivery (see the refocus channel) — **editing a file
|
||||
is not delivery to a running seat.**
|
||||
|
||||
## What this file does not cover
|
||||
|
||||
How chain files reach a RUNNING seat (the refocus channel) is specified in the
|
||||
refocus documentation; quality bars for the work itself live in the rig's
|
||||
operating-model skill and culture file.
|
||||
@@ -1,39 +0,0 @@
|
||||
# Developing OpenRig — gates and lanes
|
||||
|
||||
This is the contributor-facing statement of which checks BLOCK a change and which are
|
||||
advisory. There is no external CI at this tip: the root `package.json` script chain IS
|
||||
the gate, and the release checklists invoke it.
|
||||
|
||||
## Blocking gates (must pass before a candidate moves)
|
||||
|
||||
| Gate | Command | Covers |
|
||||
|---|---|---|
|
||||
| Typecheck | `npm run lint` | daemon + **ui** + cli + tui tsconfigs — UI typecheck STAYS blocking |
|
||||
| Build | `npm run build` | all workspaces — the UI dist ships in the package, so its build STAYS blocking |
|
||||
| Repo scripts | `npm run test:repo` | script self-tests, docs guard, skill mirror check |
|
||||
| Unit tests | `npm run test:workspaces` | `packages/daemon` + `packages/cli` + `packages/tui` |
|
||||
|
||||
`npm test` runs `test:repo` and `test:workspaces` — the blocking set is readable in the
|
||||
script itself.
|
||||
|
||||
## Advisory lane
|
||||
|
||||
| Lane | Command | Meaning |
|
||||
|---|---|---|
|
||||
| UI unit tests | `npm run test:ui` | runs `packages/ui` vitest at will; NOT part of `npm test` |
|
||||
|
||||
## The norm (web-UI freeze at 0.5.0)
|
||||
|
||||
Daemon API changes no longer require UI sync or UI verification; the contract mirrors
|
||||
under `packages/ui/src/hooks/` are no longer proactively maintained; a new `test:ui`
|
||||
failure signals a moved API contract, not a broken gate.
|
||||
|
||||
Browser/interaction testing of the web UI is not a contributor gate. (The packaged
|
||||
starter-rig agent skills that exercise the UI are product content for user rigs, not
|
||||
part of this repo's gates.)
|
||||
|
||||
## Wording rule
|
||||
|
||||
The web UI is **experimental**, in **maintenance mode**, supported **best-effort**;
|
||||
**the CLI is primary**. There is no scheduled removal and PRs are welcome. Do not
|
||||
describe the UI with stronger end-of-life language than this section uses.
|
||||
@@ -1,506 +0,0 @@
|
||||
# Getting started: one useful change in your repository
|
||||
|
||||
Start with a repository and one bounded change you can exercise. The shipped
|
||||
first-project recipes provide the same two seats: an outcome owner and an
|
||||
independent checker. Choose Claude Code, Codex, or one of each using the accounts
|
||||
you already have. Terminal-provider support does not change the harness or login.
|
||||
|
||||
You need Node.js 22 or 24 and tmux, on macOS or Linux. On a Mac with Apple
|
||||
silicon, use Node.js 22 (see the [compatibility
|
||||
history](../releases/v0.5.15.md#known-compatibility-limitation)). Native
|
||||
Windows is not supported yet, and WSL2 has not been tested. Node 20 is no longer
|
||||
supported; Node 26 and other versions are untested.
|
||||
|
||||
**Choose permissions before starting the team.** Ordinary OpenRig launches use
|
||||
Codex's `-s workspace-write`, with approval policy from your native configuration,
|
||||
or Claude Code's `acceptEdits`, which still leaves commands subject to native
|
||||
rules and prompts. Codex's sandbox normally blocks network access, including the
|
||||
local OpenRig daemon. A command allowance does not change general sandbox/network
|
||||
settings. The starter's `profile: default` selects OpenRig resources, not a native
|
||||
permission profile.
|
||||
Agent-guided setup [asks once](#have-your-agent-configure-permissions): “Allow
|
||||
your agents to run OpenRig commands without repeated permission prompts?”
|
||||
**Yes — recommended** / **No — keep prompts**. An existing explicit choice is
|
||||
reused; No or no answer leaves settings unchanged. Broader access is separate.
|
||||
|
||||
> Everything below reports **what is currently true**, never a guarantee that
|
||||
> downstream work will succeed. "Daemon up" does not mean every agent is healthy;
|
||||
> "kernel ready" does not mean every kernel agent is healthy; a workspace root
|
||||
> being *live* does not mean it is the *right* one for your project.
|
||||
|
||||
## Prepare and launch
|
||||
|
||||
Type `rig` in an ordinary terminal to open the startup and work TUI. It shows
|
||||
the daemon address; **d** expands the selected instance path and diagnostics.
|
||||
If the daemon is stopped, press Enter
|
||||
to start that daemon, then choose the rigs and seats you want. Kernel is
|
||||
recommended first; selecting its operator does not start every kernel seat.
|
||||
The same view is available with **S** from ordinary TUI work.
|
||||
**?** opens Help even while connection checks are pending. **w** skips startup;
|
||||
**Esc** goes back, or leaves startup from its first page. These choices do not
|
||||
start a daemon or a seat. **L** opens local reading before or after connecting:
|
||||
choose configured Specs, project intent, projects, or missions and slices, then
|
||||
select a directory or file. **r** reads the selected source again; **Esc** returns.
|
||||
Local reading uses this machine's configured workspace paths and file allowlist,
|
||||
including when the selected daemon address is remote. It shows disk provenance,
|
||||
missing or denied sources, binary files and the 1 MiB text truncation boundary.
|
||||
These disk snapshots may change after reading and do not supply live queue,
|
||||
execution or topology state. Live views load after a confirmed connection and
|
||||
deliberate entry; a stalled live read does not prevent Help or local reading.
|
||||
When terminal transport is unavailable, **t** starts the empty terminal service
|
||||
so recovery choices can be inspected. It launches no seats.
|
||||
|
||||
For a previously occupied seat, Enter attempts its previous conversation.
|
||||
If history is unavailable, read the reason. **f** opens a separate fresh-start
|
||||
decision for that named seat; **Esc** declines without launching it. A confirmed
|
||||
fresh conversation receives the configured context and retains the old history,
|
||||
but does not resume that history. Authentication or runtime failures require
|
||||
repair of that prerequisite. **o** opens the existing native terminal here; detach
|
||||
to return (tmux defaults to Ctrl-b, then d). Decide native trust/auth prompts
|
||||
there. If a fresh start paused before context delivery, **c** finishes that
|
||||
delivery to the same occupant. **r** reads actual state again; **d** expands details.
|
||||
|
||||
### Choose your providers
|
||||
|
||||
Ask: **“Which working account do you want this team to use: Claude Code, Codex,
|
||||
or both?”** Reuse an explicit choice already made. Recommend the account the
|
||||
user already has working; a second subscription is not a prerequisite.
|
||||
|
||||
| Choice | Starter name | Owner / checker runtime and model |
|
||||
| --- | --- | --- |
|
||||
| Two Codex agents (existing route) | `first-project` | Both `codex`, pinned `gpt-6-astra` |
|
||||
| Two Claude agents | `first-project-claude` | Both `claude-code`, configured native default model |
|
||||
| One of each | `first-project-mixed` | Claude owner (native default); Codex checker (`gpt-6-astra`) |
|
||||
|
||||
Claude uses the same unpinned model convention as the existing Claude kernel and
|
||||
implementation-pair recipes: OpenRig does not pass a model override. Read the
|
||||
selected harness's configured model and show it alongside the recipe and launch
|
||||
command before proceeding. Confirm account access to any pin; if unavailable,
|
||||
ask for a supported model choice rather than silently substituting a model or
|
||||
provider. After launch, confirm the actual native model before assigning work.
|
||||
|
||||
Install OpenRig and check `tmux -V`. Check **only the selected providers**:
|
||||
|
||||
- Claude Code: `claude --version` and `claude auth status`. If sign-in is missing,
|
||||
ask once: “Please run `claude auth login` in your launch environment.”
|
||||
- Codex: `codex --version` and `codex login status`. If sign-in is missing,
|
||||
ask once: “Please run `codex login` in your launch environment.”
|
||||
|
||||
Install a missing selected CLI using its provider's installation instructions.
|
||||
The other provider's CLI/login and Herdr/cmux are optional. Do not copy credentials
|
||||
or start repeated sign-in attempts. Recheck the selected login after the user
|
||||
completes it. `rig setup --dry-run` previews the broader setup; applying
|
||||
`rig setup` installs/checks **both** harnesses and cmux, so it is optional for
|
||||
this selected-provider path, not a requirement to fix an unused provider.
|
||||
|
||||
### Kernel startup stays automatic
|
||||
|
||||
On a fresh instance, ordinary daemon startup chooses the kernel variant from
|
||||
successful native auth probes: Claude alone, Codex alone, or both. Thus an absent
|
||||
unused provider is fine. The project recipe does **not** constrain that probe:
|
||||
if both accounts are authenticated, automatic kernel startup uses both, even
|
||||
when the two project agents use just one provider. No manual kernel setup is
|
||||
needed for this journey. The starter choice is not an instance-wide provider
|
||||
restriction; a request to use only one provider for everything is separate.
|
||||
Preserve any existing managed kernel and working rigs.
|
||||
|
||||
### Launch the two project seats
|
||||
|
||||
Set `starter` to the chosen name from the table; the existing Codex route remains:
|
||||
|
||||
```sh
|
||||
cd <your-repository>
|
||||
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 status
|
||||
rig ps --nodes --rig "$starter"
|
||||
```
|
||||
|
||||
Preview the selected seats, models and resources. Plan checks resolution and
|
||||
preflight for the working directory. Launch starts the daemon if needed, with
|
||||
the kernel behavior above. Read readiness for the project seats, not only daemon
|
||||
health. Resolve a named authentication, trust or permission prompt before giving
|
||||
that seat work. No new team is needed when returning to an existing project.
|
||||
|
||||
When a seat pauses, open its existing terminal with **o** in the startup view.
|
||||
Read the proposed command, working directory and target instance. For an intended
|
||||
local `rig` call, choose the native prompt's one-time approval if that is the scope
|
||||
you want; a saved command-prefix allowance also affects future matching calls.
|
||||
Decline an unexpected operation and tell the same agent what to do instead.
|
||||
Approval controls whether an action may run; the sandbox controls its filesystem
|
||||
and network access. Turning approvals off does not grant network access.
|
||||
|
||||
After answering, watch for the command's result and the agent continuing. Read
|
||||
the corresponding queue row and transition from your ordinary terminal. If an
|
||||
operation timed out, read its result before asking for another attempt: it may
|
||||
already have taken effect. A delivered message or disappearing prompt alone is
|
||||
not progress. If startup is still waiting for context delivery, use **c** for the
|
||||
same occupant, then **r** to refresh. Do not start another seat to clear a prompt.
|
||||
|
||||
These starters are deliberately small starting points, not universal teams.
|
||||
For a different installed runtime or team shape, inspect `rig specs ls --kind
|
||||
rig` and `rig specs preview <name>` before selecting it. A seven-seat showcase
|
||||
is optional and consumes more concurrent capacity.
|
||||
|
||||
## Give the owner an outcome
|
||||
|
||||
For example, in a project that imports CSV files:
|
||||
|
||||
```sh
|
||||
rig send "dev-owner@$starter" 'Improve the CSV import error when a required column is missing: name the column and leave the existing data unchanged. Add a regression check, ask dev-check for an independent check of the exact candidate, and record the result and how I can try it. Keep the change local; do not publish.'
|
||||
```
|
||||
|
||||
Replace the example with a real problem in your repository. Include what the
|
||||
user should observe, a boundary and how success can be checked. The owner
|
||||
creates and claims a durable task, implements it, and routes the selected
|
||||
independent check. You should not have to relay the review between terminals.
|
||||
`rig send` is the initial conversation; the queue and repository artifacts
|
||||
retain the work. An unbound shell does not need to impersonate a queue owner.
|
||||
|
||||
Use the chosen rig name in its seat addresses (for example,
|
||||
`dev-owner@first-project-claude`). From an actual project seat, follow the work with
|
||||
`rig queue list --limit 1000`: its default scope is the caller's current rig.
|
||||
`queue list` has no `--rig` option. From an observer shell or another rig, use
|
||||
`rig queue list --destination "dev-owner@$starter" --limit 1000` and the same
|
||||
command for `"dev-check@$starter"`, after verifying those live addresses.
|
||||
These show each destination's obligations, not a whole-rig view. An unbound shell
|
||||
must not pretend to be a seat to change scope; use `--all-rigs` only when that
|
||||
broader view is intended. Then read `rig queue show <id> --full` and
|
||||
`rig queue transitions <id>`. A delivered message is not a reviewed result.
|
||||
Read the artifact, exercise its behavior, and check the candidate reviewed.
|
||||
|
||||
## Share the dashboard and return to it
|
||||
|
||||
```sh
|
||||
rig tui --shared
|
||||
```
|
||||
|
||||
A fresh kernel runs the ordinary TUI in its existing `operator-human` terminal.
|
||||
This command attaches another client to that terminal. **Ctrl-b, then d**
|
||||
detaches without quitting the TUI; return with the same command and the view
|
||||
stays where it was. Another authorized agent can capture or operate that same
|
||||
pane. It should tell you before changing your view. The terminal is not a
|
||||
human inbox and does not prove anyone is watching it.
|
||||
|
||||
Plain `rig tui` remains an independent local view. If an older kernel or a TUI
|
||||
you quit shows a shell, run `rig tui` in that shell once. `--shared` does not
|
||||
start or replace a terminal, so a missing binding is reported with recovery
|
||||
guidance rather than creating a second kernel.
|
||||
|
||||
Herdr users follow the same launch and task path. To place the managed team in
|
||||
Herdr, use `rig terminal open "$starter" --provider herdr`; for the shared
|
||||
dashboard, use `rig terminal open kernel --provider herdr`. The equivalent
|
||||
cmux provider is also available. Read the opened/absent/degraded result: a
|
||||
partial terminal view is not a healthy team. Repeated terminal-open calls can
|
||||
create another provider workspace; return to the one already open when you
|
||||
want to preserve it. This is terminal integration, not native plugin enrollment.
|
||||
|
||||
## Continue real project work
|
||||
|
||||
Return to the same owner with the next outcome, citing the earlier result.
|
||||
The seat address and durable queue survive closing your viewing terminal.
|
||||
Keep intent, acceptance and evidence in the repository's existing project,
|
||||
mission and slice artifacts; the starter reads those before inventing a path.
|
||||
|
||||
If the project has no work tree, start with `rig workspace doctor` and
|
||||
`rig scope mission create --help`, then `rig scope slice create --help`. Set
|
||||
the actual intended outcome before creating work. `rig scope` retains what is
|
||||
being built. When repeated coordination warrants a workflow, discover with
|
||||
`rig workflow specs`, inspect its owners and inputs, and instantiate the
|
||||
selected name with `rig workflow instantiate --help`. A workflow is not needed
|
||||
merely to make the first local change.
|
||||
|
||||
For a continuing team, [OpenRig Software Factory](../../packages/daemon/specs/agents/shared/skills/core/openrig-software-factory/SKILL.md)
|
||||
offers manual/team work, queue-supported orchestration without Workflow, and an
|
||||
optional explicit Workflow path, with wake defaults, token costs and permission
|
||||
choices visible. Give its short request to your existing agent. After
|
||||
installation, discover the compatible bundled recipe with `rig context show
|
||||
skills/core/openrig-software-factory --json`; retain a missing/version-mismatch
|
||||
result rather than silently using newer instructions. Its growth section keeps
|
||||
three choices clear: stay with the pair, add one or two seats to the running rig
|
||||
with `rig grow` and no YAML, or optionally author a custom rig. It covers
|
||||
new-seat context/work ownership, concurrency costs and saving the expanded spec.
|
||||
This guide remains the short first-use path.
|
||||
|
||||
## Incomplete setup and restart
|
||||
|
||||
| Observation | Next action |
|
||||
| --- | --- |
|
||||
| Tool missing or login fails | Use the specific setup/auth hint; recheck that executable in the launch shell. Do not send work to an unready seat. |
|
||||
| Daemon is healthy, kernel is still starting | Read `rig status` and `rig ps --nodes --rig kernel`; kernel readiness is separate. |
|
||||
| Shared terminal is absent | Inspect the existing kernel binding and recovery state; use standalone `rig tui` while resolving it. |
|
||||
| Viewing terminal was closed | Reattach with `rig tui --shared`; do not relaunch the team. |
|
||||
| Daemon restarted but tmux survived | Re-read `rig status` and the existing queue; a daemon restart is not a fresh project. |
|
||||
| Host reboot lost tmux sessions | Open `rig`, start the daemon if needed, and select the existing rig and seats. Resume is the default; a fresh conversation needs a separate decision. |
|
||||
| Launch reports no usable snapshot | Inspect the existing rig and retained project files, then follow the same-seat recovery below. |
|
||||
| Work is waiting on a prompt or decision | Read the row, transition and named prompt; preserve the obligation until the missing decision arrives. |
|
||||
|
||||
If a snapshot is unavailable, the startup view checks the selected seat's
|
||||
retained startup source and authoritative occupant relation. It reports a
|
||||
missing or ambiguous source instead of selecting an arbitrary historical row.
|
||||
Repair the named source, retry, or leave the seat stopped. Check the retained
|
||||
queue, project notes and observed result before continuing work.
|
||||
|
||||
`rig setup` prints the short form of this path; `rig status` points back here.
|
||||
|
||||
## Kernel framing (what `rig setup` does and does not do)
|
||||
|
||||
Explicit CLI daemon startup retains its automatic kernel behavior. The TUI
|
||||
starts the daemon with kernel auto-boot disabled so the user can select seats:
|
||||
|
||||
- `rig setup` installs/verifies the runtime; it does not start the daemon or the
|
||||
kernel.
|
||||
- Starting the daemon (`rig daemon start`, or implicitly via `rig up`) is what
|
||||
boots the kernel rig in the background.
|
||||
- Starting it from bare `rig` prepares no agents automatically. The TUI offers
|
||||
kernel setup and individual seat selection after connecting.
|
||||
- **Kernel readiness is a distinct signal from daemon health.** The daemon's HTTP
|
||||
health binds early; the kernel can still be booting or a kernel agent can be
|
||||
unhealthy while the daemon is up. `rig status` surfaces kernel readiness
|
||||
separately (via `/api/kernel/status`); `rig daemon start --wait-for-kernel`
|
||||
polls it.
|
||||
|
||||
## The scope <-> workflow bridge
|
||||
|
||||
Two related primitives, often confused by new operators:
|
||||
|
||||
- **`rig scope`** manages **durable, on-disk artifacts** - missions and slices
|
||||
(markdown/YAML files in your workspace). These are the persistent record of
|
||||
*what work exists*.
|
||||
- **`rig workflow`** manages a **runtime instance** - when you
|
||||
`rig workflow instantiate <name>`, the daemon creates a workflow instance plus
|
||||
an **entry qitem** that routes the first step to an owner. This is the live
|
||||
coordination of *who does the next step*.
|
||||
|
||||
Scope files retain what the work is; workflow instances and their queue packets
|
||||
retain who acts next. Creating or editing a mission does not start work. You can
|
||||
instantiate a named workflow with `rig workflow instantiate <name>`, or explicitly
|
||||
inspect an authored lifecycle with `rig workflow compile` and create its runtime
|
||||
with `rig workflow instantiate-lifecycle`. Compilation alone does not start work.
|
||||
[OpenRig Software Factory](../../packages/daemon/specs/agents/shared/skills/core/openrig-software-factory/SKILL.md)
|
||||
shows a small reviewed example and how to retain custody through a genuine wait.
|
||||
|
||||
## Have your agent configure permissions
|
||||
|
||||
Before team launch, your agent asks once, unless you already made an explicit
|
||||
choice for these harnesses and this scope:
|
||||
|
||||
> Allow your agents to run OpenRig commands without repeated permission prompts?
|
||||
> **Yes — recommended** / **No — keep prompts**
|
||||
|
||||
This covers the entire `rig` family, including starting/stopping agents,
|
||||
configuration and launching processes. It is not global YOLO or permission to
|
||||
invent work. The scope is your personal settings for this project unless you
|
||||
explicitly choose user-wide sessions, which can affect your other projects.
|
||||
|
||||
On an actual **Yes**, the agent backs up the relevant files, adds the existing
|
||||
native rules without duplicates, and preserves stricter rules and unrelated
|
||||
settings. It checks bare and actual absolute-path invocations, rule loading and
|
||||
repeated harmless reads in the target conversation. No or no answer leaves
|
||||
settings alone and continues with existing prompts. Unsupported scope or a
|
||||
managed restriction is reported; it is not permission to grant broader access.
|
||||
|
||||
The agent remembers an explicit choice, scope and exact additions in existing
|
||||
onboarding context, so setup does not ask again. You do not need to approve each
|
||||
routine edit separately. To undo, say **“Undo the OpenRig command allowances
|
||||
added by this setup; keep my other rules.”** The agent removes only its recorded
|
||||
additions, preserves earlier rules and later edits, and verifies reloading.
|
||||
Other pre-existing allowances may still permit commands after this undo.
|
||||
|
||||
Use the maintained **Applying a permission policy** procedure:
|
||||
|
||||
```sh
|
||||
rig context get skills/applying-a-permission-policy/SKILL.md
|
||||
```
|
||||
|
||||
In a source checkout, read [its source](../../packages/daemon/assets/plugins/openrig-core/skills/applying-a-permission-policy/SKILL.md).
|
||||
In an npm installation, the same file is under
|
||||
`@openrig/cli/daemon/assets/plugins/openrig-core/skills/applying-a-permission-policy/SKILL.md`
|
||||
below the matching `npm root -g` or local `npm root`. Use the version supplying
|
||||
your `rig` executable. It covers Codex/Claude command rules, actual config roots,
|
||||
preserving restrictions and verifying the target conversation. A missing guide or
|
||||
unsupported native version is a reported gap, not permission to silently bypass.
|
||||
|
||||
The broader launch-mode recipes below are optional. Command-family rules do not
|
||||
require changing the starter's sandbox or everyone else's defaults.
|
||||
|
||||
## Opt-in permissive operation
|
||||
|
||||
Permissive operation lets agents act with your account's filesystem and network
|
||||
access with fewer permission stops. They can damage files or send data without
|
||||
another confirmation. Use it only for work and an environment you deliberately
|
||||
trust; it does not supply missing credentials or override organization policy.
|
||||
|
||||
Make changes in a **user-owned spec before its first launch**. To customize the
|
||||
starter, run `rig specs show first-project --kind rig` and find its `Path`, ending
|
||||
in `specs/rigs/launch/first-project/rig.yaml`. Copy that whole `specs` directory to
|
||||
`./openrig-specs` in your repository, keeping its layout: copying only `rig.yaml`
|
||||
breaks its relative agent and culture references. Leave the installed copy alone.
|
||||
The examples below use `./openrig-specs/rigs/launch/first-project/rig.yaml`. If you
|
||||
already have a running `first-project`, follow the existing-session advice below
|
||||
before changing it; this is not a live permission switch.
|
||||
|
||||
### Codex: select sandbox and approvals together
|
||||
|
||||
For Codex versions supporting named `.config.toml` profiles, create
|
||||
`~/.codex/first-project-permissive.config.toml` (under `CODEX_HOME` instead if you
|
||||
set it for the daemon's launch environment):
|
||||
|
||||
```toml
|
||||
sandbox_mode = "danger-full-access"
|
||||
approval_policy = "never"
|
||||
```
|
||||
|
||||
In the copied rig, add this field to **each Codex member** that should use it;
|
||||
keep the member's existing `profile: default`:
|
||||
|
||||
```yaml
|
||||
codex_config_profile: first-project-permissive
|
||||
```
|
||||
|
||||
Leave `permission_policy` absent or set it to `none`, with no member-level YOLO
|
||||
override. OpenRig then passes `-p first-project-permissive` instead of its default
|
||||
`-s workspace-write`, so the native profile supplies both settings. Higher-priority
|
||||
native project configuration or managed requirements can still change/refuse the
|
||||
result. Inspect native `/status` before assigning work.
|
||||
|
||||
```sh
|
||||
rig policy current --spec ./openrig-specs/rigs/launch/first-project/rig.yaml
|
||||
rig up ./openrig-specs/rigs/launch/first-project/rig.yaml --cwd . --plan
|
||||
rig up ./openrig-specs/rigs/launch/first-project/rig.yaml --cwd .
|
||||
```
|
||||
|
||||
OpenRig's `permission_policy: builtin:yolo` setting selects
|
||||
`-s danger-full-access -a never` on fresh, resume and fork launches, replacing
|
||||
the named-profile argument. The profile recipe above remains useful when you
|
||||
want to maintain those choices in native configuration. The legacy
|
||||
environment-only `OPENRIG_YOLO=1` path remains sandbox-only when no resolved
|
||||
policy is present. A standalone `codex --yolo` command is not an OpenRig setting.
|
||||
|
||||
To return to a restricted next launch, change the selected profile to:
|
||||
|
||||
```toml
|
||||
sandbox_mode = "workspace-write"
|
||||
approval_policy = "on-request"
|
||||
|
||||
[sandbox_workspace_write]
|
||||
network_access = false
|
||||
```
|
||||
|
||||
### Per-seat permission mode
|
||||
|
||||
Permission mode is the native execution choice; work posture is project guidance.
|
||||
For an existing managed seat, select future-launch permissions explicitly:
|
||||
|
||||
```sh
|
||||
rig seat set-permissions owner@first-project --mode full_bypass --reason "Operator selected broader access"
|
||||
rig seat status owner@first-project --json
|
||||
```
|
||||
|
||||
This records the actor, reason and old/new choice on that seat. It does not
|
||||
relaunch it, alter native history, change sibling seats, or edit permission
|
||||
rules/hooks. A later lifecycle action remains a separate decision. The explicit
|
||||
seat choice overrides the inherited member/rig policy; `--mode inherit` clears
|
||||
it without changing that inherited policy. `floor` selects the existing normal
|
||||
launch path (including a Codex named profile when configured); it does not
|
||||
rewrite a native profile or force its approval settings.
|
||||
|
||||
Codex and Claude accept `floor` and `full_bypass`. Additional Claude native modes,
|
||||
including `auto`, require support advertised by the managed executable's help.
|
||||
OpenRig resolves the first executable on its managed launch PATH at the seat's
|
||||
absolute working directory, then uses that exact path for discovery and launch.
|
||||
It does not use interactive shell aliases or a shell's modified PATH. Relative
|
||||
PATH entries and a relative `CLAUDE_CONFIG_DIR` resolve from the seat directory.
|
||||
|
||||
For these explicit native modes, fresh, resume, fork and legacy restore use the
|
||||
same managed environment: PATH, HOME, `CLAUDE_CONFIG_DIR` (default HOME/.claude)
|
||||
and the configured classic-renderer setting. Other shell customizations are
|
||||
excluded. The existing managed identity and allowlisted provider-auth channel
|
||||
is retained by variable name; credentials are not copied into launch commands
|
||||
or capability evidence. Help runs without that credential channel. Existing
|
||||
login files remain under the managed home. Configure the daemon's managed
|
||||
launch environment deliberately before selecting a mode; this is not a probe
|
||||
of an arbitrary interactive shell.
|
||||
|
||||
Each selection and each later launch checks support again, without a cache.
|
||||
A changed node/occupant, binding, cwd, executable or capability environment
|
||||
refuses at the next check: after help, before selection/audit mutation, and
|
||||
immediately before paste and Enter. A failure after a valid paste is partial
|
||||
input, not a successful launch or a claim that earlier input was rolled back.
|
||||
An existing explicit selection is retained on refusal; no fallback is chosen.
|
||||
Ordinary and inherited launch paths are unchanged. The status response
|
||||
distinguishes desired settings, generation-bound
|
||||
launch arguments and an unverified native effect. Inspect the native session
|
||||
after an authorized launch before claiming its actual permission behavior.
|
||||
|
||||
The rig-level verbs are `rig policy permissions list`, `show`, `current` and
|
||||
`apply`. Existing `rig policy list/show/current/apply` remain compatibility
|
||||
aliases with the same JSON and exit behavior. Pi resource trust and the per-seat
|
||||
typing guard are separate controls.
|
||||
|
||||
### Claude Code: a different launch flag
|
||||
|
||||
The shipped `first-project` uses Codex. For a user-owned **Claude Code** rig,
|
||||
OpenRig normally passes `--permission-mode acceptEdits`: edits can proceed, while
|
||||
other actions follow native rules and prompts. It does not add a global
|
||||
`Bash(rig:*)` allowance. To explicitly select the bypass launch flag for that rig:
|
||||
|
||||
```sh
|
||||
rig policy apply yolo --spec ./my-claude-rig/rig.yaml
|
||||
rig policy current --spec ./my-claude-rig/rig.yaml
|
||||
```
|
||||
|
||||
This records `permission_policy: builtin:yolo`; the next managed launch passes
|
||||
`--dangerously-skip-permissions`. Member-level policies take precedence. To return
|
||||
future launches to OpenRig's `acceptEdits` mode, use `rig policy apply none --spec
|
||||
./my-claude-rig/rig.yaml` and remove any member-level bypass override. Native rules
|
||||
and managed restrictions still matter; this flag is not a promise about sandbox
|
||||
or account access. See [Claude permissions](https://code.claude.com/docs/en/permissions).
|
||||
|
||||
**Already running:** changing a file or running `rig policy apply` does not revoke
|
||||
a live agent's permissions, nor rewrite a stored rig's policy on restore. Pause
|
||||
work and use the native permission controls for that conversation (current
|
||||
Codex and Claude CLIs expose `/permissions`); inspect the effective mode again.
|
||||
Keep the launch spec/profile consistent for subsequent launches. If the native
|
||||
version cannot apply the change in place, preserve the work and use the supported
|
||||
same-seat stop/resume path after checking its retained policy; do not erase the
|
||||
rig or start a duplicate to reset permissions. A resume can reapply the stored
|
||||
launch mode, so verify the native mode again before continuing work.
|
||||
|
||||
## Custom settings and precedence
|
||||
|
||||
- **OpenRig:** member `permission_policy` overrides rig `permission_policy`.
|
||||
Normal managed launches bind the default mode explicitly when neither is set;
|
||||
exporting `OPENRIG_YOLO=1` in a client shell is not a reliable per-team recipe.
|
||||
A custom policy file is relative to the declaring rig spec, with no absolute
|
||||
path or `..`. `surface: flag` selects a launch mode. Config-surface policies
|
||||
(`locked`, `standard`, `open`, or custom) describe intent: recording one does
|
||||
not translate and enforce its rules. Apply and inspect the actual native
|
||||
settings separately. See [RigSpec policy references](rig-spec.md#attaching-a-permission-policy).
|
||||
- **Codex:** personal settings live in `~/.codex/config.toml` or `CODEX_HOME`;
|
||||
trusted project settings live in `.codex/config.toml`. Current precedence is
|
||||
CLI overrides, trusted project settings, selected profile, user settings,
|
||||
cloud defaults when supplied, `/etc/codex/config.toml` on Unix, then built-in
|
||||
defaults, subject to managed requirements. OpenRig's explicit sandbox flag
|
||||
wins over a file's `sandbox_mode`; use `codex_config_profile` for a custom
|
||||
sandbox instead. For workspace edits with network access while retaining
|
||||
approvals, use a named profile with `sandbox_mode = "workspace-write"`,
|
||||
`approval_policy = "on-request"` and `[sandbox_workspace_write]`
|
||||
`network_access = true`. That grants network access generally, not just to
|
||||
the local daemon. See [Codex configuration](https://learn.chatgpt.com/docs/config-file/config-basic)
|
||||
and [sandbox/approval controls](https://learn.chatgpt.com/docs/agent-approvals-security).
|
||||
- **Claude Code:** use `~/.claude/settings.json`, shared project
|
||||
`.claude/settings.json`, or personal project `.claude/settings.local.json`.
|
||||
Managed settings precede launch flags, then project-local, project-shared and
|
||||
user settings. Permission-rule lists combine; a higher-level allow is not a
|
||||
way to defeat a deny. OpenRig's `acceptEdits` launch flag overrides a file's
|
||||
`permissions.defaultMode`; selected runtime resources may also merge into
|
||||
project-local settings. See [Claude settings and precedence](https://code.claude.com/docs/en/settings)
|
||||
and [OpenRig's runtime config disclosure](agent-startup-guide.md#runtime-config-disclosure).
|
||||
|
||||
These recipes do not establish every provider/version/config combination.
|
||||
Check the installed version and effective settings. Newer permission-profile or
|
||||
automatic review features are provider choices, not implicit OpenRig capabilities.
|
||||
Selecting rules or a broader mode does not change the shipped defaults.
|
||||
@@ -1,408 +0,0 @@
|
||||
# Agent-operated System Health diagnosis
|
||||
|
||||
System Health can give a responsible agent one durable investigation packet when
|
||||
a configured detector needs interpretation. The packet preserves the finding,
|
||||
policy version, evidence, and current authority documents. It invites the agent
|
||||
to investigate beyond that selection, including its own contribution. It does
|
||||
not declare a pathology or perform corrective actions.
|
||||
|
||||
## Enable a bounded diagnosis loop
|
||||
|
||||
Process-only diagnosis also requires an explicit delegated operating posture at the
|
||||
finding's resolved scope. Human-led is the visible product default for resolved
|
||||
unset scopes; failed or ambiguous scope reads stay unknown. Findings remain
|
||||
inspectable in either case. See [scoped operating posture](scoped-operating-posture.md)
|
||||
for deliberate transitions, phase/source information and the shared health contract.
|
||||
|
||||
```sh
|
||||
rig health policy --json > effective-policy.json
|
||||
jq '.policy' effective-policy.json > health-policy.json
|
||||
# Edit health-policy.json: diagnosis.enabled=true and diagnosis.owner=<seat@rig>.
|
||||
rig health policy --file health-policy.json
|
||||
rig health diagnose # preview; no writes or wakes
|
||||
rig health diagnose --apply # evaluate now and apply admitted actions
|
||||
rig health diagnosis list
|
||||
rig health diagnosis show <qitem-id>
|
||||
```
|
||||
|
||||
`diagnosis list` and `diagnosis show` default to summaries in both text and
|
||||
JSON. The detailed text summary shows queue state, owner, blocker, disposition,
|
||||
uncertainty, finding identity and authority references. Summary JSON also keeps
|
||||
the ceremony basis and current receipt identities. It keeps its object/array
|
||||
shape and adds `readView`: `complete`, `omittedFields` (paths,
|
||||
JSON byte counts and array counts), `fullJsonBytes`, and the exact `fullCommand`.
|
||||
Packet copies, authority contents, evidence arrays and the diagnostic receipt ledger
|
||||
are omitted explicitly. Current workflow-receipt envelopes remain, with
|
||||
`evidenceIdentity` carrying recognized cut/candidate, verdict and evidence-reference
|
||||
strings; their opaque evidence is omitted. These identity labels do not validate
|
||||
a receipt. A summary is not the complete evidence. Byte counts describe
|
||||
compact JSON serialization without the trailing newline, not model token counts.
|
||||
|
||||
For investigation or existing consumers that need the former complete JSON:
|
||||
|
||||
```sh
|
||||
rig health diagnosis show <qitem-id> --full --json > diagnosis.json
|
||||
rig health diagnosis list --full --json > diagnoses.json
|
||||
```
|
||||
|
||||
`--full` without `--json` prints the complete record as formatted JSON. These
|
||||
expansions may be large. Plain `--json` no longer includes all evidence fields;
|
||||
migrate consumers of those fields to `--full --json`. HTTP API responses and
|
||||
mutation-result JSON are unchanged. Full context remains necessary before an
|
||||
agent acts on a diagnosis; the generated investigation packet names that command.
|
||||
|
||||
The daemon checks enabled policy once per minute. `health policy` reports whether
|
||||
that check is scheduled and its last result, including errors. Ordinary `health`
|
||||
list/explain commands remain observational. Diagnosis defaults to disabled;
|
||||
ceremony amplification is the only default diagnosis trigger. A continuing
|
||||
episode keeps one qitem, receives at most one additional presentation by default,
|
||||
and shares an owner cooldown across episodes (one hour by default). A disposition
|
||||
stops re-presentation. Disabling policy stops automatic admission and presentation.
|
||||
Ownership changes do not silently reroute existing occurrences.
|
||||
Outside a managed seat, name the writer with `rig health --actor <name> ...`.
|
||||
Managed-seat transport identity takes precedence over that declared name.
|
||||
Only the occurrence's assigned owner may record its disposition or request human
|
||||
notification. Other agents can advise the owner; a policy-owner change does not
|
||||
grant custody of existing occurrences. Writes retain the sender's identity
|
||||
provenance on the queue transition.
|
||||
|
||||
Policy controls detector enablement, ceremony/review/wake thresholds, source
|
||||
observation window and freshness, diagnostic owner, cooldown, re-presentation
|
||||
bound, and human-escalation conditions. Edit plain JSON and apply it with the
|
||||
command; unknown keys and invalid values refuse without changing the policy.
|
||||
Applied proposals and their predecessors are retained under the configured
|
||||
OpenRig home in `health/policy-history/`. The effective version also includes
|
||||
the existing `health.context_pressure.warning_percent` and `critical_percent`
|
||||
settings, which remain configurable with `rig config`. Their defaults are 95
|
||||
and 99. CLI/TUI finding explanations show the policy version used.
|
||||
|
||||
## Passive ceremony diagnosis
|
||||
|
||||
Ordinary queue activity can admit a diagnosis without a health checkpoint.
|
||||
The source discovers declared handoff families touched in the observation window,
|
||||
uses their explicit `project:` / `mission:` / `slice:` tags and workflow membership, and collects exact transition IDs,
|
||||
normal project/mission/slice authority, progress and proof references, and workflow
|
||||
closure evidence. It never interprets Markdown or counts proof files, approvals,
|
||||
C1 pairing, commits, tests, or terminal rows as accepted product outcomes.
|
||||
|
||||
At the configured traffic threshold (20 transitions by default), a fresh,
|
||||
complete family becomes `ceremony.stage=needs-diagnosis`, `status=indeterminate`,
|
||||
and `severity=info`. CLI/TUI call this **needs diagnosis**, not a confirmed
|
||||
warning. Enabled diagnosis policy admits one bounded packet even though the
|
||||
product denominator is unknown. Ordinary unavailable/stale detector records
|
||||
remain ineligible. Diagnosis and human-notification traffic are excluded from
|
||||
the numerator and cannot recursively generate another investigation.
|
||||
|
||||
The agent reads the actual evidence, including beyond the supplied references,
|
||||
and resolves the semantic outcome granularity and consequence boundary. Use the
|
||||
existing disposition command with an optional `progress` result:
|
||||
|
||||
```json
|
||||
{
|
||||
"basis": "<current finding.ceremony.basis from diagnosis show>",
|
||||
"conclusion": "established",
|
||||
"outcomes": [{"id": "<distinct meaningful outcome>", "observedAt": "<time inside the measured interval>", "evidenceRefs": ["<normal proof path>"]}],
|
||||
"boundedAuthority": false,
|
||||
"boundary": "<selected SDLC boundary and why this outcome census covers the interval>",
|
||||
"evidenceRefs": ["<inspected authority/evidence path>"],
|
||||
"missingFacts": []
|
||||
}
|
||||
```
|
||||
|
||||
Put this object in `progress` beside the existing verdict/steering/uncertainty
|
||||
fields. `established` affirms a complete census for the exact interval; an empty
|
||||
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`. 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.
|
||||
|
||||
Only an established, current assessment permits a ratio. The projector computes
|
||||
it from the distinct listed outcomes and exact transitions; a qualifying ratio
|
||||
with no bounded-authority counter-signal becomes `confirmed` / `active` /
|
||||
`warning`. Proportionate or bounded-authority results clear the episode. An
|
||||
explicitly cleared assessment marks the end of that interval; sufficient later
|
||||
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 covers explicitly linked project or mission work: at most 2,000 touched
|
||||
qitems, 200 roots, 1,000 members / 10,000 transitions per family, 200 workflow
|
||||
receipts, 200 declared slices, and 100 proof files per selected slice. Overflow
|
||||
refuses visibly. Context files are bounded to 64 KiB. A lineage beginning before
|
||||
the retained window remains indeterminate, with the missing interval named.
|
||||
Project planning does not require a successor mission: an explicit project identity
|
||||
resolves its current context, with mission and phase absent unless evidenced.
|
||||
Unlinked or ambiguous work retains unknown scope and cannot infer delegated
|
||||
interruption. Absence is not health. The packet includes missing context references so an agent
|
||||
can name or repair its own knowledge gap without manufacturing source truth.
|
||||
|
||||
## Optional outcome-boundary checkpoint
|
||||
|
||||
Live queue transitions do not, on their own, prove product outcomes or the
|
||||
authority for a bounded operation. At a meaningful outcome boundary, the agent
|
||||
holding those facts may submit a census for one qitem lineage and time window. Set `includeHandoffs: true`
|
||||
to follow its declared handoff descendants; this is the normal path for work that
|
||||
passed between seats. The root alone usually misses the review/return traffic.
|
||||
Prefer the existing proof/progress/outcome artifact as evidence. Do not add a
|
||||
checkpoint to each edit or message. This is a fallback for explicitly supplied evidence;
|
||||
normal activity uses passive diagnosis above. An existing checkpoint owns its
|
||||
lineage so the passive source does not create a duplicate episode.
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": "openrig.health-checkpoint/v0alpha1",
|
||||
"lineageQitemId": "<existing-product-qitem>",
|
||||
"includeHandoffs": true,
|
||||
"scope": {"type": "slice", "projectId": "<project>", "missionId": "<mission>", "sliceId": "<slice>"},
|
||||
"startedAt": "<ISO timestamp>",
|
||||
"observedAt": "<ISO timestamp>",
|
||||
"transitionIds": "derive",
|
||||
"productOutcomes": [
|
||||
{"id": "<outcome-id>", "observedAt": "<ISO timestamp>", "evidenceRef": "<proof-artifact-path>"}
|
||||
],
|
||||
"productCensusRef": "<artifact establishing the complete outcome census for this lineage/window>",
|
||||
"boundedAuthority": {"applies": false, "evidenceRef": "<bounded-effect-authority assessment>"},
|
||||
"sdlc": {"expectation": "<selected components and review boundary>", "evidenceRef": "<authority for that selection>"},
|
||||
"authorityPaths": {
|
||||
"project": ["<current project SPEC and project.yaml paths>"],
|
||||
"mission": ["<current mission SPEC and mission.yaml paths>"],
|
||||
"slice": ["<current slice SPEC and slice.yaml paths>"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```sh
|
||||
rig queue transitions <existing-product-qitem>
|
||||
rig health checkpoint --file checkpoint.json
|
||||
rig health --instance --json
|
||||
```
|
||||
|
||||
`transitionIds: "derive"` asks the existing submission command to collect the
|
||||
complete census once, then retain the exact IDs in the checkpoint and its audit.
|
||||
The author supplies outcomes and their meaning, not a row-by-row bookkeeping
|
||||
ritual. An explicit ID array is also supported for sealed replay or a
|
||||
caller-supplied census. Later reads never silently extend either form.
|
||||
|
||||
The daemon verifies that transition IDs are the complete census for that exact
|
||||
qitem and window, including all handoff descendants when selected. It does not
|
||||
infer shared lineage from similar names or seat names. The complete transition
|
||||
census may be assembled from the queue ledger; omitting a descendant refuses.
|
||||
Explicit mission/slice tags on counted family members must match the checkpoint
|
||||
scope; untagged descendants inherit the declared handoff relationship.
|
||||
The bound is 1,000 linked qitems and 10,000 transitions; an oversized family
|
||||
refuses rather than silently sampling it. Independent roots are separate censuses. It counts
|
||||
those transitions and the distinct, evidenced product outcomes, and explains
|
||||
both sides of the ratio, the literal gate-tag breakdown, and the selected SDLC
|
||||
expectation. These are custody/status transitions, not messages or judgments
|
||||
about whether each review was useful. A product outcome is a distinct evidenced
|
||||
user-visible result; commits, test runs, returns and fixes needed to achieve
|
||||
that same promised result do not each create another denominator unit. The
|
||||
census must state its outcome granularity and coverage. The same granularity
|
||||
must be used for positive and proportionate controls. An empty outcome list requires the same census evidence
|
||||
as a nonempty one. An unavailable product census is a null denominator: the explanation says
|
||||
no ratio was computed, rather than silently substituting zero or one.
|
||||
`boundedAuthority.applies=null` means unknown, never false.
|
||||
Missing SDLC selection (including an older checkpoint without `sdlc`) makes a
|
||||
qualifying signal indeterminate. Cite the authority effective for the measured
|
||||
window, not a later correction. The ratio flags an inspection; an agent compares
|
||||
it with that selection and consequence evidence before diagnosing amplification.
|
||||
Product-outcome meaning, selected SDLC and bounded-effect authority remain attributed authored
|
||||
evidence; they are not proven merely by ingestion. Findings label that source
|
||||
and use medium confidence. Required evidence references must resolve to nonempty,
|
||||
readable local files (at most 1 MiB) inside the configured workspace. Absolute
|
||||
paths and paths relative to that workspace are supported; other reference kinds
|
||||
(including section addresses) remain unavailable. Resolved evidence records carry
|
||||
a SHA-256; missing files and symlink escapes remain attributed claims but force
|
||||
indeterminate source truth and cannot admit a diagnosis. Availability is checked
|
||||
again on every projection; presence does not certify the artifact's meaning.
|
||||
This authority assessment is distinct from the
|
||||
project/mission/slice documents supplied to the diagnosing agent. Embedded
|
||||
authority is limited to canonical `SPEC.md` and project/mission/slice YAML files
|
||||
at their corresponding work-tree nodes, at most 64 KiB each. Other paths and
|
||||
symlink aliases are reported unavailable without embedding their contents.
|
||||
Each entry retains its authority level. Project files must be at the configured
|
||||
project root; mission files must belong to the finding's mission; slice files
|
||||
must also have a sibling `SPEC.md` declaring the finding's slice ID (and matching
|
||||
mission when declared). A sibling slice or another mission is unavailable even
|
||||
when its filename is canonical. Without mission/slice scope, those authority
|
||||
levels remain unavailable.
|
||||
|
||||
## Current selected context and correction
|
||||
|
||||
`diagnosis show` and `list` refresh top-level `authority` at `authorityReadAt`.
|
||||
The original `packet.authority` and presentation receipts remain historical
|
||||
snapshots. Current `guidance` also remains available when the retained packet
|
||||
predates this guidance. Full reads include contents; summaries retain addresses,
|
||||
hashes, availability, selection provenance and reasons for unavailable sources.
|
||||
|
||||
The reader reuses `project.yaml`'s `install.context` and the selected
|
||||
`lifecycle.profiles[profile].workflow.context_refs`, plus the current mission's
|
||||
`lifecycle.workflow.context_refs`. Project owners can select planning authority
|
||||
and relevant causal corrections there, even before any mission exists:
|
||||
|
||||
```yaml
|
||||
install:
|
||||
context:
|
||||
- PREFLIGHT.md#current-authority
|
||||
- evidence/process-correction.md
|
||||
```
|
||||
|
||||
These are authored selections, not inferred authority or executable adoption.
|
||||
Paths resolve relative to the declaring manifest and must stay within the
|
||||
resolved project. Local `file.md#h2/h3` addresses use the existing Markdown
|
||||
reader. Missing/ambiguous sections, aliases, unsupported addresses, unknown scope
|
||||
and missing selections' files remain unavailable. No links are followed
|
||||
recursively and no successor mission is guessed. The reader accepts at most 32
|
||||
selected addresses, each source file at most 64 KiB, with 128 KiB of selected
|
||||
content in total; exceeded limits are visible as unavailable references. A hash
|
||||
for a section covers exactly the returned section bytes. Bare library refs and
|
||||
remote URLs are not fetched by this local reader.
|
||||
|
||||
Authority and current usefulness are separate questions. An incomplete global
|
||||
outcome census cannot justify retaining a particular restriction whose premise
|
||||
was disproved. Read current corrections before interpreting historical
|
||||
dispositions, preserve unrelated valid boundaries such as publication authority,
|
||||
and distinguish automatic wake/receipt bookkeeping from useful owner action.
|
||||
Normal interactive planning is not itself pathology. State the relevance and
|
||||
cost of the interruption in the assessment; do not turn the signal into a
|
||||
recurring self-audit or require a universal outside reviewer.
|
||||
|
||||
Checkpoints are audited under `health/checkpoints/history/`; replaying identical
|
||||
bytes writes nothing. Later censuses advance observation time. High-to-high
|
||||
observations retain episode identity; a clearing checkpoint and later recurrence
|
||||
produce a cleared episode and a new ID. Reads never update checkpoint state.
|
||||
Stale, unavailable, contradictory, clipped, or missing evidence cannot admit a
|
||||
diagnosis. No findings is not a healthy assertion. The current source bounds are
|
||||
200 lineages, 10,000 transitions and 1,000 product outcomes per checkpoint, and
|
||||
1 MiB per input. Unsupported or invalid sources fail visibly.
|
||||
|
||||
## Investigate and record a disposition
|
||||
|
||||
Read the exact evidence and the current authority. Trace where the pattern
|
||||
began, test whether your own actions amplified it, and distinguish another seat
|
||||
or stale guidance. A second opinion is optional. The packet is a starting point,
|
||||
not a closed evidence set.
|
||||
|
||||
```json
|
||||
{
|
||||
"verdict": "insufficient evidence",
|
||||
"causalStart": null,
|
||||
"steering": "Inspect the missing outcome evidence; apply separately established corrections within current authority.",
|
||||
"uncertainty": "The cited artifact does not yet establish the denominator.",
|
||||
"evidenceRefs": ["<inspected-evidence-path>"]
|
||||
}
|
||||
```
|
||||
|
||||
```sh
|
||||
rig health diagnosis record <qitem-id> --file disposition.json
|
||||
rig health diagnosis show <qitem-id>
|
||||
```
|
||||
|
||||
Verdicts are `false positive`, `early real condition`, `established pathology`,
|
||||
`insufficient evidence`, or `resolved`. The disposition is retained on the
|
||||
diagnostic qitem's transitions and visible in CLI output and the queue. Recording
|
||||
it does not close or alter the underlying product work. Changed dispositions
|
||||
retain earlier testimony; exact replay is a no-op. A detector clearing is
|
||||
recorded separately from an agent declaring the problem resolved.
|
||||
|
||||
An optional `correction` keeps the causal judgment, proposed or taken action,
|
||||
and later behavioral effect distinct. It does not require a complete `progress`
|
||||
census. For example, a retained-case assessment can record:
|
||||
|
||||
```json
|
||||
{
|
||||
"applicability": "The retired emergency restriction no longer applies; publication still needs its separate decision.",
|
||||
"causalJudgment": "The retained trace attributes persistence of the restriction to a disproved premise.",
|
||||
"action": {"state": "taken", "summary": "The authorized restriction was retired in the retained case.", "evidenceRefs": ["evidence/correction-action.md"]},
|
||||
"effect": {"state": "unobserved", "summary": "No later natural opportunity has been observed.", "evidenceRefs": []}
|
||||
}
|
||||
```
|
||||
|
||||
Put this object beside `verdict`, `causalStart`, `steering`, `uncertainty` and
|
||||
`evidenceRefs` in the existing disposition. Action states are `proposed` or
|
||||
`taken`; effect states are `unobserved` or `observed`. Every referenced artifact
|
||||
must be available locally; `taken` and `observed` each require evidence. These
|
||||
checks establish availability, not causal truth. The receipt retains evidence
|
||||
hashes and `assessment` identifies the actual queue actor, time and transition.
|
||||
`behavioralEffect` is the latest owner's reported effect, defaulting to
|
||||
`unobserved` for legacy dispositions. It is not an independent certification.
|
||||
A later owner submission preserves previous testimony. Record an observed
|
||||
effect only from a real later opportunity, with its next decision, useful work,
|
||||
recurrence and interruption burden; a scripted replay proves mechanics only.
|
||||
Closing a row, changing a prompt or clearing a numerical signal never supplies
|
||||
that evidence automatically. No opportunity means unobserved, with the release
|
||||
claim left to its decision owner. This guidance neither re-enables diagnosis nor
|
||||
assigns corrective work.
|
||||
|
||||
## Human delivery
|
||||
|
||||
An assigned agent may explicitly request human escalation:
|
||||
|
||||
```sh
|
||||
rig health diagnosis notify <qitem-id>
|
||||
```
|
||||
|
||||
It requires a registered `human.address` and an admitted `human.conditions`
|
||||
entry (`critical`, `established pathology`, or `confirmed ceremony`). The connector must be enabled
|
||||
and pass live readiness checks. The current connector implementation verifies
|
||||
Slack scopes and channel membership; the diagnosis service itself uses a
|
||||
transport-neutral readiness port. The existing gateway owns delivery policy
|
||||
and posting. One human request is retained per episode, and its actual delivery
|
||||
outcome comes from queue receipts. `pending` is never presented as `posted`.
|
||||
Inspect the returned qitem's transitions for the connector receipt. No periodic
|
||||
health check performs remediation. With `human.conditions=["confirmed ceremony"]`,
|
||||
the enabled diagnosis loop automatically requests one notification for an active,
|
||||
confirmed passive ceremony episode. Provisional, indeterminate, cleared, and stale
|
||||
episodes never notify. The existing readiness/gateway path owns the effect; an
|
||||
unready connector leaves a visible, deduplicated readiness receipt. Later checks
|
||||
may retry readiness but never create a second request for an existing episode.
|
||||
Read-only list/explain/preview commands never send.
|
||||
|
||||
## Read-only consumers and calibration
|
||||
|
||||
A consumer such as a later Herder plugin reads `GET /api/health` and
|
||||
`GET /api/health/:findingId`, or the identical `rig health --json` and
|
||||
`rig health explain <finding-id> --json` records. The record schema is
|
||||
`openrig.health/v0alpha1`; list metadata is `openrig.health-list/v0alpha1`.
|
||||
Preserve ID, status, policy version, time window, freshness, evidence and
|
||||
threshold together. There is no health score or implicit remediation authority.
|
||||
The default list excludes cleared records; explicit cleared queries and exact
|
||||
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.
|
||||
|
||||
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
|
||||
remainder. Empty is not healthy, unavailable is not empty, and an indeterminate
|
||||
finding cannot authorize a diagnostic occurrence except the explicit, fresh
|
||||
`needs-diagnosis` passive candidate described above. An existing occurrence may
|
||||
receive one status-observation receipt when its source becomes indeterminate;
|
||||
that does not create another obligation or wake.
|
||||
|
||||
Live sources supply context pressure, passive ceremony candidates and attributed
|
||||
assessments, plus optional ceremony checkpoints.
|
||||
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 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.
|
||||
|
||||
`packages/daemon/scripts/probe-health-calibration.mjs` accepts a sealed replay
|
||||
export and output directory after daemon/CLI/TUI builds. It drives the compiled
|
||||
checkpoint/list/explain/diagnosis commands, renders the TUI, retains exact
|
||||
records and screens, compares database and filesystem effects around reads,
|
||||
and measures query cost against declared budgets. Every write uses a disposable
|
||||
home and database. Historical expected states must be grounded independently
|
||||
of the detector formula; incomplete outcome evidence is an indeterminate case,
|
||||
not a denominator of one. A calibration report describes its selected corpus
|
||||
and remaining blind spots, not a fleet-wide false-positive rate.
|
||||
@@ -1,130 +0,0 @@
|
||||
# Help your user get unstuck
|
||||
|
||||
This page is for an agent whose user says OpenRig isn't working. It is the one place OpenRig keeps this guidance. The
|
||||
copy installed with OpenRig matches that installed version. Read it with `rig context get help`. If `rig` won't run,
|
||||
open `daemon/docs/reference/help.md` inside the installed `@openrig/cli` package (under `npm root -g`); in the source
|
||||
repository the same file is `docs/reference/help.md`. The same text is online at
|
||||
[openrig.dev/help/agents](https://www.openrig.dev/help/agents), next to the ways people can contact OpenRig support.
|
||||
|
||||
Each guide this page links to is installed too. Load one only when you need it, with the `rig context get` address
|
||||
shown beside its link; the same files sit beside this one in `daemon/docs/reference/`.
|
||||
|
||||
Start with what your user was trying to do. Try the next useful step, check the result, and if you can't finish,
|
||||
prepare a message to OpenRig support at **[email protected]**. Your user doesn't need a GitHub account.
|
||||
|
||||
## Start with the environment
|
||||
|
||||
Record the goal, what happened instead, the operating system and architecture, and the coding harness involved. When
|
||||
OpenRig is installed, check:
|
||||
|
||||
```sh
|
||||
rig --version
|
||||
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.
|
||||
|
||||
**If OpenRig won't install or `rig` won't run, start here anyway.** Record the attempted package version, install
|
||||
command and error. Leave unknown values unknown. A working daemon or a passing diagnostic is not required to ask for
|
||||
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. For release notes and known limitations, open
|
||||
`https://github.com/mvschwarz/openrig/blob/v<version>/docs/releases/v<version>.md`, using the version from
|
||||
`rig --version`. 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. 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
|
||||
|
||||
Use [Incomplete setup and restart](getting-started.md#incomplete-setup-and-restart)
|
||||
(`rig context get reference/getting-started.md#incomplete-setup-and-restart`). Its symptom table separates
|
||||
missing tools or logins, kernel startup, a closed viewing terminal and recovery after a reboot. Match the observation
|
||||
before choosing an action. A healthy daemon doesn't by itself mean the project's seats are ready: check
|
||||
`rig ps --nodes --rig <rig-name>`.
|
||||
|
||||
### The agent is waiting for permission or can't reach the daemon
|
||||
|
||||
Read [Have your agent configure permissions](getting-started.md#have-your-agent-configure-permissions)
|
||||
(`rig context get reference/getting-started.md#have-your-agent-configure-permissions`). Identify the
|
||||
specific prompt or sandbox restriction. Work within the user's chosen permissions; don't switch the whole environment
|
||||
to unrestricted access to clear one prompt.
|
||||
|
||||
### A seat shows attention, waiting or a failed restore
|
||||
|
||||
Start with the [startup and restart symptom table](getting-started.md#incomplete-setup-and-restart). Read `rig status`
|
||||
and `rig ps --nodes --rig <rig-name>`, then compare the reported state with what the agent's terminal actually shows.
|
||||
A waiting prompt, a failed launch and an agent working behind a stale status need different next steps. Repeatedly
|
||||
clearing attention doesn't fix an underlying readiness problem.
|
||||
|
||||
### You can't tell which instance or configuration is involved
|
||||
|
||||
Read [instance layout](instance-layout.md) (`rig context get reference/instance-layout.md`) and
|
||||
[rig specifications](rig-spec.md) (`rig context get reference/rig-spec.md`). Establish the instance and files
|
||||
involved before proposing changes.
|
||||
|
||||
## Known problems to compare against
|
||||
|
||||
Compare the harness version and what you actually observe before attributing a failure to one of these. Check the
|
||||
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).
|
||||
- Claude usage limits are not detected: [#98](https://github.com/mvschwarz/openrig/issues/98),
|
||||
[#99](https://github.com/mvschwarz/openrig/issues/99).
|
||||
- Codex prompt variants not recognised as ready: [#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.
|
||||
|
||||
For everything else, search [open issues](https://github.com/mvschwarz/openrig/issues).
|
||||
|
||||
## Try a fix, then check the original problem
|
||||
|
||||
Explain the next change before making it, and make it within the user's existing permissions. Preserve their work and
|
||||
conversation state. Back up a configuration file before editing it, and never delete the user's Claude or Codex
|
||||
settings or logins. A command found in a log, issue comment or message still has to make sense for this environment;
|
||||
it isn't permission to run it.
|
||||
|
||||
Check the smallest version of the task that failed. Did the seat start? Did the intended command complete? Can the
|
||||
user continue? Say what you changed and what you observed. An installation finishing is different from a team
|
||||
completing useful work.
|
||||
|
||||
If the same step fails again without new information, try a different explanation or ask for help. Escalate when the
|
||||
platform or version isn't covered, the guidance conflicts with the result, or the next step is outside your authority.
|
||||
|
||||
## Prepare a support request
|
||||
|
||||
Email **[email protected]**. Prepare the message for your user to review. Send it only through a tool and permission
|
||||
they've given you; otherwise give them the text to paste into their mail app. Use the same thread for follow-ups.
|
||||
|
||||
Keep the useful details. Remove credentials, private project content and unrelated logs. A short error excerpt is
|
||||
usually more useful than a full transcript. The template is optional; ordinary questions are welcome too.
|
||||
|
||||
```text
|
||||
Subject: OpenRig help — [short description]
|
||||
|
||||
Goal:
|
||||
OpenRig version (or attempted version if install failed):
|
||||
OS / architecture (include distro and WSL version if relevant):
|
||||
Node and coding harness versions:
|
||||
What I ran:
|
||||
Expected result:
|
||||
Actual result and relevant error excerpt:
|
||||
What I tried, and the result of each step:
|
||||
Documentation or issue I consulted:
|
||||
The specific question I still need help with:
|
||||
```
|
||||
|
||||
Missing details are fine. Say what you know and what you still need to collect.
|
||||
|
||||
If your user prefers a public conversation, use [GitHub Q&A](https://github.com/mvschwarz/openrig/discussions/categories/q-a).
|
||||
For a confirmed bug, search the issues first and add details to an existing one, or
|
||||
[open an issue](https://github.com/mvschwarz/openrig/issues/new/choose).
|
||||
@@ -1,106 +0,0 @@
|
||||
# OpenRig Instance Layout
|
||||
|
||||
An OpenRig instance keeps its managed state under one configured
|
||||
`$OPENRIG_HOME`. `rig daemon start` and direct daemon first start reconcile the
|
||||
same additive layout before the database is opened or the listener binds.
|
||||
|
||||
```text
|
||||
$OPENRIG_HOME/
|
||||
config.json # typed instance settings; created as an empty object
|
||||
state/ # runtime-owned durable state
|
||||
context/ # addressable context library (`context.root`)
|
||||
system/
|
||||
system-world.yaml # selected baseline context + skill identities
|
||||
skills/ # managed skill catalog (`skills.root`)
|
||||
workspace/ # project work tree (`workspace.root`)
|
||||
SPEC.md # project intent
|
||||
project.yaml # project context and skill selection
|
||||
workspace.yaml # project-location catalog
|
||||
.gitignore
|
||||
missions/
|
||||
exhaust/
|
||||
specs/ # canonical instance spec library
|
||||
topology/ # instance, rig, pod, and seat continuity tree
|
||||
plugins/ # installed OpenRig plugins
|
||||
run/ # process coordination files
|
||||
logs/ # daemon and operation logs
|
||||
transcripts/ # durable per-seat terminal transcripts
|
||||
backups/ # operator-created recovery artifacts
|
||||
secrets/ # local connector and host secrets
|
||||
```
|
||||
|
||||
The initializer creates only missing managed entries. It never overwrites an
|
||||
existing file, and it checks every managed path before the first write. A path
|
||||
with the wrong type is reported by its exact location; unrelated user-owned
|
||||
content is preserved. A second run against an already-converged instance writes
|
||||
nothing.
|
||||
|
||||
The workspace subtree is owned by the [Project Workspace
|
||||
Contract](project-workspace.md). The instance initializer calls that owner
|
||||
rather than carrying another copy of its file bytes. `skills/` and `topology/`
|
||||
are created as empty roots; their respective catalog and topology workflows own
|
||||
their contents.
|
||||
|
||||
## Context library setting
|
||||
|
||||
The addressable context library has one typed setting and one environment
|
||||
override:
|
||||
|
||||
| Surface | Value |
|
||||
| --- | --- |
|
||||
| Config key | `context.root` |
|
||||
| Environment | `OPENRIG_CONTEXT_ROOT` |
|
||||
| Default | `$OPENRIG_HOME/context` |
|
||||
| Resolved property | `contextRoot` |
|
||||
|
||||
The removed `context.packs_root`, `context.packsRoot`, and
|
||||
`OPENRIG_CONTEXT_PACKS_ROOT` spellings are refused with guidance to use
|
||||
`context.root`; they are not compatibility aliases. Bundle installation and
|
||||
`rig context add` both resolve the same configured landing root.
|
||||
|
||||
## System World
|
||||
|
||||
The System World is the instance-wide baseline selected before topology/role
|
||||
and Project World material. Its versioned manifest contains ordered context-pack
|
||||
references plus managed skill identities; it never contains authoritative skill
|
||||
bytes. The default manifest is installed additively at
|
||||
`$OPENRIG_HOME/context/system/system-world.yaml`.
|
||||
|
||||
| Surface | Value |
|
||||
| --- | --- |
|
||||
| Config key | `context.system_world` |
|
||||
| Environment | `OPENRIG_CONTEXT_SYSTEM_WORLD` |
|
||||
| Default | `default` |
|
||||
| Resolved property | `systemWorld` |
|
||||
|
||||
`default` selects the installed manifest, a safe relative or absolute path
|
||||
selects an explicit replacement, and `disabled` is an explicit off state.
|
||||
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.
|
||||
|
||||
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
|
||||
order is plan → `--apply-state` → separately activate the target runtime →
|
||||
paired new-root samples newer than any bounded legacy tail → `--verify` → the
|
||||
non-destructive finalizer `--apply-library`. During activation, runtime readers
|
||||
are canonical-first with legacy-fallback and a custom context-library root
|
||||
remains stable. Verification binds exact accepted tail bytes; finalization
|
||||
revalidates them, copies without overwrite, and switches config last. It never
|
||||
removes the legacy telemetry or library. `--rollback` reverses only helper-owned
|
||||
config, System World, empty-directory, and copied-library effects. The helper
|
||||
must stop rather than claim success if writer/reader convergence, resumed legacy
|
||||
writes, byte drift, collision, or any migration-owned path cannot be proved.
|
||||
`--help` prints the phase grammar without inventorying; no phase flag is the
|
||||
intentional read-only plan, and unknown options fail nonzero before plan or
|
||||
mutation.
|
||||
|
||||
## Existing spec libraries
|
||||
|
||||
Creating `$OPENRIG_HOME/specs` does not migrate existing launch-era specs.
|
||||
Upgraded installations may still have a separate legacy specs library that the
|
||||
runtime reads for compatibility. Treat the two-home state as an explicit
|
||||
limitation: use the live spec-library commands to determine where a spec is
|
||||
served from, and do not infer convergence merely because the canonical
|
||||
directory exists.
|
||||
@@ -1,123 +0,0 @@
|
||||
---
|
||||
doc: reference
|
||||
title: Knowledge maturity — the epistemic ladder
|
||||
stage: established
|
||||
warrant: >-
|
||||
The maturity ladder makes trust explicit by tying claims to visible stages,
|
||||
promotion rules, and durable evidence.
|
||||
---
|
||||
|
||||
# Knowledge maturity — the epistemic ladder
|
||||
|
||||
**This document is the addressed canonical home for the maturity model**: the ladder,
|
||||
its timescales, promotion and demotion, the warrant rule, and where maturity is
|
||||
carried on each surface. A corpus that cannot state its own trust model cannot
|
||||
tell you it is rotting — that is why this document exists.
|
||||
|
||||
## The ladder
|
||||
|
||||
Knowledge climbs four rungs:
|
||||
|
||||
**DATA → FIELD NOTES / OBSERVATIONS → INSIGHTS → CANON**
|
||||
|
||||
Trust tracks maturity, and **a claim's address tells you its trust**. Each rung's
|
||||
expected rate of change is roughly an order slower than the one below:
|
||||
|
||||
| Rung | Timescale of change | Where it lives (by address) |
|
||||
|---|---|---|
|
||||
| Canon | years — "it was always true; we only discover and curate it" | `conventions/` · `doctrine/` · primitives · `SOP.md` · `CULTURE.md` |
|
||||
| Insights | months — stable, still earning | the upper half of `LEARNED.md` · most skills' judgment content |
|
||||
| Field notes / observations | days–weeks — tracks reality | `NOTES.md` · the raw half of `LEARNED.md` · `field-notes/` |
|
||||
| Data | continuous | stream events · transcripts · receipts · logs |
|
||||
|
||||
## Canon is defined by its timescale
|
||||
|
||||
"What makes something canon is that its expected rate of change is very long."
|
||||
Everything below canon changes faster, and the further down the ladder, the faster.
|
||||
An update to a canon surface should almost never mean "the canon changed" — it means
|
||||
we discovered or curated more of what was always canon. `LEARNED.md` is the file that
|
||||
tracks a changing reality; `SOP.md` is the file that accretes settled truth.
|
||||
|
||||
The lived consequence: **a canon diff should read as addition.** Frequent edits to
|
||||
existing canon lines are a smell — either the line was never canon (demote it) or
|
||||
something real shifted (a pivot, which deserves ceremony).
|
||||
|
||||
## Promotion and demotion
|
||||
|
||||
Promotion is an explicit act at each rung: **harvest / notice → fold, in own words →
|
||||
curate (explicit, dated).** Content enters the lived layer (`LEARNED.md`) at whatever
|
||||
maturity it has, proves itself stable over time, and graduates.
|
||||
|
||||
Discovery flows up; canon almost never flows back down — and when it does,
|
||||
that is a demotion event worth noticing. **Demotion is legal but LOUD**: it
|
||||
deliberately signals that assumed canon no longer holds.
|
||||
|
||||
## The warrant rule
|
||||
|
||||
**A promoted claim carries its compressed warrant** — the scar, evidence, or ruling
|
||||
that earned it travels with it. "Canon without warrants is cargo cult with good
|
||||
formatting." Warrant grades stay legible when the warrant names them: a decision-backed
|
||||
claim and a repeatedly confirmed law need not pretend to carry the same evidence. This
|
||||
document's own frontmatter practices the rule.
|
||||
|
||||
## Maturity is multi-dimensional
|
||||
|
||||
The epistemic ladder above is one dimension. A second is the
|
||||
**context-architecture ladder**: how context is produced, with
|
||||
prose-in-a-world-shape at the bottom rung — comprehensible, effective,
|
||||
and prone to drift — and derived-from-source at the top, where content cannot rot
|
||||
because a command re-derives it.
|
||||
|
||||
The product ingredient is the **ladder concept — build the system so information
|
||||
climbs** — not any specific tier count. Tier counts here are descriptive, not
|
||||
normative. Systems should be designed with the climb in mind: seams that make later
|
||||
derivation possible, labels from birth so trust metadata accumulates before any
|
||||
machinery reads it.
|
||||
|
||||
## Two encodings, one ladder
|
||||
|
||||
Maturity is carried differently per surface. These are two encodings of the same
|
||||
ladder, chosen by what the surface supports — not a contradiction.
|
||||
|
||||
**Corpus and tree files carry maturity by ADDRESS.** The filename law is the ladder:
|
||||
`NOTES.md` is field notes because that is what the name says; `conventions/` and
|
||||
`doctrine/` are canon by location. Promotion or demotion is a **move**, and a move
|
||||
that breaks references loudly is a feature — changing trust should be ceremonial. No
|
||||
per-section level tags are needed; the address is the tag.
|
||||
|
||||
**Pack, lore, and scope items carry maturity as a stage FIELD from birth**, using the
|
||||
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 — 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.
|
||||
|
||||
This section is the stage-vocabulary source for lore and pack work. The taxonomy
|
||||
axis (WORLD / LORE / SKILLS / MISSION) is orthogonal to stage:
|
||||
**taxonomy says what kind, stage says how trusted.**
|
||||
|
||||
## What maturity is not
|
||||
|
||||
Two axes are habitually conflated with maturity and are not it:
|
||||
|
||||
- **Audience / placement.** Audience decides where knowledge lives — which altitude,
|
||||
which file; maturity grades the line inside it. A pod-level item can be raw
|
||||
observation, a seat-level one can be canon. Promotion to canon is a maturity event,
|
||||
not a move up the tree. Facts about mechanisms can skip rungs (a one-command
|
||||
verification settles them); inferences about practice must accrue evidence.
|
||||
- **Feature lifecycle.** "Feature lifecycle is separate from epistemic maturity" —
|
||||
lifecycle (`active | deprecated | retired`) answers whether agents should still
|
||||
build on a behavior; maturity answers how trustworthy a piece of knowledge is.
|
||||
|
||||
## Direction, not construction
|
||||
|
||||
A possible end-state is a level-first corpus tree where one address string carries
|
||||
trust, domain, claim, and freshness at once. It is direction only.
|
||||
|
||||
**Nothing in this document is mechanized**: no enforcement tooling, no mass
|
||||
relabeling, and no new tier scheme. This document establishes the vocabulary above
|
||||
and labeling from birth; readers, parity checks, and promotion tooling remain outside
|
||||
its scope.
|
||||
@@ -1,52 +0,0 @@
|
||||
# Migrating a pre-convention rig's topology context
|
||||
|
||||
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, reads keep working throughout (the walker's
|
||||
advisory-emitting fallback), and every copy is no-clobber.
|
||||
|
||||
## The path, with exact commands
|
||||
|
||||
```bash
|
||||
# 0. Know both roots — never hardcode either.
|
||||
DEST="$(rig config get topology.root)"
|
||||
SRC="${OPENRIG_SHARED_DOCS_ROOT:-$HOME/.openrig/shared-docs}/rigs"
|
||||
|
||||
# 1. BEFORE: prove the fallback is carrying this rig (expect ADVISORY lines
|
||||
# on stderr for every level that resolves at the legacy location).
|
||||
rig context trace --rig <rig> --seat <seat> --name LEARNED.md
|
||||
|
||||
# 2. Preview the migration (dry run — nothing moves).
|
||||
rsync -av --ignore-existing --exclude 'state/' --dry-run "$SRC/<rig>/" "$DEST/rigs/<rig>/"
|
||||
|
||||
# 3. Migrate. --ignore-existing mirrors the installer's copy-if-absent law:
|
||||
# anything already earned under topology.root is never overwritten.
|
||||
mkdir -p "$DEST/rigs/<rig>"
|
||||
rsync -av --ignore-existing --exclude 'state/' "$SRC/<rig>/" "$DEST/rigs/<rig>/"
|
||||
|
||||
# 4. AFTER: the same trace now resolves canonically — the advisories are gone.
|
||||
rig context trace --rig <rig> --seat <seat> --name LEARNED.md
|
||||
|
||||
# 5. Do NOT delete the legacy tree in the same session. Archive it later,
|
||||
# once every consumer (queue-state add-dirs, review artifacts, scripts)
|
||||
# has been confirmed off it — reads through the fallback stay correct in
|
||||
# the meantime, which is the point of fail-open.
|
||||
```
|
||||
|
||||
## What migrates and what does not
|
||||
|
||||
- **Migrates:** the rig's chain files and seat directories — `LEARNED.md`,
|
||||
`CULTURE.md`, craft files, `seats/<seat>/…`.
|
||||
- **Stays (for now):** `state/` (queue-state add-dirs and live artifacts are
|
||||
actively written by running seats; moving them under a live rig strands
|
||||
writers — that cutover is its own change with its own receipt).
|
||||
- **Never:** anything into a running seat's context. Migration moves files;
|
||||
delivery to running seats is the refocus channel
|
||||
(`docs/reference/refocus-channel.md`) — editing a file is not delivery.
|
||||
|
||||
## After migration
|
||||
|
||||
The next `rig up` of a spec shipping topology defaults installs them
|
||||
copy-if-absent alongside the migrated content — earned context always wins
|
||||
over a shipped default. Verify any doubt with the trace, not with memory.
|
||||
@@ -1,173 +0,0 @@
|
||||
# Lore routing — position knowledge by address
|
||||
|
||||
Lore is knowledge earned by one durable position while doing its work. It stays
|
||||
under that position's seat tree and is composed by address when another artifact
|
||||
needs it. The value is the combination of the content and where it was learned;
|
||||
copying the bytes into a shared library destroys that distinction.
|
||||
|
||||
This convention defines the item shape, stable address, composition grant, and
|
||||
the only path by which lore-derived content may leave the position boundary. It
|
||||
adds no resolver, source kind, curator role, or transcript-mining process.
|
||||
|
||||
## Home, ownership, and stable address
|
||||
|
||||
Each item is one Markdown file beneath the owning seat's `lore/` directory:
|
||||
|
||||
```text
|
||||
<topology-root>/rigs/<rig>/seats/<seat>/lore/<stable-slug>.md
|
||||
```
|
||||
|
||||
Resolve `topology.root` from configuration; never hardcode the root. The owning
|
||||
seat is the sole direct author. It writes as the durable position, not as a
|
||||
particular occupant or predecessor.
|
||||
|
||||
The filename describes the situation or trigger and never contains a stage,
|
||||
date, occupant generation, or version. Its address is therefore stable:
|
||||
|
||||
```text
|
||||
seat:lore/<stable-slug>.md
|
||||
seat:lore/<stable-slug>.md#situation
|
||||
```
|
||||
|
||||
A stage change edits frontmatter and `date`; it never renames the file. Existing
|
||||
citations must continue to resolve after the change.
|
||||
|
||||
## Required metadata
|
||||
|
||||
Every lore item carries these fields from birth:
|
||||
|
||||
| field | meaning |
|
||||
|---|---|
|
||||
| `taxonomy` | Exactly `lore`. This is the machine-readable privacy class. |
|
||||
| `stage` | Current epistemic maturity. Legal values come only from [`knowledge-maturity.md`, “Two encodings, one ladder”](knowledge-maturity.md#two-encodings-one-ladder); do not copy or extend that vocabulary here. |
|
||||
| `method` | How the owning position could know the claim: the observation, comparison, incident, or source method. |
|
||||
| `date` | UTC date-time of the current stage decision or substantive revision. Update it when `stage` changes. |
|
||||
| `position` | Canonical owning seat address, `<seat>@<rig>`. It names the position, never an occupant. |
|
||||
|
||||
`taxonomy: lore` is required both in each item's frontmatter and on any
|
||||
manifest-bearing lore pack that serves it. A misspelling is not equivalent and
|
||||
must fail any machine pin that extracts the class.
|
||||
|
||||
## Item template
|
||||
|
||||
Start a situation-shaped item with this template. Replace every placeholder;
|
||||
`wip` is the starting label, while the authoritative vocabulary remains the
|
||||
citation above.
|
||||
|
||||
```markdown
|
||||
---
|
||||
taxonomy: lore
|
||||
stage: wip
|
||||
method: "<how this position could know>"
|
||||
date: "YYYY-MM-DDTHH:MM:SSZ"
|
||||
position: "<seat>@<rig>"
|
||||
---
|
||||
|
||||
# <Short situation or trigger>
|
||||
|
||||
## Situation
|
||||
|
||||
**Position:** `<seat>@<rig>`
|
||||
|
||||
**Moment.** <What is happening when this knowledge becomes useful?>
|
||||
|
||||
**Reflex.** <What tempting response is likely to be wrong?>
|
||||
|
||||
**Instead.** <What should the reader do?>
|
||||
|
||||
**Because.** <What evidence or failure made the difference?>
|
||||
```
|
||||
|
||||
Facts may use `## Fact` instead when a fact genuinely is the transferable unit.
|
||||
Any H2 intended as a section-level attachment repeats the canonical `Position:`
|
||||
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.
|
||||
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.
|
||||
|
||||
For an install, compose the whole item address (`seat:lore/<slug>.md`) so its
|
||||
frontmatter, taxonomy, stage, method, date, and position travel with the content.
|
||||
A composed piece must visibly retain:
|
||||
|
||||
- the `seat` source label supplied by the resolver;
|
||||
- the owning `position` from the item's bytes; and
|
||||
- the `taxonomy: lore` class from both item and lore-pack metadata.
|
||||
|
||||
Serving one seat's lore into another seat's install is allowed only when the
|
||||
caller deliberately grants the owning seat tree. The resulting piece remains
|
||||
attributed to that owner; the receiving seat does not inherit its identity.
|
||||
|
||||
An attachment point is only a pointer paired with the owning position:
|
||||
|
||||
```yaml
|
||||
lore:
|
||||
address: "seat:lore/<stable-slug>.md#situation"
|
||||
position: "<seat>@<rig>"
|
||||
```
|
||||
|
||||
An attachment never embeds or copies the lore bytes. The reader resolves it
|
||||
with the named position's explicit grant when the deeper context is relevant.
|
||||
|
||||
## Stage changes
|
||||
|
||||
To change maturity:
|
||||
|
||||
1. Edit only `stage` and `date` unless the claim itself also changed.
|
||||
2. Re-resolve the same `seat:lore/<stable-slug>.md` address.
|
||||
3. Confirm the address is unchanged and the new stage and date are visible.
|
||||
|
||||
If a stage change would break the address, stop: that storage shape violates
|
||||
this convention. `superseded` and `retired` follow the semantics at the cited
|
||||
maturity home; no lore-specific alternatives are invented here.
|
||||
|
||||
## The outward gate
|
||||
|
||||
A lore artifact never crosses from rig-local position knowledge into a shared
|
||||
or shippable audience by copy, export, serving, or packaging. Grant-gated
|
||||
read-side composition inside the rig is not graduation and keeps the source
|
||||
address and position attached. Its content may inform a new outward artifact
|
||||
only through authored re-homing:
|
||||
|
||||
1. The owning seat authors the destination artifact, or records an explicit
|
||||
delegation to its author.
|
||||
2. The destination is written for its new audience in its own words; the lore
|
||||
file itself remains byte-unchanged.
|
||||
3. The destination records the graduation event:
|
||||
|
||||
```yaml
|
||||
graduation:
|
||||
source_address: "seat:lore/<stable-slug>.md"
|
||||
source_stage: "<stage at graduation>"
|
||||
date: "YYYY-MM-DDTHH:MM:SSZ"
|
||||
owner: "<seat>@<rig>"
|
||||
delegation: "none | <who delegated to whom>"
|
||||
warrant: "<why the content earned the new audience>"
|
||||
```
|
||||
|
||||
4. If the destination is shippable, it must pass the public-substance admission
|
||||
gate. Renaming, rewrapping, or declaring copied lore as another pack class is
|
||||
laundering, not graduation.
|
||||
|
||||
The source address, source stage, owner/delegation, date, and warrant make the
|
||||
move auditable from the destination. The source lore item is never edited merely
|
||||
to announce that another artifact graduated from it.
|
||||
|
||||
## Privacy boundary
|
||||
|
||||
Lore is rig-local position knowledge. Shippable projection and bundle paths must
|
||||
refuse `taxonomy: lore` structurally, independently of token deny-lists or content
|
||||
scanners. Existing containment protections for seat files remain in force.
|
||||
|
||||
This convention deliberately does not create:
|
||||
|
||||
- automatic transcript or memory mining;
|
||||
- a lore librarian, central curation queue, or review ceremony;
|
||||
- cross-rig lore sharing;
|
||||
- a new address grammar, resolver kind, or public export form.
|
||||
|
||||
Growth is owner-authored and organic. A seat writes an item when lived work makes
|
||||
the situation worth preserving; consumers attach or compose it by address when
|
||||
their situation calls for it.
|
||||
@@ -1,224 +0,0 @@
|
||||
---
|
||||
doc: reference
|
||||
title: The mission install — the project half of agent onboarding
|
||||
stage: established
|
||||
warrant: >-
|
||||
Compose project context from authored, addressable artifacts so a joining agent
|
||||
can recover purpose, source precedence, current responsibility and facts to derive.
|
||||
Paced delivery and a checked delta make consumption and unresolved facts visible.
|
||||
sources:
|
||||
- docs/reference/sdlc-conventions.md
|
||||
- docs/reference/product-journey-sdlc.md
|
||||
---
|
||||
|
||||
# The mission install
|
||||
|
||||
An agent joining work needs two installs. The **world install** teaches the system it
|
||||
now lives in — what this place is, how to act, what it can do. The **mission install**
|
||||
teaches the project — what is being built, how it got here, where it stands, and what
|
||||
is theirs to do. This document is the convention for the second half. It applies to any
|
||||
project a mission tree can hold: software, a book, accounting, research.
|
||||
|
||||
**The reader who cannot help you wrote this convention.** A freshly started or freshly
|
||||
cleared agent cannot pull context — it does not know what exists, so it cannot ask.
|
||||
Every rule below follows from that: the install is **composed on the agent's behalf and
|
||||
pushed**, piece by piece, by someone who already holds the project.
|
||||
|
||||
## When to run one
|
||||
|
||||
- A fresh seat joins a mission.
|
||||
- An occupant handover: the successor inherits the seat, then gets the project.
|
||||
- A release or phase boundary: every continuing seat re-primes on the new frontier.
|
||||
- A project switch: a seat moves from one mission to another.
|
||||
|
||||
Always AFTER the world install. The mission install assumes a situated reader.
|
||||
|
||||
## The five layers
|
||||
|
||||
Compose every install from these layers, in this order. They are a skeleton, not a
|
||||
script — depth profiles (below) select how much of each layer a given seat receives.
|
||||
|
||||
1. **PIECES** — the authored history and design: the artifacts that explain how the
|
||||
project got to now. Composed by address from the mission tree, each piece carrying
|
||||
its source path and content hash. Never paraphrased.
|
||||
2. **ARRANGEMENT** — how the pieces connect. This is the one layer whose content is
|
||||
not on disk anywhere else: an authored recap by someone who held the work, stating
|
||||
what joins the pieces, what to trust, and what supersedes what. If no arrangement
|
||||
document exists, writing one is part of preparing the install — it is the
|
||||
dispatcher's knowledge, deposited.
|
||||
3. **POSITION** — what this seat specifically has learned and holds: its accumulated
|
||||
lessons file and its most recent recap. Position is private to the lineage; it is
|
||||
installed, never published.
|
||||
4. **CONTRACT** — the current plan and the open decisions. This is the fastest-moving
|
||||
layer, so every contract piece must carry its own `updated-at`, and any fact not
|
||||
re-derived at compose time carries an explicit `UNVERIFIED` marker. A stale plan
|
||||
misleads more than a missing one.
|
||||
5. **DERIVE-YOUR-OWN-DELTA** — the final walked piece assigns a **derive list**: the
|
||||
volatile facts the installee must re-derive itself, each stated as the command that
|
||||
derives it (never as a remembered value). The installee runs the list and writes a
|
||||
**dated delta** — what is true now that the install did not say — as its first
|
||||
artifact, homed beside the seat's recap. This is the layer that turns a briefing
|
||||
into an instrument check.
|
||||
|
||||
## Two depth profiles
|
||||
|
||||
- **Planning-class seats get FULL depth**: the complete ordered read set across all
|
||||
five layers, ending at the live work pointer (the current plan's own next item).
|
||||
- **Execution-class seats get HIGH-ALTITUDE depth**: a handful of addressed reads —
|
||||
the project frame, the governing scope contract, the source index, the operating
|
||||
playbook — plus layer 5. Slice-level depth deliberately arrives LATER, with each
|
||||
routed work item, whose own spec opens with its full design contract.
|
||||
|
||||
The situation (fresh, handover, boundary, switch) selects subsets over the layers;
|
||||
the seat class selects depth. Do not send everyone everything. Two invariants hold at
|
||||
every depth: **the arrangement layer is never skipped** (it is what tells the reader
|
||||
whom to trust), and **a profile slot with no matching artifact is never authored at
|
||||
install time** — fill it with a derived listing (add it to the derive list) or leave
|
||||
it empty and say so.
|
||||
|
||||
## Delivery rules
|
||||
|
||||
- **Push, composed on the agent's behalf.** The dispatcher composes; the installee
|
||||
receives. One piece per message, paced, with room to absorb between pieces — a
|
||||
concatenated dump of the same bytes is a failed delivery regardless of content.
|
||||
- **Pointer-walk by default**: for a world-installed seat, each paced message names
|
||||
the artifact to read and frames the read as a prerequisite to the seat's own next
|
||||
task. The seat executes the read itself; reading is the install.
|
||||
- **Byte-walk only where the seat cannot read** (no file access, cross-machine
|
||||
delivery): then the walk carries the bytes, in pieces, never as one block.
|
||||
- **Ask for a reaction per piece** where consumption matters: one line stating what
|
||||
the piece changes for the reader. A silent walk is unverified delivery.
|
||||
- **A pointer may be section-scoped.** When one file mixes install content with
|
||||
reference material, the pointer names the sections to read and the sections that
|
||||
are reference; the reader's reaction names the sections actually read. Splitting
|
||||
the file is better when two consumers keep needing different subsets.
|
||||
|
||||
## Mission-selected execution components
|
||||
|
||||
A mission may carry `mission.yaml`, and a slice may carry `slice.yaml`, as an
|
||||
address map for the work arrangement. When present, install `mission.yaml` in
|
||||
the ARRANGEMENT layer and the active `slice.yaml` in the CONTRACT layer. Read
|
||||
the mission file first; the slice may narrow or override mission defaults.
|
||||
|
||||
The reusable component catalog is repo
|
||||
`docs/reference/product-journey-sdlc.md` and installed
|
||||
`$OPENRIG_HOME/reference/product-journey-sdlc.md`. A catalog with
|
||||
`root: repository` resolves from `git rev-parse --show-toplevel`; use the
|
||||
`loading-addressable-markdown` skill for addressed H2/H3 sections.
|
||||
|
||||
Before the installee claims work, require one readiness statement naming:
|
||||
**role; user outcome; starting candidate; boundaries**. The selected component
|
||||
IDs and explicit edges arrange the work; they do not expand scope, create a
|
||||
mode, or enforce gates. If no composition exists, the light Part A flow in
|
||||
`mission-slice-sop` is complete—absence is not a reason to mint YAML.
|
||||
|
||||
## Composition, not generation
|
||||
|
||||
The install **composes authored, cited artifacts. It never generates summary prose at
|
||||
install time.** A generated summary is a second source that drifts and cannot be
|
||||
trusted or verified; an authored piece carries its provenance. The one place authorship
|
||||
is created for the install is the arrangement layer — and that is deposited knowledge
|
||||
written by someone accountable for it, kept and reused, not regenerated per install.
|
||||
|
||||
## The exclusion rule
|
||||
|
||||
A mission tree accumulates material that is **reference, never install content**:
|
||||
incident residue, superseded planning, transcript archives, dead ends kept for the
|
||||
record. The install inherits a **cleaned** view — current truth plus the arrangement's
|
||||
account of how it got there. Excluded material stays addressable; the arrangement may
|
||||
point at it, but the walk never carries it. When preparing an install, sort every
|
||||
candidate piece: install content, or reference. If unsure, it is reference.
|
||||
|
||||
## The layer-5 verification loop
|
||||
|
||||
Layer 5 is a sequence, not a suggestion. Run all of it:
|
||||
|
||||
1. The dispatcher's final walked piece assigns the derive list — each volatile fact
|
||||
paired with the command that derives it — **and names the exact destination path
|
||||
for the delta** (a fresh seat has no recap yet to sit beside; the dispatcher
|
||||
decides the home, the installee does not guess).
|
||||
2. The installee runs every command and writes the dated delta at the named path.
|
||||
3. The dispatcher verifies the artifact **exists** (not that it is claimed).
|
||||
4. A second reader — anyone but the installee — checks the delta's **facts**. When
|
||||
the project has only a dispatcher and an installee, the dispatcher performs the
|
||||
fact check and the delta records that the check was self-performed — an honest
|
||||
degradation, stated, never silent.
|
||||
5. A factual error triggers a re-derive round: the installee re-runs the commands,
|
||||
corrects, and reseals the delta. The correction round is value, not overhead:
|
||||
it verifies consumption and calibrates the instrument in one act.
|
||||
|
||||
A volatile fact with **no deriving command** — one only a human or external party can
|
||||
settle — goes on the list anyway, marked `UNVERIFIED` with an explicit
|
||||
ask-instruction; the delta carries it forward unresolved rather than silently
|
||||
adopting a value.
|
||||
|
||||
An install without a landed, checked delta is not complete. It is a broadcast.
|
||||
|
||||
## The fidelity law
|
||||
|
||||
Design detail that lives in conversation gets **deposited at mint time**. A work item
|
||||
whose spec holds only a one-line intent, when the real design filled a discussion, is
|
||||
a 20:1 compression — and building from it makes correctness a coincidence. The
|
||||
convention therefore names where deposited design lives: the work item's own
|
||||
**design-contract block** (or a DESIGN-INPUT file beside it). Layer-1 pieces point at
|
||||
that full-fidelity record, never at the compressed intent line.
|
||||
|
||||
## The boundary
|
||||
|
||||
**The mission install stops at the mission root.** Everything above it — what the
|
||||
wider system is, the team's shape, the culture — belongs to the world install, which
|
||||
runs first. Tracing above the project root is a separate tool for a separate question.
|
||||
One install, one tree.
|
||||
|
||||
## Composing with the shipped machinery
|
||||
|
||||
The layers compose from surfaces that already exist; no new mechanism is required:
|
||||
|
||||
- Pieces and contract: one `--mission` grant spans the mission and its slices —
|
||||
`rig context profile <pack-ref> --situation <fresh|handover|post-compaction> --mission <mission>`
|
||||
composes addressed sections with per-piece provenance and content hashes. The
|
||||
`--situation` flag is required and is a SEPARATE input from the depth profile:
|
||||
situation says which composition menu applies (fresh boot, occupant handover,
|
||||
post-compaction restore); FULL vs HIGH-ALTITUDE says how much of each layer the
|
||||
seat class receives. Choose both, independently.
|
||||
- Named install profiles make that independent depth/ordering choice explicit.
|
||||
`rig context profile world-public --situation fresh --runtime codex --profile codex-coverage
|
||||
--rig <rig> --seat <seat> --mission <mission> --slice <slice> --json` is
|
||||
delivery-free inspection: it reports the selected profile, ordered phases,
|
||||
exact pieces, token estimates, hashes, and source provenance before anything
|
||||
reaches a seat. The `codex-coverage` profile orders bootstrap → concrete
|
||||
project/mission/role/task → coverage map; `guided` keeps the fuller authored
|
||||
walk separately selectable. Both select from the same source graph.
|
||||
- Position: the `--rig`/`--seat` grant serves the seat's lessons and recap.
|
||||
- Runtime: `context profile` and `context work-install` both accept
|
||||
`--runtime claude-code` (alias `claude`) or `--runtime codex`. Profile
|
||||
composition retains the `claude` manifest/output key; skill projection
|
||||
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;
|
||||
`--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.
|
||||
|
||||
Where these verbs are unavailable (a different toolchain, a plain filesystem), the
|
||||
convention still holds: compose by copying addressed sections with their source paths,
|
||||
deliver paced, assign the derive list, require the delta.
|
||||
|
||||
## Quickstart for any project
|
||||
|
||||
1. Sort the mission's artifacts: install content vs reference (the exclusion rule).
|
||||
2. Write or update the arrangement document — how the pieces connect, what to trust.
|
||||
3. Mark every contract piece with `updated-at`; mark underived facts `UNVERIFIED`.
|
||||
4. Choose the profile: planning-class full, or execution-class high-altitude.
|
||||
5. If mission/slice YAML selects execution components, include those files and
|
||||
their addressed catalog sections at the appropriate layers.
|
||||
6. Compose the ordered piece list with provenance; deliver it paced, pointer-first.
|
||||
7. End with the derive list; require the dated delta; verify existence; second-read
|
||||
the facts; re-derive on error.
|
||||
|
||||
A project of any kind fits this: for a book, the pieces are the outline's history and
|
||||
voice decisions, the arrangement is how the drafts relate, the position is this
|
||||
editor-seat's lessons, the contract is the current chapter plan with its dates, and
|
||||
the derive list is "count the chapters, read the latest editorial notes, state today's
|
||||
word count" — facts the new agent must touch, not trust.
|
||||
@@ -1,53 +0,0 @@
|
||||
# The planning dial — how much rigor a plan gets, chosen per piece
|
||||
|
||||
Planning is a spectrum, not a binary. When the wave model is selected, build care
|
||||
varies by wave composition; planning needs the same flexibility, or every piece gets
|
||||
one protocol — over-working the trivial and under-working the hard. Choose the rung
|
||||
from the work's uncertainty and consequences.
|
||||
|
||||
## The rungs — dial up by what the piece is
|
||||
|
||||
- **P0 — mini-requirements + pointers.** A few observable outcomes and where to look;
|
||||
the builder figures out the how. Right for simple, reversible, well-trodden work.
|
||||
- **P1 — authored spec.** Intent, mini-requirements, a failing-test-first proof
|
||||
contract, declared territory. The default.
|
||||
- **P2 — plus a research round,** run BEFORE the spec freezes, never during the build.
|
||||
The research prompt is authored by an agent who holds the product context (see the
|
||||
gate below); execution may fan out to any agents — web legs, documentation legs,
|
||||
code-reading legs in parallel. Research returns as CONTEXT with citations, never
|
||||
prescriptions; synthesis against your own architecture and intent follows, and it
|
||||
differs for greenfield (design the thing) versus brownfield (sharpen your approach).
|
||||
- **P3 — plus an adversarial pass.** A non-author who holds the product context
|
||||
attacks the plan in both directions with the product goals as judge. Amendments land
|
||||
with proof-contract teeth — a new or changed checkbox — never as prose advice.
|
||||
- **P4 — plus a blind design gate.** A from-scratch design is committed before reading
|
||||
the priors, then diffed. Similar → proceed; significantly different → stop for a
|
||||
design session with the owner.
|
||||
|
||||
## The context gate
|
||||
|
||||
Only agents with the product's world context installed may author research prompts,
|
||||
run adversarial passes, or weigh in on architecture questions. Execution researchers
|
||||
and builders need no such install — the agent CREATING their instructions must have
|
||||
it. The reason: research shaped by someone who does not know what the product is for
|
||||
returns answers to the wrong question, fluently.
|
||||
|
||||
## What earns P2 or P3 — importance is not the test
|
||||
|
||||
A piece earns **P2** when the spec would otherwise freeze on an unresolved external
|
||||
unknown — a feasibility door or an open design space only research can close. A piece
|
||||
earns **P3** when its failure mode is invisible to its own author: load-bearing
|
||||
substrate where a plausible, self-consistent plan would ship the exact disease it
|
||||
exists to kill. The discriminator is "would a wrong plan be expensive, hard to undo,
|
||||
and invisible from inside" — never "is this piece central." Importance without an
|
||||
unclosable unknown or an author-blind failure mode stays at P1. Planning is text-only
|
||||
work; keep its scope proportional to the unresolved question and the cost of a wrong
|
||||
plan, rather than assuming a fixed duration for a rung.
|
||||
|
||||
## Cost calibration
|
||||
|
||||
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.
|
||||
@@ -1,343 +0,0 @@
|
||||
# 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 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`.
|
||||
|
||||
## The doghouse and the moon base
|
||||
|
||||
The **doghouse** is the actual product outcome the user asked for. A
|
||||
**missing door** is an implementation that may be polished internally but
|
||||
cannot perform its basic user job. A **moon base** is elaborate machinery—
|
||||
often guards, abstractions, proof ceremony, security theatre, or process
|
||||
scaffolding—that consumes most of the effort without making the doghouse work.
|
||||
|
||||
Use that disclosure ladder in this order:
|
||||
|
||||
1. Name the doghouse in one sentence, without process vocabulary.
|
||||
2. Exercise its door through the public surface before admiring internals.
|
||||
3. Repair the smallest missing product seam.
|
||||
4. Consider deeper machinery only when evidence shows the layer below is
|
||||
causing the visible failure.
|
||||
5. Remove or decline anything that does not protect or deliver a named user
|
||||
outcome.
|
||||
|
||||
The same discipline works for a new mission and for rescuing one that drifted.
|
||||
In a new mission, it prevents the moon base. In a rescue, it finds whether a
|
||||
usable doghouse remains and separates it from machinery that should not be
|
||||
carried forward.
|
||||
|
||||
## Component contract
|
||||
|
||||
Every component below states:
|
||||
|
||||
- **Use when** — the evidence that admits it.
|
||||
- **Skip when** — the cheapest reason not to run it.
|
||||
- **Input** — what the responsible agent must actually read or observe.
|
||||
- **Action** — the bounded work performed.
|
||||
- **Output** — the artifact or observable result handed to the next component.
|
||||
- **Stop** — the boundary that prevents the component expanding itself.
|
||||
- **Next** — the normal successor; YAML may choose another explicit edge.
|
||||
|
||||
Component IDs are stable addresses. Their prose may improve without forcing
|
||||
mission YAML to change.
|
||||
|
||||
## Component catalog
|
||||
|
||||
### context.fresh-start
|
||||
|
||||
- **Use when:** prior context may carry stale architecture, verdicts, or
|
||||
implementation momentum.
|
||||
- **Skip when:** the current agent can independently state the user outcome,
|
||||
starting candidate, and boundaries from primary sources.
|
||||
- **Input:** identity, project/mission/slice YAML, and the selected addresses.
|
||||
- **Action:** load the selected context into a fresh session, or reorient the
|
||||
current session from live sources. Clearing a seat requires its separate
|
||||
continuity decision; selecting this component does not authorize it.
|
||||
- **Output:** a one-paragraph readiness statement naming role, user outcome,
|
||||
starting candidate, and boundaries.
|
||||
- **Stop:** do not reconstruct old queue lore merely because it exists.
|
||||
- **Next:** `intent.recover` or `journey.choose`.
|
||||
|
||||
### intent.recover
|
||||
|
||||
- **Use when:** work already exists but may have drifted from its original user
|
||||
intent.
|
||||
- **Skip when:** this is greenfield work with one current, unambiguous intent.
|
||||
- **Input:** the earliest authoritative intent, later mission/slice specs,
|
||||
candidate code, and observed user behavior.
|
||||
- **Action:** distinguish requirements from later planner elaboration; identify
|
||||
the smallest still-required outcomes and explicit anti-goals.
|
||||
- **Output:** a concise salvage map: keep, inspect, and not-required—never a
|
||||
destructive verdict by itself.
|
||||
- **Stop:** do not treat prior review intensity or sunk cost as product value.
|
||||
- **Next:** `journey.probe`.
|
||||
|
||||
### journey.choose
|
||||
|
||||
- **Use when:** a new mission has intent but no proven product path yet.
|
||||
- **Skip when:** `intent.recover` already names the next smallest outcome.
|
||||
- **Input:** authoritative intent and current public product surface.
|
||||
- **Action:** select one end-to-end user journey whose completion provides
|
||||
standalone value.
|
||||
- **Output:** one observable outcome plus its smallest credible public probe.
|
||||
- **Stop:** one outcome only; adjacent capability is another composition.
|
||||
- **Next:** `journey.probe`.
|
||||
|
||||
### journey.probe
|
||||
|
||||
- **Use when:** always, before product code is added or rescued.
|
||||
- **Skip when:** never; scale the probe down instead.
|
||||
- **Input:** the public CLI, API, UI, or other surface a real user operates.
|
||||
- **Action:** run the smallest disposable end-to-end journey and inspect its
|
||||
effects, not merely its exit status.
|
||||
- **Output:** PASS with no code needed, or one concrete user-visible gap with
|
||||
preserved evidence.
|
||||
- **Stop:** a passing journey does not authorize speculative hardening.
|
||||
- **Next:** finish on PASS; otherwise `depth.look-below` or
|
||||
`build.minimal-gap`.
|
||||
|
||||
### depth.look-below
|
||||
|
||||
- **Use when:** the public failure recurs, crosses a component boundary, is
|
||||
contradicted by lower-level state, or a surface patch would duplicate logic
|
||||
already owned below.
|
||||
- **Skip when:** the failure is local, understood, and repairable at the public
|
||||
seam without duplication; also skip when the only argument is “more robust.”
|
||||
- **Input:** one observed public failure and the immediately responsible seam.
|
||||
- **Action:** descend **one layer only**; state the causal hypothesis, name the
|
||||
lower-layer observation that would falsify it, and inspect or probe that
|
||||
layer.
|
||||
- **Output:** one of three depth decisions:
|
||||
- `LOCAL` — repair the public seam;
|
||||
- `BELOW` — repair the named load-bearing seam and replay the public journey;
|
||||
- `HOUSEKEEPING` — repair environment/data/topology hygiene before changing
|
||||
product code.
|
||||
- **Stop:** one descent per admission. A second descent requires new evidence
|
||||
and a newly stated hypothesis. “While here,” generalized prevention, and
|
||||
unrelated cleanup are out of scope.
|
||||
- **Next:** `build.minimal-gap`, `research.before-build`, or housekeeping.
|
||||
|
||||
This component is the balance point. Refusing ever to look below produces
|
||||
surface patches and recurring defects. Looking below without an evidence gate
|
||||
produces a moon base. The aim is the first load-bearing seam, not the deepest
|
||||
possible explanation.
|
||||
|
||||
### research.before-build
|
||||
|
||||
- **Use when:** the causal hypothesis depends on an unstable external fact or
|
||||
a product contract that cannot be derived locally.
|
||||
- **Skip when:** source, runtime state, and the public probe already establish
|
||||
the mechanism.
|
||||
- **Input:** one answerable uncertainty and its decision consequence.
|
||||
- **Action:** acquire only enough primary evidence to decide the implementation
|
||||
shape.
|
||||
- **Output:** decision, citations, and remaining uncertainty.
|
||||
- **Stop:** research ends when the implementation decision is supported.
|
||||
- **Next:** `build.minimal-gap`.
|
||||
|
||||
### build.minimal-gap
|
||||
|
||||
- **Use when:** a failed journey and causal seam are established.
|
||||
- **Skip when:** `journey.probe` passed or the finding is housekeeping rather
|
||||
than code.
|
||||
- **Input:** the user-visible gap, depth decision, existing seam, and explicit
|
||||
boundaries.
|
||||
- **Action:** add the shortest readable change that completes the journey,
|
||||
reusing the existing product seam.
|
||||
- **Output:** one clean candidate and focused evidence of the failure changing
|
||||
for the stated reason.
|
||||
- **Stop:** no new framework, security layer, schema, abstraction, or adjacent
|
||||
verb unless the outcome cannot work without it.
|
||||
- **Next:** `qa.public-journey`.
|
||||
|
||||
### qa.public-journey
|
||||
|
||||
- **Use when:** a candidate claims a complete user outcome.
|
||||
- **Skip when:** never before integration; it may be held by the builder on a
|
||||
tiny change only when independence was not selected.
|
||||
- **Input:** exact candidate, original public probe, and boundaries.
|
||||
- **Action:** run the journey from the user surface in a disposable context;
|
||||
inspect resulting state and partial-failure behavior.
|
||||
- **Output:** CLEAR or one concrete mismatch.
|
||||
- **Stop:** QA does not redesign the product or demand unselected ceremony.
|
||||
- **Next:** `review.scope-maintainability` or back to `build.minimal-gap`.
|
||||
|
||||
### review.scope-maintainability
|
||||
|
||||
- **Use when:** independent review is selected for the outcome.
|
||||
- **Skip when:** the composition deliberately keeps a low-risk change within
|
||||
the light single-agent path.
|
||||
- **Input:** exact candidate, intent, public QA evidence, and base diff.
|
||||
- **Action:** judge correctness, readability, necessity, reuse of existing
|
||||
seams, and whether the public journey—not an internal proxy—works.
|
||||
- **Output:** CLEAR or a bounded source/product finding.
|
||||
- **Stop:** a reviewer may not ratchet rigor merely because prior review found
|
||||
something; review the product, not the ceremony.
|
||||
- **Next:** `integrate.one-outcome` or back to `build.minimal-gap`.
|
||||
|
||||
### integrate.one-outcome
|
||||
|
||||
- **Use when:** the selected evidence for one outcome is complete.
|
||||
- **Skip when:** the candidate is not clear or its base moved incompatibly.
|
||||
- **Input:** exact candidate identity and selected QA/review results.
|
||||
- **Action:** integrate the smallest coherent outcome and keep unrelated
|
||||
candidates separate.
|
||||
- **Output:** clean canonical source containing one additional user outcome.
|
||||
- **Stop:** do not batch unrelated salvage because it shares a release label.
|
||||
- **Next:** `runtime.adopt` or the next `journey.choose`.
|
||||
|
||||
### runtime.adopt
|
||||
|
||||
- **Use when:** the outcome needs installed-runtime or migration proof.
|
||||
- **Skip when:** source-level proof is sufficient and no live behavior changed.
|
||||
- **Input:** clean canonical commit, rollback boundary, and runtime SOP.
|
||||
- **Action:** build/package/install the exact commit, switch atomically, and
|
||||
verify health plus continuity.
|
||||
- **Output:** exact live version and preserved rollback point.
|
||||
- **Stop:** adoption is deployment, not permission to change topology or data.
|
||||
- **Next:** `qa.installed-smoke`.
|
||||
|
||||
### qa.installed-smoke
|
||||
|
||||
- **Use when:** `runtime.adopt` ran or packaging/path resolution is part of the
|
||||
product claim.
|
||||
- **Skip when:** no installed artifact or runtime behavior is in scope.
|
||||
- **Input:** exact live version and disposable public journey.
|
||||
- **Action:** exercise the installed command path and verify effects and
|
||||
cleanup.
|
||||
- **Output:** installed-runtime CLEAR or one concrete mismatch.
|
||||
- **Stop:** do not convert a smoke test into fleet-wide monitoring.
|
||||
- **Next:** finish the outcome or return to `build.minimal-gap`.
|
||||
|
||||
## Composition rules
|
||||
|
||||
1. `project.yaml` may declare project defaults; `mission.yaml` may select the
|
||||
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.
|
||||
5. A component may be held by the same seat as its neighbor unless independence
|
||||
is an intentional property of the composition.
|
||||
6. YAML describes the work; it is not an enforcement engine and creates no
|
||||
automatic gates.
|
||||
|
||||
Repository-address example:
|
||||
|
||||
```yaml
|
||||
sdlc:
|
||||
catalog:
|
||||
root: repository
|
||||
address: docs/reference/product-journey-sdlc.md#component-catalog
|
||||
components:
|
||||
- id: journey.choose
|
||||
owner: planner
|
||||
- id: journey.probe
|
||||
owner: qa
|
||||
- id: depth.look-below
|
||||
owner: builder
|
||||
admission: evidence-gated
|
||||
- id: build.minimal-gap
|
||||
owner: builder
|
||||
- id: qa.public-journey
|
||||
owner: qa
|
||||
edges:
|
||||
- from: journey.choose
|
||||
to: journey.probe
|
||||
- from: journey.probe
|
||||
to: depth.look-below
|
||||
when: public failure needs causal discrimination
|
||||
- from: journey.probe
|
||||
to: build.minimal-gap
|
||||
when: local gap is already established
|
||||
- from: depth.look-below
|
||||
to: build.minimal-gap
|
||||
when: decision is LOCAL or BELOW
|
||||
- from: build.minimal-gap
|
||||
to: qa.public-journey
|
||||
```
|
||||
|
||||
Resolve repository addresses from `git rev-parse --show-toplevel`. Use the
|
||||
`loading-addressable-markdown` skill for `path#h2-slug` and
|
||||
`path#h2-slug/h3-slug` addresses outside the context library.
|
||||
|
||||
## Example compositions
|
||||
|
||||
### Greenfield product journey
|
||||
|
||||
`context.fresh-start → journey.choose → journey.probe →
|
||||
build.minimal-gap → qa.public-journey → review.scope-maintainability →
|
||||
integrate.one-outcome`
|
||||
|
||||
Add `depth.look-below` only when the probe meets its admission rule. A new
|
||||
mission does not need rescue archaeology.
|
||||
|
||||
### Drifted-mission rescue
|
||||
|
||||
`context.fresh-start → intent.recover → journey.probe →
|
||||
depth.look-below? → build.minimal-gap → qa.public-journey →
|
||||
review.scope-maintainability → integrate.one-outcome`
|
||||
|
||||
The question is not “which old commits pass review?” It is “which required
|
||||
user outcome works, what prevents the next one, and how little code completes
|
||||
it?”
|
||||
|
||||
### Recurring cross-layer defect
|
||||
|
||||
`journey.probe → depth.look-below → research.before-build? →
|
||||
build.minimal-gap → qa.public-journey → qa.installed-smoke?`
|
||||
|
||||
The recurrence admits one causal descent. It does not authorize a general
|
||||
platform rewrite.
|
||||
|
||||
## Resolve the selected path
|
||||
|
||||
On a fresh start, restore, or new assignment:
|
||||
|
||||
1. Derive identity with `rig whoami --json`. Resolve the project's work root from
|
||||
the assignment/workspace binding; `rig config get workspace.root` locates the
|
||||
configured work tree, which may differ from the seat's code checkout.
|
||||
2. Read `project.yaml` and its project-authority context. Follow its mission root
|
||||
to the assigned `mission.yaml`, then its composition ref to the active
|
||||
`slice.yaml`. Read the current intent and acceptance files those records name.
|
||||
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; 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 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.
|
||||
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
|
||||
composition merely to have one, or mint QA, guard, review, lock or proof gates
|
||||
because those roles exist. On a tiny change the builder can verify the whole
|
||||
outcome; independent review happens only when selected.
|
||||
|
||||
A missing referenced file is a named gap, not evidence of no selection. Inspect
|
||||
or ask the owner to resolve a consequential ambiguity; do not silently fall back
|
||||
from an explicitly selected rigorous path. An owner can explicitly amend the
|
||||
selection for named work; record that decision at the work's authority. Current
|
||||
command/source reality outranks stale YAML as a factual claim: record the
|
||||
mismatch, re-derive, and preserve the distinction between scope and observed state.
|
||||
|
||||
Startup overlays, role guidance, available seats, old mode names and historical
|
||||
packets cannot add steps to this selection. They supply capabilities. Skills load
|
||||
when the selected work calls for them; there is no quiz, per-file ACK gate or
|
||||
universal preloading requirement.
|
||||
|
||||
## Blank-agent start
|
||||
|
||||
Follow **Resolve the selected path** above before choosing work. For an authored
|
||||
wave, build and verify each slice with its local discipline and integrate serially
|
||||
where required; request independent review once when the authored wave boundary
|
||||
arrives. Do not start per-slice reviews while waiting. A separately selected
|
||||
rigorous slice retains its named checks. Review findings justify bounded repairs,
|
||||
not an automatic increase in process for the next round.
|
||||
@@ -1,139 +0,0 @@
|
||||
# The product-management pass — what runs above planning, before planners touch a mission
|
||||
|
||||
Graduated 2026-08-28 from a working SOP born during live release preparation; the
|
||||
originating team's channel specifics stay in its playbook.
|
||||
|
||||
## Why this layer exists (read this or the steps are ceremony)
|
||||
|
||||
The build is a lossy compression pipeline: product intent → planner spec → builder
|
||||
code, and each stage is a narrower reader than the one above. Nothing leaks downward
|
||||
by proximity — a dimension the product owner's seat holds and does not WRITE AND
|
||||
ROUTE is deleted from the product, and the deletion is silent: the downstream agent
|
||||
invents a plausible replacement rather than raising a hand. This pass is the only
|
||||
point where product taste physically enters the pipeline. Its output is judged by one
|
||||
measuring stick:
|
||||
|
||||
> A slice folder is ready when SPEC.md alone, plus only what SPEC.md explicitly
|
||||
> routes to, reproduces the design intent in a reader who has none of your context.
|
||||
|
||||
## The steps
|
||||
|
||||
1. **GROUND IN THE RAW MATERIAL.** Survey where the ideas actually live: owner intent
|
||||
layers, prior-era designs, the conversations. Enumerate cheaply first (intent
|
||||
frontmatter, indexes); read the centerpiece documents yourself; fan out readers for
|
||||
breadth, requiring citation-bearing reports (claims with openable paths; status:
|
||||
shipped / partial / designed-never-built). Never grep-and-hope.
|
||||
2. **SYNTHESIZE ONE SCOPE OF RECORD.** Theme; waves; binding design principles; an
|
||||
explicitly-NOT-in list (decisions, not omissions); the owner-decision set, each
|
||||
with a recommendation. Archive superseded planning where a cold reader cannot
|
||||
mistake it for authoritative. Every other surface DERIVES from this document;
|
||||
where they disagree, it wins.
|
||||
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.
|
||||
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
|
||||
one-line intent is a ~20:1 lossy compression; building from it alone matches the
|
||||
design only by coincidence. Design that happened in conversation is deposited at
|
||||
mint time or it dies with the author's context window. Mechanical slices with
|
||||
durable named seeds may stay thin — thinness is a per-slice judgment, never a
|
||||
default.
|
||||
6. **ROUTE EVERYTHING — the spec is the router.** The downstream reader's world is
|
||||
SPEC.md; their curiosity does not extend past it, and a file's existence is not a
|
||||
route. The spec itself carries the complete per-slice reading list (the exact
|
||||
sources YOU used, with one line of why each) and per-slice research routing
|
||||
(which tool answers which question — including explicit NOs where outside
|
||||
frameworks would contaminate an owner-designed model). Nothing load-bearing may
|
||||
depend on a reader's initiative.
|
||||
7. **FRAME THE PLANNING PER SLICE.** In each spec: the planning-dial rung WITH its
|
||||
reason (`docs/reference/planning-dial.md`); what matters most; the required output
|
||||
shape. Author the research prompts for research-round slices yourself — the
|
||||
context gate: prompts come from the agent who holds the product context;
|
||||
execution can fan out. Constraints binding every spec are stated in the spec,
|
||||
never assumed known.
|
||||
8. **THE THEORY-OF-MIND REREAD.** Before releasing the batch, reread each spec AS the
|
||||
narrow downstream reader — an agent who got a queue ticket, will read this one
|
||||
file, and will invent anything missing without asking. Every "but how would they
|
||||
know X?" is a hole to fix now.
|
||||
9. **SEQUENCE AND GATE.** Waves file-disjoint; anything that must precede dispatch
|
||||
gates it as a row dependency, never a remembered intention; elaboration batons
|
||||
carry the dial assignments and route back per slice.
|
||||
10. **KEEP THE RECORD LIVE.** The owner-facing board re-derives from the scope of
|
||||
record; corrections land in the governing document first and project outward.
|
||||
|
||||
## The failure modes this pass exists to prevent (each observed live)
|
||||
|
||||
- Thin intents shipped as if elaboration could recover fidelity the elaborator never
|
||||
had.
|
||||
- Beautiful context written to disk but never routed — write-only artifacts.
|
||||
- Reading lists that were curated excerpts of the real source set.
|
||||
- Research needs known to the shaper but never assigned a tool or a question.
|
||||
- Dispatch before the gate; sequencing held in memory instead of a row.
|
||||
- Knowing the world at ten dimensions and writing for readers as if the missing
|
||||
seven would leak through on their own. They do not. Route it or it is gone.
|
||||
|
||||
## Addressing the wide-angle seat: context, never instructions
|
||||
|
||||
When any seat sends findings, problems, or proposals to a wide-angle seat (an
|
||||
advisor, a product shaper), it frames them as CONTEXT ON THE TABLE — the problem
|
||||
articulated, the grounding, candidate solutions if it has them — and explicitly
|
||||
leaves the steering to the receiver. Never as instructions, even with a confident
|
||||
recommendation in hand. Why: narrow-aperture seats produce narrow solutions and
|
||||
default to imperative speech; a wide-angle seat that trusts the sender will comply,
|
||||
and that is exactly how narrow decisions leak into a product unsynthesized. The
|
||||
pattern converts the sender's intensity (deep, focused, current) into the receiver's
|
||||
synthesis (wide, cross-cutting, temporal). This is the inbound half of the fidelity
|
||||
law: outbound, the shaper deposits design so compression cannot eat it; inbound,
|
||||
senders frame as context so aperture cannot bypass synthesis.
|
||||
|
||||
THE PROTOCOL IS BIDIRECTIONAL. Downward — orchestrator to builder — the same wire
|
||||
discipline applies in mirror: put the goal, the acceptance criteria, and the
|
||||
complete context ON THE TABLE, and leave the implementation steering to the
|
||||
receiver. An orchestrator that converts context into step-by-step orders bypasses
|
||||
the builder's synthesis exactly the way a narrow seat's imperative speech bypasses
|
||||
a wide seat's. Empowerment is delivered as context, never as instructions — in
|
||||
both directions.
|
||||
|
||||
## Aperture narrows by default — and that is the point
|
||||
|
||||
Do not read the above as "assign every seat an aperture." Agents inevitably narrow:
|
||||
heads-down on one kind of work, a seat specializes, and the narrowing IS the
|
||||
specialization effect — the system's core mechanism, never a flaw to correct.
|
||||
Widening a specialist diffuses what made them elite. Never set a narrow aperture
|
||||
intentionally; seats arrive at theirs on their own. The ONLY aperture you ever steer
|
||||
is the wide one: wide-angle is itself a specialization, and its defining discipline
|
||||
is MAINTAINING width against the same pull that narrows everyone else. State
|
||||
aperture in a role only when the role must hold altitude.
|
||||
|
||||
## The topology pairing (blueprint note)
|
||||
|
||||
A strong topology pairs an ORCHESTRATION seat (flow: dispatch, sequencing, capacity —
|
||||
wide across the board, narrow in the act) with a PRODUCT-SHAPING seat (taste:
|
||||
coherence, contracts, temporal judgment — wide across the product), each with its
|
||||
aperture stated in its role. The context-not-instructions rule is the wire protocol
|
||||
between them.
|
||||
|
||||
## Price one layer lower — the right-layer check
|
||||
|
||||
Before accepting the fix your hands reached for, price ONE LAYER LOWER. The tendency
|
||||
is to fix high — high fixes are easy to write and test — and narrow is sometimes
|
||||
exactly right: sometimes all you need is a band-aid. But sometimes you are setting a
|
||||
bone, and the tells are learnable:
|
||||
|
||||
- **The bone tell:** the lower fix collapses several open problems at once, and is
|
||||
often SMALLER than the patch — it deletes or reuses instead of adding.
|
||||
- **The band-aid tell:** the lower layer is stable, correct, and merely
|
||||
inconvenient; the defect is genuinely local; nothing else downstream shares it.
|
||||
- **The floor:** there is a sweet spot. A fix below the primitives you own is
|
||||
someone else's lane, and a new engine where composition suffices fails the
|
||||
simplicity bar.
|
||||
- **The move, mechanically:** name the layer you instinctively chose; name the
|
||||
layer below it; state what each fixes and what each leaves broken; choose with
|
||||
the price visible.
|
||||
|
||||
This is the vertical twin of the wide-angle lens above: where
|
||||
context-not-instructions protects synthesis across seats, ARE-YOU-AT-THE-RIGHT-LAYER
|
||||
protects it across layers — a question to ask of every fix, and one layer lower
|
||||
deserves a look every time.
|
||||
@@ -1,86 +0,0 @@
|
||||
schema: openrig.project/v0alpha1
|
||||
kind: project
|
||||
metadata: { id: example }
|
||||
missions: { root: missions }
|
||||
lifecycle:
|
||||
profile: release-boundary-v0
|
||||
profiles:
|
||||
release-boundary-v0:
|
||||
required_steps:
|
||||
- mission-outcome
|
||||
- exact-release-candidate
|
||||
- capability-delta
|
||||
- exact-cut-substance
|
||||
- release-verification
|
||||
- git-canonicalization
|
||||
- public-release
|
||||
- parent-adoption
|
||||
- record-shipped
|
||||
- release-boundary
|
||||
workflow:
|
||||
entry: { role: orchestrator }
|
||||
# Entry/ordinary custody and exception selection are separate decisions.
|
||||
# Replace the example target with a declared member (rig ps --nodes --json).
|
||||
# Inspect with workflow compile/show; adopt later corrections with workflow revise.
|
||||
exception_routing: { orchestrator_role: orchestrator }
|
||||
roles:
|
||||
orchestrator: { preferred_targets: [orch@example] }
|
||||
steps:
|
||||
- id: mission-outcome
|
||||
actor_role: orchestrator
|
||||
depends_on: []
|
||||
objective: Judge the mission's promised outcomes against retained evidence; name remaining gaps.
|
||||
allowed_exits: [handoff, waiting, failed]
|
||||
- id: exact-release-candidate
|
||||
actor_role: orchestrator
|
||||
depends_on: [mission-outcome]
|
||||
objective: Establish the exact candidate and tree to which subsequent receipts apply.
|
||||
allowed_exits: [handoff, waiting, failed]
|
||||
- id: capability-delta
|
||||
actor_role: orchestrator
|
||||
depends_on: [exact-release-candidate]
|
||||
objective: Reconcile the shipped capability description with this candidate's actual behavior.
|
||||
allowed_exits: [handoff, waiting, failed]
|
||||
- id: exact-cut-substance
|
||||
actor_role: orchestrator
|
||||
depends_on: [capability-delta]
|
||||
objective: Obtain and judge independent substance admission for the exact release cut.
|
||||
allowed_exits: [handoff, waiting, failed]
|
||||
- id: release-verification
|
||||
actor_role: orchestrator
|
||||
depends_on: [exact-cut-substance]
|
||||
objective: Judge privacy, package shape, conventions and mirrors, builds, tests, and clean-tree evidence for the exact admitted release candidate.
|
||||
allowed_exits: [handoff, waiting, failed]
|
||||
- id: git-canonicalization
|
||||
actor_role: orchestrator
|
||||
depends_on: [release-verification]
|
||||
objective: Obtain the authorized canonical Git identity and reconcile it with the verified candidate.
|
||||
allowed_exits: [handoff, waiting, failed]
|
||||
- id: public-release
|
||||
actor_role: orchestrator
|
||||
depends_on: [git-canonicalization]
|
||||
objective: Obtain publication authorization and the release owner's exact public artifact receipt.
|
||||
allowed_exits: [handoff, waiting, failed]
|
||||
- id: parent-adoption
|
||||
actor_role: orchestrator
|
||||
depends_on: [public-release]
|
||||
objective: Obtain separately authorized parent adoption and judge its effect receipt.
|
||||
allowed_exits: [handoff, waiting, failed]
|
||||
- id: record-shipped
|
||||
actor_role: orchestrator
|
||||
depends_on: [parent-adoption]
|
||||
objective: Record durable shipped truth after judging ceremony receipts; the post-release boundary follows.
|
||||
allowed_exits: [handoff, waiting, failed]
|
||||
- id: release-boundary
|
||||
actor_role: orchestrator
|
||||
depends_on: [record-shipped]
|
||||
objective: >-
|
||||
After the release ceremony, author one attributed disposition record
|
||||
covering seat renewal and re-prime, memory distillation, destination
|
||||
queue sweep, substrate teardown or retention, board freeze and clean-box
|
||||
baseline, capability-delta absorption and expiry, and packaged-product
|
||||
discoverability. These are agent-judged guides, not seven daemon gates.
|
||||
Inspect beyond this packet when useful. Record reasoned not-applicable
|
||||
or deferred dispositions and wait on live dependencies. Finish after
|
||||
this boundary when no successor is authored.
|
||||
allowed_exits: [done, waiting, failed]
|
||||
@@ -1,12 +1,9 @@
|
||||
# Project Workspace Contract
|
||||
|
||||
OpenRig's Project TUI is a file-backed view over a workspace root. The folder
|
||||
OpenRig's Project UI is a file-backed view over a workspace root. The folder
|
||||
shape is intentionally simple so humans and agents can create or repair it
|
||||
without daemon-internal knowledge.
|
||||
|
||||
This subtree is part of the wider [OpenRig Instance Layout](instance-layout.md).
|
||||
The instance initializer delegates these exact workspace bytes to this owner.
|
||||
|
||||
## Default Shape
|
||||
|
||||
`rig config init-workspace` creates the default workspace at
|
||||
@@ -14,101 +11,48 @@ The instance initializer delegates these exact workspace bytes to this owner.
|
||||
|
||||
```text
|
||||
workspace/
|
||||
SPEC.md
|
||||
project.yaml
|
||||
workspace.yaml
|
||||
.gitignore
|
||||
README.md
|
||||
STEERING.md
|
||||
missions/
|
||||
exhaust/
|
||||
README.md
|
||||
idea-ledger/
|
||||
README.md
|
||||
PROGRESS.md
|
||||
slices/
|
||||
capture-product-ideas/
|
||||
README.md
|
||||
PROGRESS.md
|
||||
IMPLEMENTATION-PRD.md
|
||||
triage-product-ideas/
|
||||
README.md
|
||||
PROGRESS.md
|
||||
IMPLEMENTATION-PRD.md
|
||||
handoff-loop/
|
||||
README.md
|
||||
PROGRESS.md
|
||||
slices/
|
||||
route-work-packets/
|
||||
README.md
|
||||
PROGRESS.md
|
||||
IMPLEMENTATION-PRD.md
|
||||
verify-loop-evidence/
|
||||
README.md
|
||||
PROGRESS.md
|
||||
IMPLEMENTATION-PRD.md
|
||||
progress/
|
||||
field-notes/
|
||||
specs/
|
||||
```
|
||||
|
||||
The scaffold is additive: it creates missing canonical entries and never
|
||||
overwrites existing files, including with the deprecated `--force` flag.
|
||||
`exhaust/` and local `.openrig/` runtime projections are ignored; authored
|
||||
project context and mission/slice files remain versionable. `workspace.yaml`
|
||||
is the project-location catalog. The project manifest exposes empty
|
||||
`install.context` and `install.skills` selectors for ordered Markdown
|
||||
addresses and stable managed-catalog skill IDs, but neither skill source nor a
|
||||
System World belongs in this tree.
|
||||
|
||||
## Project-world install
|
||||
|
||||
`project.yaml` may select project context and managed skills together:
|
||||
|
||||
```yaml
|
||||
schema: openrig.project/v0alpha1
|
||||
kind: project
|
||||
install:
|
||||
intent: SPEC.md
|
||||
context:
|
||||
- conventions.md
|
||||
skills:
|
||||
- repository-maintenance
|
||||
```
|
||||
|
||||
`install.context` contains project-relative Markdown addresses. `install.skills`
|
||||
contains stable skill identities only. Skill source bytes live in the single
|
||||
configured managed catalog (`skills.root`, default `$OPENRIG_HOME/skills`),
|
||||
never under the project or workspace. `rig context work-install --runtime
|
||||
<claude-code|codex>` resolves both parts; add `--apply-skills` to reconcile the
|
||||
selected exact bytes into `.claude/skills/` or `.agents/skills/` under the
|
||||
caller's current working directory. Use `--cwd` when the receiving agent works
|
||||
somewhere else; the project-world metadata root is never assumed to be its code
|
||||
working directory.
|
||||
|
||||
The generated harness directories and `.openrig/skill-loadouts/` ownership
|
||||
receipts are projections, not source. Product repositories should ignore them.
|
||||
Reconciliation removes a deselected entry only when its current bytes still
|
||||
match OpenRig's last owned projection; unrelated and locally modified entries
|
||||
are preserved or reported as conflicts.
|
||||
|
||||
Seats of the same runtime commonly share one working directory. Their topology
|
||||
selectors are retained per canonical seat identity and projected as a union, so
|
||||
starting one role cannot remove another role's skill. A changed projection is
|
||||
visible only to a fresh harness process; reconciliation reports that boundary
|
||||
instead of claiming a running seat hot-reloaded it.
|
||||
|
||||
An installed project selection is also retained in that working directory's
|
||||
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."
|
||||
|
||||
## TUI project selection
|
||||
|
||||
Open **PROJECTS** (or enter `projects`) to choose an ID and root from the
|
||||
configured workspace catalog. `project <id>` selects an exact catalog entry;
|
||||
`mission <directory>` then opens that project's execution view. The historical
|
||||
`scopes` machine section ID remains valid. Project selection and its canonical
|
||||
root travel through mission, slice, source-file and Back navigation. Changing a
|
||||
catalog root requires selecting it again. Missing or malformed sources remain
|
||||
unavailable; another project's matching work ID is never a fallback.
|
||||
|
||||
`source` opens the current project, mission or slice's actual source through the
|
||||
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 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
|
||||
`projectRoot` parameters to scopes, execution and slice-detail reads. Slice
|
||||
detail also requires the selected mission directory. Existing reads without a
|
||||
project parameter keep their legacy contract.
|
||||
|
||||
## UI Mapping
|
||||
|
||||
- `workspace.root` maps to the Project workspace.
|
||||
- `workspace.catalog_path` maps to the `workspace.yaml` project catalog.
|
||||
- `workspace.projects_root` is the default home for catalogued project worlds.
|
||||
- `workspace.root/missions/<mission-id>` maps to a Project mission.
|
||||
- `workspace.root/missions/<mission-id>/slices/<slice-id>` maps to a Project slice.
|
||||
- Mission `PROGRESS.md` frontmatter supplies the mission status badge when the
|
||||
file root is allowlisted.
|
||||
- Mission and slice `SPEC.md` frontmatter supplies intent, advisory sibling
|
||||
build-order `depends_on`, lifecycle status, and queue linkage hints.
|
||||
- Slice `PROGRESS.md` is the durable acceptance checklist; `PROOF.md` and
|
||||
`proof/` retain evidence paired to the SPEC proof contract.
|
||||
- Slice `README.md`, `PROGRESS.md`, and `IMPLEMENTATION-PRD.md` frontmatter
|
||||
supply display name, lifecycle status, mission id, and queue linkage hints.
|
||||
|
||||
Mission and slice ids should be stable kebab-case strings. Keep slice ids
|
||||
unique inside the workspace so `/project/slice/<slice-id>` resolves without
|
||||
@@ -146,13 +90,12 @@ default setup contract.
|
||||
If Project shows a mission discovery warning:
|
||||
|
||||
1. Run `rig config get workspace.root --show-source`.
|
||||
2. Run `rig config get workspace.catalog_path --show-source`.
|
||||
3. Run `rig config get workspace.slices_root --show-source`.
|
||||
4. Confirm `workspace.slices_root` points at a folder containing mission
|
||||
2. Run `rig config get workspace.slices_root --show-source`.
|
||||
3. Confirm `workspace.slices_root` points at a folder containing mission
|
||||
directories with `slices/` children.
|
||||
5. Confirm `files.allowlist` includes `workspace:<workspace.root>` so the TUI
|
||||
4. Confirm `files.allowlist` includes `workspace:<workspace.root>` so the UI
|
||||
can read mission `PROGRESS.md`.
|
||||
6. If the workspace is missing, run `rig config init-workspace` after operator
|
||||
5. If the workspace is missing, run `rig config init-workspace` after operator
|
||||
approval.
|
||||
|
||||
No daemon restart is required for most config reads. Restart when changing
|
||||
|
||||
@@ -1,90 +0,0 @@
|
||||
# The Refocus Channel
|
||||
|
||||
**How orientation content reaches a RUNNING seat.** Editing a file is not
|
||||
delivery: a running seat read its configuration at session start, and nothing
|
||||
in its context re-reads disk on its own. The refocus channel closes that gap —
|
||||
it is the mechanism that makes shipped chain files (see
|
||||
`chain-file-convention.md`) live doctrine rather than boot-time decoration.
|
||||
|
||||
## The mechanism
|
||||
|
||||
`openrig-core` ships `hooks/scripts/refocus.cjs`, registered on both runtimes:
|
||||
|
||||
| event | Claude Code | Codex | why |
|
||||
|---|---|---|---|
|
||||
| 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 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
|
||||
sustained work, not elapsed time). Its default threshold is ~2.6MB of JSONL
|
||||
growth (≈300k tokens); tune with `OPENRIG_REFOCUS_BYTES`. Codex never uses that
|
||||
threshold: its exact `PostCompact` lifecycle hook is the trigger, avoiding a
|
||||
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. 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:
|
||||
the next prompt the seat processes carries the content. The latency bound is
|
||||
"the seat's next turn," which is also the earliest moment new orientation
|
||||
could have been acted on anyway.
|
||||
|
||||
## The content is configurable — and never project-specific in source
|
||||
|
||||
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 (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
|
||||
questions, the ladder itself, and a pointer to the separately shipped
|
||||
onboarding assets.
|
||||
|
||||
The hook names a resolved REF in the delivered payload. If REF resolution
|
||||
fails, the payload starts with `REFOCUS CONTENT REF FAILED`, the exact ref, and
|
||||
the resolver's reason, then continues with generic orientation. A broken ref
|
||||
therefore stays visible without blocking the seat's session boundary. With REF
|
||||
unset, the existing FILE and generic paths are unchanged.
|
||||
|
||||
Mission-, project-, or box-specific refocus text belongs in a context-library
|
||||
entry or one of those FILES on the instance that needs it. **It must never be committed into product
|
||||
source** — the shipped default carries no path, seat name, mission, or
|
||||
practice that is not generally applicable.
|
||||
|
||||
Every delivered refocus pairs its content with the public `refocusing` skill's
|
||||
path-only trace. Configure `OPENRIG_REFOCUS_TREES=topology|work|both` and
|
||||
`OPENRIG_REFOCUS_DEPTH=light|full`; optional `OPENRIG_REFOCUS_TOPOLOGY_NODE`
|
||||
and `OPENRIG_REFOCUS_WORK_NODE` select starts that cannot be derived. The
|
||||
script resolves `topology.root` and `workspace.root` through live config and
|
||||
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.
|
||||
|
||||
## 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 `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
|
||||
|
||||
A refocus corrects drift; it is not a wake (which restores liveness and must
|
||||
not reframe work) and not a checkpoint (a deliberate phase-boundary pause).
|
||||
Sending the heavy intervention when the light one was due is the most common
|
||||
self-inflicted stall — the hook fires the light one automatically, which is
|
||||
the point.
|
||||
@@ -1,120 +0,0 @@
|
||||
# The release boundary — housekeeping run once per fence
|
||||
|
||||
A CHECKLIST OF JUDGMENT GUIDES, not gates: every item says WHY, most items are one
|
||||
act, and anything situational expires at the next boundary. Runs once per release
|
||||
fence, after the prior release's ceremony completes. The project and seat owners
|
||||
select the applicable actions and preserve their reasons in the boundary record.
|
||||
|
||||
## 1. Seats — reset or re-prime, per each seat's continuity needs
|
||||
|
||||
- **Choose continuity per seat, with its owner.** Fresh launch, managed compaction
|
||||
with re-prime, or retaining the current session serve different needs. Role names
|
||||
alone do not select one. Record the choice, the reason and custody of open work;
|
||||
selecting a procedure does not itself authorize a lifecycle action.
|
||||
- **Fresh launch** can clear accumulated context and load current startup guidance.
|
||||
Before an authorized exit, preserve the seat's earned knowledge and continuation
|
||||
(recap where provisioned); verify the new occupant's actual identity and install.
|
||||
- **Managed compaction with re-prime** can retain planning continuity while
|
||||
restoring the context needed for the next phase. **Retaining the current session**
|
||||
can preserve ongoing custody. In either case, inspect which guidance is stale and
|
||||
deliver the selected current context; an edit on disk is not delivery to a session.
|
||||
- **Re-prime = the world walk + the current capability delta + the mission install**
|
||||
per the mission-install convention (`docs/reference/mission-install.md`): the world
|
||||
half restores where-you-are; the project half (five layers, two depth profiles,
|
||||
paced pointer-walk) restores what-you-are-doing. Composing from named artifacts
|
||||
keeps source precedence visible.
|
||||
- **THE CEREMONY IS THE EXPERIMENT.** Every act above runs on the product's own
|
||||
primitives, so the ceremony doubles as their live test. Observe passively: what did
|
||||
each re-primed seat's first natural turns reach for, and what broke? Findings land
|
||||
in one dated observations file beside the boundary record.
|
||||
|
||||
## 2. Memory — distill, never accumulate
|
||||
|
||||
- Per-seat learned files: a distillation pass. The cut test: "has this changed a
|
||||
decision recently?" Keep those; move the rest to a dated archive section in the
|
||||
same file. A learned file at volume stops constraining and starts justifying.
|
||||
- Any shared agent memory: same pass, same test; retire entries the release
|
||||
falsified.
|
||||
- The finished release's mission notes: SEALED AS RECORD, carried as nothing. The
|
||||
new mission starts thin. Rules do not migrate; requirements do, via the plan.
|
||||
|
||||
## 3. Queue — sweep by destination, disposition everything
|
||||
|
||||
- Every seat sweeps its DESTINATION for open rows (wakes are unreliable; the sweep
|
||||
is the read). Each open row from the finished release gets exactly one of:
|
||||
done-with-receipt · carried-to-the-new-mission (re-filed against the new plan,
|
||||
never dragged) · closed-superseded. The sweep exposes obligations that a missed
|
||||
wake or a stale remembered work list can hide.
|
||||
- Verify every closing-paper inheritance has a live intake row with an owner. Zero
|
||||
orphans.
|
||||
|
||||
## 4. Substrate — teardown as its own atom
|
||||
|
||||
- Retain the current release and the immediately previous release. At a boundary
|
||||
for release N, worktrees and other release-scoped substrate from N-2 and older
|
||||
are eligible for cleanup. Eligibility is not permission to discard unique dirty
|
||||
bytes: archive or otherwise disposition those first. Identify live `main` and
|
||||
runtime state by their actual refs and identity, never by a stale directory name.
|
||||
- Prune worktrees; remove session-scoped scratch trees; verify merged branches
|
||||
deleted (merge receipts authorize).
|
||||
- Scratch homes and scenario roots in temp directories: swept.
|
||||
- Runtime installs: keep LIVE + LAST-KNOWN-GOOD; archive the hotfix chain;
|
||||
disposition launcher backups.
|
||||
- Mid-release vendored-file backups removed once the release containing the real
|
||||
fix is live.
|
||||
- Snapshots of torn-down topology: indexed in one line each, or deleted.
|
||||
|
||||
## 5. Instruments and boards
|
||||
|
||||
- The finished release's tracking and planning boards: FROZEN as records, labeled
|
||||
so. The new mission gets fresh boards — source-of-truth markdown first, board
|
||||
derived.
|
||||
- Frozen review criteria: archived beside their evidence, marked "available,
|
||||
unweakened, not gates."
|
||||
- Capture ONE clean-box baseline receipt at mission start (load, process counts,
|
||||
health tail latency) — the next performance question deserves a before.
|
||||
|
||||
## 6. The capability-delta lifecycle (standing law)
|
||||
|
||||
Each release's capability delta is authored at the fence and bound to the exact
|
||||
candidate, then reconciled to the published cut. Its baseline is the canon's actual
|
||||
last-absorbed marker, not an assumption that the immediately prior semver was
|
||||
absorbed. When canon is behind, the new delta is a cumulative synthesis of every
|
||||
intervening delta, preserving supersessions and pivots rather than concatenating
|
||||
old prose.
|
||||
|
||||
Canon absorbs the kept public-product truths. Expiry requires BOTH the canon header
|
||||
naming that exact delta AND a distinct successor delta file existing. A header alone
|
||||
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.
|
||||
|
||||
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
|
||||
obligations start at ITS cut.
|
||||
|
||||
## 7. World absorption and discoverability
|
||||
|
||||
- Every changed capability gets one small map: **user situation · current capability
|
||||
· authoritative source · natural first product encounter · durable context home ·
|
||||
clean-agent probe**. Record an already-good route and leave it alone.
|
||||
- Prefer point-of-need truth from the existing `--help`, error, command output, live
|
||||
state, context catalog, work install, or skill router. The world install supplies
|
||||
width and ontology; it should not copy exact facts a live surface can derive.
|
||||
- The release mission owns this review before its cut when possible, so public
|
||||
world/help changes ship with the capability. This boundary verifies the exact
|
||||
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 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
|
||||
|
||||
- No process migration: situational rules expired at the fence. The standing corpus
|
||||
is the four checking principles — verify by effect · evidence at source · honest
|
||||
verdicts including against yourself · never fabricate.
|
||||
- No re-litigating the finished release's verdicts; the sealed paper is the record.
|
||||
- No additions to this checklist without a lived specimen attached.
|
||||
@@ -1,7 +1,7 @@
|
||||
# RigBundle Reference
|
||||
|
||||
Version: 2 (pod-aware)
|
||||
Last validated against code: 2026-09-29 (install paths and `--target` only; other sections last checked 2026-04-11)
|
||||
Last validated against code: 2026-04-11
|
||||
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`
|
||||
|
||||
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.
|
||||
@@ -180,13 +180,6 @@ If any check fails, extraction is aborted and an error is thrown.
|
||||
|
||||
## CLI Surface
|
||||
|
||||
### Paths
|
||||
|
||||
`rig bundle create`, `inspect` and `install` resolve every path you give them (`<spec-path>`, `-o`, `--rig-root`,
|
||||
`<bundle-path>`, `--target`) to an absolute path against **your** current directory before sending the request. The
|
||||
daemon then reads and writes those paths on **its own host**: nothing is uploaded, so the files must already exist
|
||||
where the daemon runs.
|
||||
|
||||
### Create a bundle
|
||||
|
||||
```bash
|
||||
@@ -218,7 +211,7 @@ The create command:
|
||||
rig bundle inspect <bundle-path> [--json]
|
||||
```
|
||||
|
||||
Shows the manifest, digest validity, and integrity verification result. Inspect extracts the archive into a temporary directory for safe validation, then cleans that directory up. It does not install or launch anything.
|
||||
Shows the manifest, digest validity, and integrity verification result. Inspect extracts the archive into a temporary directory for safe validation, then cleans that directory up. It does not install the bundle.
|
||||
|
||||
### Install a bundle
|
||||
|
||||
@@ -229,20 +222,12 @@ rig bundle install <bundle-path> [--plan] [--yes] [--target <root>] [--json]
|
||||
| Flag | Required | Default | Description |
|
||||
|------|----------|---------|-------------|
|
||||
| `<bundle-path>` | yes | — | Path to the `.rigbundle` file. |
|
||||
| `--plan` | no | `false` | Preview without installing or launching. Not side-effect free: it runs the preflight, which executes the members' runtime `--version` probes, and it records a bootstrap run. It writes nothing to the target. |
|
||||
| `--plan` | no | `false` | Preview the bootstrap plan without installing or launching. |
|
||||
| `--yes` | no | `false` | Auto-approve trusted actions during apply mode. |
|
||||
| `--target <root>` | yes in apply mode | — | Directory the bundle is installed into and launched from. Required unless `--plan` is used. |
|
||||
| `--target <root>` | yes in apply mode | — | Target root directory for package installation. Required unless `--plan` is used. |
|
||||
| `--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>` unless you are running with `--plan`.
|
||||
|
||||
For a pod-aware (schema version 2) bundle, apply copies the extracted contents (`bundle.yaml`, `rig.yaml`, `agents/`, culture and docs files) 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: "."` (or no `cwd`) starts in the target;
|
||||
- an absolute member `cwd` stays as authored, and `rig up --cwd <dir>` 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 files are accepted, so reinstalling the same bundle into the same target works. Use an empty or dedicated directory as the target.
|
||||
|
||||
Legacy (schema version 1) bundles keep their old behavior: `--target` is only where packages are installed.
|
||||
Extracts the bundle, validates integrity, and bootstraps the rig. In apply mode, the daemon requires `targetRoot`, so `rig bundle install` must be given `--target <root>` unless you are running with `--plan`.
|
||||
|
||||
### Launch directly
|
||||
|
||||
@@ -252,9 +237,8 @@ rig up <bundle-path> [--target <root>] [--cwd <dir>]
|
||||
|
||||
`rig up` auto-detects `.rigbundle` files and routes them through the bundle bootstrap path.
|
||||
|
||||
- `--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`, the CLI defaults the install target to the current working directory, so the bundle's files are written there
|
||||
- `rig up` resolves a relative `--target` against your current directory before sending it, like `rig bundle install`; with `--host`, `--target` is sent as given and must be a path that exists on that host
|
||||
- `--target <root>` controls where packaged files are installed
|
||||
- if `--target` is omitted for a `.rigbundle`, the CLI defaults the install target to the current working directory
|
||||
- `--cwd <dir>` does **not** change the install target; it only overrides the launched members' working directory for that run
|
||||
|
||||
---
|
||||
@@ -380,4 +364,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 (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.
|
||||
The bundle is extracted to a temporary directory, integrity is verified, packaged files are installed into the target root, and the rig is bootstrapped 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.
|
||||
+8
-109
@@ -174,73 +174,12 @@ edges:
|
||||
| `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). |
|
||||
| `permission_policy` | string | no | — | Permission policy attached to the rig. Either a built-in (`builtin:locked`, `builtin:standard`, `builtin:open`, `builtin:yolo`) 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, 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. |
|
||||
|
||||
### Attaching a permission policy
|
||||
|
||||
Attach a policy to a rig with `permission_policy`, either at the rig level or on a member:
|
||||
|
||||
```yaml
|
||||
# a built-in, by name:
|
||||
permission_policy: builtin:standard
|
||||
|
||||
# or a custom policy file, by relative path (resolved from this spec's directory):
|
||||
permission_policy: policies/my-cautious-dev.policy.md
|
||||
```
|
||||
|
||||
Built-in policies (`locked` / `standard` / `open` / `yolo`) are read-only and are
|
||||
referenced as `builtin:<name>`. A custom policy lives in your own project and is
|
||||
referenced by a safe relative path (no `..`, no absolute). A shipped example of the
|
||||
custom shape is `packages/daemon/policies/examples/my-cautious-dev.policy.md` — copy it
|
||||
into your project and edit it to taste.
|
||||
|
||||
This records a selection, not a live permission change. Flag-surface policies
|
||||
select launch flags; config-surface policies still need native configuration
|
||||
application and inspection. In particular, `builtin:yolo` selects Codex's
|
||||
`danger-full-access` sandbox and `never` approval policy, and replaces
|
||||
any `codex_config_profile` argument. See [practical permission choices](getting-started.md#opt-in-permissive-operation).
|
||||
|
||||
An explicit `rig seat set-permissions` choice overrides member/rig policy for
|
||||
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).
|
||||
|
||||
### Choosing the Claude instruction file
|
||||
|
||||
OpenRig writes its instructions for Claude Code members into managed blocks in
|
||||
the member's working directory. By default the file is `CLAUDE.md`. If your
|
||||
repository tracks `CLAUDE.md`, write the blocks to `CLAUDE.local.md` instead:
|
||||
|
||||
```yaml
|
||||
managed_blocks:
|
||||
claude-code: CLAUDE.local.md
|
||||
```
|
||||
|
||||
Claude Code loads `CLAUDE.local.md` from the working directory as well. By
|
||||
convention the file is kept out of git, for example with a `.gitignore` entry.
|
||||
|
||||
- Accepted values are `CLAUDE.md` and `CLAUDE.local.md`. Any other value or
|
||||
runtime key is rejected before a member launches.
|
||||
- The setting applies to launch, restore, relaunch, handover, adding members,
|
||||
and export. `rig down` removes OpenRig's blocks from the selected file only.
|
||||
- OpenRig never edits, moves or deletes blocks in the other file.
|
||||
|
||||
A rig that already wrote blocks into `CLAUDE.md` keeps them there after you
|
||||
switch. Until you remove them, `CLAUDE.md` stays modified and Claude Code loads
|
||||
both copies. Delete each `<!-- BEGIN OpenRig MANAGED BLOCK: … -->` …
|
||||
`<!-- END OpenRig MANAGED BLOCK: … -->` section by hand and keep the rest of the
|
||||
file. If `CLAUDE.md` has no other uncommitted edits you need to keep, you can
|
||||
instead run `git restore CLAUDE.md`; that command discards every unstaged change
|
||||
to the file, not only OpenRig's blocks. Running `rig down` on a rig that still uses
|
||||
the default is not a substitute: it strips every OpenRig block from that
|
||||
directory's `CLAUDE.md`, including blocks written by other rigs.
|
||||
|
||||
---
|
||||
|
||||
## Pod
|
||||
@@ -271,7 +210,6 @@ directory's `CLAUDE.md`, including blocks written by other rigs.
|
||||
| `id` | string | yes | — | Member identifier. Must not contain dots. Must be unique within the pod. |
|
||||
| `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. |
|
||||
| `runtime` | string | yes | — | Agent runtime. Current supported values: `claude-code`, `codex`, `terminal`. |
|
||||
| `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. |
|
||||
@@ -386,51 +324,12 @@ Startup blocks can appear at three levels: rig, pod, and member. They are merged
|
||||
|
||||
| Field | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `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. |
|
||||
| `type` | string | yes | — | Action type. One of: `slash_command`, `send_text`. Note: `shell` is explicitly NOT supported in v1. |
|
||||
| `value` | string | yes | — | The command or text to send. |
|
||||
| `phase` | string | no | `after_files` | When to execute. One of: `after_files` (after startup files are delivered), `after_ready` (after harness readiness check passes). |
|
||||
| `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
|
||||
|
||||
Startup adds no orientation exercise by default. To select the authenticated
|
||||
startup challenge, declare an action in an agent, profile, rig, pod, member, or
|
||||
operator startup block:
|
||||
|
||||
```yaml
|
||||
startup:
|
||||
actions:
|
||||
- type: startup_proof
|
||||
value: authenticated
|
||||
idempotent: true
|
||||
```
|
||||
|
||||
Use `value: none` in a later layer to select lean startup explicitly. The last
|
||||
applicable declaration wins in agent → profile → rig → pod → member → operator
|
||||
order. Culture contributes files, not a proof selection. With no applicable
|
||||
declaration, the result is `none`; the number of startup files never selects
|
||||
proof. Invalid values and non-idempotent proof declarations fail validation,
|
||||
including declarations overridden later. These actions declare policy and are
|
||||
never typed into a terminal.
|
||||
|
||||
An authenticated selection challenges only a fresh or fresh-fallback managed
|
||||
agent launch. Resumed, forked, rebuilt, and adopted sessions receive no new
|
||||
challenge; terminal nodes never receive one. `applies_on` follows the requested
|
||||
startup context, so a fresh fallback during restore uses `restore` selections.
|
||||
Keep the default `[fresh_start, restore]` to cover both fresh launch paths.
|
||||
|
||||
Identity delivery, projection, readiness, and ordinary startup actions still
|
||||
run. `startup_status: ready` means startup completed, while `oriented: missing`
|
||||
means a selected proof awaits authenticated submission. Omission/`none` yields
|
||||
`oriented: n-a` on a new fresh launch and retires an older challenge without
|
||||
deleting its audit history. Retirement follows successful harness launch,
|
||||
before readiness checks, so attention, timeout, or a readiness exception cannot
|
||||
retain the preceding proof. A replacement that fails to launch does not retire
|
||||
the current proof; resume/adoption also preserves existing proof history.
|
||||
The effective selection is recorded on `node.startup_pending`; actions are
|
||||
persisted in startup context for restore and fresh relaunch.
|
||||
|
||||
---
|
||||
|
||||
## Services Block
|
||||
@@ -559,7 +458,7 @@ These rules are enforced by the validator. A spec that violates any of these wil
|
||||
19. Each wait target must define exactly one of: `service`, `url`, `tcp`.
|
||||
20. `condition` is only valid on `service` targets and must be `healthy`.
|
||||
21. Startup file `delivery_hint` must be one of: `auto`, `guidance_merge`, `skill_install`, `send_text`.
|
||||
22. Startup action `type` must be one of: `slash_command`, `send_text`, `startup_proof`. (`shell` is explicitly rejected.) Proof selection requires `value: authenticated` or `none` and `idempotent: true`.
|
||||
22. Startup action `type` must be one of: `slash_command`, `send_text`. (`shell` is explicitly rejected.)
|
||||
23. Startup action `phase` must be one of: `after_files`, `after_ready`.
|
||||
24. Startup action `idempotent` is a required boolean.
|
||||
25. Non-idempotent actions must not include `restore` in `applies_on`.
|
||||
@@ -573,8 +472,8 @@ These are the built-in specs shipped with OpenRig. Read them as worked examples.
|
||||
|
||||
| Spec | Location | Pods | Members | Services |
|
||||
|------|----------|------|---------|----------|
|
||||
| `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 |
|
||||
| `product-team` | `packages/daemon/specs/rigs/product-team.yaml` | orch, dev, rev | 7 (lead, peer, impl, qa, design, r1, r2) | no |
|
||||
| `implementation-pair` | `packages/daemon/specs/rigs/implementation-pair.yaml` | dev | 2 (impl, qa) | no |
|
||||
| `adversarial-review` | `packages/daemon/specs/rigs/adversarial-review.yaml` | orch, rev | 3 (lead, r1, r2) | no |
|
||||
| `research-team` | `packages/daemon/specs/rigs/research-team.yaml` | orch, research | 3 (lead, analyst, synthesizer) | no |
|
||||
| `secrets-manager` | `packages/daemon/specs/rigs/launch/secrets-manager/rig.yaml` | vault | 1 (specialist) | yes (Vault) |
|
||||
@@ -1,95 +0,0 @@
|
||||
# Scoped operating posture
|
||||
|
||||
Human-led work is quiet by default for process-only diagnosis. Delegated work can
|
||||
receive oversight during planning as well as implementation. This preference does
|
||||
not grant execution authority or change permissions, work phase, workflow reminders,
|
||||
context/continuity health, or health policy.
|
||||
|
||||
## Inspect and choose
|
||||
|
||||
Use the existing `rig mode` surface. Give an exact rig or authored work scope:
|
||||
|
||||
```sh
|
||||
rig mode effective --rig my-rig --json
|
||||
rig mode effective --project my-project --mission release-1 --json
|
||||
rig mode effective --qitem my-packet --json
|
||||
rig mode set delegated --scope mission --qualifier my-project/release-1 --evidence "Operator delegated this outcome"
|
||||
# The proposal above exits 2 without writing. Apply the deliberate choice:
|
||||
rig mode set delegated --scope mission --qualifier my-project/release-1 --evidence "Operator delegated this outcome" --confirm
|
||||
rig mode set human-led --scope mission --qualifier my-project/release-1 --evidence "Return to interactive planning" --confirm
|
||||
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, 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.
|
||||
|
||||
## One scope and phase contract
|
||||
|
||||
`GET /api/rig-mode/effective` accepts `rig`, `project`, `mission`, `workstream`, and
|
||||
`qitem`. Its additive `operatingPosture` object is also attached to health records
|
||||
and diagnosis findings. CLI explanation and TUI health detail display the same data.
|
||||
Consumers of posture, phase, and health should use this object rather than invent
|
||||
another preference store or infer delegation from workflow existence or activity.
|
||||
|
||||
| Field | Meaning |
|
||||
| --- | --- |
|
||||
| `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 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 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,
|
||||
global host. The qualifiers are respectively a qitem ID, `project/mission/slice-id`,
|
||||
`project/mission`, project ID, canonical rig ID, and null. Rig names resolve to IDs.
|
||||
The workstream is an existing authored slice, found by its directory or SPEC ID;
|
||||
the returned identity uses its SPEC ID and project/mission qualification.
|
||||
|
||||
Project selection reads `workspace.yaml`'s declared `projects: [{id, root}]`
|
||||
catalog, or the workspace's own `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. 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.
|
||||
|
||||
Legacy ergonomic modes (`sleep`, `desk`, `mobile`, `away`, `focus`, `debug`) retain
|
||||
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. Setting another mode at the
|
||||
same scope replaces that row; inspect effective posture after any mode change.
|
||||
|
||||
## Diagnosis effects
|
||||
|
||||
Process-category findings remain visible under human-led or unknown posture, but
|
||||
new diagnosis presentations, re-presentations and human notifications require
|
||||
explicit delegated posture. Retained occurrences are not canceled or rewritten
|
||||
when posture changes. Their current finding is refreshed for inspection and
|
||||
notification; unavailable current findings cannot reuse old delegated posture.
|
||||
Notification admission is rechecked after readiness I/O.
|
||||
|
||||
Delegation is necessary for process interruptions and is insufficient by itself:
|
||||
enabled diagnosis policy, detector selection, source freshness, custody, cooldown,
|
||||
recurrence limits and human delivery readiness still apply. Other health categories
|
||||
and ordinary queue/workflow reminders retain their existing behavior. The automatic
|
||||
ceremony source reads declared catalog projects through the same resolver; unresolved
|
||||
lineages remain visible with unknown scope instead of acquiring invented authority.
|
||||
|
||||
See [health diagnosis](health-diagnosis.md) for policy, evidence and disposition.
|
||||
@@ -1,368 +0,0 @@
|
||||
# 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, 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
|
||||
records intent; agents turn intent into a plan, the plan into a build, the
|
||||
build into proof. The TUI projects authored work on disk and, where an owning
|
||||
proof policy is selected, derives readiness from recorded judgments. These
|
||||
authoring conventions are **advisory / fail-open for agents**: the audit
|
||||
records and advises; the selected proof policy separately governs who may judge.
|
||||
|
||||
|
||||
## HOW TO READ THIS DOCUMENT — two parts, and only one of them is the default
|
||||
|
||||
| | applies | contents |
|
||||
|---|---|---|
|
||||
| **PART A — THE SIMPLE SDLC** | **ALWAYS. This is the default.** | artifact conventions, proportionality, the advisory audit, the honesty rails |
|
||||
| **PART B — THE RIGOROUS OVERLAY** | **ONLY when the human operator, or an orchestrator relaying that decision, ASSIGNS the heavy path to a NAMED piece of work** | the proof-contract format, the two locks, C1 proof drops, the locked role contracts |
|
||||
|
||||
**You may not select Part B for yourself.** If you believe something earns it, say so in ONE
|
||||
sentence and continue on Part A until told otherwise. Part A corresponds to the `mission-slice-sop`
|
||||
skill; Part B is defined below and applies only when assigned.
|
||||
|
||||
|
||||
## THE COMPONENT MENU — this document is a menu, not a pipeline
|
||||
|
||||
The SDLC is assembled from **components chosen per mission**, not a single mandated flow.
|
||||
This document describes the components and carries recommendations; a mission (or the team
|
||||
running it) picks per phase. Multiple valid options can exist for the same phase — choosing
|
||||
one does not deprecate the others. Nothing below deletes or overrides an existing component.
|
||||
|
||||
| phase | components available today |
|
||||
|---|---|
|
||||
| **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); 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`. |
|
||||
|
||||
> Full reference documents for each component (graduated 2026-08-28): the
|
||||
> product-management pass — `product-management-pass.md` · the
|
||||
> 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` (lands with its own slice). The
|
||||
> summaries above remain the one-glance description; this document remains the SSOT
|
||||
> pointer for the whole menu.
|
||||
|
||||
Mission and slice YAML may select component IDs from
|
||||
`product-journey-sdlc.md` and record explicit edges between them. That YAML is
|
||||
an address map and execution dashboard prototype, not an enforcement engine.
|
||||
If it is absent, Part A remains the complete default; agents do not invent a
|
||||
composition merely to make one exist.
|
||||
|
||||
# PART A — THE SIMPLE SDLC (applies always)
|
||||
|
||||
## A1. The flow in one pass
|
||||
|
||||
```
|
||||
intent (what is this for, what does done look like)
|
||||
→ build it
|
||||
→ test it with your own eyes
|
||||
→ record honestly what you verified, and what you did NOT
|
||||
→ hand off (rig queue handoff) or stop
|
||||
```
|
||||
|
||||
Verify the whole outcome at completion, not through a review chain per increment.
|
||||
For a tiny change the builder may hold this check. Independent QA/review runs only
|
||||
when selected by the project/mission/slice composition or an explicit owner
|
||||
assignment; for a wave, at its authored boundary. Available roles never add gates.
|
||||
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, 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.
|
||||
|
||||
**The heavier flow — proof contracts, plan-lock, C1 drops, proof-lock — is PART B and is not in
|
||||
force unless assigned.**
|
||||
|
||||
## A2. Slice artifact conventions (what the UI projects)
|
||||
|
||||
Each slice directory carries:
|
||||
|
||||
- **`SPEC.md`** — the one authored node file. Its frontmatter carries
|
||||
`intent:` and may carry `depends_on:` as a list of sibling work-node IDs;
|
||||
`depends_on` orders siblings and is never followed by the path-only context
|
||||
trace. The body opens with the three convention sections, in this order and
|
||||
with these exact headings:
|
||||
- **`## Intent`** — the recorded intent, verbatim. The UI projects this
|
||||
text as the INTENT section.
|
||||
- **`## Mini-requirements`** — the concise, one-glance requirement tier
|
||||
(numbered list). This is the human operator's first structured catchpoint;
|
||||
approval starts here.
|
||||
- **`## Proof contract`** — a checkbox list of promised deliverables (see
|
||||
§3). The UI's DELIVERED section pairs each item with its proof.
|
||||
- **`PROGRESS.md`** — the slice's acceptance checklist: the durable
|
||||
mission/slice-level to-do checked at acceptance. 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 (§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.
|
||||
|
||||
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. 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.
|
||||
|
||||
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 (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)
|
||||
|
||||
### Public-repo surfaces read as product engineering
|
||||
|
||||
Commit messages, code comments, and markdown/docs are **public-repo surfaces**: they
|
||||
ship to readers who have no access to — and no interest in — how the work was
|
||||
governed internally. Two rules, **forward-only** (existing history is not rewritten
|
||||
for these):
|
||||
|
||||
- **No verbatim internal quotes**, and especially not emotional or frustrated ones.
|
||||
Quote the *technical content* of a decision, never the person or the mood in which
|
||||
it was made.
|
||||
- **No governance framing.** Write what the change does and why it is correct on its
|
||||
own terms — not who ruled it, who approved it, or which internal gate it passed.
|
||||
"The guard fires at lock because a placeholder would otherwise satisfy the join"
|
||||
is product engineering. "X ruled this at the Y gate" is internal governance leaking
|
||||
into a public artifact.
|
||||
|
||||
The test: a reader outside the project should be able to act on the text without
|
||||
knowing any internal role, seat, or process name. This is the same principle applied
|
||||
to attribution and tone rather than to vocabulary.
|
||||
### A cited hash STATES WHAT IT COVERS
|
||||
|
||||
A hash offered as evidence is only checkable if the reader knows what bytes it
|
||||
was taken over. **State the coverage with the hash**, in one of two forms:
|
||||
|
||||
- **whole-file** — and say so, including whether a **trailing newline** is
|
||||
inside the hashed bytes; or
|
||||
- **file + an exact span definition** — the span is *part of the definition*,
|
||||
not a hint about where to look.
|
||||
|
||||
Two honest people can hash the same artifact and get different digests without
|
||||
either being wrong (for example, one over the frontmatter block and one over
|
||||
the whole file). Coverage is what makes a cited hash verifiable rather than
|
||||
merely impressive.
|
||||
|
||||
**Use path + anchor as the authority and a whole-file hash only to date the
|
||||
citation.** The address survives legitimate content changes; the digest does not.
|
||||
|
||||
## A4. When implementation finds the intent rested on something that does not exist
|
||||
|
||||
A slice's intent can only be honoured to the extent its assumptions hold. Sometimes implementation
|
||||
discovers that a LOCKED intent depends on functionality that **is not there** — not a missing
|
||||
detail, a missing capability.
|
||||
|
||||
**The honest response is to revise the ambition DOWN to what reality supports, and name the missing
|
||||
functionality as its own work.** Mark the slice **PARTIAL**, and write one document that tells a
|
||||
downstream reader the accurate story:
|
||||
|
||||
1. what the intent asked for (quote the locked text)
|
||||
2. what actually shipped, and how it was verified BY EFFECT
|
||||
3. **what did not ship and precisely why** — name each missing capability, at source, with the file
|
||||
and line that proves it is absent
|
||||
4. what the delivery does NOT cover, stated plainly — a scenario or feature that overstates its
|
||||
coverage is worse than one that does not exist
|
||||
5. **follow-on slices scoped from what you know NOW**, including which release you think they belong
|
||||
in — the agents holding the context at discovery time are the most knowledgeable readers that
|
||||
problem will ever have, and a downstream planner should not have to rediscover any of it
|
||||
|
||||
**What is NOT acceptable:** silently narrowing the claim; quietly expanding the slice to build the
|
||||
missing capability; or declaring victory on a reduced surface while still using the original slice's
|
||||
name. **Building the missing pieces inside the slice IS the scope creep.** Discovering them and
|
||||
routing them is the slice working correctly — and a slice that reveals a real product gap has
|
||||
produced something more valuable than the feature it set out to deliver.
|
||||
|
||||
Do not over-engineer this. The entire goal is an accurate story for whoever reads it next.
|
||||
|
||||
## A5. The elastic middle (proportionality — no minted ceremony)
|
||||
|
||||
The SDLC has exactly three fixed capture points: **intent** → a
|
||||
**proportional structured requirement** → **proof**. Everything between is
|
||||
elastic. For a small slice (a bug fix, a research note), the
|
||||
mini-requirements may BE the whole specification — the convention sections must be
|
||||
present so the slice projects, but their contents scale to the work. Gates
|
||||
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` (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` + `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 agent overlay points fresh seats at the skill
|
||||
and this document at boot.
|
||||
|
||||
# PART B — THE RIGOROUS OVERLAY (assigned only)
|
||||
|
||||
> **ENTRY CONDITION:** everything below applies **only** when the human operator — or an orchestrator
|
||||
> explicitly relaying that decision — has assigned the heavy path to a **named** piece of work.
|
||||
> If you arrived here without an assignment, stop and use Part A.
|
||||
>
|
||||
> **Rails:** the locks are **two, and only two**. Nothing here authorizes a second gate round on
|
||||
> the same work, a gate on documentation / comments / tests / fixtures, or asking a peer to gate
|
||||
> what you can verify with your own eyes. **Cut rounds, never checks.** The tier is **re-chosen**
|
||||
> when the surface changes.
|
||||
|
||||
## B0. The assigned flow in one pass
|
||||
|
||||
```
|
||||
intent → mini-requirements + proof contract → (UI slices: mockups)
|
||||
→ plan-lock (rig scope slice approve --scope spec)
|
||||
→ build the LOCKED set
|
||||
→ QA: mockup ↔ delivered VISUAL compare
|
||||
→ proof drops (rig proof add <slice> …)
|
||||
→ proof-lock (rig scope slice approve --scope delivery)
|
||||
```
|
||||
|
||||
## B1. The proof contract format
|
||||
|
||||
`## Proof contract` is a markdown checkbox list; each item is one promised
|
||||
deliverable, written as an observable outcome:
|
||||
|
||||
```markdown
|
||||
## Proof contract
|
||||
|
||||
- [ ] The consolidated `rig ps` default renders all rigs with a rollup footer — captured.
|
||||
- [ ] UI: the slice review tab renders the three-section stack — screenshot vs the locked mockup.
|
||||
```
|
||||
|
||||
- Each item is joined (by item text or 1-based index) to the proof artifacts
|
||||
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`): 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
|
||||
not a gap and not a gate.
|
||||
- A deliverable QA did not actually verify shows as `unverified`/`missing`
|
||||
in the UI — visible, never hard-blocking.
|
||||
|
||||
## B2. The two locks (shipped verb — not new machinery)
|
||||
|
||||
Two deliberate stamps, both written by the SAME shipped verb
|
||||
(`rig scope slice approve`, one daemon-side write path: frontmatter stamp +
|
||||
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.
|
||||
- **Proof-lock:** `rig scope slice approve <slice> --scope delivery`
|
||||
(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, §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).
|
||||
|
||||
## B3. Proof drops and the C1 header (closed sets)
|
||||
|
||||
Proof artifacts land in `proof/` via the shipped verb:
|
||||
|
||||
```bash
|
||||
rig proof add <slice> \
|
||||
--artifact-type qa \
|
||||
--verdict PASS \
|
||||
--candidate-sha <the-proven-tip> \
|
||||
--money-evidence "one line of money evidence" \
|
||||
--file <artifact.md> \
|
||||
--evidences "1,3" \
|
||||
--media "walk.webm,panel.png" \
|
||||
--self-check "I looked at the captures; they show the claim"
|
||||
```
|
||||
|
||||
The C1 header's five required fields: `slice`, `candidate_sha`,
|
||||
`artifact_type`, `verdict`, `money_evidence`. Two **ratified closed sets**
|
||||
(extending either is a convention change, not a local edit):
|
||||
|
||||
- `artifact_type`: `guard | qa | rev1-r1 | rev1-r2 | adjudication`
|
||||
- `verdict`: `CLEAR | BLOCKING | CONCERNING | PASS | NOT-CLEAR`
|
||||
|
||||
`candidate_sha` is the join key: the proven candidate tip this artifact
|
||||
judges. `--evidences` names which proof-contract deliverable(s) the drop
|
||||
covers (item text or 1-based index) — that reference populates the
|
||||
planned↔delivered pairing. `--self-check` is the agent's recorded assertion
|
||||
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
|
||||
(§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)
|
||||
|
||||
- **Planning agent:** authors intent verbatim, the mini-requirements, and the
|
||||
`## Proof contract` (each UI deliverable with its mockup `plannedRef`);
|
||||
produces the mockups; locks the plan (`--scope spec`).
|
||||
- **Build agent:** builds against the LOCKED set only; looks at the mockups,
|
||||
not just the spec text.
|
||||
- **QA agent (owns the compare):** for each deliverable — load the locked
|
||||
`plannedRef`, produce the real artifact in a test/demo environment,
|
||||
**visually compare**, record the verdict + note via a proof drop, and
|
||||
**curate** the canonical proof set. On mismatch beyond minutiae: fix and
|
||||
have another agent review, or kick back with the reason — never escalate a
|
||||
raw mismatch to the human. A proof drop with no recorded comparison leaves
|
||||
the deliverable `unverified` — visibly.
|
||||
|
||||
**Curation rule:** the primary proof set is the curated canonical "this is
|
||||
what it looks like now" evidence the agent stands behind — bounded, mapped
|
||||
1:1 (or few:1) to deliverables. The fix-loop's full artifact history stays in
|
||||
`proof/`, one drill-in down, NEVER in the primary view. The anti-pattern:
|
||||
an append-only pile where the human can't tell final from superseded.
|
||||
|
||||
## Scratch-daemon hermeticity: the DB a scratch daemon opens is the one you named
|
||||
|
||||
A scratch daemon launch **strips the inherited environment's `OPENRIG_DB` and names an explicit
|
||||
scratch DB path under the scratch `OPENRIG_HOME`** — both halves, every launch:
|
||||
|
||||
```bash
|
||||
env -u OPENRIG_DB \
|
||||
OPENRIG_HOME="$SCRATCH_HOME" \
|
||||
OPENRIG_DB="$SCRATCH_HOME/openrig.sqlite" \
|
||||
node <daemon entry> …
|
||||
```
|
||||
|
||||
An inherited fleet DB reaching a scratch daemon is a **harness defect regardless of outcome** —
|
||||
the scratch context read or wrote state it never owned, and whether anything visibly broke is
|
||||
luck, not hermeticity.
|
||||
|
||||
**The discriminator that keeps this rule honest:** an explicit `OPENRIG_DB` still WINS by design
|
||||
(`daemon-db-path.ts`) — deliberate split-path configuration remains legitimate and
|
||||
untouched. This rule governs **inheritance into scratch contexts**, where nobody
|
||||
decided anything: strip what you did not choose, then choose.
|
||||
@@ -1,90 +0,0 @@
|
||||
# Create your own Slack app for OpenRig (experimental)
|
||||
|
||||
> **Experimental in 0.6.0.** The manifest (`rig slack manifest`) and this setup guide are new
|
||||
> and have not been confirmed against a real app creation. The Slack connector itself and its
|
||||
> `setup`, `verify`, `enable`, `disable` and `status` commands are not experimental. If a step
|
||||
> here does not match what Slack shows you, please
|
||||
> [open an issue](https://github.com/mvschwarz/openrig/issues/new/choose) or send a pull request
|
||||
> ([CONTRIBUTING.md](../../CONTRIBUTING.md)).
|
||||
|
||||
OpenRig's Slack connector talks to a Slack app that you create in your own workspace. OpenRig
|
||||
ships the app's manifest; it does not host an app, run an install endpoint, or publish anything
|
||||
to the Slack Marketplace. The app is a Socket Mode app, so it lives in the one workspace you
|
||||
create it in.
|
||||
|
||||
`rig slack manifest` prints the manifest. It works offline, before any daemon or token exists:
|
||||
|
||||
```bash
|
||||
rig slack manifest # the manifest as YAML
|
||||
rig slack manifest --url # Slack's create-app link with the manifest prefilled
|
||||
rig slack manifest --json # the manifest, its scopes and events, and why each scope is requested
|
||||
```
|
||||
|
||||
The TUI shows the same link on the Connections page while Slack is not configured. Neither the
|
||||
CLI nor the TUI opens a browser, accepts tokens, or creates an app.
|
||||
|
||||
## Steps
|
||||
|
||||
These are the expected steps, based on Slack's app-manifest documentation. They have not yet
|
||||
been confirmed against a real creation run. Slack's form may ask for something the prefill did
|
||||
not fill in; if so, follow the form.
|
||||
|
||||
1. Open the link from `rig slack manifest --url` in a browser.
|
||||
2. Sign in to Slack if asked, pick the workspace, review the prefilled manifest, and click
|
||||
**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-`).
|
||||
5. Install the app to the workspace and approve the requested scopes.
|
||||
6. Under **OAuth & Permissions**, copy the **Bot User OAuth Token** (it starts with `xoxb-`).
|
||||
7. Put both tokens in a private env file readable only by you (`chmod 600`):
|
||||
|
||||
```bash
|
||||
SLACK_BOT_TOKEN=xoxb-...
|
||||
SLACK_APP_TOKEN=xapp-...
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
Run `rig slack manifest --json` for the exact list and the reason for each scope. There are two
|
||||
groups:
|
||||
|
||||
- **Baseline scopes**: posting messages, reading message history in public channels the app is
|
||||
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), 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:
|
||||
|
||||
- **Attachments** (`files:read`, `files:write`): the file download or upload call fails. A
|
||||
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, and
|
||||
nothing in OpenRig reports that they are missing.
|
||||
|
||||
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`) and to
|
||||
mentions of the app (`app_mention`). It does not request direct-message or private-channel access.
|
||||
|
||||
## What the connector does with the tokens
|
||||
|
||||
The tokens stay in the env file you created. The connector reads them from that file and uses them
|
||||
to authenticate to Slack: it opens an outbound Socket Mode connection with the app-level token and
|
||||
calls Slack's Web API with the bot token. This connector has no OpenRig-hosted component and
|
||||
makes outbound connections only. That statement is about this Slack connector, not about every
|
||||
part of OpenRig.
|
||||
|
||||
## Next
|
||||
|
||||
- `rig slack status` shows what is still missing, without contacting Slack.
|
||||
- `rig slack verify` checks the granted baseline scopes and channel membership with Slack.
|
||||
@@ -1,244 +0,0 @@
|
||||
# Occupant-owned stream classification and shadow capture (experimental)
|
||||
|
||||
> **Experimental in 0.6.0, optional and off by default.** The Jev classification path and shadow
|
||||
> capture may be incomplete or not work, and no accuracy or production-reliability claim is
|
||||
> made. OpenRig's delivery, watchdog and routing decisions do not use their output. If they do
|
||||
> not behave as described here, please
|
||||
> [open an issue](https://github.com/mvschwarz/openrig/issues/new/choose) or send a pull request
|
||||
> ([CONTRIBUTING.md](../../CONTRIBUTING.md)).
|
||||
|
||||
This source provides a bounded receiver for one real classifier occupant. It does
|
||||
not start an agent, register a watchdog job, or enable capture by default.
|
||||
Taxonomy, questions and decisions belong to the occupant; the daemon supplies
|
||||
source facts and enforces its existing lease, execution and idempotency fences.
|
||||
An explicit optional Jev mode supplies advisory decisions through the same worker.
|
||||
Experimental labels have no demonstrated accuracy or calibrated confidence and
|
||||
do not replace delivery, watchdog, or routing decisions.
|
||||
|
||||
## Optional foreground Jev experiment
|
||||
|
||||
With no configuration, the experiment is off. Choose an explicit local JSON path
|
||||
in an existing private directory; the file contains only enabled state and bounds:
|
||||
|
||||
```sh
|
||||
rig project experimental status --config ./experiment.json --json
|
||||
rig project experimental enable --config ./experiment.json --max-requests 3 --timeout-ms 10000 --json
|
||||
rig project experimental disable --config ./experiment.json --json
|
||||
```
|
||||
|
||||
Enable does not start processing, capture, a daemon or an agent. Status and disable
|
||||
make no provider request. The invoking process needs `OPENROUTER_API_KEY` in its
|
||||
environment for an enabled run; this entry never searches credential files or
|
||||
copies credentials into configuration. Missing credentials fail before attempts
|
||||
or provider work. Normal key provisioning remains with the operator.
|
||||
|
||||
The selected route is `https://openrouter.ai/api/alpha/decisions`, pinned to
|
||||
`typesafe/jev-1.13`, without provider fallback or HTTP redirects. A request declares
|
||||
maximum provider prices of $0.05 per million prompt tokens, zero completion and
|
||||
request price. These are admission ceilings, not a price quote, spend estimate or
|
||||
credential-access claim. Each foreground run allows 1–20 requests (default 3),
|
||||
each with a 1–30 second deadline (default 10), 24 KiB request and 256 KiB response
|
||||
limits. Failed requests consume their count. Nothing retries in the background.
|
||||
|
||||
To process stream items from the actual selected occupant:
|
||||
|
||||
```sh
|
||||
rig project wake --project PROJECT --taxonomy ./taxonomy.yaml \
|
||||
--classifier-version experimental-jev-1.13 --evidence-epoch OWNER_EPOCH \
|
||||
--limit 3 --experiment ./experiment.json --json
|
||||
```
|
||||
|
||||
Use the taxonomy format described below. Each criterion must have a nonempty
|
||||
string description; `__unknown__` is reserved. Questions stay outside the daemon.
|
||||
The request sends the selected item's body, supplied taxonomy questions/criteria,
|
||||
canonical scope IDs and current roster destinations to OpenRouter. Select inputs
|
||||
appropriate for that external processing. It does not transmit the credential
|
||||
in evidence or store it in the classification. The output binds current source,
|
||||
taxonomy, candidate version, lease, occupant generation and attempt execution.
|
||||
No action or confidence label is inferred. Duplicate judgment remains manual.
|
||||
|
||||
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 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 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
|
||||
request remains reported pending and cannot cause a late write or a second call
|
||||
in that run. Remote cancellation or refund is not proven by local cancellation.
|
||||
The command registers no wake, returns no automatic continuation, and requires
|
||||
an explicit later invocation to do more work.
|
||||
|
||||
For selected observations from an existing shadow archive:
|
||||
|
||||
```sh
|
||||
rig project experimental capture --config ./experiment.json \
|
||||
--input ./selected-shadow.jsonl --output ./new-advisory-results.jsonl --json
|
||||
```
|
||||
|
||||
This reads at most 8 MiB and considers only the first configured maximum number
|
||||
of records. It never captures a terminal. The input remains unchanged; output is
|
||||
exclusively created at mode 0600. Keep prior output and choose another filename
|
||||
only for a deliberately selected new run. It sends captured post-screen text to
|
||||
the same provider, and retains the original attempt/node/occupant/pane binding and
|
||||
capture hash beside the answer. Missing capture or binding is unavailable and
|
||||
makes no provider call. State answers are experimental hints; delivery remains
|
||||
`INDETERMINATE` because screen text cannot prove submitted/consumed/effect and the
|
||||
archive does not retain the original sent text. No result feeds back into live
|
||||
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.
|
||||
|
||||
## One bounded wake
|
||||
|
||||
From the selected occupant, read candidates using the configured project ID:
|
||||
|
||||
```sh
|
||||
rig project candidates --project PROJECT --taxonomy /private/taxonomy.yaml \
|
||||
--classifier-version VERSION --evidence-epoch OWNER_EPOCH --limit 20 --json
|
||||
```
|
||||
|
||||
The result includes eligible stream IDs, authored scope IDs with exact source
|
||||
paths/hashes, the current running roster of the occupant's rig, observation time,
|
||||
and a candidate version. Taxonomy YAML supplies `version` and
|
||||
`fields.{kind,urgency,maturity,area}` with a `question` and `values` mapping. These
|
||||
questions are returned to the occupant; draft values are not verified truth.
|
||||
Confidence has no selectable values until calibration selects that contract.
|
||||
Destination choices are the current roster sessions plus explicit `pool`.
|
||||
Null/omitted destination remains unknown; it is not converted into `pool`.
|
||||
The candidate hash binds the selectable values as well as source and taxonomy
|
||||
hashes. Packets prepared before this pool correction require fresh preparation;
|
||||
it does not reopen historical attempts or change the evidence epoch.
|
||||
|
||||
Read each eligible item with `rig stream show ITEM --json`. Duplicate candidates
|
||||
are the latest 100 nonarchived items with exact body-hash evidence references;
|
||||
their preview is capped at 2,000 characters and marked when truncated. Read the
|
||||
complete candidate before selecting a duplicate. A retrieval miss means unknown.
|
||||
Directory names, issue IDs and bare membership never supply scope IDs. Source
|
||||
errors are explicit, and partial source snapshots cause abstention.
|
||||
|
||||
Write an occupant-owned decision file (at most 100 unique item IDs, at most 1 MiB):
|
||||
|
||||
```json
|
||||
{
|
||||
"candidateSetVersion": "sha256:<version returned by candidates>",
|
||||
"decisions": [{
|
||||
"streamItemId": "<eligible ID>",
|
||||
"bodyHash": "sha256:<SHA256 of the exact UTF-8 item body>",
|
||||
"decision": { "kind": "classify", "labels": {
|
||||
"classificationType": "<selected taxonomy value>",
|
||||
"scopeRef": "<selected canonical mission or slice ID>",
|
||||
"needsHuman": null
|
||||
}}
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
An explicit abstention is `{"kind":"abstain","reason":"why unknown"}`. Other
|
||||
label keys are `classificationUrgency`, `classificationMaturity`,
|
||||
`classificationDestination`, `area`, and `classificationConfidence`. Omitted or
|
||||
null labels stay unknown. A duplicate needs both `duplicateOfStreamItemId` and
|
||||
the matching `duplicateEvidenceRef` from the candidates, plus occupant judgment
|
||||
that it really is a duplicate. An existing item alone is not that judgment.
|
||||
|
||||
```sh
|
||||
rig project wake --project PROJECT --taxonomy /private/taxonomy.yaml \
|
||||
--classifier-version VERSION --evidence-epoch OWNER_EPOCH --limit 20 \
|
||||
--decisions /private/decisions.json --json
|
||||
```
|
||||
|
||||
This command actually invokes one `StreamClassificationWorker.wake()` through
|
||||
the existing HTTP services. It derives sender identity through `DaemonClient`,
|
||||
requires a current running occupant, and carries the captured generation through
|
||||
each lease/attempt/classification request. It never invents a daemon holder.
|
||||
Existing direct HTTP callers keep their documented sender-provenance behavior.
|
||||
|
||||
The command refreshes source candidates before acquiring a lease. Missing or
|
||||
stale decision packets return unavailable without starting attempts; refresh
|
||||
preparation if the roster, scopes, taxonomy or recent stream changed. During a
|
||||
wake, an item with no exact body-bound decision, missing sources, or a selected
|
||||
candidate that is unavailable abstains. This is deliberately strict; continuous
|
||||
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 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.
|
||||
|
||||
The result carries per-item outcomes, `moreEligible`, `nextWakeAt`, and a watchdog
|
||||
`wakeRequest` descriptor with the real session/generation and a receiving
|
||||
instruction. `registered:false` is literal. A periodic-reminder message asks the
|
||||
occupant to prepare and run this entry; delivery of that message is not execution.
|
||||
Registration/placement remains an explicit later action. Honor `nextWakeAt`:
|
||||
lease maintenance uses TTL/3 opportunities; lease loss or an unavailable service
|
||||
backs off 60 seconds. The daemon's retry/exhaustion ledger remains authoritative.
|
||||
The ordinary client bounds each request at five seconds; a timed-out write has
|
||||
an unknown outcome until the ledger is read, and is never reported as written.
|
||||
|
||||
There is no provider in the manual-decision path. The reusable asynchronous worker has one
|
||||
pending classifier slot; timeout requests cancellation but cannot force it. An
|
||||
uncooperative classifier blocks further calls in that instance and late results
|
||||
cannot write. That in-memory pending slot is not cross-process cancellation.
|
||||
|
||||
## Separate bounded shadow drain
|
||||
|
||||
The production transport and inventory probes accept the same optional observer.
|
||||
They record only captures already taken, with the node, occupant, pane and capture
|
||||
target bound before awaits. The ordinary cheap inventory path still takes no
|
||||
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.
|
||||
This document supplies no live destination or activation instruction. Required
|
||||
fields and engineering ceilings are:
|
||||
|
||||
| Field | Meaning | Maximum |
|
||||
|---|---|---|
|
||||
| `destination` | New absolute JSONL file in a canonical, current-user-owned 0700 directory | Explicit path |
|
||||
| `maxRecords` | Total reserved sink records | 100,000 |
|
||||
| `maxBytes` | Total reserved sink bytes, including newlines | 1 GiB |
|
||||
| `capacity` | Queued observation count | 1,000 |
|
||||
| `maxQueuedBytes` | Serialized bytes waiting in the queue | 8 MiB |
|
||||
| `maxObservationBytes` | Serialized bytes per observation | 1 MiB |
|
||||
|
||||
All numeric fields are required positive safe integers. These are engineering
|
||||
capacity limits, not approved corpus sizes or classification thresholds. One
|
||||
in-flight drain can hold up to 64 additional observations, bounded by the queue's
|
||||
byte allowance; queue plus drain can therefore retain up to twice that allowance.
|
||||
The standalone observer defaults are 256 entries, 4 MiB queued and 256 KiB per
|
||||
observation; explicit production configuration supplies each value.
|
||||
|
||||
`rig project shadow-status` only inspects configuration/counters.
|
||||
`rig project shadow-drain` asks the existing HTTP service to drain up to 64 rows;
|
||||
it requires an actor and never enables capture. No background drain timer is added.
|
||||
`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;
|
||||
inspect status after a client timeout instead of assuming the flush completed.
|
||||
Enabling capture again requires a separately authorized daemon start with a new
|
||||
destination; enabling the local provider experiment does not enable capture.
|
||||
The file is exclusively created with mode 0600. An existing file is refused,
|
||||
never overwritten, appended, rotated or deleted. A restart requires a new selected
|
||||
destination. Private-file creation currently requires POSIX ownership support.
|
||||
|
||||
The hot path only performs bounded synchronous enqueue work; it never awaits disk
|
||||
or drain completion. Slow sinks leave one drain pending; concurrent drains do not
|
||||
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 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 /
|
||||
submitted / consumed / effect evidence remain outside this source entry.
|
||||
@@ -1,102 +0,0 @@
|
||||
# The wave SDLC — parallel build, wave-level review, composition as the care dial
|
||||
|
||||
This is a selectable build and review model from `sdlc-conventions.md`'s component
|
||||
menu. The mission owner decides whether it fits the work. Lock stamps in this model
|
||||
are ADDITIVE: approval appends metadata and never rewrites authored bytes, so a
|
||||
candidate's identity survives its own approval.
|
||||
|
||||
## The model in one paragraph
|
||||
|
||||
Slices build IN PARALLEL across every build-class seat, each in a DISJOINT FILE
|
||||
TERRITORY, each merged serially by one integrator the moment its candidate freezes
|
||||
with builder-proven receipts. Independent review happens ONCE PER WAVE over the wave's
|
||||
whole accumulated range — two reviewers with different vantages (ideally different
|
||||
runtimes), never the writers — and their findings drive fix rounds that re-earn both
|
||||
verdicts at the round's final revision. Checks stay per-slice (failing-test-first
|
||||
proof, verify-by-effect, honest receipts); rounds happen per-wave.
|
||||
|
||||
## The mechanics
|
||||
|
||||
1. **PLAN:** wave entries in the plan of record; the planner shapes specs; the plan
|
||||
authority locks them. Every slice gets a real workspace or proof has no home.
|
||||
2. **DISPATCH:** batons fan out with EXCLUSIVE file territories. THE BRIEF IS THE
|
||||
UNIT: every assignment carries the goal, the acceptance criteria, the complete
|
||||
context routes (exact paths), the territory — and this standing grant: "Navigate
|
||||
the implementation yourself: derive what you need, research, spawn readers,
|
||||
decide your own build order. Ask when stuck; the orchestrator is here to help."
|
||||
DEFAULT SCOPE IS THE WHOLE SPEC, built in one sustained run to ONE frozen
|
||||
candidate. Handing out anything smaller requires naming the reason on the brief
|
||||
itself (an unresolved decision, a live territory conflict, a genuine
|
||||
fork-in-the-road risk) — an unexplained small chunk is a dispatch defect.
|
||||
Territory overlap = serialize. Conflict discovered mid-build = STOP AND RULE.
|
||||
Why: the builder holds the spec and the code; decisions about how to build
|
||||
belong where the building context lives. Detailed sequencing instructions were
|
||||
scaffolding when models were weak; today they are a cage, and per-command
|
||||
routing is the failure mode, not diligence.
|
||||
THE BRIEF IS A MAP, NOT THE TERRITORY. Distillation is welcome — for a minimal
|
||||
slice the brief may honestly be richer than the spec — but it is never the
|
||||
receiver's ONLY context: the builder's first act is self-onboarding from the
|
||||
routed reading list (the mission-install pattern at slice scale), then checking
|
||||
the map against the ground it actually stands on. Nobody knows the ground floor
|
||||
better than the builder; the wide angle lives a layer up. When the ground
|
||||
disagrees with the map, that is a finding to raise — not a reason to follow
|
||||
the map off a cliff.
|
||||
3. **BUILD:** failing-test-first against a pristine base with committed final test
|
||||
bytes; freeze a single candidate revision; receipts cite the FINAL revision
|
||||
(re-earned after any rebase).
|
||||
4. **MERGE:** integrator-only, serially, verified at source each time (candidate
|
||||
parent equals pre-merge tip; changed files equal declared territory). Merge
|
||||
announcements are REBASE TRIGGERS for every open candidate.
|
||||
5. **WAVE REVIEW:** fires when the wave's build completes. Two independent reviewers,
|
||||
base-scoped at the tip, writers excluded from reviewing their own work. The two
|
||||
gates ask DIFFERENT questions — does the structure hold, versus does each claim
|
||||
survive contact with source. That is the design, not redundancy.
|
||||
Reviewers also review for DRIFT, not only defects: does the built thing still
|
||||
match the acceptance criteria the brief stated — is this still the doghouse the
|
||||
owner asked for, or did locally-defensible steps accrete toward a moon base?
|
||||
Plot-loss is a first-class finding with the same standing as a logic defect.
|
||||
Reviews also DISPOSE each miss by cause: CONTEXT-GAP — the spec or its routes
|
||||
lacked what the moment needed (a planning finding; the fix lands in the spec) —
|
||||
versus JUDGMENT-GAP — the context was there and the call was wrong (a builder
|
||||
finding; the fix is a check). One word in the verdict artifact. The rate this
|
||||
produces is the calibration the dispatch shape tunes on.
|
||||
6. **FIX ROUNDS:** findings become forward-fix candidates (merges stand; merged is
|
||||
not running). One re-review pass per round re-earns both legs at the final
|
||||
revision. Narrow rechecks for narrow corrections.
|
||||
7. **SEAL:** both legs clear at one revision = wave sealed; the next slot opens.
|
||||
|
||||
## THE WAVE IS THE CARE DIAL
|
||||
|
||||
Wave COMPOSITION is the control surface for how carefully a piece is handled: a
|
||||
large, complicated, or load-bearing slice gets a wave OF ITS OWN (its review ceremony
|
||||
fires for it alone); a big piece can even split across waves. This decouples what an
|
||||
older model conflated: mission and slice workspaces stay flexible organizational
|
||||
containers; waves are the separate layer that sequences work, assigns it, and prices
|
||||
its handling care. Care is a per-piece property, never a per-mission one.
|
||||
|
||||
## When to use it
|
||||
|
||||
Many small-to-medium, root-caused, evidence-backed slices; enough seats to
|
||||
parallelize; territories that partition cleanly; an integrator who can merge serially
|
||||
and verify fast.
|
||||
|
||||
## When NOT to use it
|
||||
|
||||
Design-uncertain or shared-region work (one slice, classic two-leg review, or a
|
||||
design session first). Anything irreversible within the hour (publish, cutover,
|
||||
destructive operations) — that is the heavy path. And when no independent non-writing
|
||||
reviewers exist: nothing ever self-reviews; without them the wave gate is theater.
|
||||
|
||||
## Failure modes and mitigations
|
||||
|
||||
- **Freeze-merge races:** a candidate freezes seconds before a merge moves the tip.
|
||||
Mitigation: zero-overlap restack with content-identity proof (stable patch-id) in
|
||||
an isolated worktree; builder-side self-catch on merge announcements.
|
||||
- **Evidence theater:** a failing test that fails for the wrong reason reads
|
||||
identical to a real one. Mitigation: reviewers re-derive the failures
|
||||
independently; false characterizations retire to a correction history, never a
|
||||
silent rewrite.
|
||||
- **Presence-not-absence tests:** asserting the true line exists while the false
|
||||
line still prints. Rule: pin the ABSENCE of the false claim in every encoding.
|
||||
- **Phantom checkout status:** merge-by-reference leaves a shared checkout's index
|
||||
stale. Never build or commit from a shared checkout; sync its index at fences.
|
||||
@@ -1,39 +0,0 @@
|
||||
# Worktree builds: use a per-worktree install, never a symlinked `node_modules`
|
||||
|
||||
**Filed as** build friction (a TS2688 `@types/node` failure). **Grounded as** something worse:
|
||||
the symlink shortcut that avoids the install produces builds and typechecks that silently
|
||||
consume ANOTHER tree's source — a false-green generator, not an inconvenience.
|
||||
|
||||
## What actually happens
|
||||
|
||||
`npm install` in a worktree creates `node_modules/@openrig/<pkg>` as a RELATIVE symlink
|
||||
(`-> ../../packages/<pkg>`). Relative links resolve against the directory they live in, so:
|
||||
|
||||
| setup | `@openrig/daemon` resolves to | verdict |
|
||||
|---|---|---|
|
||||
| per-worktree `npm install` | that worktree's `packages/daemon` | correct |
|
||||
| `ln -s <primary>/node_modules node_modules` | **the PRIMARY tree's** `packages/daemon` | **cross-tree** |
|
||||
|
||||
Verified by discriminator, not by inference: with a symlinked `node_modules`, a deliberate type
|
||||
error introduced in the WORKTREE's `packages/daemon` is seen by that package's own `tsc` and NOT
|
||||
seen by `packages/cli`'s `tsc`, which exits 0 — because it type-checked the primary tree's daemon.
|
||||
A worktree can therefore report green against code it does not contain.
|
||||
|
||||
## Rules
|
||||
|
||||
1. **Run `npm install` in each worktree** so workspace packages resolve to the
|
||||
worktree's own source.
|
||||
2. **Never symlink `node_modules` from the primary checkout.** It appears to work — builds pass,
|
||||
typechecks pass — which is exactly the danger.
|
||||
3. **`npx tsc` with no `node_modules` installs an unrelated `tsc` package** and prints
|
||||
"This is not the tsc command you are looking for". That message means *no install*, not a
|
||||
TypeScript error.
|
||||
4. **Build `@openrig/daemon` before typechecking `@openrig/cli`** in a fresh worktree: cli imports
|
||||
`@openrig/daemon/crash-cart` etc., which resolve to daemon's `dist`. Absent dist reads as
|
||||
TS2307 "Cannot find module" plus a cascade of implicit-any — a provisioning artifact, not a
|
||||
code defect.
|
||||
|
||||
## Self-check before trusting any worktree build
|
||||
|
||||
[ "$(readlink -f packages/daemon)" = "$(readlink -f node_modules/@openrig/daemon)" ] \
|
||||
|| echo "CROSS-TREE: this worktree resolves @openrig/* into another tree"
|
||||
+3
-42
@@ -33,53 +33,14 @@ For each release:
|
||||
|
||||
1. Copy `_template.md` to `vX.Y.Z.md`.
|
||||
2. Fill in the release summary, included changes, operator notes, known limitations, and verification performed.
|
||||
3. Run the **substance gate** at the exact release cut. The gate derives every
|
||||
file under the shipped pack sources, verifies a hash-bound human judgment
|
||||
and an individual disposition for each mechanical candidate, scans the
|
||||
complete npm artifact set derived by the packager, and writes the durable
|
||||
receipt. The receipt records both artifact and scanned file lists; their
|
||||
artifact-minus-scanned diff must be empty. The review JSON carries one
|
||||
entry per file:
|
||||
|
||||
```json
|
||||
{
|
||||
"surfaces": [{
|
||||
"path": "packages/daemon/context-packs-src/example/guide.md",
|
||||
"sha256": "<sha256 of the reviewed bytes>",
|
||||
"verdict": "ship",
|
||||
"reason": "Generic product guidance.",
|
||||
"candidateDispositions": []
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
Assemble the package first, then run the named gate from the same clean
|
||||
worktree with the judge and cut SHA explicit. The assembly emits the
|
||||
substance roots it actually staged; the gate never carries its own root
|
||||
list. A non-shipping human verdict is one of `instance-fact`,
|
||||
`internal-path`, `position-knowledge`, or `lore-class` and carries its
|
||||
reason in the same per-file entry:
|
||||
|
||||
```bash
|
||||
bash scripts/build-package.sh
|
||||
npm run gate:substance -- \
|
||||
--review /path/to/substance-review.json \
|
||||
--receipt /path/to/substance-receipt.json \
|
||||
--judge <seat-or-person> \
|
||||
--cut-sha "$(git rev-parse HEAD)"
|
||||
```
|
||||
|
||||
A missing/stale judgment, an undispositioned candidate, internal substance,
|
||||
a lore-classed pack, a failed full artifact scan, or any artifact absent
|
||||
from the scanned set refuses the cut.
|
||||
4. Create a git tag for the release:
|
||||
3. Create a git tag for the release:
|
||||
|
||||
```bash
|
||||
git tag vX.Y.Z
|
||||
git push origin vX.Y.Z
|
||||
```
|
||||
|
||||
5. Create a GitHub Release using the same file:
|
||||
4. Create a GitHub Release using the same file:
|
||||
|
||||
```bash
|
||||
gh release create vX.Y.Z \
|
||||
@@ -88,7 +49,7 @@ For each release:
|
||||
--notes-file docs/releases/vX.Y.Z.md
|
||||
```
|
||||
|
||||
6. Publish the npm package if that is part of the release flow.
|
||||
5. Publish the npm package if that is part of the release flow.
|
||||
|
||||
## Guidance
|
||||
|
||||
|
||||
@@ -1,336 +0,0 @@
|
||||
# OpenRig v0.3.1
|
||||
|
||||
## Summary
|
||||
|
||||
OpenRig v0.3.1 builds on v0.3.0 with operator-facing UX work, the headline
|
||||
Claude auto-compaction policy, a dashboard + For You visual refresh, the
|
||||
Plugin Primitive v0 surface (`rig plugin`), Library Explorer finishing
|
||||
(skills + plugins + specs with real folder browsing), Settings Destination
|
||||
Explorer, action outcome + inline error UX, and a comprehensive privacy
|
||||
hygiene pass.
|
||||
|
||||
No schema-breaking migrations. Existing v0.3.0 databases upgrade on first
|
||||
`rig daemon start` (adds migration `040_workflow_specs_diagnostic` — two
|
||||
new diagnostic columns on `workflow_specs` cache, `ALTER TABLE ADD COLUMN`
|
||||
with safe defaults).
|
||||
|
||||
## Included In This Release
|
||||
|
||||
- **Claude Auto-Compaction Policy** — operator-configurable session
|
||||
auto-`/compact` with safe defaults (opt-in default-off; no behavior
|
||||
change unless explicitly enabled). 7 new ConfigStore keys; 6-stage
|
||||
daemon-to-LLM lifecycle (pre-prep prompt → compact → handshake →
|
||||
restore → compliance audit → cooldown); PreCompact hook +
|
||||
SessionStart/UserPromptSubmit bridge.
|
||||
- **Plugin Primitive v0** — `rig plugin` command surface (read-only at
|
||||
v0: `list`, `show`, `used-by`, `validate`). Plugin discovery from
|
||||
`$OPENRIG_HOME/plugins/`, vendored-and-provenance pattern. No
|
||||
`install` verb at v0; deferred to 0.3.2.
|
||||
- **Library Explorer Finishing** — skills + plugins + specs as a
|
||||
fully operator-facing surface with real folder browsing. New
|
||||
daemon-owned library discovery API (`/api/skills/library`,
|
||||
`/api/skills/:id/files/...`, `/api/plugins/:id/files/...`).
|
||||
- **Settings Destination Explorer** — settings became a 4-item
|
||||
Explorer destination matching Topology / Project / Library / For-You
|
||||
pattern, with `/settings`, `/settings/policies`, `/settings/log`,
|
||||
`/settings/status` sub-routes.
|
||||
- **Dashboard And For You Visual Refresh** — both routes adopt a
|
||||
shared "vellum" surface language (translucent stone-tinted cards,
|
||||
paper-grid background, ambient shadow, mono+dot kind indicators,
|
||||
L-shaped corner-bracket registration marks). Single source of truth
|
||||
between production and `/lab/vellum-lab`.
|
||||
- **For You Storytelling Adapter** — Progress / Shipped / Incident /
|
||||
Approval card kinds wired to real data (missions, slices, activity
|
||||
feed, queue items). ApprovalCard surfaces real queue items waiting
|
||||
on approval.
|
||||
- **Action Outcome + Inline Error Surface** — queue-item verb actions
|
||||
(Approve/Deny/Route/Hold/Drop/Annotate/Handoff) render outcomes
|
||||
immediately on success and surface failures inline without
|
||||
silently reverting. Closes a demo-blocking silent-revert bug.
|
||||
- **Mobile Drawer Behavior** — 375px Explorer drawer now layers above
|
||||
the rail tray for Settings / Project / Library / For-You. Topology
|
||||
mobile drawer is intentionally hidden in 0.3.1; scheduled for full
|
||||
restoration in 0.3.2.
|
||||
- **Vendored Skill Provenance** — vendored skills declare upstream
|
||||
lineage via `metadata.openrig` frontmatter and (when modified) a
|
||||
companion `OPENRIG.md` sidecar. Applied to all 10 process-skill
|
||||
surfaces.
|
||||
- **Workflow specs diagnostic surface** — migration `040` adds
|
||||
`status` + `error_message` columns to the `workflow_specs` cache so
|
||||
the Library UI can render parse/validation errors as diagnostic
|
||||
rows instead of hiding them.
|
||||
- **Privacy hygiene pass** — three filter-repo passes scrubbed
|
||||
personal data, internal references, and historic versions from
|
||||
history; commit subjects and bodies polished for public surface.
|
||||
Backup repos preserved for rollback.
|
||||
|
||||
## User-Facing Changes
|
||||
|
||||
### Claude Auto-Compaction Policy
|
||||
|
||||
Operator-configurable auto-`/compact` for Claude sessions, with safe
|
||||
defaults:
|
||||
|
||||
- **Opt-in default-off**: nothing changes unless you explicitly enable
|
||||
the policy. With no policy configured, the daemon never sends an
|
||||
auto-`/compact`.
|
||||
- **7 new ConfigStore keys** in the `policies.claude_compaction.*`
|
||||
namespace: `enabled`, `threshold_percent` (strict integer 1-100),
|
||||
`compact_instruction` (operator-supplied; appended to `/compact`
|
||||
args when set), `message_inline`, `message_file_path`,
|
||||
`pre_compact_instruction`, `post_restore_audit_instruction`. Strict
|
||||
validation across all source layers (`set`/`POST`/env/file). Invalid
|
||||
env values fall back to defaults with a stderr warning rather than
|
||||
silently coercing.
|
||||
- **5 operator-editable prompt surfaces** in Settings → Policies UI:
|
||||
pre-compaction prep, compact instruction, post-compaction restore
|
||||
(inline), restore file path, post-restore audit. Daemon-owned
|
||||
wrappers (usage/threshold framing, trust-channel preservation,
|
||||
marker paths, read-depth enforcement, turn-boundary handshake,
|
||||
dedup + cooldown) are non-editable.
|
||||
- **6-stage lifecycle**: pre-compact prep prompt (save-game-before-quit
|
||||
mental-model restore map) → `/compact` with operator instructions
|
||||
→ post-compact turn-boundary handshake → restore prompt with
|
||||
defense-in-depth fallback chain → compliance audit (forces
|
||||
FULL/PARTIAL/NOT_READ table) → 10-minute cooldown.
|
||||
- **Safety hardening**: typed prompt drafts classified as attention
|
||||
state so auto-`/compact` retries later instead of overwriting human
|
||||
input. Send-failure does not advance dedup state. Re-arm requires
|
||||
threshold-crossing.
|
||||
|
||||
### New `rig plugin` Command (read-only at v0)
|
||||
|
||||
```
|
||||
rig plugin list # Discoverable plugins across vendored + runtime caches
|
||||
rig plugin show <id> # Plugin manifest + skills + hooks + mcp servers
|
||||
rig plugin used-by <id> # Agents referencing this plugin
|
||||
rig plugin validate <path> # Validate plugin manifest + skill frontmatter
|
||||
```
|
||||
|
||||
No `install` verb at v0 — installation is explicit operator copy or
|
||||
symlink to `$OPENRIG_HOME/plugins/<plugin-id>/`. See each plugin's
|
||||
`OPENRIG-INSTALL.md` for the documented copy/symlink workflow. A
|
||||
`rig plugin install <substrate-path>` verb is deferred to 0.3.2.
|
||||
|
||||
### Library Explorer Finishing
|
||||
|
||||
The Library destination (skills + plugins + specs) is now fully
|
||||
operator-facing:
|
||||
|
||||
- No duplicate top-level entries (`> SKILLS` / `> PLUGINS` rows removed
|
||||
from `SpecsTreeView`; bottom-row clicks navigate + expand the tree).
|
||||
- Plugins above Skills in the tree.
|
||||
- 32 OpenRig-managed shared skills are now discoverable in production
|
||||
VM environments (previously empty due to workspace-relative path
|
||||
lookup).
|
||||
- Daemon-owned library discovery API: `GET /api/skills/library`,
|
||||
`GET /api/skills/:id/files/list?path=...` + `/files/read?path=...`,
|
||||
parallel routes under `/api/plugins/:id/`.
|
||||
- Real file-browser + docs-browser on plugin and skill detail pages.
|
||||
Markdown auto-renders; non-markdown files render as text. Folder
|
||||
navigation works.
|
||||
- Rolled-up index pages at `/specs/skills` and `/specs/plugins` with
|
||||
flat-row listings, source labels, file counts, and entry links.
|
||||
|
||||
### Settings Destination Explorer
|
||||
|
||||
Settings is now a top-level Explorer destination matching the Topology /
|
||||
Project / Library / For-You pattern:
|
||||
|
||||
- `/settings` (general config keys form)
|
||||
- `/settings/policies` (Claude auto-compaction policy form lives here)
|
||||
- `/settings/log`
|
||||
- `/settings/status`
|
||||
|
||||
Old top-row tab navigation removed. Shared `SettingsPageShell` chrome
|
||||
across all 4 sub-routes.
|
||||
|
||||
### Dashboard And For You Visual Refresh
|
||||
|
||||
A coordinated visual refresh to a shared "vellum" surface language:
|
||||
|
||||
- **Dashboard `/`** — full rewrite over new `dashboard/vellum/`
|
||||
primitives. Hero typography ("WELCOME BACK") at display-lg + headline-
|
||||
bold. Tactical instrument-panel stats line with tabular numerals.
|
||||
Six destination cards (Topology / Project / For You / Library /
|
||||
Search / Settings) share the numeral-layout treatment. Real-data
|
||||
hooks: `useRigSummary`, `usePsEntries`, `useSpecLibrary`.
|
||||
- **For You `/for-you`** — both card systems unified to the vellum
|
||||
recipe: storytelling band (`CardShell` rewritten with bg-stone-100/45
|
||||
+ backdrop-blur + ambient shadow + corner brackets) and queue-item
|
||||
`FeedCard.tsx` (same outer chrome; vellum bordered-no-fill action
|
||||
buttons with hover-invert and 44px touch targets).
|
||||
- **Single source of truth** between `/dashboard` and
|
||||
`/lab/vellum-lab` via `packages/ui/src/components/dashboard/vellum/`.
|
||||
- **Lab routes** — `/lab/card-previews`, `/lab/vellum-lab`,
|
||||
`/lab/vellum-bg/{a-large,b-small,c-allover}` are checked-in
|
||||
experiment surfaces for designer iteration. Reachable in production
|
||||
by direct URL; not linked from main navigation.
|
||||
|
||||
### For You Storytelling Adapter
|
||||
|
||||
The storytelling band at top of `/for-you` now wires four card kinds to
|
||||
real data:
|
||||
|
||||
- **Progress** — first 2 active missions (`useMissionDiscovery`)
|
||||
- **Shipped** — slices with status = shipped/complete/done (capped at 3;
|
||||
from `useSlices`)
|
||||
- **Incident** — slices with status = blocked/failed/danger (capped at 3)
|
||||
- **Approval** — queue items waiting on approval, from
|
||||
`useActivityFeed` + `classifyFeed` (capped at 2)
|
||||
|
||||
`ConceptCard` component is preserved in source but not emitted by the
|
||||
production adapter; a deliberate data-source decision is scheduled for
|
||||
0.3.2.
|
||||
|
||||
### Action Outcome And Inline Error Surface
|
||||
|
||||
Queue-item verb actions (Approve/Deny/Route/Hold/Drop/Annotate/Handoff):
|
||||
|
||||
- On success, `ActionOutcomePanel` renders immediately ("Approved by X",
|
||||
"Routed by X to Y") — no waiting for audit-log roundtrip.
|
||||
- On error, a tertiary-bordered error block renders below the verb
|
||||
buttons with the daemon's error message; verb-selection state is
|
||||
preserved so the operator can correct and retry.
|
||||
- Replaces the prior silent-revert UX. Regression test guards the class
|
||||
explicitly.
|
||||
|
||||
## Operator / Setup Notes
|
||||
|
||||
After upgrading the published CLI:
|
||||
|
||||
```bash
|
||||
npm install -g @openrig/cli@0.3.1
|
||||
rig --version # expect 0.3.1
|
||||
rig daemon stop
|
||||
rig daemon start
|
||||
```
|
||||
|
||||
Migration `040_workflow_specs_diagnostic` applies automatically on first
|
||||
post-upgrade daemon start. It is a non-destructive `ALTER TABLE ADD
|
||||
COLUMN` with safe defaults (existing rows retroactively get
|
||||
`status: 'valid'`). No manual action required.
|
||||
|
||||
For Claude auto-compaction policy: opt-in default-off. Visit
|
||||
`/settings/policies` to configure. Recommended for sessions where
|
||||
context exhaustion is a recurring operational concern. Read the docs
|
||||
section in the Settings UI before enabling.
|
||||
|
||||
For the new `rig plugin` surface: no behavior change unless you install
|
||||
plugins. Bundled `openrig-core` plugin ships with the daemon (11 skills).
|
||||
Operators can install `gstack` (45 skills) or `obra-superpowers`
|
||||
(14 skills) by following each plugin's `OPENRIG-INSTALL.md` workflow.
|
||||
|
||||
## Known Limitations
|
||||
|
||||
- **`rig down <name>` still returns HTTP 404** — name-based teardown
|
||||
still doesn't resolve through the daemon down route at v0.3.1. Use
|
||||
`rig down <rigId> --delete` instead. Carries forward as known issue
|
||||
to v0.3.2.
|
||||
- **`rig queue list --json --limit` and `rig view list/show --json`
|
||||
flag inconsistency** — flags scaffolded but not fully wired. Use
|
||||
human-readable output for now. Carries forward to v0.3.2.
|
||||
- **Topology mobile drawer hidden** at 375px viewports in 0.3.1
|
||||
(intentional; clicking the hamburger triggered a pre-existing
|
||||
`TopologyTableView` renderer cascade). Full restoration scheduled
|
||||
for 0.3.2 via a dedicated render-path slice.
|
||||
- **`ConceptCard` component preserved in source** but not emitted by
|
||||
the production For You adapter. A deliberate data-source decision is
|
||||
scheduled for 0.3.2.
|
||||
- **`/lab/*` routes ship to production builds** intentionally per
|
||||
founder direction; 0.3.2 adds an index page + per-lab banner +
|
||||
manifest pattern.
|
||||
- **Plugin install ergonomics** — v0 plugin install is operator-driven
|
||||
copy or symlink; first-class `rig plugin install <substrate-path>`
|
||||
is deferred to 0.3.2.
|
||||
- **Lifecycle classifications** remain truthful but still rely on
|
||||
heuristics rather than perfect provider-native primitives in some
|
||||
recovery paths.
|
||||
|
||||
## Verification Performed
|
||||
|
||||
- `npm run lint` clean.
|
||||
- `npm run build` clean across all workspaces.
|
||||
- `npm run test:repo` green.
|
||||
- Daemon test suite: 3600 pass, 1 pre-existing host-env-sensitive
|
||||
failure on `restore-check-routes` reading malformed local Claude
|
||||
settings (banked as environment-dependent class).
|
||||
- UI test suite: 1106 pass / 0 fail (post-test-fixes merge; was 1093
|
||||
pass + 3 failing on stale-test pre-fix).
|
||||
- TypeScript checks clean on all touched files.
|
||||
- Code review (review-lead, advisory-clean) on every merge in the
|
||||
release window.
|
||||
- Founder-walk VM at `http://100.95.124.51:17459/` walked end-to-end
|
||||
on host-main `4d88d98d` with realistic demo seed (8 seeded queue
|
||||
items, 8 feed events, 4 verified `/for-you` action scenarios
|
||||
including the inline error path).
|
||||
|
||||
## Commits Included (highlights)
|
||||
|
||||
The full v0.3.0 → v0.3.1 delta is 224 commits / 376 files / +37,391
|
||||
insertions / −3,153 deletions. The list below groups load-bearing
|
||||
commits by theme:
|
||||
|
||||
### Claude Auto-Compaction Policy
|
||||
- `feat(daemon,cli)`: Claude auto-compaction policy scaffolding +
|
||||
ConfigStore keys
|
||||
- `feat(daemon)`: 6-stage compaction lifecycle (pre-prep → compact →
|
||||
handshake → restore → compliance → cooldown)
|
||||
- `feat(daemon)`: PreCompact hook + SessionStart/UserPromptSubmit
|
||||
bridge for marker restoration
|
||||
- `feat(daemon)`: SessionTransport draft-attention classification +
|
||||
send-failure dedup discipline
|
||||
|
||||
### Plugin Primitive v0
|
||||
- `feat(daemon,cli)`: `rig plugin` command + plugin discovery surface
|
||||
- `feat(daemon)`: plugin manifest + skill provenance metadata schema
|
||||
- `chore(skills)`: vendoring metadata + `OPENRIG.md` sidecars for 10
|
||||
process-skill surfaces
|
||||
|
||||
### Library Explorer
|
||||
- `feat(daemon)`: library discovery API
|
||||
(`/api/skills/library`, `/api/{skills,plugins}/:id/files/list+read`)
|
||||
- `feat(ui)`: SpecsTreeView dual-action + plugin/skill detail file
|
||||
browsers
|
||||
- `feat(ui)`: rolled-up `/specs/skills` and `/specs/plugins` index
|
||||
pages
|
||||
|
||||
### Settings Destination Explorer
|
||||
- `feat(ui)`: 4-route Settings Explorer destination
|
||||
(`/settings`/`policies`/`log`/`status`) with shared `SettingsPageShell`
|
||||
|
||||
### Dashboard + For You Visual Refresh
|
||||
- `redesign(dashboard)`: full rewrite over `dashboard/vellum/`
|
||||
primitives + 6 destination cards
|
||||
- `redesign(for-you)`: vellum-coherent storytelling cards + queue-item
|
||||
FeedCard chrome unification
|
||||
- `refactor(dashboard)`: extract vellum primitives — single source of
|
||||
truth between `/dashboard` and `/lab/vellum-lab`
|
||||
- `simplify(dashboard)`: drop back layer + back vellum sheet; add
|
||||
ambient shadow
|
||||
- `merge(release)`: storytelling adapter extension — approval cards
|
||||
wired to real data
|
||||
- `feat(for-you)`: wire ApprovalCard to real data; remove ConceptCard
|
||||
from production switch
|
||||
- `fix(for-you)`: optimistic action outcome + inline error surface in
|
||||
VerbActions
|
||||
|
||||
### Migration 040 (workflow_specs diagnostic)
|
||||
- `feat(daemon)`: migration 040 adds `status` + `error_message`
|
||||
diagnostic columns to `workflow_specs` cache
|
||||
|
||||
### Final test alignment
|
||||
- `test(ui)`: fix 3 pre-existing failures — match deliberate design
|
||||
changes
|
||||
- `docs(changelog)`: cover 0.3.1 dashboard + for-you visual refresh +
|
||||
action UX
|
||||
|
||||
### Privacy hygiene
|
||||
- Three filter-repo passes (LOCAL-INSIGHTS personal-data scrub +
|
||||
commit-body internal-doc reference scrub + file-content historic
|
||||
versions scrub)
|
||||
- Commit subject rewrites to remove privacy-scream patterns
|
||||
- Force-pushed at commit `7e55d9d3` as the privacy-cleaned baseline
|
||||
|
||||
See `CHANGELOG.md` for the full agent-readable changelog with quick
|
||||
verification commands and operator notes.
|
||||
@@ -1,362 +0,0 @@
|
||||
# OpenRig v0.3.2
|
||||
|
||||
## Summary
|
||||
|
||||
OpenRig v0.3.2 ships Rigbundles as a first-class cross-primitive bundling
|
||||
mechanism, GAs the workspace + workflow operator surface, lands a
|
||||
4-bug `rig up <starter>` paper-cut fix-round, ships a 5-fix
|
||||
coordination + first-user-setup round (slice 21), scrubs internal
|
||||
substrate paths from daemon source + tests, wires `ConceptCard` to a
|
||||
shaped data source, and adds server-side priority windowing on For You.
|
||||
|
||||
No schema-breaking migrations. Existing v0.3.1 databases upgrade on first
|
||||
`rig daemon start` (adds migration `041_rig_policy` for the new
|
||||
operator-context-mode bindings table — `CREATE TABLE` with no impact on
|
||||
existing data; binding rows are operator-authored at runtime).
|
||||
|
||||
## Included In This Release
|
||||
|
||||
- **Rigbundles First-Class (slice 05)** — cross-primitive bundling for
|
||||
five content kinds (skills + plugins HYBRID + workflow_specs +
|
||||
context_packs + agent_images) routed end-to-end. `rig bundle create`
|
||||
auto-detects an author `bundle.yaml`, vendors declared content with
|
||||
both-sides path containment and symlink-escape protection, and
|
||||
emits an integrity-hashed manifest. `rig bundle install` routes
|
||||
each content kind to its canonical library at `$OPENRIG_HOME`
|
||||
with consumer-scan visibility. `rig bundle inspect` surfaces the
|
||||
cross-primitive content fields as first-class. CLI install timeout
|
||||
bumped (the 5-second cap was too short for tmux-session-bootstrapping
|
||||
installs).
|
||||
- **Workspace + Workflow GA (slice 01)** — operator-facing surface
|
||||
hardened. `rig workspace validate --max-files` strict-int regex;
|
||||
`rig workflow project --exit` enum guard; 3-part error returned
|
||||
before `client.post` for early-fail clarity; 14 new discriminator
|
||||
tests on the validator paths.
|
||||
- **`rig up <starter>` Paper-Cut Fix-Round (slice 22)** — unblocks
|
||||
the homepage quick-start on fresh 0.3.1→0.3.2 installs. Four bounded
|
||||
fixes:
|
||||
- HTTP 4xx surface for pre-launch failures
|
||||
(`cycle_error` / `preflight_failed` / `validation_failed` /
|
||||
`service_boot_failed`) — was bare 500.
|
||||
- No orphan rig record on pre-launch failure — instantiator
|
||||
re-ordered + rollback path + compose teardown order tightened.
|
||||
- Path-form `rig up <install-internal-spec>` defaults `cwd` to the
|
||||
caller directory (closes the divergence between path-form and
|
||||
bare-form invocation).
|
||||
- `walkYamlFiles` skips standard noise dirs (`.worktrees`,
|
||||
`node_modules`, `.git`, `dist`, `.turbo`, `.next`) + stale
|
||||
`workflow_specs` rows prune at startup with an install-root
|
||||
preservation guard (so shipped built-in specs survive the prune).
|
||||
- **Coordination + First-User Setup Fix-Round (slice 21)** — five
|
||||
bounded follow-rounds:
|
||||
- FR-1: Coordination-model boot instinct surfaced in
|
||||
`core/openrig-user/SKILL.md` (`rig send` vs `rig queue` vs
|
||||
`rig queue handoff` + §1b doctrine).
|
||||
- FR-2: First-user workspace + workflow setup teaching content
|
||||
(skill + docs).
|
||||
- FR-3: MISSION_NOTES durable-pattern hardening (template +
|
||||
codemap convention + scope-primitive auto-scaffold via
|
||||
`rig scope mission create`).
|
||||
- FR-4: Queue ergonomics — `rig queue create --body-file <path>`
|
||||
(use `-` for stdin) kills the backtick-shell-corruption class for
|
||||
multiline bodies; first-class `--mission` / `--slice` flags
|
||||
compose into tags; `lastNudgeResult` wording fix;
|
||||
closure-vs-acceptance documented.
|
||||
- FR-5: `rig workspace doctor` subcommand — 7-check workspace
|
||||
readiness diagnostic (workspace root, missions folder, file
|
||||
allowlist, daemon alignment, daemon reload, optional slice
|
||||
docs, MISSION_NOTES presence).
|
||||
- **Daemon Test Substrate-Path Scrub (slice 14)** — internal-team
|
||||
substrate path shape scrubbed from 4 daemon source sites + 10 test
|
||||
files. Hook-constants de-duplicated. Privacy class closed for
|
||||
tracked source/test surface.
|
||||
- **`ConceptCard` Data Source (slice 17)** — wired to shaped backlog
|
||||
candidates; storytelling-adapter completion deferred from 0.3.1
|
||||
is now complete.
|
||||
- **For-You Priority Windowing (slice 20)** — server-side attention
|
||||
query (Option 3): SQL predicate pushdown, exact-match attention
|
||||
regex, dismissal as string-keyed for queue-derived cards.
|
||||
- **Operator Context-Mode Bindings (slice 09)** — new `rig policy`
|
||||
command surface paired with a daemon-side typed-primitive store
|
||||
(migration `041_rig_policy`). Six modes
|
||||
(`sleep | desk | mobile | away | focus | debug`) bind to four
|
||||
scope tiers (`global_host | rig | workstream | qitem`) with a
|
||||
restate-and-confirm posture so scripts cannot silently apply a
|
||||
binding without explicit `--confirm`. Citation, effective-mode
|
||||
resolve, and `defaults` commands round out the surface.
|
||||
- **Scope Tree Primitive (slice 12)** — new `rig scope` command for
|
||||
operating the substrate scope tree (missions, slices, sub-slices)
|
||||
per `conventions/scope-and-versioning`. Mission-tier
|
||||
(`ls` / `show` / `create`) + slice-tier
|
||||
(`ls` / `show` / `create` / `ship` / `close` / `move`) commands.
|
||||
Auto-mints stable dot-IDs into mission frontmatter; mission
|
||||
templates include `release` / `placeholder` / `mission-notes`.
|
||||
|
||||
## User-Facing Changes
|
||||
|
||||
### Rigbundles First-Class
|
||||
|
||||
`rig bundle` now ships first-class cross-primitive bundling:
|
||||
|
||||
```
|
||||
rig bundle create <spec> -o <path>
|
||||
[--name <n>] [--bundle-version <v>] [--include-packages <refs...>]
|
||||
[--rig-root <r>] [--notes <text>]
|
||||
[--min-daemon-version <ver>] [--min-cli-version <ver>] [--json]
|
||||
rig bundle inspect <path> [--json]
|
||||
rig bundle install <path>
|
||||
[--plan] [--yes] [--target <root>]
|
||||
[--skip-version-check] [--force] [--json]
|
||||
rig bundle history [--rig <name>] [--since <iso>] [--json]
|
||||
```
|
||||
|
||||
Content kinds routed at install: `skills`, `plugins` (hybrid), `workflow_specs`,
|
||||
`context_packs`, `agent_images`. Each kind lands in its canonical
|
||||
library under `$OPENRIG_HOME`; consumer-scan visibility is preserved.
|
||||
|
||||
`bundle.yaml` author manifests are auto-detected when present.
|
||||
Vendoring uses both-sides path containment (source and destination)
|
||||
and symlink-escape protection. Integrity hashing is captured in the
|
||||
bundle manifest.
|
||||
|
||||
`--skip-version-check` and `--force` on `install` are operator-explicit
|
||||
overrides for the install-time daemon/CLI compatibility gate and the
|
||||
install-time conflict gate respectively (NOT recommended for routine
|
||||
use; the overrides exist for known-good operator scenarios).
|
||||
|
||||
`rig bundle history` reads `~/.openrig/bundle-audit.jsonl` — the
|
||||
audit ledger of every install — with optional filters on
|
||||
target rig name and earliest install time.
|
||||
|
||||
### Workspace Doctor (`rig workspace doctor`)
|
||||
|
||||
7-check workspace-readiness diagnostic against the daemon's resolved
|
||||
workspace:
|
||||
|
||||
```
|
||||
rig workspace doctor [--workspace <path>] [--strict] [--json]
|
||||
```
|
||||
|
||||
Checks: workspace root, missions folder, file allowlist, daemon
|
||||
alignment, daemon reload, optional slice docs, MISSION_NOTES presence.
|
||||
|
||||
Default exit-code: non-zero only on `fail`. `--strict` makes
|
||||
warn-or-fail non-zero. The CLI overlays `OPENRIG_FILES_ALLOWLIST`
|
||||
from the operator's shell env so the diagnostic reflects the
|
||||
operator's intended allowlist even when the daemon's env is unchanged.
|
||||
|
||||
### Queue Ergonomics
|
||||
|
||||
`rig queue create` accepts a body from a file or stdin and exposes
|
||||
first-class mission/slice scope:
|
||||
|
||||
```
|
||||
rig queue create --source <s> --destination <d> \
|
||||
(--body <text> | --body-file <path>) \
|
||||
[--mission <id>] [--slice <id>] \
|
||||
[--priority <p>] [--tier <t>] [--tags <csv>] \
|
||||
[--target-repo <name>] [--no-nudge] \
|
||||
[--expires-at <iso>] [--id <qitemId>] [--json]
|
||||
```
|
||||
|
||||
`--body-file -` reads from stdin. `--mission <id>` / `--slice <id>`
|
||||
translate to `mission:<id>` / `slice:<id>` tags (compose with
|
||||
`--tags`).
|
||||
|
||||
### Operator Context-Mode Bindings (`rig policy`)
|
||||
|
||||
```
|
||||
rig policy set <mode> [--scope <scope>] [--qualifier <id>] \
|
||||
[--<field> ...] [--evidence <citation>] \
|
||||
[--confirm] [--bearer <token>] [--json]
|
||||
rig policy show [--json]
|
||||
rig policy effective [--rig <id>] [--workstream <id>] [--qitem <id>] [--json]
|
||||
rig policy cite [--rig <id>] [--workstream <id>] [--qitem <id>]
|
||||
rig policy unset <scope> [qualifier] [--bearer <token>] [--json]
|
||||
rig policy defaults [--json]
|
||||
```
|
||||
|
||||
`set` is restate-only without `--confirm` (the CLI echoes the proposed
|
||||
binding and exits with `exit 2` so scripts cannot silently apply).
|
||||
|
||||
Six modes: `sleep | desk | mobile | away | focus | debug`. Four
|
||||
scopes: `global_host | rig | workstream | qitem`. `--qualifier` is
|
||||
required for `rig | workstream | qitem` scopes and explicitly
|
||||
rejected for `global_host`.
|
||||
|
||||
Operator-edit verbs (`set --confirm`, `unset`) require an operator
|
||||
bearer token (`--bearer` or `OPENRIG_AUTH_BEARER_TOKEN` env).
|
||||
|
||||
### Scope Tree Primitive (`rig scope`)
|
||||
|
||||
```
|
||||
rig scope slice ls [--mission <m>] [--state <s>] [--json]
|
||||
rig scope slice show <slice-path> [--mission <m>] [--json]
|
||||
rig scope slice create <mission> <slug> [--template <k>] [--title <t>] [--json]
|
||||
rig scope slice ship <slice-path> <release-mission> [--mission <m>] [--json]
|
||||
rig scope slice close <slice-path> --reason <r> [--note <t>] [--mission <m>] [--json]
|
||||
rig scope slice move <slice-path> <dest-mission> [--mission <m>] [--json]
|
||||
rig scope mission ls [--json]
|
||||
rig scope mission show <mission> [--json]
|
||||
rig scope mission create <name> [--template <k>] [--id <dot-id>] [--title <t>] [--json]
|
||||
```
|
||||
|
||||
Top-level option `--workspace <path>` overrides workspace root
|
||||
(otherwise inferred from `cwd` or `$OPENRIG_WORK_ROOT`).
|
||||
|
||||
### `rig up` Paper-Cut Fixes
|
||||
|
||||
```
|
||||
rig up <source> [--plan] [--yes] [--cwd <path>] [--target <root>] [--existing] [--json]
|
||||
```
|
||||
|
||||
- Pre-launch failures now return structured HTTP 4xx
|
||||
(`cycle_error` / `preflight_failed` / `validation_failed` /
|
||||
`service_boot_failed`) instead of bare 500.
|
||||
- Failed boots no longer leave orphan rig records on disk.
|
||||
- Path-form invocations default `cwd` to the caller directory.
|
||||
- `--existing` skips library-spec name resolution and treats
|
||||
`<source>` as an existing rig name directly.
|
||||
|
||||
### MISSION_NOTES Durable Pattern (slice 21 FR-3)
|
||||
|
||||
`rig scope mission create` auto-scaffolds `MISSION_NOTES.md` from
|
||||
`conventions/mission-notes/TEMPLATE.md` by default; `--no-mission-notes`
|
||||
opts out (rare). The convention codifies the durable-pattern model
|
||||
documented in workspace skills + canonical templates so missions
|
||||
ship with a uniform top-of-mind notes surface.
|
||||
|
||||
## Operator / Setup Notes
|
||||
|
||||
After upgrading the published CLI:
|
||||
|
||||
```bash
|
||||
npm install -g @openrig/cli@0.3.2
|
||||
rig --version # expect 0.3.2
|
||||
rig daemon stop
|
||||
rig daemon start
|
||||
```
|
||||
|
||||
Migration `041_rig_policy` applies automatically on first post-upgrade
|
||||
daemon start. It is a non-destructive `CREATE TABLE` with no impact on
|
||||
existing data; binding rows are operator-authored at runtime through
|
||||
`rig policy set --confirm`.
|
||||
|
||||
For the new `rig policy` surface: opt-in default-none. With no
|
||||
bindings set, no behavior change. Use `rig policy defaults` to inspect
|
||||
the recommended per-mode 6×7 + default-scope mapping before authoring.
|
||||
|
||||
For the new `rig scope` surface: read-only against workspace by
|
||||
default (`ls`/`show`); authoring verbs (`create`/`ship`/`close`/`move`)
|
||||
operate on the substrate scope tree as advertised. Use `--workspace
|
||||
<path>` to override the resolved workspace root.
|
||||
|
||||
## Known Limitations / 0.3.3 Deferrals
|
||||
|
||||
- **Slice-05 Item-3 sub-scopes deferred to 0.3.3**: agent/port/managed-app
|
||||
collision detection (Item 4.3); broader install-into-existing-rig
|
||||
pathway acceptance (Item 4.4); the `--target-name` CLI flag for
|
||||
install-time rig-name overrides. Design-contingent on the CLI surface
|
||||
decision (A-breaking rename vs A-additive new flag).
|
||||
- **Slice-21 FR-4(d) accepted-queue-state schema deferred to 0.3.3**:
|
||||
the new `accepted` queue state is a schema model change; carried
|
||||
forward per the banked release-triage philosophy.
|
||||
- **Onboarding journey + battle-hardening deferred to 0.3.3**: slices
|
||||
04 (new-user-journey), 08 (hooks-elite), 10 (rig-self), 11
|
||||
(personal-rig) physically moved to the `release-0.3.3` mission tree
|
||||
at wrap.
|
||||
- **Workspace symlink alignment**: the daemon-side workspace-resolver
|
||||
alignment with operator symlinked workspace roots is a follow-up
|
||||
surfaced by slice-21 FR-5 QA; non-blocking for 0.3.2.
|
||||
- **Slice-13 permission-block-routing-architecture remains held**:
|
||||
big-green-light gated by operator review; `rigx-experimental` only;
|
||||
not split-deferred to 0.3.3 (stays held).
|
||||
- **`rig down <name>` still returns HTTP 404** — name-based teardown
|
||||
still doesn't resolve through the daemon down route at v0.3.2; use
|
||||
`rig down <rigId> --delete` instead. Carries forward as known issue.
|
||||
- **`rig view list/show --json` flag inconsistency** — flag scaffolding
|
||||
on the wrapper-layer routing path remains; the daemon's
|
||||
`view show <name>` route returns JSON correctly when invoked directly
|
||||
(per v0.3.1 cutover evidence). Workaround: use human-readable output
|
||||
for now. Wrapper-layer fix is the documented target.
|
||||
|
||||
## Verification Performed
|
||||
|
||||
- `npm run lint` clean.
|
||||
- `npm run build` clean across all workspaces.
|
||||
- `npm run test:repo` green.
|
||||
- Daemon test suite: 3996 PASS at slice-22 close.
|
||||
- TypeScript checks clean on every touched file at per-commit guard.
|
||||
- Per-commit guard CLEAR across every shipped slice;
|
||||
velocity-qa adversarial dogfood + orch heavy pre-merge verify on
|
||||
each merge.
|
||||
- Post-QA-fix deltas (when present) routed back to guard before
|
||||
merge per the banked qa-fix-lands-post-guard pattern.
|
||||
- Review-lead continuous-parallel-review ADVISORY-CLEAN on slice-22
|
||||
close with five POSITIVE observations.
|
||||
|
||||
## Commits Included (highlights)
|
||||
|
||||
The full v0.3.1 → v0.3.2 delta is 143 commits / 203 files /
|
||||
+29,028 insertions / −2,081 deletions. The list below groups
|
||||
load-bearing commits by theme:
|
||||
|
||||
### Rigbundles First-Class
|
||||
- `feat(daemon,cli)`: cross-primitive bundle routing — five content
|
||||
kinds plumbed end-to-end with both-sides path containment +
|
||||
symlink-escape protection + integrity hashing.
|
||||
- `feat(cli)`: `rig bundle` surface — `create` / `inspect` /
|
||||
`install` / `history` subcommands with operator-explicit override
|
||||
flags on install.
|
||||
|
||||
### Workspace + Workflow GA
|
||||
- `feat(daemon,cli)`: workspace `validate --max-files` strict-int
|
||||
regex; workflow `project --exit` enum guard; 3-part error before
|
||||
`client.post`.
|
||||
- `feat(cli)`: 14 new discriminator tests on the validator paths.
|
||||
|
||||
### `rig up <starter>` Paper-Cut Fix-Round
|
||||
- `fix(daemon)`: HTTP 4xx surface for pre-launch failures.
|
||||
- `fix(daemon)`: no orphan rig record on pre-launch failure.
|
||||
- `fix(cli)`: path-form `rig up` defaults `cwd` to caller dir.
|
||||
- `fix(daemon)`: `walkYamlFiles` skips standard noise dirs + stale
|
||||
`workflow_specs` row prune with install-root preservation.
|
||||
|
||||
### Coordination + First-User Setup Fix-Round (slice 21)
|
||||
- `feat(skill)`: coordination-model boot instinct surfaced in
|
||||
`core/openrig-user/SKILL.md`.
|
||||
- `feat(docs)`: first-user workspace + workflow setup teaching.
|
||||
- `feat(cli)`: MISSION_NOTES auto-scaffold via
|
||||
`rig scope mission create`.
|
||||
- `feat(cli)`: `rig queue create --body-file` + first-class
|
||||
`--mission` / `--slice` flags.
|
||||
- `feat(daemon,cli)`: `rig workspace doctor` 7-check diagnostic.
|
||||
|
||||
### Daemon Test Substrate-Path Scrub
|
||||
- `chore(privacy)`: substrate path shape scrubbed from daemon source
|
||||
+ test surface; hook-constants de-duplicated.
|
||||
|
||||
### ConceptCard Data Source
|
||||
- `feat(ui,daemon)`: wire `ConceptCard` to shaped backlog candidates.
|
||||
|
||||
### For-You Priority Windowing
|
||||
- `feat(daemon)`: server-side attention query with SQL predicate
|
||||
pushdown.
|
||||
- `feat(ui)`: dismissal as string-keyed for queue-derived cards.
|
||||
|
||||
### Operator Context-Mode Bindings
|
||||
- `feat(daemon)`: migration `041_rig_policy` + typed-primitive store.
|
||||
- `feat(cli)`: `rig policy` command surface
|
||||
(`set` / `show` / `effective` / `cite` / `unset` / `defaults`).
|
||||
|
||||
### Scope Tree Primitive
|
||||
- `feat(cli)`: `rig scope` command surface — mission + slice tiers.
|
||||
- `feat(cli)`: scope templates (release, placeholder, mission-notes,
|
||||
bug-fix, research, etc.) ship under `dist/lib/scope-templates/`.
|
||||
|
||||
### Privacy and Release Prep
|
||||
- `chore(privacy)`: pre-release scrub of residual founder-attribution
|
||||
comments + an internal-shape substrate-path JSDoc example.
|
||||
|
||||
See `CHANGELOG.md` for the full agent-readable changelog with quick
|
||||
verification commands and operator notes.
|
||||
@@ -1,596 +0,0 @@
|
||||
# OpenRig v0.3.3
|
||||
|
||||
## Summary
|
||||
|
||||
OpenRig v0.3.3 is a usability + honesty release. Two new top-level CLI
|
||||
verbs land (`rig archive`/`rig unarchive` and `rig add`/`rig add-member`),
|
||||
several long-standing paper cuts are retired (large-payload startup
|
||||
delivery, dash-prefixed `send_text`, cmux 0.64.x compatibility, `rig down`
|
||||
by name, golden-path discovery), and three honesty surfaces are tightened
|
||||
to stop misclassifying ambiguous outcomes as success (`rig send --verify`
|
||||
delivery outcomes, Codex restore gates, `rig whoami` peers contract). The
|
||||
For-You feed gets a manage-by-exception pass (drill-to-terminal,
|
||||
decision-band sort, one-click approve). Slice 13's deterministic
|
||||
release-surface parser + skill-binding index ship as product code in
|
||||
service of the auto-feature-rollout system.
|
||||
|
||||
One new migration in 0.3.3: `042_rig_archive`
|
||||
(`ALTER TABLE rigs ADD COLUMN archived_at TEXT` + `idx_rigs_archived`).
|
||||
Append-only, non-destructive, no rigs-row restructure. Existing v0.3.2
|
||||
databases upgrade on first `rig daemon start`.
|
||||
|
||||
## Included In This Release
|
||||
|
||||
- **Large Startup-File Transport (slice 16)** — `TmuxAdapter.sendText`
|
||||
payloads over 100KB now travel via a per-call tmux buffer
|
||||
(`load-buffer` + `paste-buffer -d -r`) instead of being embedded in
|
||||
a single `send-keys -l` argv. Closes the >128KB silent-launch-fail
|
||||
class on Linux (`MAX_ARG_STRLEN`) for large per-seat startup packs.
|
||||
`-r` preserves raw LF so multi-line packs do not early-submit on
|
||||
every newline; the single trailing C-m stays the caller's separate
|
||||
submit. Small payloads keep the exact inline `send-keys -l` command.
|
||||
Temp file + buffer cleanup on success AND paste-error paths; unique
|
||||
names per call so parallel `rig up` seats do not collide.
|
||||
- **`send_text` Inline Dash Sentinel (slice 17)** — inline
|
||||
`tmux send-keys -t <t> -l <text>` now carries a `--` end-of-options
|
||||
sentinel so any startup payload whose content begins with `-`
|
||||
(notably `---` YAML frontmatter — the norm for per-seat packs) is
|
||||
not parsed by tmux as flags. The slice-16 large/buffer path is
|
||||
already immune (content travels via a file, never argv) and is
|
||||
untouched. Inert for non-dash content.
|
||||
- **cmux 0.64.x Compatibility (slice 18)** — cmux 0.64.x renamed the
|
||||
surface identifier (`list-panels --json` rows carry `ref`, not
|
||||
`id`). The transport's `surface.list` normalizer remapped the array
|
||||
key but left row keys untouched, so `surface.sendText` silently
|
||||
failed under the new cmux line. Fixed via a `normalizeSurfaceRow`
|
||||
helper that resolves the handle from `ref ?? surface_ref ??
|
||||
surface_id ?? id`, normalizing every row regardless of array key.
|
||||
One resolution order serves both cmux 0.64.x and 0.63.x — no
|
||||
version-negotiation shim. Adaptation via the same pattern the code
|
||||
already uses for workspace rows and create/split handles.
|
||||
- **`rig archive` Affordance (slice 19)** — new top-level commands
|
||||
`rig archive <rigId>` + `rig unarchive <rigId>`. Archive is
|
||||
non-destructive: rig row is preserved, `archived_at` is set, and a
|
||||
`rig.archived` event fires. Default reads exclude archived (no
|
||||
surprise listings); `rig ps --include-archived`, `?includeArchived=
|
||||
true`, and `?archived=only` opt them back in. The UI gains a lazy
|
||||
collapsible "Archive" section under the localhost host node, fed
|
||||
by a separate archived-only query. `rig up <name>` against an
|
||||
archived-only name is refused honestly with an error pointing at
|
||||
`rig unarchive` — no silent restore, no silent fall-through. The
|
||||
running/degraded archive guard surfaces a 3-part fact / consequence
|
||||
/ action error and accepts `--force` to override. UI query
|
||||
invalidation consumes `rig.archived` / `rig.unarchived` events
|
||||
end-to-end so a CLI archive in one window reactively refreshes
|
||||
another mounted UI.
|
||||
- **`rig add` / `rig add-member` (slice 24)** — new top-level command
|
||||
for the `add_member` converge op. Adds a member to an existing pod
|
||||
in a live rig from a YAML/JSON member fragment file. Built on the
|
||||
new converge spine (`Op` union + differ + `convergeOp`), with
|
||||
imperative CLI sugar over the converge interface (not a bypass).
|
||||
Daemon route `POST /api/rigs/:rigId/pods/:podNamespace/members`
|
||||
maps `AddMemberOutcome` codes to HTTP (404 / 409 / 400 / 201).
|
||||
MCP tool `rig_add` ships in lockstep. Edge validation tightened in
|
||||
the same slice: non-array `edges` is rejected (not silently
|
||||
dropped); edge kinds are validated against the canonical
|
||||
`VALID_EDGE_KINDS` set exported from `rigspec-schema.ts` and
|
||||
reused (not duplicated), so `rig add` edges share the existing
|
||||
graph contract.
|
||||
- **`rig down` Accepts Name-or-Id (slice 22)** — the v0.2.0-era
|
||||
`rig down <name>` HTTP 404 caveat is gone. The resolver now fetches
|
||||
`/api/rigs/summary?includeArchived=true` and id-matches across ALL
|
||||
rigs (archived ids still reach teardown), then name-matches ACTIVE
|
||||
rigs only. Active+archived same-name pair resolves the active rig;
|
||||
archived-only name does not resolve by name. The packaged
|
||||
`openrig-user` skill (specs source + assets/plugins copy +
|
||||
`_canonical` mirror) and the `down.ts` resolver comment are
|
||||
corrected to reflect the real behavior. Historical CHANGELOG /
|
||||
v0.3.1 / v0.3.2 release notes are left intact — the bug genuinely
|
||||
existed at those releases.
|
||||
- **Honest Codex Restore Gate (slice 21 FR-2)** — `verifyResumeLaunch`
|
||||
no longer returns `ok:true` unless the native-resume-probe proves
|
||||
the seat actually resumed. Unresolved operator-action gates (an
|
||||
update that cannot auto-dismiss, trust, model-selection) and a
|
||||
bounded poll that never reaches `resumed` now return `ok:false`
|
||||
with `recovery: attention_required` and last-12-line pane evidence,
|
||||
routed into the existing
|
||||
`HarnessLaunchResult` -> startup-orchestrator
|
||||
`startupStatus: attention_required` -> `ps`/`status` projection —
|
||||
no new state machinery. The working auto-dismiss path is preserved
|
||||
(a skippable update gate still auto-dismisses and continues to
|
||||
success); only UNRESOLVED gates fail loudly. Resolves the 04.3
|
||||
clean-VM `kernel_state bootstrap_failed` failure-mode the herder
|
||||
surfaced.
|
||||
- **`rig send --verify` Honest Delivery Outcomes (slice 99.0.6.3)** —
|
||||
the prior `Verified: no` collapsed two materially different states
|
||||
into one: a message that LANDED (text pasted + Enter submitted,
|
||||
both succeeded) but whose post-send capture raced a TUI redraw,
|
||||
and a message that genuinely did not land. Careful agents paid a
|
||||
manual `rig capture` roundtrip on every send; careless agents read
|
||||
no as failure and double-sent. The three outcomes are now named in
|
||||
the response:
|
||||
- `delivered` — verified succeeded.
|
||||
- `rendered-unconfirmed` — text + Enter both succeeded but the
|
||||
capture could not re-confirm (redraw race, or capture threw).
|
||||
Landed-but-unconfirmable, NOT failure.
|
||||
- `failed` — the transport itself failed.
|
||||
The legacy `Verified: yes/no` line is preserved verbatim
|
||||
(parsers); a new `Delivery:` line carries the named outcome plus,
|
||||
for the middle case, a `rig capture <session>` confirmation
|
||||
pointer. `--json` carries the field through automatically.
|
||||
- **`rig whoami` Peers Contract (slice 99.0.6.1)** — the `peers[]`
|
||||
field was readable as a directionally-edged subset or as host
|
||||
inventory; it is neither. The grounded contract is now stated
|
||||
in-band: `peers[]` is this rig's roster EXCLUDING self (built from
|
||||
`rig.nodes` with only a self-skip — no edge/status/binding
|
||||
filter), `edges{}` is the directional graph, and
|
||||
`rig ps --nodes` is the inventory including self + live state.
|
||||
Additive clarification only — no behavior or shape change.
|
||||
`WhoamiResult` gains a required `peersNote` field carrying the
|
||||
three pointers; the CLI Peers header keeps the literal `Peers:`
|
||||
prefix verbatim (shipped tests grep on it) and adds the in-band
|
||||
clarifier.
|
||||
- **Workflow Instantiate By Name (slice 04.1)** — `rig workflow
|
||||
instantiate <built-in-name>` (e.g. `conveyor`, `basic-loop`)
|
||||
used to fail with `spec_file_missing` because instantiate fed the
|
||||
bare name straight to `WorkflowSpecCache.readThrough` (which
|
||||
treats its argument as a literal file path). Only a raw
|
||||
sourcePath worked — a hidden path that violated the
|
||||
fresh-operator goal: discovery advertised names you then could
|
||||
not use. `WorkflowRuntime.instantiate` now resolves the passed
|
||||
identifier against the seeded spec cache BY NAME first, falling
|
||||
back to literal-sourcePath only when no named spec matches. The
|
||||
cache returns the STORED path verbatim (no source-tree
|
||||
re-derivation), preserving the `dist/builtins` production layout.
|
||||
- **Guided Golden Path State Clarity (slice 04.2)** — the
|
||||
new-operator golden path said `rig workflow list` shows the
|
||||
seeded built-ins, but `rig workflow list` lists workflow
|
||||
INSTANCES; the built-in / spec discovery surface is
|
||||
`rig workflow specs` (built-ins tagged `(built-in)`). A fresh
|
||||
operator following the ordered path before `workflow instantiate
|
||||
<name>` was sent to the wrong command. Corrected in
|
||||
`docs/reference/getting-started.md` and in the CLI's
|
||||
`goldenPathNextSteps()` step 4.
|
||||
- **For-You Manage-By-Exception (slice 20)** — feed-interaction UX
|
||||
on existing signals only (the 0.4.0 attention-detection layer is
|
||||
untouched):
|
||||
- **Drill-to-terminal** — new `FeedCardTerminalDrill` opens the
|
||||
resolved source/author session's terminal PREVIEW directly
|
||||
from a card, by reusing `TerminalPreviewPopover` over
|
||||
`GET /api/sessions/:sessionName/preview`. Honest framing —
|
||||
"terminal preview" / "captured snapshot, not live", never
|
||||
claims live state; when no session resolves, the drill renders
|
||||
DISABLED with an honest title rather than an empty terminal.
|
||||
- **Decision-band sort** — a stable two-band partition lifts
|
||||
action-required + approval cards above progress / observation /
|
||||
shipped within the existing newest-first comparator. NOT a
|
||||
ranking engine (no scores, no card mutation). Applied at the
|
||||
single Feed merge-consumption seam.
|
||||
- **One-click approve (approve-only)** — `VerbActions` gains an
|
||||
additive `oneClickVerbs` prop. APPROVE submits directly on
|
||||
click; deny/route stay select+confirm. Defense in depth: the
|
||||
prop type narrows to `Extract<MissionControlVerb, "approve">`
|
||||
so misuse is a compile error, and a runtime
|
||||
`ONE_CLICK_SAFE_VERBS` allowlist rejects cast-forced
|
||||
`"deny"`/`"route"` at the call site. Reuses the same
|
||||
`performSubmit` mutation path (identical optimistic receipt
|
||||
and held-error behavior).
|
||||
- **CLI Release-Surface Parser (slice 13.1)** — deterministic TypeScript
|
||||
Compiler API extractor that walks the Commander registrations in
|
||||
`packages/cli/src/commands/*.ts` at two git refs and emits a
|
||||
structured release-surface-diff of added commands, added flags, and
|
||||
removed/renamed surface. Resolves both Commander idioms (chained
|
||||
inline subcommands and factory indirection). Emits the
|
||||
REGISTRATION name (`rig-policy.ts` surfaces as `policy`); option
|
||||
name-tokens are taken from `.option()` arg[0] only, so
|
||||
template-literal descriptions never drop an option. Reads batched
|
||||
via one `git cat-file --batch` per ref (fast, offline,
|
||||
deterministic). 3-part honest failure shape; never a silent empty
|
||||
diff. Not registered as a `rig` verb at 0.3.3 (a separate decision)
|
||||
— the module is product code with hermetic test fixtures
|
||||
(including a v0.3.1..v0.3.2 worked example).
|
||||
- **Skill <-> CLI-Surface Binding Index (slice 13.2)** — deterministic
|
||||
offline lookup that joins a release surface-diff to "which skills
|
||||
are affected by this release". Composes with the slice 13.1 parser;
|
||||
invocation-agnostic. Implements the ratified join grammar:
|
||||
component-wise prefix match in either direction (so `up` does not
|
||||
match `update`); conservative over-include bias for the
|
||||
no-false-negative floor. Drops `--version` from the binding index
|
||||
(the canonical grammar is command paths only, not global flags);
|
||||
the skill body still documents `rig --version` as prose. Ships
|
||||
with the v0.3.2-affected-skills regression fixture derived from
|
||||
the corpus.
|
||||
|
||||
## User-Facing Changes
|
||||
|
||||
### `rig archive` and `rig unarchive`
|
||||
|
||||
New top-level commands. Archive is non-destructive: the rig row is
|
||||
preserved, an `archived_at` timestamp is set, and a `rig.archived`
|
||||
event fires.
|
||||
|
||||
```
|
||||
rig archive <rigId> [--force] [--json]
|
||||
rig unarchive <rigId> [--json]
|
||||
```
|
||||
|
||||
`rig unarchive` is always safe (no `--force`, no guard). `rig
|
||||
archive` against a running or degraded rig surfaces a 3-part
|
||||
fact / consequence / action error and accepts `--force` to
|
||||
override.
|
||||
|
||||
Default reads exclude archived rigs:
|
||||
|
||||
```
|
||||
rig ps [--include-archived]
|
||||
GET /api/rigs/summary?includeArchived=true
|
||||
GET /api/rigs/summary?archived=only
|
||||
GET /api/ps?includeArchived=true
|
||||
```
|
||||
|
||||
`rig ps` marks archived rows with `*` and renders a legend. The
|
||||
`--include-archived` flag propagates through cross-host argv.
|
||||
|
||||
`rig up <name>` against an archived-only name is refused honestly
|
||||
with an error pointing at `rig unarchive` (no silent restore, no
|
||||
silent fall-through); `--json` form emits `rig_archived`.
|
||||
|
||||
UI surfaces a lazy collapsible "Archive" section under the
|
||||
localhost host node. The section is fed by a separate archived-only
|
||||
query (`useArchivedRigs`, `?archived=only`), not by client-side
|
||||
filtering of the default list. `rig.archived` / `rig.unarchived`
|
||||
events drive global query invalidation
|
||||
(`["rigs","summary"]` + `["rigs","summary","archived"]` + `["ps"]`)
|
||||
so a CLI archive reactively refreshes other mounted UIs.
|
||||
|
||||
### `rig add` and `rig add-member`
|
||||
|
||||
New top-level command for the `add_member` converge op. Adds a
|
||||
member to an existing pod in a live rig from a YAML/JSON member
|
||||
fragment file:
|
||||
|
||||
```
|
||||
rig add <rigId> <podNamespace> <member-fragment-path> \
|
||||
[--json] [--rig-root <root>]
|
||||
```
|
||||
|
||||
The member fragment tolerates a bare member or a `{ member }`
|
||||
wrapper. Field names follow the spec snake_case shape (`id`,
|
||||
`runtime`, `agent_ref`, `profile`, `cwd`, ...). Optional
|
||||
pod-local `edges` (array of `{from, to, kind}`) is preserved
|
||||
through to the converge op:
|
||||
|
||||
- Present-but-non-array `edges` is REJECTED (not silently dropped):
|
||||
CLI prints a clear error and exits 1 before POST; route returns
|
||||
400 `validation_failed`; domain also returns `validation_failed`
|
||||
as defense in depth.
|
||||
- Edge `kind` is validated against the canonical `VALID_EDGE_KINDS`
|
||||
set exported from `rigspec-schema.ts` and reused (not duplicated).
|
||||
`kind: nonsense` returns 400 `validation_failed` naming the valid
|
||||
set; no edge is persisted.
|
||||
|
||||
Daemon route: `POST /api/rigs/:rigId/pods/:podNamespace/members`.
|
||||
Outcome -> HTTP mapping: `rig_not_found` / `pod_not_found` -> 404;
|
||||
`member_conflict` -> 409; `validation_failed` /
|
||||
`preflight_failed` -> 400; success -> 201 (with per-node launch
|
||||
status in the body). MCP tool `rig_add` ships in lockstep.
|
||||
|
||||
### `rig down` Accepts Name-or-Id
|
||||
|
||||
`rig down <name>` now works. The v0.2.0-era `rig down <name>` HTTP
|
||||
404 caveat is gone.
|
||||
|
||||
```
|
||||
rig down <rigId-or-name> [--delete] [--json]
|
||||
```
|
||||
|
||||
Resolver semantics:
|
||||
|
||||
- `/api/rigs/summary?includeArchived=true` is fetched, then:
|
||||
- id-match across ALL rigs (archived ids still reach teardown);
|
||||
- name-match ACTIVE rigs only (`archivedAt == null`).
|
||||
|
||||
Same-name active+archived pair resolves the ACTIVE rig (not
|
||||
ambiguous). Archived-only name does not resolve by name (use the
|
||||
id, or `rig unarchive` first).
|
||||
|
||||
### Send Text Inline Dash Sentinel (slice 17)
|
||||
|
||||
The internal tmux `send_text` path now carries an explicit `--`
|
||||
end-of-options sentinel before user-supplied content, so tmux no
|
||||
longer parses content beginning with `-` or `--` as its own flag
|
||||
arguments. Companion to the slice 16 large-payload transport fix:
|
||||
|
||||
```
|
||||
rig send <session> "content with -- dashes or - hyphens"
|
||||
```
|
||||
|
||||
delivers literally without the agent having to escape or work
|
||||
around dash-prefixed leading characters (notably `---` YAML
|
||||
frontmatter in per-seat startup payloads). This is a daemon-side
|
||||
adapter fix in `packages/daemon/src/adapters/tmux.ts`; the
|
||||
`rig send` CLI surface itself is unchanged.
|
||||
|
||||
### `rig send --verify` Delivery Outcomes
|
||||
|
||||
`--verify` responses now name the outcome explicitly:
|
||||
|
||||
- `delivered` — verified succeeded.
|
||||
- `rendered-unconfirmed` — text + Enter both succeeded but the
|
||||
post-send capture could not re-confirm (TUI redraw race, or
|
||||
capture threw). The message LANDED; the render is not
|
||||
re-confirmable.
|
||||
- `failed` — the transport itself failed.
|
||||
|
||||
The legacy `Verified: yes/no` line is preserved verbatim
|
||||
(parsers); a new `Delivery:` line carries the named outcome plus,
|
||||
for `rendered-unconfirmed`, a `rig capture <session>`
|
||||
confirmation pointer. `--json` carries the `outcome` field
|
||||
through.
|
||||
|
||||
`exit` codes: `delivered` and `rendered-unconfirmed` exit 0; the
|
||||
middle is not dressed as success or failure. `failed` exits
|
||||
non-zero with HTTP mapping unchanged. Mid-work / wait-for-idle
|
||||
REFUSALS deliberately carry no outcome (nothing was sent; a
|
||||
refusal is not a failed delivery).
|
||||
|
||||
### `rig whoami --json` Peers Contract
|
||||
|
||||
`peers[]` is this rig's roster EXCLUDING self. It is NOT a
|
||||
directionally-edged subset, and it is NOT host inventory.
|
||||
|
||||
- For the directional graph, read `edges{}`.
|
||||
- For the inventory including self + live state, use
|
||||
`rig ps --nodes`.
|
||||
|
||||
`WhoamiResult.peersNote` carries the contract in-band. The CLI
|
||||
Peers header keeps the literal `Peers:` prefix verbatim (shipped
|
||||
parsers grep on it) and adds the clarifier pointing at `edges`
|
||||
and `rig ps --nodes`. `peers[]` name and shape are untouched;
|
||||
this is an additive clarification only.
|
||||
|
||||
### Workflow Instantiate By Name
|
||||
|
||||
`rig workflow instantiate <name>` now resolves built-in names
|
||||
end-to-end:
|
||||
|
||||
```
|
||||
rig workflow instantiate <name-or-source-path> [--cwd <path>] [--json]
|
||||
```
|
||||
|
||||
Built-in names (`conveyor`, `basic-loop`, ...) are resolved
|
||||
against the seeded spec cache BY NAME first; literal source paths
|
||||
remain a fallback for unmatched names (honest 404 if neither
|
||||
matches). Closes the discovery / use divergence where
|
||||
`rig workflow specs` advertised names that `rig workflow
|
||||
instantiate` could not consume.
|
||||
|
||||
### Guided Golden Path Discovery Surface
|
||||
|
||||
The new-operator golden path now points at the correct discovery
|
||||
verb:
|
||||
|
||||
- `rig workflow specs` lists built-in / seeded workflow specs
|
||||
(`(built-in)` tagged). USE THIS to discover names before
|
||||
`rig workflow instantiate <name>`.
|
||||
- `rig workflow list` lists workflow INSTANCES (created from
|
||||
specs). Empty for a fresh operator.
|
||||
|
||||
Corrected in `docs/reference/getting-started.md` and in the
|
||||
CLI's `setup` golden-path text.
|
||||
|
||||
### For-You Manage-By-Exception
|
||||
|
||||
Feed-interaction UX on existing signals (the 0.4.0
|
||||
attention-detection layer is untouched):
|
||||
|
||||
- **Drill to terminal preview** — each card's footer carries a
|
||||
drill that opens the resolved source/author session's terminal
|
||||
PREVIEW via `GET /api/sessions/:sessionName/preview`. Labelled
|
||||
"terminal preview" / "captured snapshot, not live" — never
|
||||
claims live state. Disabled with an honest title when no
|
||||
session resolves.
|
||||
- **Decision-band sort** — action-required + approval cards lift
|
||||
above progress / observation / shipped within the existing
|
||||
newest-first comparator. Stable two-band partition; not a
|
||||
ranking engine.
|
||||
- **One-click approve** — APPROVE submits directly on click; deny
|
||||
and route stay select+confirm. Compile-time + runtime guards
|
||||
prevent the one-click path from being applied to non-approve
|
||||
verbs (`ONE_CLICK_SAFE_VERBS = {"approve"}`).
|
||||
|
||||
## Operator / Setup Notes
|
||||
|
||||
After upgrading the published CLI:
|
||||
|
||||
```bash
|
||||
npm install -g @openrig/cli@0.3.3
|
||||
rig --version # expect 0.3.3
|
||||
rig daemon stop
|
||||
rig daemon start
|
||||
```
|
||||
|
||||
Migration `042_rig_archive` applies automatically on first
|
||||
post-upgrade daemon start. It is `ALTER TABLE rigs ADD COLUMN
|
||||
archived_at TEXT` plus `idx_rigs_archived` — append-only,
|
||||
non-destructive, no rigs-row restructure / rebuild / drop.
|
||||
Existing rows are unaffected.
|
||||
|
||||
For the new `rig archive` surface: default reads still exclude
|
||||
archived rigs at the daemon layer. With no rigs archived, no
|
||||
behavior change. `rig ps --include-archived`, the
|
||||
`?includeArchived=true` / `?archived=only` query params, and the
|
||||
UI's lazy Archive section opt archived rigs back in.
|
||||
|
||||
For the new `rig add` surface: the member fragment file is a YAML
|
||||
or JSON document using the rig spec's snake_case field names
|
||||
(same authoring format as a `RigSpec` pod member). The MCP
|
||||
`rig_add` tool accepts the same fragment shape.
|
||||
|
||||
For `rig down <name>`: previously-documented agent workarounds
|
||||
that resolved the rig id by hand before calling `rig down` no
|
||||
longer need to do that step. The id-based form continues to work
|
||||
unchanged.
|
||||
|
||||
## Known Limitations / 0.3.3 Deferrals
|
||||
|
||||
- **Slice-21 FR-1 (native Codex session-id hook)**: scope-tipped
|
||||
to 0.4.0 after the build-time forensic. FR-2 (honest restore
|
||||
gate) ships alone in 0.3.3.
|
||||
- **Slice-13 component 3 (auto-rollout dispatcher)**: the slice
|
||||
13 vertical's dispatcher / rollout-invocation layer is the
|
||||
skill-layer landing for this release, not product code. The
|
||||
product-code halves (13.1 parser + 13.2 binding index) ship in
|
||||
0.3.3; invocation is intentionally out of the shipped runtime
|
||||
bundle.
|
||||
- **Slice-05 sub-scopes from 0.3.2**: agent / port / managed-app
|
||||
collision detection (Item 4.3); broader install-into-existing-rig
|
||||
pathway acceptance (Item 4.4); the `--target-name` CLI flag for
|
||||
install-time rig-name overrides. Carried forward; CLI-surface
|
||||
decision (A-breaking rename vs A-additive flag) still pending.
|
||||
- **Slice-21 FR-4(d) accepted-queue-state schema**: deferred from
|
||||
0.3.2; new `accepted` queue state is a schema model change.
|
||||
Carried forward.
|
||||
- **Onboarding journey + battle-hardening**: slices 04
|
||||
(new-user-journey), 08 (hooks-elite), 10 (rig-self), 11
|
||||
(personal-rig) physically moved to the `release-0.3.3` mission
|
||||
tree at 0.3.2 wrap; the 0.3.3 cut focused on usability + honesty
|
||||
surfaces ahead of the onboarding journey. Carried forward to a
|
||||
later release.
|
||||
- **Workspace symlink alignment**: daemon-side workspace-resolver
|
||||
alignment with operator symlinked workspace roots remains a
|
||||
follow-up; non-blocking for 0.3.3.
|
||||
- **Slice-13 permission-block-routing-architecture remains held**:
|
||||
big-green-light gated by operator review; `rigx-experimental`
|
||||
only; not split-deferred (stays held).
|
||||
- **`rig view list/show --json` flag inconsistency** — wrapper-layer
|
||||
routing path remains; the daemon's `view show <name>` route
|
||||
returns JSON correctly when invoked directly. Workaround:
|
||||
human-readable output for now. Wrapper-layer fix is the
|
||||
documented target.
|
||||
|
||||
## Verification Performed
|
||||
|
||||
- `npm run lint` clean.
|
||||
- `npm run build` clean across all workspaces.
|
||||
- TypeScript checks clean on every touched file at per-commit
|
||||
guard across every shipped slice.
|
||||
- Per-slice focused-suite tests green:
|
||||
- Slice 16: tmux-adapter buffer path (small + large) +
|
||||
Claude/Codex adapters large-payload delivery.
|
||||
- Slice 17: tmux-adapter dash-prefix discriminator
|
||||
(`-l -- '<text>'`); 77/77 in the touched suite.
|
||||
- Slice 18: cmux 130/130 unit tests; VM e2e 0.64.x launch +
|
||||
0.63.x non-regression.
|
||||
- Slice 19: archive route / repo / projection + UI
|
||||
`topology-archive-section` + `global-events` (archived /
|
||||
unarchived invalidation); AC-4 host-scoped no-cross-host-leak;
|
||||
AC-8 archive-vs-down-delete non-destruction discriminator.
|
||||
- Slice 22: down 22/22 (id-exact-first; archived-id reaches
|
||||
teardown; active+archived same-name -> active; archived-only
|
||||
name halts not_found; AC-3 active-active discriminator).
|
||||
- Slice 21 FR-2: 45/45 in the verifyResumeLaunch suite
|
||||
including the unresolved-gate discriminator, trust-gate,
|
||||
model-selection-gate, and poll-exhaustion coverage.
|
||||
- Slice 24: add-member-route 8/8; add (CLI) 8/8; edge
|
||||
validation +6 (domain + route + CLI); cli index/expand/MCP +
|
||||
daemon rig-expansion green (41 cli + 49 daemon).
|
||||
- Slice 99.0.6.3: session-transport + transport-routes 76/76;
|
||||
cli send 12/12.
|
||||
- Slice 99.0.6.1: whoami-service 15/15; cli whoami 20/20.
|
||||
- Slice 04.1: workflow-spec-cache + workflow-routes 44/44.
|
||||
- Slice 04.2: setup AC-1 asserts the path references
|
||||
`rig workflow specs` and does not use `rig workflow list`.
|
||||
- Slice 20: feed-classifier 17, attention-feed 17,
|
||||
verb-actions-one-click 6, verb-actions-optimistic-error 7,
|
||||
feed-card-terminal-drill 4, feed-decision-band-sort 5,
|
||||
feed-card-dismiss 12, activity-feed 25, session-preview-pane
|
||||
3 — 102/102 touched + adjacent.
|
||||
- Slice 13.1: release-surface 10/10; sample byte-identical
|
||||
across two runs (determinism).
|
||||
- Slice 13.2: affected-skills 12/12.
|
||||
- Per-commit guard CLEAR across every shipped slice;
|
||||
velocity-qa adversarial dogfood + dual rev1 CLEAR on each
|
||||
merge.
|
||||
- The cumulative-workspace test runs surface the documented
|
||||
pre-existing baseline (cmux / preflight / archived_at-harness /
|
||||
@tanstack dep cascade); ZERO regressions versus the v0.3.2 base
|
||||
on every shipped slice.
|
||||
|
||||
## Commits Included (highlights)
|
||||
|
||||
The full v0.3.2 -> v0.3.3 delta is 56 commits / 93 files /
|
||||
+6,669 insertions / -238 deletions. The list below groups
|
||||
load-bearing commits by theme:
|
||||
|
||||
### Startup Transport + Cmux Compatibility
|
||||
- `fix(daemon)`: deliver large startup `send_text` via tmux
|
||||
buffer, not argv (slice 16).
|
||||
- `fix(daemon)`: add `--` end-of-options sentinel to inline
|
||||
`send_text` (slice 17).
|
||||
- `fix(daemon)`: cmux 0.64.x surface-listing `ref` / `id`
|
||||
normalization (slice 18).
|
||||
|
||||
### `rig archive` Affordance
|
||||
- `feat(daemon)`: archive vertical — migration `042_rig_archive`,
|
||||
repository filter, projection filter, routes
|
||||
`/api/rigs/:id/archive` + `/unarchive`,
|
||||
`?includeArchived=true` / `?archived=only` query params.
|
||||
- `feat(cli,ui)`: `rig archive` / `rig unarchive` commands,
|
||||
`rig ps --include-archived`, `rig up` archived-name refusal,
|
||||
UI archived-only hook + lazy "Archive" section under localhost
|
||||
host node.
|
||||
- `fix(ui)`: wire `rig.archived` / `rig.unarchived` into global
|
||||
query invalidation.
|
||||
|
||||
### `rig add` / `rig add-member`
|
||||
- `feat(daemon)`: `add_member` converge op on
|
||||
`PodRigInstantiator`; topology-converge spine
|
||||
(`Op` union + differ + `convergeOp`) scaffold.
|
||||
- `feat(cli,daemon)`: `rig add` HTTP route + CLI command for the
|
||||
`add_member` converge op.
|
||||
- `feat(cli)`: `rig_add` MCP tool.
|
||||
- `fix(daemon,cli)`: honest edge validation — reject non-array
|
||||
edges + non-canonical kinds (shared `VALID_EDGE_KINDS` with
|
||||
rigspec schema).
|
||||
|
||||
### `rig down` Name-or-Id
|
||||
- `fix(cli,docs)`: `rig down` resolves by name-or-id;
|
||||
`?includeArchived=true` summary fetch; archived-id reaches
|
||||
teardown; name-match active only; packaged-skill caveat
|
||||
retired across specs source + assets/plugins copy +
|
||||
`_canonical` mirror.
|
||||
|
||||
### Honest Outcomes
|
||||
- `feat(daemon)`: honest Codex restore gate — unresolved gates
|
||||
are `attention_required`, not launch success (slice 21 FR-2).
|
||||
- `feat(daemon,cli)`: `rig send --verify` honest delivery
|
||||
outcomes — `delivered` / `rendered-unconfirmed` / `failed`.
|
||||
- `feat(daemon,cli,docs)`: `rig whoami` peers contract stated
|
||||
in-band — `peersNote` field + CLI clarifier; `peers[]` shape
|
||||
unchanged.
|
||||
|
||||
### Workflow Discovery + Instantiate
|
||||
- `fix(daemon)`: resolve workflow instantiate by discovered name
|
||||
(slice 04.1 AC-3).
|
||||
- `fix(cli,docs)`: golden path points to `rig workflow specs`
|
||||
for built-in discovery (slice 04.2 rev1-r2).
|
||||
|
||||
### For-You Manage-By-Exception
|
||||
- `feat(ui)`: For-You drill-to-terminal + decision-band sort +
|
||||
one-click approve (slice 20).
|
||||
- `fix(ui)`: enforce approve-only one-click in code — narrowed
|
||||
type + runtime `ONE_CLICK_SAFE_VERBS` allowlist.
|
||||
|
||||
### Auto-Feature-Rollout (product-code halves)
|
||||
- `feat(cli)`: CLI release-surface parser POC (slice 13.1) —
|
||||
deterministic Commander-registration extractor; sample diff
|
||||
fixture; v0.3.1..v0.3.2 worked example.
|
||||
- `feat(cli)`: skill <-> CLI-surface binding-index lookup
|
||||
(slice 13.2 component 2) — composes with 13.1; ratified join
|
||||
grammar; v0.3.2-affected-skills regression fixture.
|
||||
- `fix(cli)`: drop `--version` flag token from the binding
|
||||
index (slice 13.2 guard B1).
|
||||
|
||||
See `CHANGELOG.md` for the agent-readable changelog with quick
|
||||
verification commands and operator notes.
|
||||
@@ -1,593 +0,0 @@
|
||||
# OpenRig v0.3.4
|
||||
|
||||
## Summary
|
||||
|
||||
OpenRig v0.3.4 is a recovery + resilience release. Two new top-level CLI
|
||||
verbs land (`rig start` and `rig reconcile-session`), `rig up` flips
|
||||
from fresh-by-default to resume-original-by-default with `--fresh
|
||||
<seats...>` as the explicit per-seat opt-in, the restore status surface
|
||||
collapses every honest outcome into a named five-term vocabulary
|
||||
(`resumed` / `fresh-primed` / `awaiting-decision` / `attention_required`
|
||||
/ `failed`) across `rig up` / `rig restore` / `rig ps`, and a periodic
|
||||
snapshot scheduler ships as the crash-insurance floor under
|
||||
event-driven and teardown snapshots. A handful of long-standing
|
||||
recovery paper cuts are retired in the same cut: pod-aware narrow
|
||||
launch leaves dead-end-land for a node-granular managed partial
|
||||
restore through `rig launch`, a stuck `attention_required` seat now
|
||||
clears through an evidence-gated `rig seat clear-attention` rather
|
||||
than hand-edited SQLite, the Codex profile-v2 preflight stops
|
||||
misclassifying invalid TOML as a legacy-profile reason, the cmux
|
||||
launch-readiness gate surfaces honest partial workspace state, and a
|
||||
slow Codex resume no longer gets mis-categorized.
|
||||
|
||||
No new schema-bumping migrations in 0.3.4. Existing v0.3.3 databases
|
||||
upgrade by running `rig daemon start` on the new daemon.
|
||||
|
||||
## Included In This Release
|
||||
|
||||
- **`rig start` (slice 01)** — new top-level recovery entry point.
|
||||
One command that sequences daemon-start, kernel readiness wait,
|
||||
restore-usable candidate listing, picker or headless flag
|
||||
selection, and per-rig restore + reconcile. Re-codes nothing
|
||||
underneath: it sequences existing primitives. Flags `--last`,
|
||||
`--all`, `--rigs <names...>`, `--json`. Candidate listing and
|
||||
apply are both id-grounded against `/api/rigs/:id/up` (the
|
||||
same-name-rigs class never reaches the name-based `/api/up`
|
||||
route).
|
||||
- **`rig up` Resume-By-Default (slice 02)** — `rig up <existing-rig>`
|
||||
now resumes original sessions by default. `--fresh <seats...>`
|
||||
becomes the explicit per-seat opt-in for operation B (deliberate
|
||||
fresh-prime). Previously the default was fresh-prime; agents had
|
||||
to know to ask for resume out-of-band. The seat-level outcome
|
||||
rides the five-term vocabulary below; `awaiting-decision` is the
|
||||
honest zero-session state when the daemon cannot resume and the
|
||||
operator has not opted into fresh.
|
||||
- **`rig reconcile-session` (slice 03)** — new top-level command.
|
||||
Adopts a LIVE, hand-resumed canonical session back into its
|
||||
persisted node without launching, relaunching, killing, replaying
|
||||
startup, pressing resume menus, compacting, or typing into the
|
||||
pane. The repair for "I manually resumed the seat; the daemon
|
||||
still shows it down." Same node id, no re-key; reports projection
|
||||
drift honestly; conversation continuity is never claimed.
|
||||
- **`rig up --plan` Read-Only Restore Preview (slice 04)** —
|
||||
`rig up <existing-rig> --plan` returns a read-only restore
|
||||
preview keyed by the five-term vocabulary and an honest async
|
||||
timeout. No mutation; no silent claims of resumability when the
|
||||
daemon cannot prove it.
|
||||
- **Five-Term Restore Status Vocabulary (slice 06)** — the prior
|
||||
2-3 term collapsed model is replaced across `rig up`,
|
||||
`rig restore`, and `rig ps`:
|
||||
- `resumed` — original session continuity proven.
|
||||
- `fresh-primed` — deliberate fresh-prime (operation B); a brand
|
||||
new session was started instead of resumed.
|
||||
- `awaiting-decision` — daemon could not resume and operator has
|
||||
not opted into fresh; ZERO session started. The honest
|
||||
zero-session state, not a silent failure.
|
||||
- `attention_required` — seat is live or parked but needs
|
||||
operator action (auth gate, model-selection menu, trust
|
||||
prompt, stuck recovery). NEVER `failed`.
|
||||
- `failed` — the launch transport itself failed.
|
||||
- **Codex Profile-V2 Preflight (slice 07)** — profile-load check
|
||||
on profile-bearing launch and restore surfaces. Legacy-profile
|
||||
detection narrowed to legacy-specific patterns only (`contains
|
||||
legacy`, `[profiles.<name>]`, `cannot be used while.*legacy`,
|
||||
`legacy profile selector`); the prior generic match against
|
||||
`failed to load configuration` was also catching invalid-TOML
|
||||
stderr and giving the wrong migration hint. Invalid TOML now
|
||||
surfaces the actual parse reason (up to 3 stderr lines) with a
|
||||
TOML-validity hint.
|
||||
- **cmux Launch Readiness (slice 08)** — launch path no longer
|
||||
silently produces a partial cmux workspace. When cmux comes up
|
||||
with a subset of expected windows / panes, the seat surfaces an
|
||||
honest partial-workspace state with a one-click open-missing
|
||||
affordance instead of being reported as launched-clean.
|
||||
- **Periodic Snapshots (slice 09)** — `snapshots.periodic` config
|
||||
family plus a daemon-side `PeriodicSnapshotScheduler`. Every
|
||||
enabled rig captures an `auto-periodic` snapshot on interval and
|
||||
the repository prunes by retention-keep. Provides a true
|
||||
crash-insurance floor — `auto-periodic` and `auto-pre-down`
|
||||
compete on freshness in the same restore selector (the newer
|
||||
wins), so a daemon crash between teardown snapshots no longer
|
||||
costs an arbitrary amount of lifecycle state. Last-snapshot /
|
||||
floor surfaced in `rig ps` / status.
|
||||
- **`rig seat clear-attention` (slice 10)** — new subcommand on
|
||||
`rig seat`. Evidence-gated, operator-attested, audited reconcile
|
||||
of a stuck `attention_required` seat back to `ready`. Replaces
|
||||
the prior hand-edit-SQLite / fake-clear pattern that agents
|
||||
reached for when a seat got stuck. The audit row records who
|
||||
cleared, from-state, the evidence path, and any operator
|
||||
attestation; `--reason <text>` is the operator-attestation
|
||||
override for the evidence gate.
|
||||
- **Node-Granular Managed Partial Restore (slice 11)** — `rig
|
||||
launch <rigId> <nodeRef>` and `rig launch <rigId> --seats <a,b>`
|
||||
relaunch a seat or subset by logical id through the
|
||||
orchestration layer. Retires the v0.3.x-era
|
||||
`pod_aware_launch_unsupported` dead-end and the
|
||||
"use rig up instead" workaround that lost per-seat control.
|
||||
Held seats carry a `held-reason`; failed targets surface as
|
||||
`failed (liveness unknown)`; already-running seats are reported,
|
||||
not relaunched.
|
||||
- **Slow Codex Resume Classification Fix (slice 13)** — internal
|
||||
classification tweak for slow-resume Codex sessions: a seat that
|
||||
was genuinely resuming but slowly was previously mis-categorized
|
||||
by `verifyResumeLaunch`. Now correctly classified through the
|
||||
same five-term vocabulary.
|
||||
- **Pod-Aware Claude Resume-Selection Menu (slice 05 rev1)** —
|
||||
follow-on to 0.3.3 slice 21 FR-2: `ClaudeCodeAdapter.verifyResumeLaunch`
|
||||
now treats a Claude resume-selection menu the same way it treats
|
||||
the Codex unresolved-gate case — returns immediately with
|
||||
`recovery: attention_required` and last-12-line pane evidence,
|
||||
never sends a numeric selection keystroke, and never lets the
|
||||
loop time out to a generic failure.
|
||||
|
||||
## User-Facing Changes
|
||||
|
||||
### `rig start` — Recovery Entry Point
|
||||
|
||||
New top-level command. Starts the daemon, waits for the kernel, lists
|
||||
restore-usable rigs, and applies restore + reconcile through the
|
||||
existing primitives:
|
||||
|
||||
```
|
||||
rig start Interactive: daemon + kernel + pick-and-restore
|
||||
rig start --last Headless: restore all rigs that were last running
|
||||
rig start --all Headless: restore all rigs with restore-usable snapshots
|
||||
rig start --rigs <name> [<name>...] Headless: restore only the named rigs
|
||||
rig start --json JSON output for agents
|
||||
```
|
||||
|
||||
Listing and apply are both id-grounded against
|
||||
`POST /api/rigs/:id/up`. Same-name rigs surface as separate
|
||||
candidates; selection carries the candidate's `rigId` end-to-end so
|
||||
the name-based `/api/up` route is never consulted (no
|
||||
`ambiguous_name` 409 in the recovery path).
|
||||
|
||||
`rig start` is sequencing-only; it does not invent recovery
|
||||
semantics. The per-rig restore call is the same `/api/rigs/:id/up`
|
||||
that `rig up <existing>` uses, and seat-level outcomes carry the
|
||||
same five-term vocabulary.
|
||||
|
||||
### `rig up` — Resume Original By Default
|
||||
|
||||
`rig up <existing-rig>` resumes original sessions by default.
|
||||
`--fresh <seats...>` is the per-seat opt-in for deliberate
|
||||
fresh-prime (operation B):
|
||||
|
||||
```
|
||||
rig up <existing-rig> Resume original sessions (default)
|
||||
rig up --existing <name> --fresh dev-impl Deliberately fresh-prime dev-impl only
|
||||
rig up <existing-rig> --plan Read-only restore preview (no mutation)
|
||||
```
|
||||
|
||||
- Seats whose original session resumes report `resumed`.
|
||||
- Seats opted into `--fresh` report `fresh-primed`.
|
||||
- Seats the daemon cannot resume and the operator has not opted
|
||||
into fresh report `awaiting-decision` — ZERO session started.
|
||||
Headless callers see the explicit hint `rig up --existing
|
||||
<source> --fresh <logical-id>`; TTY callers are offered a
|
||||
per-seat `[y/N]` prompt before any fresh-prime is started.
|
||||
- Seats live or parked but needing operator action (auth gate,
|
||||
model selection, trust prompt, stuck recovery) report
|
||||
`attention_required` — never silently re-classified as `failed`.
|
||||
- Only transport-level failure reports `failed`.
|
||||
|
||||
The prior fresh-by-default behavior is gone. If a workflow relied on
|
||||
implicit fresh, name `--fresh <seats...>` explicitly.
|
||||
|
||||
### `rig up --plan` — Read-Only Restore Preview
|
||||
|
||||
```
|
||||
rig up <existing-rig> --plan [--json]
|
||||
```
|
||||
|
||||
Returns the restore plan without mutating: per-node intended action
|
||||
(resume / fresh-prime / awaiting-decision), the snapshot the plan
|
||||
would consume, and whether the current state would be captured before
|
||||
mutation. The plan path carries an honest async timeout — when the
|
||||
preview cannot complete within bound, the response says so rather
|
||||
than claiming a clean plan.
|
||||
|
||||
### `rig reconcile-session` — Adopt a Hand-Resumed Session
|
||||
|
||||
New top-level command. Use after manually resuming a seat (e.g.
|
||||
`claude --resume <id>` / `codex resume <id>`) inside its canonical
|
||||
tmux session: the daemon still shows the seat down. Reconcile binds
|
||||
the live process to its OWN persisted node and updates the
|
||||
projection so `rig ps` / topology / `rig send` / `rig capture` /
|
||||
queue routing work again. It NEVER launches, relaunches, kills,
|
||||
replays startup, presses resume menus, compacts, or types into the
|
||||
pane.
|
||||
|
||||
```
|
||||
rig reconcile-session <session> Auto-resolve target node
|
||||
rig reconcile-session <session> --rig <rigId> --node <logicalId> Disambiguate
|
||||
rig reconcile-session <session> --no-launch Explicit (default mode)
|
||||
rig reconcile-session <session> --json JSON output for agents
|
||||
```
|
||||
|
||||
`--rig` and `--node` must be provided together (disambiguation).
|
||||
Same node id, no re-key. Anything the reconcile could not prove is
|
||||
reported as projection drift (a list of unproven metadata fields);
|
||||
conversation continuity is reported as a status string, never
|
||||
claimed as proven.
|
||||
|
||||
### Five-Term Restore Status Vocabulary
|
||||
|
||||
The seat-level status field on `rig up`, `rig restore`, and `rig ps`
|
||||
now carries one of five values:
|
||||
|
||||
| Status | Meaning |
|
||||
| --------------------- | -------------------------------------------------------------------------------------------------- |
|
||||
| `resumed` | Original session continuity proven by the native-resume probe. |
|
||||
| `fresh-primed` | Operator opted into a deliberate fresh-prime (operation B); a brand new session started. |
|
||||
| `awaiting-decision` | Daemon could not resume and operator has not opted into fresh. ZERO session started. |
|
||||
| `attention_required` | Seat is live or parked but needs operator action (auth, model selection, trust, stuck recovery). |
|
||||
| `failed` | The launch transport itself failed. |
|
||||
|
||||
`awaiting-decision` is new and replaces the prior pattern where a
|
||||
zero-session outcome was either misreported as success or as
|
||||
failure. `attention_required` covers the broader live-but-stuck
|
||||
class; a live or parked seat is NEVER reported as `failed`.
|
||||
|
||||
### `rig seat clear-attention` — Audited Stuck-Seat Recovery
|
||||
|
||||
Subcommand on `rig seat`. Evidence-gated, operator-attested, audited
|
||||
reconcile of a stuck `attention_required` seat back to `ready`:
|
||||
|
||||
```
|
||||
rig seat clear-attention <session>
|
||||
rig seat clear-attention <session> --reason "<operator attestation>"
|
||||
rig seat clear-attention <session> --json
|
||||
```
|
||||
|
||||
- Without `--reason`, the clear requires evidence the seat is
|
||||
actually back to a clean state (the daemon-side gate).
|
||||
- `--reason <text>` is the operator-attestation override; the
|
||||
audit row records the attestation string verbatim.
|
||||
- Output: `Cleared <session>: <from> -> ready (<clearedBy>)`. The
|
||||
audit log captures session, from-state, gate-or-attestation, and
|
||||
operator address.
|
||||
|
||||
Replaces the prior hand-edit-SQLite / fake-clear pattern. The seat's
|
||||
node id is unchanged.
|
||||
|
||||
### Node-Granular Managed Partial Restore
|
||||
|
||||
`rig launch` works for single-seat and subset relaunch on a running
|
||||
rig through the orchestration layer:
|
||||
|
||||
```
|
||||
rig launch <rigId> <nodeRef> Single seat (logical id or node id)
|
||||
rig launch <rigId> --seats <a,b,c> Subset (comma-separated logical ids)
|
||||
rig launch <rigId> --seats <a,b> --hold-reason "<text>" Reason for held non-targets
|
||||
rig launch <rigId> --seats <a,b> --json
|
||||
```
|
||||
|
||||
- Single-target: `POST /api/rigs/:rigId/nodes/:nodeRef/launch`.
|
||||
- Subset: `POST /api/rigs/:rigId/nodes/launch-subset`. Reports
|
||||
`launched`, `held` (with reason), `alreadyRunning`, and
|
||||
`failedTargets` (liveness unknown) separately — partial outcomes
|
||||
are never collapsed.
|
||||
|
||||
Retires the `pod_aware_launch_unsupported` dead-end and the
|
||||
"use rig up instead" workaround. Use `rig launch` for per-seat or
|
||||
per-subset relaunch on a running rig; `rig up <existing>` remains
|
||||
the whole-rig restore entry.
|
||||
|
||||
### Periodic Snapshots
|
||||
|
||||
The crash-insurance floor under event-driven and teardown
|
||||
snapshots. New `snapshots.periodic` settings family:
|
||||
|
||||
| Key | Default | Meaning |
|
||||
| -------------------------------------- | ------- | ------------------------------------------ |
|
||||
| `snapshots.periodic.enabled` | `true` | Master switch |
|
||||
| `snapshots.periodic.interval_seconds` | `300` | Snapshot interval per enabled rig |
|
||||
| `snapshots.periodic.retention_keep` | `10` | Per-rig `auto-periodic` retention count |
|
||||
|
||||
Snapshots are captured with kind `auto-periodic`; the repository
|
||||
prunes by `retention_keep` per rig. Restore selection treats
|
||||
`auto-periodic` and `auto-pre-down` symmetrically — the newer of
|
||||
the two wins, so a daemon crash between teardown snapshots no
|
||||
longer loses arbitrary lifecycle state. Last-snapshot / floor is
|
||||
surfaced in `rig ps` / status so an operator can see the floor
|
||||
at a glance.
|
||||
|
||||
Tune via the settings store (`rig config set ...`) or rely on
|
||||
defaults; the scheduler reads at daemon startup and respects
|
||||
`snapshots.periodic.enabled = false` as a master switch.
|
||||
|
||||
### Codex Profile-V2 Preflight
|
||||
|
||||
The profile-load check on profile-bearing launch and restore
|
||||
surfaces is now honest about WHICH failure it sees:
|
||||
|
||||
- **Legacy-profile detection narrowed**: matches `contains legacy`,
|
||||
`[profiles.<name>]`, `cannot be used while.*legacy`, and `legacy
|
||||
profile selector` only. The prior generic match against `failed
|
||||
to load configuration` was also catching invalid-TOML stderr.
|
||||
- **Invalid TOML surfaces the parse reason**: up to 3 stderr lines
|
||||
(e.g. `expected newline`), with a TOML-validity hint instead of
|
||||
a wrong migration hint pointing at `[profiles.<profile>]`.
|
||||
|
||||
The auth-refusal projection path is unchanged; this is a
|
||||
classification fix in the preflight discriminator.
|
||||
|
||||
### cmux Launch Readiness
|
||||
|
||||
The cmux launch path no longer silently produces a partial
|
||||
workspace. When cmux comes up with a subset of expected windows or
|
||||
panes, the seat surfaces an honest partial-workspace state with a
|
||||
one-click open-missing affordance instead of being projected as
|
||||
launched-clean.
|
||||
|
||||
### Slow Codex Resume Classification
|
||||
|
||||
Internal classification tweak in `verifyResumeLaunch` for slow but
|
||||
genuinely-resuming Codex sessions. Previously the slow path got
|
||||
mis-categorized through the unresolved-gate branch; now it
|
||||
correctly classifies through the same five-term vocabulary and
|
||||
reaches `resumed` when the readiness probe confirms it.
|
||||
|
||||
### Pod-Aware Claude Resume-Selection Menu
|
||||
|
||||
Follow-on to 0.3.3 slice 21 FR-2. `ClaudeCodeAdapter.verifyResumeLaunch`
|
||||
now treats a Claude resume-selection menu the same way it treats
|
||||
the Codex unresolved-gate case: returns immediately with
|
||||
`recovery: attention_required` and last-12-line pane evidence on
|
||||
both the inner poll loop and the final-probe exit path. Zero
|
||||
numeric selection keystrokes are ever sent.
|
||||
|
||||
## What to STOP Using
|
||||
|
||||
These patterns are retired by 0.3.4. Stop reaching for them; the
|
||||
named replacement is the supported path:
|
||||
|
||||
- **STOP** treating `rig up <existing-rig>` as fresh-by-default.
|
||||
Resume-original is now default. Use `--fresh <seats...>` when a
|
||||
deliberate fresh-prime is the goal (operation B).
|
||||
- **STOP** reading a stuck or parked seat as `failed`. A live or
|
||||
parked seat carries `attention_required`; only the transport
|
||||
itself failing is `failed`. The honest zero-session state is
|
||||
`awaiting-decision`, not `failed`.
|
||||
- **STOP** reaching for `pod_aware_launch_unsupported` workarounds
|
||||
or "use `rig up` instead" for per-seat relaunch. Use `rig launch
|
||||
<rigId> <nodeRef>` or `rig launch <rigId> --seats <a,b>`.
|
||||
- **STOP** hand-editing SQLite or fake-clearing a stuck
|
||||
`attention_required` seat. Use `rig seat clear-attention
|
||||
<session>` (evidence-gated) or `rig seat clear-attention
|
||||
<session> --reason "<attestation>"` (operator-attested,
|
||||
audited).
|
||||
- **STOP** relying only on event-driven or teardown snapshots for
|
||||
crash safety. The periodic snapshot scheduler is the floor;
|
||||
tune `snapshots.periodic.interval_seconds` /
|
||||
`snapshots.periodic.retention_keep` to taste.
|
||||
- **STOP** classifying invalid TOML as a legacy-profile problem.
|
||||
The Codex profile-v2 preflight now surfaces the actual TOML
|
||||
parse reason; legacy detection requires legacy-specific
|
||||
patterns.
|
||||
- **STOP** restoring a hand-resumed session by relaunching the
|
||||
whole rig. Use `rig reconcile-session <session> --no-launch` —
|
||||
no relaunch, no input written, same node id.
|
||||
- **STOP** projecting a partial cmux workspace as launched-clean.
|
||||
The launch-readiness gate surfaces partial state honestly with
|
||||
a one-click open-missing path.
|
||||
|
||||
## Operator / Setup Notes
|
||||
|
||||
After upgrading the published CLI:
|
||||
|
||||
```bash
|
||||
npm install -g @openrig/cli@0.3.4
|
||||
rig --version # expect 0.3.4
|
||||
rig daemon stop
|
||||
rig daemon start
|
||||
```
|
||||
|
||||
No new schema-bumping migrations in 0.3.4. The
|
||||
`snapshots.periodic.*` settings have built-in defaults
|
||||
(`enabled=true`, `interval_seconds=300`, `retention_keep=10`); no
|
||||
operator action is required to pick up the crash-insurance floor.
|
||||
|
||||
Operators installing v0.3.4 fresh from npm have full access to the
|
||||
new surfaces immediately. Operators upgrading an existing host
|
||||
follow the standard daemon-restart flow above; the 0.3.4 host-
|
||||
upgrade flow is held for separate sequencing and is NOT a
|
||||
prerequisite for fresh-install access.
|
||||
|
||||
For the new `rig start` surface: it sequences existing primitives
|
||||
(daemon + kernel + per-rig `/api/rigs/:id/up`). The picker is TTY-
|
||||
interactive by default; the headless flags `--last`, `--all`, and
|
||||
`--rigs <names...>` cover scripted recovery.
|
||||
|
||||
For `rig up` resume-original-by-default: any agent or script that
|
||||
implicitly depended on fresh-prime as the default must now name
|
||||
`--fresh <seats...>` explicitly. The five-term vocabulary applies
|
||||
on the response; treat `awaiting-decision` as the headless
|
||||
"operator must decide" outcome, not an error.
|
||||
|
||||
For `rig seat clear-attention`: prefer evidence-gated clear when
|
||||
the seat is genuinely back. The `--reason <text>` override is the
|
||||
audited operator-attestation path; the attestation string lands in
|
||||
the audit row verbatim.
|
||||
|
||||
For periodic snapshots: tune `snapshots.periodic.interval_seconds`
|
||||
down for higher-churn rigs and `snapshots.periodic.retention_keep`
|
||||
up for longer recovery windows. The default 5-minute interval +
|
||||
10-snapshot retention is a balanced floor.
|
||||
|
||||
## Known Limitations / 0.3.4 Carry-forwards
|
||||
|
||||
- **`rig view list/show --json` flag inconsistency** — wrapper-
|
||||
layer routing path remains; the daemon's `view show <name>`
|
||||
route returns JSON correctly when invoked directly. Workaround:
|
||||
human-readable output for now. Wrapper-layer fix is the
|
||||
documented target.
|
||||
- **`docs/DESIGN.md` docs-guard ledger** — the docs-guard ledger
|
||||
for design-doc updates carries forward; no behavior impact on
|
||||
the shipped runtime surface.
|
||||
- **Slice-21 FR-1 (native Codex session-id hook)**: scope-tipped
|
||||
to 0.4.0 after build-time forensic. Carried forward from 0.3.3.
|
||||
- **Slice-13 component 3 (auto-rollout dispatcher)**: skill-layer
|
||||
landing remains; product-code dispatcher / invocation is
|
||||
intentionally out of the shipped runtime bundle. Carried
|
||||
forward from 0.3.3.
|
||||
- **Slice-05 sub-scopes from 0.3.2**: agent / port / managed-app
|
||||
collision detection (Item 4.3); broader install-into-existing-
|
||||
rig pathway acceptance (Item 4.4); `--target-name` CLI flag for
|
||||
install-time rig-name overrides. Carried forward.
|
||||
- **Slice-21 FR-4(d) accepted-queue-state schema**: deferred from
|
||||
0.3.2; new `accepted` queue state remains a schema model
|
||||
change. Carried forward.
|
||||
- **Onboarding journey + battle-hardening**: slices 04
|
||||
(new-user-journey), 08 (hooks-elite), 10 (rig-self), 11
|
||||
(personal-rig) carried forward to a later release. The 0.3.4
|
||||
cut focused on recovery + resilience surfaces ahead of the
|
||||
onboarding journey.
|
||||
- **Workspace symlink alignment**: daemon-side workspace-resolver
|
||||
alignment with operator symlinked workspace roots remains a
|
||||
follow-up; non-blocking for 0.3.4.
|
||||
- **Slice-13 permission-block-routing-architecture remains held**:
|
||||
big-green-light gated by operator review; `rigx-experimental`
|
||||
only; not split-deferred (stays held).
|
||||
- **0.3.4 host-upgrade flow held**: operators installing v0.3.4
|
||||
fresh from npm have full access immediately; upgrading an
|
||||
existing host follows the standard daemon-restart flow above.
|
||||
The named host-upgrade flow is held for separate sequencing.
|
||||
|
||||
## Verification Performed
|
||||
|
||||
- `npm run lint` clean.
|
||||
- `npm run build` clean across all workspaces.
|
||||
- TypeScript checks clean on every touched file at per-commit
|
||||
guard across every shipped slice.
|
||||
- Per-slice focused-suite tests green:
|
||||
- Slice 01 (`rig start`): pod-aware id-grounded preview + apply
|
||||
(rev1 BLOCKING b4c6ada4); same-name disambiguation; `/api/up`
|
||||
never reached in the recovery path; `--last` / `--all` /
|
||||
`--rigs <names...>` headless paths.
|
||||
- Slice 02 (`rig up` resume-original-by-default): seat-level
|
||||
outcomes drive `resumed` / `fresh-primed` / `awaiting-
|
||||
decision`; per-seat TTY [y/N] prompt; headless explicit-hint
|
||||
path for `awaiting-decision`.
|
||||
- Slice 03 (`rig reconcile-session`): adopt a hand-resumed
|
||||
session with same node id; projection-drift reporting; never
|
||||
launches, never writes to the pane.
|
||||
- Slice 04 (`rig up --plan`): read-only restore preview; honest
|
||||
async timeout; no mutation; same five-term vocabulary on the
|
||||
per-node `intendedAction`.
|
||||
- Slice 05 rev1 (pod-aware Claude resume-selection menu):
|
||||
`ClaudeCodeAdapter.verifyResumeLaunch` returns
|
||||
`recovery: attention_required` with last-12-line evidence;
|
||||
zero numeric keystrokes sent.
|
||||
- Slice 06 (five-term vocabulary): `rig up` / `rig restore` /
|
||||
`rig ps` projections carry the named outcome on every
|
||||
representative seat-state path.
|
||||
- Slice 07 (Codex profile-v2 preflight): narrowed legacy
|
||||
detection regex; invalid-TOML stderr surfaces the parse
|
||||
reason and a TOML-validity hint (rev1 BLOCKING).
|
||||
- Slice 08 (cmux launch readiness): partial-workspace state
|
||||
surfaces honestly with the open-missing affordance; no
|
||||
silent launched-clean projection.
|
||||
- Slice 09 (periodic snapshots): `PeriodicSnapshotScheduler`
|
||||
captures + prunes by retention; `auto-periodic` vs
|
||||
`auto-pre-down` newest-wins in the restore selector;
|
||||
settings-store integration for the `snapshots.periodic.*`
|
||||
family.
|
||||
- Slice 10 (`rig seat clear-attention`): evidence-gated clear;
|
||||
operator-attestation override via `--reason`; audit row
|
||||
captures session / from-state / cleared-by.
|
||||
- Slice 11 (node-granular launch): single-seat
|
||||
`/api/rigs/:rigId/nodes/:nodeRef/launch`; subset
|
||||
`/api/rigs/:rigId/nodes/launch-subset`; partial outcomes
|
||||
(launched / held / alreadyRunning / failedTargets) never
|
||||
collapsed.
|
||||
- Slice 13 (slow Codex resume classification): slow-resume
|
||||
Codex path classifies through the five-term vocabulary and
|
||||
reaches `resumed` when the readiness probe confirms.
|
||||
- Per-commit guard CLEAR across every shipped slice;
|
||||
velocity-qa adversarial dogfood + dual rev1 CLEAR on each
|
||||
merge.
|
||||
- VM end-to-end suite green against the 0.3.4 cut; recovery
|
||||
paths (`rig start` + `rig up` resume-by-default +
|
||||
`rig reconcile-session` + `rig seat clear-attention`)
|
||||
exercised against a real macOS VM through the vm-e2e harness.
|
||||
- Zero regressions versus the v0.3.3 base on every shipped
|
||||
slice.
|
||||
|
||||
## Commits Included (highlights)
|
||||
|
||||
The full v0.3.3 -> v0.3.4 delta is 67 commits / 69 files /
|
||||
+7,193 insertions / -267 deletions. The list below groups
|
||||
load-bearing commits by theme:
|
||||
|
||||
### Recovery Entry Points
|
||||
|
||||
- `feat(cli)`: `rig start` one-command recovery orchestrator —
|
||||
daemon-start, kernel wait, candidate listing, picker / flags,
|
||||
per-rig restore + reconcile (slice 01).
|
||||
- `fix(cli,daemon)`: `rig start` id-grounded preview + apply —
|
||||
same-name rigs no longer hit `ambiguous_name` 409 (slice 01
|
||||
rev1 BLOCKING).
|
||||
- `feat(cli)`: `rig reconcile-session` — adopt a live, hand-
|
||||
resumed canonical session into its persisted node without
|
||||
launch / relaunch / kill / startup-replay / resume-menu /
|
||||
pane-input (slice 03).
|
||||
|
||||
### Resume Original By Default
|
||||
|
||||
- `feat(cli,daemon)`: `rig up` resume-original-by-default;
|
||||
`--fresh <seats...>` becomes the per-seat opt-in for
|
||||
operation B; per-seat TTY [y/N] for `awaiting-decision`;
|
||||
headless explicit-hint path (slice 02).
|
||||
- `feat(cli,daemon)`: `rig up --plan` read-only restore preview
|
||||
with honest async timeout (slice 04).
|
||||
|
||||
### Honest Restore Vocabulary
|
||||
|
||||
- `feat(daemon,cli)`: five-term restore status vocabulary across
|
||||
`rig up` / `rig restore` / `rig ps` — `resumed` /
|
||||
`fresh-primed` / `awaiting-decision` / `attention_required` /
|
||||
`failed` (slice 06).
|
||||
- `fix(daemon)`: pod-aware Claude resume-selection menu surfaces
|
||||
`attention_required` instead of timeout (slice 05 rev1
|
||||
BLOCKING).
|
||||
- `fix(daemon)`: slow Codex resume classification — slow but
|
||||
genuinely-resuming sessions no longer mis-categorize through
|
||||
the unresolved-gate branch (slice 13).
|
||||
|
||||
### Preflight + Readiness Honesty
|
||||
|
||||
- `fix(daemon)`: Codex profile-v2 preflight narrows legacy
|
||||
detection regex; invalid TOML surfaces parse reason + TOML-
|
||||
validity hint (slice 07 rev1 BLOCKING).
|
||||
- `fix(daemon,ui)`: cmux launch readiness — partial workspace
|
||||
surfaces honestly; one-click open-missing affordance instead
|
||||
of silent launched-clean (slice 08).
|
||||
|
||||
### Crash-Insurance Floor
|
||||
|
||||
- `feat(daemon)`: `PeriodicSnapshotScheduler` + `snapshots.
|
||||
periodic` settings family; `auto-periodic` snapshot kind;
|
||||
restore selector treats `auto-periodic` and `auto-pre-down`
|
||||
symmetrically (newest-wins); last-snapshot / floor in
|
||||
`rig ps` (slice 09).
|
||||
|
||||
### Stuck-Seat Recovery
|
||||
|
||||
- `feat(cli,daemon)`: `rig seat clear-attention` — evidence-
|
||||
gated, operator-attested, audited reconcile of a stuck
|
||||
`attention_required` seat; audit row captures session / from-
|
||||
state / cleared-by (slice 10).
|
||||
|
||||
### Node-Granular Managed Partial Restore
|
||||
|
||||
- `feat(cli,daemon)`: node-granular launch through orchestration
|
||||
— `rig launch <rigId> <nodeRef>` single-seat;
|
||||
`rig launch <rigId> --seats <a,b>` subset; partial outcomes
|
||||
(launched / held / alreadyRunning / failedTargets) reported
|
||||
separately; retires `pod_aware_launch_unsupported` dead-end
|
||||
(slice 11).
|
||||
|
||||
See `CHANGELOG.md` for the agent-readable changelog with quick
|
||||
verification commands and operator notes.
|
||||
@@ -1,431 +0,0 @@
|
||||
# OpenRig v0.4.0
|
||||
|
||||
## Summary
|
||||
|
||||
OpenRig v0.4.0 is a token-efficient-defaults + recovery-capstone release.
|
||||
Five read-commands every agent runs constantly (`rig ps`, `rig whoami`,
|
||||
`rig queue list`, `rig restore-check`, `rig context`) flip from
|
||||
firehose-by-default to compact-by-default with an explicit `--full` /
|
||||
`--all` opt-in; `rig queue list` adopts the docker/kubectl-aligned
|
||||
read-command grammar (`-a` for history, `-A` for cross-rig breadth,
|
||||
`-o json|wide` for encoding, `--mine` / `--source` / `--destination`
|
||||
for scope). `rig seat clear-attention` extends to cover the
|
||||
restoreOutcome-derived projection staleness class that v0.3.4 shipped
|
||||
but couldn't reach. `rig scope mission|slice create` now scaffolds
|
||||
`PROGRESS.md` reliably and ships a `progress` update verb so agents
|
||||
update progress through the command rather than hand-editing markdown.
|
||||
|
||||
Behind those user-visible defaults: the daemon-side payload
|
||||
source-dedup (`rig ps` `recoveryGuidance` no longer duplicated
|
||||
per-node, `contextUsage` compact in the list payload) ships at slice 26
|
||||
so even `--full` and the UI consumers stop paying for it; live agent
|
||||
terminals replace the read-only 3-second snapshot view (slice 01);
|
||||
multi-host dogfooding hardens the `--host` flag's cross-host story
|
||||
(slice 02); the Agent Images library gains a Fork-now affordance + row
|
||||
metadata (slice 07); attention/activity detection consumes
|
||||
`agentActivity` truth more richly across the UI (slice 09);
|
||||
skill-cascade provenance + freshness gets a new read-only `rig skill
|
||||
audit` surface (slice 10); the identity refactor foundation lands the
|
||||
common identity types both the daemon and CLI consume (slice 11);
|
||||
`rig scope` progress rails reconnect the mission/slice tree to
|
||||
`PROGRESS.md` to the Project UI (slice 15); Codex resume preserves the
|
||||
launching seat's approval posture so resumed seats can run lifecycle
|
||||
commands without hitting implicit-deny (slice 17); the active/idle
|
||||
node-state ring becomes reliable (slice 18); a diagonal ghost in the
|
||||
topology graph view is fixed at source (slice 21); convergence-fix
|
||||
P1 (For-You drill captured/live contract) + P2 (daemon test-harness
|
||||
WebSocket registration) land as the wrap-blocking bug-fix slice 24.
|
||||
|
||||
Existing v0.3.4 databases upgrade by running `rig daemon start` on the
|
||||
new daemon. Migrations are additive.
|
||||
|
||||
## Included In This Release
|
||||
|
||||
### New top-level CLI verbs + new subcommands
|
||||
|
||||
- **`rig skill audit` (slice 10)** — new read-only command + daemon
|
||||
surface (`/api/skills/audit`, discovery, mirror-drift detection,
|
||||
skills route). Reports skill-cascade provenance findings —
|
||||
missing / stale / self-referential / invalid-date / mirror-drift —
|
||||
across the canonical → product mirror → hub cwd → installed plugin
|
||||
cascade. Prevents false-green CLI success when mirror-drift evidence
|
||||
is unavailable (the failure mode the v0.3.4 wrap-gate AC-3 almost
|
||||
shipped). Composes with the existing `scripts/mirror-skills.mjs`
|
||||
guardrails.
|
||||
- **`rig scope mission progress` / `rig scope slice progress` (slice 33)** —
|
||||
new `progress` verbs that append/set/update entries in `PROGRESS.md`
|
||||
deterministically through the command surface rather than hand-edited
|
||||
markdown. Writes the canonical structure the OpenRig PROGRESS UI page
|
||||
reads.
|
||||
|
||||
### Compact-by-default read commands (the token-efficiency family)
|
||||
|
||||
- **`rig ps` — compact default + `--full` + current-rig default + `-A`/`--all-rigs` (slices 25 + 34)** — default
|
||||
emits a compact TL;DR per node (session, rig, activity state +
|
||||
reason, assigned/pending counts; identity-recovery essentials only).
|
||||
`--full` returns the complete record (raw byte-equivalent). **Slice 34 — breadth default flipped to CURRENT-RIG** (derived from `OPENRIG_SESSION_NAME`'s `@<rig>` suffix) to match the docker/kubectl-aligned `rig queue list` grammar: `-A`/`--all-rigs` for fleet breadth; `--rig <name>` overrides the current-rig default; `--session <sess>` narrows further. All-states stays the default (per orch-lead's ruling: ps surfaces topology/readiness, where stopped/recoverable/attention is the actionable signal — unlike queue-list where the actionable set is active items). `--active` / `--running` remains the opt-in active-state filter. Closes a ~77,000-token status-glance incident at root + a fleet-scale unbounded-default-output bomb. **Resume-token security**: `--full` JSON now emits `resumeTokenPresent` (boolean) instead of the resume token value itself, so an orch glance never accidentally leaks token material.
|
||||
- **`rig ps` payload source dedup (slice 26)** — daemon node-list
|
||||
payload trims at source: `recoveryGuidance` is no longer serialized
|
||||
as near-identical templated prose on every node (relocated to a
|
||||
guidance-by-reference map at the top level so the 4 current
|
||||
consumers still resolve it); `contextUsage` is a compact summary in
|
||||
the list payload (full telemetry remains retrievable per-node via
|
||||
whoami / detail query). The ~7 contextUsage UI consumers + 4
|
||||
recoveryGuidance consumers migrated without regression. Even
|
||||
`--full` and the UI Project view stop paying for the redundant
|
||||
per-node blobs.
|
||||
- **`rig whoami` — compact default + `--full` (slice 27)** — `rig
|
||||
whoami` and `rig whoami --json` default to identity-recovery
|
||||
essentials only (`identity` / `peers` names + sessionNames / `edges`
|
||||
directional kind + to.sessionName / `transcriptPath`). `--full`
|
||||
(alias `--verbose`) returns today's complete payload including
|
||||
`contextUsage`, `commands`, `peersNote`, `runtimeContext`. Daemon
|
||||
skips the `contextUsageStore` lookup and `runtimeContext` build when
|
||||
compact is requested. The first command every agent runs on boot +
|
||||
every compaction-restore now costs ~192 tokens instead of ~909.
|
||||
- **`rig queue list` — active-frontier compact default + read-command
|
||||
grammar (slices 28 + 32)** — `rig queue list` (no flags) returns
|
||||
active states only (`pending` / `in-progress` / `claimed` /
|
||||
`blocked` / `handed-off`; not `done` / `canceled`), current-rig
|
||||
breadth, compact rows (id, state, source→destination /
|
||||
current-owner, closure_reason / closure_target when handed-off /
|
||||
blocked, mission, slice, tier / priority, age / updated_at, short
|
||||
title, capped tags). The four orthogonal axes are composable:
|
||||
- **`-a` / `--all`** — include closed/done history within the
|
||||
current breadth (the docker `-a` axis: history).
|
||||
- **`-A` / `--all-rigs`** — widen to cross-rig breadth (the
|
||||
kubectl `-A` axis: breadth).
|
||||
- **`--full`** — add body / chain-of-record / full-tags / transition
|
||||
history to whichever scope is selected (the field-breadth axis).
|
||||
- **`-o json|wide`** — encoding, compact-by-default. `-o json`
|
||||
does NOT imply full body (compact JSON is token-safe + machine-
|
||||
parseable); `--full -o json` returns the full JSON.
|
||||
- `--mine` returns just the caller's items; `--destination <s>` /
|
||||
`--source <s>` for explicit scoping. The bare unscoped firehose
|
||||
that aggregated cross-rig + full-history (~64,000 tokens on the
|
||||
live host) is retired as a default — opt-in via `-A -a --full`.
|
||||
- **`rig restore-check` — summary + not-ready default + `--full`
|
||||
(slice 29)** — default emits summary counts (total / ready / not-
|
||||
ready / error-degraded) plus the not-ready seats only (each compact:
|
||||
seat + readiness reason). `--full` / `--json` returns today's
|
||||
complete per-seat readiness across the fleet. Daemon skips
|
||||
per-seat-detail assembly for ready seats when compact (computes
|
||||
verdict, omits detail). `--rig <name>` / `--as <me>` narrow.
|
||||
Closes the largest measured bomb (~79,000 tokens) on the
|
||||
read-command surface.
|
||||
- **`rig context` — compact summary default + `--full` (slice 30)** —
|
||||
default emits a compact context summary (the few fields the common
|
||||
use needs); `--full` / `--json` returns the complete current
|
||||
payload. Daemon skips the expensive aggregation when compact. Lower
|
||||
leverage than 28/29 but keeps the read-command surface coherent
|
||||
compact-by-default after the upgrade.
|
||||
|
||||
### Recovery + resilience capstone
|
||||
|
||||
- **`rig seat clear-attention` extends to derived projection staleness
|
||||
(slice 16)** — v0.3.4 shipped `clear-attention` gating on
|
||||
`session.startupStatus` only. First real production use (the host
|
||||
cutover's residual `advisor-lead@kernel` projection) found the gap:
|
||||
when a seat is `startupStatus=ready` + `sessionStatus=running` but
|
||||
carries `restoreOutcome=failed` / `continuityOutcome=failed`, the
|
||||
daemon derives `lifecycleState=attention_required` and the verb
|
||||
refused with `{ok:false, code:not_in_attention}`. v0.4.0
|
||||
`clear-attention` now reaches both classes — the
|
||||
startupStatus-driven attention (already shipped) AND the
|
||||
restoreOutcome-derived projection — with the same evidence-gated
|
||||
audit row and the same operator-attested `--reason <text>` override.
|
||||
- **Codex Resume Preserves Approval Posture (slice 17)** — a
|
||||
resumed Codex seat now comes back with the same permission /
|
||||
approval posture as a fresh Codex launch. Previously a resumed
|
||||
seat hit "approval required but approvals disabled" implicit-deny
|
||||
with no path when running shipped lifecycle commands. Bounded
|
||||
bug-fix grounded against the 0.4.0 resilience set; surfaced
|
||||
during the GS1 Studio capture.
|
||||
|
||||
### UI + topology surfaces
|
||||
|
||||
- **Real (Interactive) Terminals (slice 01)** — the per-seat
|
||||
terminals in the UI become interactive. Click into a seat, type at
|
||||
the agent directly (shared-pane; "hands near the wheel"); the
|
||||
read-only 3-second snapshot view is retired for local-host seats.
|
||||
Performance constraint met for the rig-altitude "all terminals"
|
||||
view (~20–30 panes open simultaneously) via a **global
|
||||
`LiveTerminalRegistry`** that caps concurrently-live terminals
|
||||
(`ui.terminal.max_live_terminals` config key, env
|
||||
`OPENRIG_UI_TERMINAL_MAX_LIVE_TERMINALS`) and a **progressive
|
||||
multi-live** interaction model: live where the user is looking
|
||||
(focused popover / in-place grid expansion / node-detail panel),
|
||||
static smoked-glass thumbnails everywhere else, coordinated by a
|
||||
`LiveTerminalProvider`. In-place multi-live in the topology grid +
|
||||
shared smoked-glass styling across focused / popover / grid /
|
||||
node-detail surfaces. Remote-seat terminals ride 0.4.1 (need
|
||||
daemon-to-daemon transport).
|
||||
- **Real-Terminal Session Broker (slice 38)** — release-critical
|
||||
reliability fix grounded in founder live dogfood 2026-06-21. The
|
||||
prior architecture opened its own WebSocket per view, and each
|
||||
WebSocket started its own tmux `pipe-pane` against the same pane;
|
||||
tmux allows ONE pipe-pane per pane, so opening a second live view
|
||||
of the same session would **steal output from the first** —
|
||||
typing in one visible terminal sent echo to a different tab. The
|
||||
v0.4.0 architecture: a daemon-owned
|
||||
**`TerminalSessionBroker`** keyed by canonical `sessionName` —
|
||||
one tmux pipe-pane per session, N WebSocket subscribers, output
|
||||
fanout, session-level seed + shared scrollback ring for late
|
||||
subscribers, explicit input-owner semantics (the focused view is
|
||||
eligible to send input), and honest cleanup when the last
|
||||
subscriber leaves or the session dies. `terminal-ws` is now a
|
||||
thin broker subscriber; it no longer owns pipe-pane per
|
||||
connection. **Resize policy = canonical fixed geometry**: the
|
||||
broker pins the tmux pane at the optimal Claude/Codex TUI grid
|
||||
(120×40); subscribers fit/scroll their container to it (CSS),
|
||||
they never send tmux resize. One stable source of truth, zero
|
||||
resize-fighting, TUI always renders at its optimal width.
|
||||
- **Unified Static / Live Terminal Component (slice 39)** —
|
||||
the static thumbnail and live xterm now share one
|
||||
`StaticTerminalPlate` component + one mirror geometry (90×27 for
|
||||
thumbnails / mirror; the broker's live stream is 120×40 — the
|
||||
thumbnail is a fit-to-container projection of that live stream).
|
||||
Opaque mirror render + static line-return fix + grid in-place
|
||||
multi-live + graph/table popover. Live-terminal selection on a
|
||||
scaled view now uses fontSize scaling (not CSS transform), so
|
||||
text selection lands on the correct character cell. Geometry
|
||||
comment sweep is behavior-neutral but eliminates stale comments
|
||||
that confused subsequent edits.
|
||||
- **Agent Images Library Polish (slice 07)** — the Agent Images
|
||||
library UI gains a `Fork now` action for cloneable images
|
||||
(composes the existing add-member endpoint with
|
||||
`session_source.mode: "agent_image"`), lightweight row metadata
|
||||
(version, token, fork-count, last-used), and nested-failure
|
||||
rendering (nested `failed` / `attention_required` outcomes render
|
||||
as red failure rather than green success). Fork-now is hidden /
|
||||
disabled when the image lacks `sourceCwd`; the confirm path
|
||||
requires a runtime-matched sibling carrying `agentRef` + `profile`;
|
||||
no fallback cwd is invented.
|
||||
- **Attention / Activity Detection — Elite Tier (slice 09)** —
|
||||
richer consumption of the `agentActivity` truth landed in 0.3.4
|
||||
across UI + operator surfaces. Needs-input prominence,
|
||||
time-in-state, activity rollups POST-18.
|
||||
- **Topology Graph-View Ghost Render Fix (slice 21)** — diagonal
|
||||
ghost artifact behind the nodes in the dashboard topology /
|
||||
graph view is fixed at source. Was present in every graph-view
|
||||
capture across the launch-video reviewer kit; the table view was
|
||||
already ghost-free. Hero surface across launch videos +
|
||||
dashboard.
|
||||
- **Reliable Active/Idle Node State (slice 18)** — the lit/dark
|
||||
activity ring already shipped; this slice closes the
|
||||
`DOT→terminalActive` fallback and removes the dead
|
||||
`pane_silence_flag` derivation. Flagship video F1's signal layer.
|
||||
|
||||
### Multi-host + identity foundations
|
||||
|
||||
- **Multi-Host Dogfood (slice 02)** — the `--host` CLI flag was
|
||||
shipped pre-0.4.0; this slice closes the cross-machine integration
|
||||
story (multi-machine dogfood + external QA). HTTP-primary
|
||||
transport; cross-host identity rides 0.4.1.
|
||||
- **Native Codex Session Identity (slice 11)** — landing the common
|
||||
identity types both the daemon and CLI consume — native Codex
|
||||
session-identity capture + the foundation for the slice-12
|
||||
identity-refactor that rides 0.4.1.
|
||||
|
||||
### Scope automation
|
||||
|
||||
- **`rig scope` PROGRESS.md + README scaffolding (slice 33)** —
|
||||
`rig scope mission create` and `rig scope slice create` now
|
||||
scaffold a canonical `PROGRESS.md` (the structure the OpenRig
|
||||
PROGRESS UI page parses) plus a convention-correct README with
|
||||
proper frontmatter, per
|
||||
`conventions/scope-and-versioning/README.md`. Fixes the bug where
|
||||
newly-created missions + slices were missing `PROGRESS.md`
|
||||
entirely. A `rig scope ... progress` update verb appends / sets /
|
||||
records progress entries deterministically — agents update
|
||||
progress through the command (UI-valid by construction) rather
|
||||
than hand-editing markdown and drifting.
|
||||
- **`rig scope` stage / verified / reconcile verbs (slice 35)** —
|
||||
the maturity vocabulary from `conventions/scope-and-versioning`
|
||||
§2 (`stage` + `verified`) becomes enforced through commands
|
||||
instead of hand-editing markdown. Composes with slice 33's
|
||||
PROGRESS.md + scaffolding to make `rig scope` the deterministic
|
||||
convention-enforcer.
|
||||
- `rig scope <slice|mission> stage <id> <new-stage>` — set
|
||||
`stage` (wip / provisional / established / canonical /
|
||||
superseded / retired) deterministically. `superseded` REQUIRES
|
||||
`--successor <id>` (rejected otherwise); `retired` warns
|
||||
"do not use"; invalid stages rejected with the valid set
|
||||
named.
|
||||
- `rig scope <slice|mission> verified <id> --against
|
||||
"<source>"` — stamp `verified: <today> against <source>` in
|
||||
frontmatter. `--against` is MANDATORY — bare timestamps
|
||||
rejected (the anti-stale keystone: a bare timestamp is
|
||||
exactly what lets stale trackers lie while looking fresh).
|
||||
Overwrites the prior verified line.
|
||||
- `rig scope <slice|mission> reconcile <id>` — idempotent repair
|
||||
verb that backfills missing `PROGRESS.md`, conforms mandatory
|
||||
frontmatter (`id` / `stage` / `verified`), and repairs
|
||||
id-registration ghosts (`id:null` / doubled-prefix artifacts).
|
||||
Safe to re-run.
|
||||
- `rig scope <slice|mission> create` now writes the MANDATORY
|
||||
`stage` (default `wip`) + a `verified` placeholder, so no new
|
||||
artifact ships missing them.
|
||||
- `rig scope <slice|mission> show` derives a read-time
|
||||
effective-reliability projection from (stage × verified): a
|
||||
stale-`verified` `canonical` is reported as effectively
|
||||
`provisional` (derivation, not stored). Self-correcting signal
|
||||
for the UI + agents.
|
||||
- **Scope-Backed Progress Rails (slice 15)** — connects the scope
|
||||
tree, startup skills, `PROGRESS.md` rails, and Project UI
|
||||
warnings into one coherent workflow. From the 0.3.4 release
|
||||
audit (the mission/slice tree existed + queue traffic was rich,
|
||||
but `PROGRESS.md` surfaces the dashboard depends on were missing
|
||||
or under-used). Pairs with 33 — 33 ships the command; 15 ships
|
||||
the workflow that uses it.
|
||||
|
||||
### Bug-fix wrap
|
||||
|
||||
- **Wrap Convergence Fixes (slice 24)** — the wrap-blocking
|
||||
bug-fix slice from the 0.4.0 convergence deep-review. Two narrow
|
||||
real-terminals integration defects: **P1** For-You terminal-drill
|
||||
mixed captured / live contract (cross-slice 01↔09 seam); **P2**
|
||||
daemon test-harness broken by unconditional Node WebSocket
|
||||
registration (51→411 suite failures). Both pre-wrap blockers per
|
||||
founder ("real convergence bugs land as 0.4.0 bug-fix slices
|
||||
before wrap"). Reviewers found NO broader cross-slice coherence
|
||||
defect — the convergence is clean.
|
||||
|
||||
## User-Facing Changes
|
||||
|
||||
### New surfaces (use these)
|
||||
|
||||
- **Read-commands compact by default**: `rig ps`, `rig whoami`,
|
||||
`rig queue list`, `rig restore-check`, `rig context`. Same
|
||||
breadth, much smaller default payload. Use `--full` (or `-A -a
|
||||
--full` for queue list) when you need the firehose.
|
||||
- **`rig queue list` grammar (docker / kubectl aligned)**:
|
||||
```
|
||||
rig queue list # active, compact, current-rig
|
||||
rig queue list -a # + closed/done history
|
||||
rig queue list -A # cross-rig breadth (same as -A in kubectl)
|
||||
rig queue list --full # add body + chain-of-record
|
||||
rig queue list -o json # compact JSON (token-safe)
|
||||
rig queue list --full -o json # full JSON
|
||||
rig queue list --mine # caller's items only
|
||||
rig queue list --destination <s> # destined to <s>
|
||||
rig queue list --source <s> # sourced by <s>
|
||||
rig queue show <qitemId> # full single item (kubectl describe)
|
||||
```
|
||||
- **`rig skill audit`** — read-only audit of the skill cascade.
|
||||
Detects missing / stale / self-referential / invalid-date /
|
||||
mirror-drift across the canonical → product mirror → hub cwd
|
||||
→ installed plugin chain. Prevents false-green CLI success when
|
||||
mirror-drift evidence is unavailable.
|
||||
- **`rig scope ... progress`** — deterministic `PROGRESS.md`
|
||||
updates. Append entries, set status, record milestones through
|
||||
the command surface; the UI reads the same canonical structure
|
||||
the command writes.
|
||||
- **`rig seat clear-attention` for restoreOutcome-derived
|
||||
projection** — the v0.3.4 verb now reaches the second class of
|
||||
projection staleness. Same evidence-gated audit row; same
|
||||
`--reason <text>` operator-attestation override.
|
||||
|
||||
### What to STOP using
|
||||
|
||||
- **Stop assuming `rig ps --nodes --json` is the casual status
|
||||
check.** Compact default is the casual check; the firehose is
|
||||
`--full`. Per-node `recoveryGuidance` near-identical-prose
|
||||
duplication is retired; per-node full `contextUsage` is retired
|
||||
from the list payload (relocate to single-node / whoami / detail
|
||||
queries).
|
||||
- **Stop using bare `rig queue list` as the cross-rig firehose.**
|
||||
Default is now active + compact + current-rig. The cross-rig
|
||||
ambient-frontier view is `-A`; cross-rig + history is `-A -a`;
|
||||
the full firehose is `-A -a --full -o json`.
|
||||
- **Stop using `rig whoami --json` to get the heavy payload on
|
||||
boot.** Default is compact identity-essentials; `--full` (or
|
||||
`--verbose`) returns today's complete payload.
|
||||
- **Stop using `rig restore-check` as a per-seat-detail fleet
|
||||
scan.** Default is summary + not-ready only; `--full` for the
|
||||
per-seat detail when actually needed.
|
||||
- **Stop hand-editing `PROGRESS.md` with markdown to record
|
||||
progress.** Use `rig scope ... progress` — UI-valid by
|
||||
construction, deterministic, no drift.
|
||||
- **Stop hand-creating `PROGRESS.md` for new missions / slices.**
|
||||
`rig scope mission create` + `rig scope slice create` scaffold
|
||||
it now.
|
||||
- **Stop applying the token-efficiency-boot-guardrail's
|
||||
CLI-command prohibitions on hosts running 0.4.0** (the
|
||||
prohibitions were host-version workarounds for the bloated
|
||||
defaults this release closes). The pack's bounded-local-search
|
||||
rule + scope/over-flag discipline GRADUATE to a standing
|
||||
convention (`conventions/bounded-local-search-and-flag-scope`)
|
||||
and continue to apply host-independently. The
|
||||
CLI-command-prohibitions half of the pack RETIRES at
|
||||
host-upgrade-to-0.4.0.
|
||||
|
||||
### Operator / Setup Notes
|
||||
|
||||
- **No new schema-bumping migrations.** Existing v0.3.4 databases
|
||||
upgrade by running `rig daemon start` on the new daemon.
|
||||
- **`rig scope` backfill on existing trees**: missions and slices
|
||||
created before 0.4.0 that are missing `PROGRESS.md` can be
|
||||
backfilled by running the `rig scope` repair / doctor step (see
|
||||
slice 33 IMPLEMENTATION-PRD for the exact verb).
|
||||
- **Compact JSON is machine-parseable**. The compact-row schema
|
||||
for `rig queue list -o json` is stable; downstream parsers
|
||||
reading the compact rows don't need migration. Parsers that
|
||||
read body / chain-of-record must use `--full` explicitly.
|
||||
- **`rig skill audit` on the host** — first real production run
|
||||
surfaces the current cascade state (missing / stale /
|
||||
mirror-drift findings). The lifecycle's cascade-propagation
|
||||
pass (canonical `openrig-work/skills/` → product mirror → hub
|
||||
cwd → installed plugin) coordinates with the audit's findings
|
||||
going forward.
|
||||
|
||||
### Known Limitations + carry-forward
|
||||
|
||||
- **Plugin-Lineage Drift in `openrig-core`**: the openrig-core
|
||||
plugin skill lineage is divergent / stale (see OPR.0.4.1.4 —
|
||||
the full plugin re-sync, rides 0.4.1). v0.4.0 ships with this
|
||||
drift known; the cascade-sweep this release ran verified the
|
||||
canonical + config-mirror layers agents boot from are correct
|
||||
/ current at the release SHA, and `rig skill audit` (slice 10)
|
||||
is the new runtime mechanism to detect future drift. The full
|
||||
openrig-core plugin re-sync lands in 0.4.1.
|
||||
- All earlier "PUSHED to 0.4.1" carry-forwards were RESTORED to
|
||||
0.4.0 during the wrap: slice 34 (`rig ps` current-rig default
|
||||
+ `-A`/`--all-rigs` + `resumeTokenPresent` security) landed —
|
||||
see the rig ps entry under Compact-by-default read commands;
|
||||
slice 35 (`rig scope` stage / verified / reconcile verbs)
|
||||
landed — see Scope automation section. Nothing of substance
|
||||
carries forward to 0.4.1 from the original wrap-gate set.
|
||||
- **Real-terminal-related slices** (38 + 39) shipped via founder
|
||||
live-dogfood forward-fix authorization 2026-06-21 (the
|
||||
TerminalSessionBroker reliability fix + the unified
|
||||
static/live terminal component). Both are in 0.4.0; no
|
||||
carry-forward.
|
||||
|
||||
## Verification Performed
|
||||
|
||||
- npm + GitHub release surfaces: published at the lifecycle wrap step (founder-authorized).
|
||||
- Wrap worktree clean on `8d55ea60` (the wrap-gate target SHA).
|
||||
- `rig daemon start` upgrades 0.3.4 → 0.4.0 databases additively (no schema-breaking migrations).
|
||||
- CLI help surfaces for every changed command (`rig ps`, `rig whoami`,
|
||||
`rig queue list`, `rig restore-check`, `rig context`, `rig scope`)
|
||||
source-verified against the command source at the release SHA per
|
||||
`feedback_release_docs_source_verify_each_cli_surface_dont_carry_forward`.
|
||||
- CLI→skill cascade sweep — canonical
|
||||
`openrig-work/skills/openrig-user/SKILL.md` → product mirror at
|
||||
`packages/daemon/specs/agents/shared/skills/core/openrig-user/SKILL.md`
|
||||
→ hub cwd `.claude/skills/openrig-user/SKILL.md` +
|
||||
`.agents/skills/openrig-user/SKILL.md` updated for the six changed
|
||||
commands and the new `--full` / `-a` / `-A` / `-o` grammar; obsolete
|
||||
caveats retired (the `--notify`-required footgun footnote where it
|
||||
appeared, any "this command dumps everything" warnings made false
|
||||
by the compact defaults).
|
||||
- AC-6 wrap-gate self-check PASS — see the durability-close ledger
|
||||
evidence for the cascade-sweep grep evidence + cli-reference diff.
|
||||
|
||||
## Commits Included
|
||||
|
||||
`git log v0.3.4..7e6ba168` against the wrap worktree at the release
|
||||
SHA. The release commits are the version bump + the durability-close
|
||||
sweep + the lifecycle wrap commits per the
|
||||
`conventions/release-durability-close` convention.
|
||||
@@ -1,269 +0,0 @@
|
||||
# OpenRig v0.4.1
|
||||
|
||||
## Summary
|
||||
|
||||
OpenRig v0.4.1 is an observability + operator-UI overhaul: the workspace
|
||||
becomes a developer's mission cockpit. Across the Project UI, altitude
|
||||
projection (workspace → mission → slice) and a coherent tab set replace
|
||||
the partially-built Project pages from v0.4.0. The Mission landing tab
|
||||
shows steering + the human-facing mission brief. The Story tab
|
||||
reconstructs what actually happened on a mission as a scrollable
|
||||
git-graph derived from queue lineage. The Workflow tab visualizes the
|
||||
configured workflow spec. The Artifacts navigator + Proof tab + Progress
|
||||
heat-map give workspace altitude its own native surfaces. The Dashboard
|
||||
route gets a clean cosmetic refresh as the launcher home.
|
||||
|
||||
Underneath: a UI digital twin renders all six real Project surfaces
|
||||
1:1 daemon-free from typed fixtures so visual intent can be approved
|
||||
before any UI slice is built, then proven against a real screenshot at
|
||||
the end. A topology edge-flow animation surfaces real queue/handoff
|
||||
movement on the topology graph (signal-driven, never decorative). The
|
||||
For-You feed picks up a phone-friendly restyle with real-data fidelity.
|
||||
|
||||
New CLI: `rig auth` lands as a product-native, CLI-local Codex
|
||||
auth-profile manager with a hardened secret boundary that refuses
|
||||
symlink + hardlink escapes out of CODEX_HOME. `rig send` ships a 3-layer
|
||||
interactive-prompt guard (default-blocked at a target pane's prompt;
|
||||
`--raw` keystrokes still guarded; `--dangerously-interact --reason`
|
||||
audited override) so a peer message can no longer accidentally select
|
||||
an option in another agent's terminal.
|
||||
|
||||
Reliability fixes: a fresh `npm install -g @openrig/cli` followed by
|
||||
`rig daemon start` now resolves cleanly (a missing `@hono/node-ws`
|
||||
runtime dep was masked by monorepo hoisting on the dev host but failed
|
||||
on a fresh install; the CLI now mirrors the daemon's full runtime
|
||||
dep set, gated by a packaging-completeness test). Table-view + hybrid
|
||||
terminal-action errors surface as visible alerts instead of silent
|
||||
failures, and the table terminal opens. Queue items take a
|
||||
human-readable `summary` field (additive migration 044; phased
|
||||
WARN-on-author).
|
||||
|
||||
Existing v0.4.0 databases upgrade by running `rig daemon start` on the
|
||||
new daemon. Migrations are additive (044 adds a nullable
|
||||
`queue_items.summary` column; pre-0.4.1 items degrade cleanly to a
|
||||
body-fallback label).
|
||||
|
||||
## Included In This Release
|
||||
|
||||
### New top-level CLI surface
|
||||
|
||||
- **`rig auth`** — product-native, CLI-local Codex auth-profile
|
||||
management. List / show / switch / capture / forget Codex profiles
|
||||
under a CLI-owned `~/.openrig/codex-auth/`, never reaching outside
|
||||
CODEX_HOME. The adversarial path is closed: a symlinked active auth
|
||||
is refused, hardlinks and symlinked parents cannot escape CODEX_HOME,
|
||||
and the secret boundary is integration-tested. Replaces the prior
|
||||
ad-hoc out-of-product Codex auth swap with a single first-class
|
||||
surface.
|
||||
|
||||
### `rig send` — interactive-prompt guard
|
||||
|
||||
A peer message can no longer accidentally pick an option or approve a
|
||||
permission in another agent's terminal. Three layers:
|
||||
|
||||
- **L0 (default)** — `rig send` is **blocked** when the target pane is
|
||||
at an interactive prompt or permission block. Detection is
|
||||
hook-primary (Codex `PermissionRequest`) with a hardened capture-pane
|
||||
fallback (12-line trailing-content scan + 15-second send-readiness
|
||||
freshness).
|
||||
- **L1 — `--raw`** — exact keystrokes; the L0 guard still applies.
|
||||
- **L2 — `--dangerously-interact --reason "..."`** — explicit override,
|
||||
implies `--raw`, requires `--reason`, writes an audit row.
|
||||
|
||||
This closes the long-standing "stand-down message submitted an
|
||||
authorize-publish default" footgun.
|
||||
|
||||
### Workspace observability tabs (the headline)
|
||||
|
||||
- **Steering tab (mission landing)** — Panel 1 projects `STEERING.md`
|
||||
(what agents are currently being told to do); Panel 2 projects the
|
||||
mission's human-facing `MISSION_BRIEF.md` derived from the new locked
|
||||
7-section schema. The landing tab when you click into a mission;
|
||||
Overview stays available.
|
||||
- **Mission brief doc-type + projection** — a real canonical
|
||||
human-facing doc-type alongside `README.md` / `PROGRESS.md` /
|
||||
`MISSION_NOTES.md`. `rig scope init-workspace` /
|
||||
`rig scope mission create` emit a root `MISSION_BRIEF.md` from the
|
||||
7-section template (Brief / What & why / Building / Progress / Proven
|
||||
/ Needs you / Pointers); backfill the same template into existing
|
||||
missions on demand. The Mission Steering tab renders it
|
||||
markdown → UI.
|
||||
- **Story tab — queue-item DAG git-graph** — reconstructs a forest of
|
||||
DAGs from `chain_of_record` + handoff lineage as a scrollable,
|
||||
upward-growing git-graph. Single-parent edges only (no invented merge
|
||||
state); one-line rows over a curved gutter; full-width expanded row;
|
||||
a Tier-3 drawer reuses the queue-item viewer for the full agent-speak
|
||||
body + chain. Both mission and slice altitudes; client-side from the
|
||||
existing `/api/queue` read API (no new surface). The Queue tab folds
|
||||
into Story.
|
||||
- **Workflow tab — spec visualizer** — finishes the half-built Project
|
||||
Topology tab into a real read-only visualizer of the configured
|
||||
workflow spec: dotted-grid canvas, dark-header step cards, per-step
|
||||
state dot, dagre LR layout, amber reject → rework loop-back. Label
|
||||
rename Topology → Workflow (test-id stays `project-tab-topology`,
|
||||
id-stable). Both mission and slice altitudes. Workspace-only; the
|
||||
standalone Topology page (NOC) is unchanged.
|
||||
- **Proof tab** — per-slice proof galleries + empty-state for
|
||||
scaffolded-but-unpopulated slices. Reads from the slice's
|
||||
`proof/` directory + a `PROOF.md` summary if present.
|
||||
- **Progress heat-map** — Project Progress tab consolidates to the
|
||||
heat-map (per-slice rollup cards retired); the heat-map carries
|
||||
status at a glance without the duplicate-card noise.
|
||||
- **Artifacts navigator** — slice-altitude `ArtifactsNavigator`
|
||||
replaces the prior `SliceArtifactsTab` card wall; files and docs
|
||||
resolve through the same `/api/files/*` surface; the Proof tab owns
|
||||
proof artifacts; the Decisions surface routes through Story
|
||||
(decision-of-record items are already Story nodes).
|
||||
- **Workspace portfolio** — workspace parent altitude renders a
|
||||
cross-mission portfolio panel: mission list with steering glance on
|
||||
expand, lazy `MISSION_BRIEF.md` fetch, rollup metric counts
|
||||
*proven* (from `hasProofPacket`) rather than `done`.
|
||||
|
||||
### UI digital twin + visual intent → proof convention
|
||||
|
||||
- **UI digital twin (harness)** — a derive-from-source twin renders all
|
||||
six real Project UI surfaces 1:1 daemon-free from typed fixtures
|
||||
(cache-seed + a thin fetch override + a seeded SSE stream; **not**
|
||||
MSW). One self-contained `intent.html` per surface; tsc
|
||||
compile-time drift-guard (a real interface change breaks the twin
|
||||
build); ~2-step per-slice authoring loop; production-isolated
|
||||
dev-only target. Build any surface with
|
||||
`TWIN_ROUTE=<route> npm run twin:build`.
|
||||
- **`rig scope` intent-visual slot** — `rig scope slice create`
|
||||
scaffolds a slice `README.md` that includes an
|
||||
`## Intent visual` slot with `[change.diff]` + the
|
||||
`TWIN_ROUTE=<route> npm run twin:build` rebuild command. A non-visual
|
||||
slice gets an explicit `N/A` line, so the slot is *present-or-N/A*
|
||||
per slice.
|
||||
- **Visual intent → proof convention** — adopted alongside the
|
||||
harness: visual intent is approved as a twin mockup before build,
|
||||
then proven against a real screenshot at the end. The convention's
|
||||
twin-data-freshness condition (every brand-new UI surface has a twin
|
||||
fixture; data shapes match real) is folded into the release-close
|
||||
gate.
|
||||
|
||||
### Topology + For-You
|
||||
|
||||
- **Topology edge-flow animation** — when a real queue handoff or
|
||||
`rig send` travels an edge (source → destination), the edge animates
|
||||
in the handoff direction, brightens while live, then settles static
|
||||
after TTL. Honesty-contract held: animates **only** on a real
|
||||
queue / send signal (no workflow DAG, no ambient motion);
|
||||
un-signaled edges stay static; reduced-motion omits the flow.
|
||||
Topology-graph surface only.
|
||||
- **For-You phone restyle + real-data fidelity** — the Dashboard
|
||||
restyle reaches For-You as a phone-friendly cards layout with an
|
||||
altitude-dial level filter (All activity → Highlights → Needs you,
|
||||
card set changes per level). The internal `source.type` wrapper
|
||||
string no longer renders in feed cards, and the vestigial
|
||||
storytelling-preview band above the filtered feed is removed (it
|
||||
ignored the level filters and visually masked the restyle).
|
||||
|
||||
### Reliability + correctness
|
||||
|
||||
- **Fresh-install daemon-start fix** — `@hono/node-ws` is now declared
|
||||
in the CLI package (the CLI vendors the built daemon and does not
|
||||
depend on `@openrig/daemon`, so its `package.json` must mirror the
|
||||
daemon's runtime deps for a global `npm install -g @openrig/cli` to
|
||||
resolve them). A monorepo-hoisting blind spot meant the dev host
|
||||
worked while a fresh install failed; a packaging-completeness gate
|
||||
now fails the test suite if a daemon runtime dep is not mirrored in
|
||||
the CLI.
|
||||
- **Table / hybrid terminal-action reliability** — terminal-action
|
||||
errors surface as a visible cmux/auth alert instead of silent
|
||||
failure on the topology Table view + the hybrid surface; the Table
|
||||
terminal now opens cleanly.
|
||||
- **Queue-item human-readable summary** — additive nullable `summary`
|
||||
field on queue items (migration 044). `rig queue create` +
|
||||
`rig queue handoff` gain `--summary` with WARN-on-author (warns if
|
||||
missing; does **not** hard-break existing callers — phased
|
||||
enforcement). The agent-speak body remains the source of truth and
|
||||
is inspectable in the queue-item drawer. The Story-row label prefers
|
||||
the authored summary and degrades cleanly to the body fallback for
|
||||
pre-0.4.1 items.
|
||||
- **Seat-scoped post-compaction restore** — Claude Code seats get a
|
||||
scoped, idempotent restore packet derived from the JSONL transcript;
|
||||
the post-compact agent rebuilds its working mental model from
|
||||
durable evidence rather than fuzzy recall.
|
||||
- **Table-view crash fix** — null-safe TanStack filter + an
|
||||
`ErrorBoundary` on all three topology Table mounts (host / rig /
|
||||
pod) so a single bad row no longer takes down the page; regression
|
||||
test added.
|
||||
- **Dashboard route refresh** — cosmetic visual overhaul of the
|
||||
welcome / home launcher route (paper-draft launcher grid + six
|
||||
cards + Field Environment + drafting footer). Pure cosmetic; the
|
||||
six launcher routes + card test-ids preserved.
|
||||
|
||||
### Conventions adopted
|
||||
|
||||
- **Visual intent → proof** — the digital-twin convention is adopted
|
||||
with three ratified parts: derive-from-source twin (no MSW), one
|
||||
`intent.html` per surface, and twin-data-freshness as the residual
|
||||
release-close check.
|
||||
- **Release-durability close — AC-9 (skill-cascade integrity)** —
|
||||
`rig skill audit` clean for the shipping set, every drift edge
|
||||
green, and bundled plugin reconciled to canonical modulo declared
|
||||
transform. Condition 2 (drift edges) remains advisory until the
|
||||
shipping cascade checker lands; conditions 1 and 3 are hard from
|
||||
this release.
|
||||
- **Release-durability close — AC-10 (twin-data-freshness)** — the
|
||||
twin's component look is 1:1 by construction; the gate covers only
|
||||
the two residuals construction does not — dummy dataset
|
||||
representativeness (caught mechanically by twin build) and
|
||||
net-new-route fixture coverage.
|
||||
|
||||
## Behavior + Compatibility
|
||||
|
||||
- **Migrations** — additive only. Migration 044 adds a nullable
|
||||
`queue_items.summary` column; pre-0.4.1 items degrade to the
|
||||
body-fallback label. Pre-0.4.1 daemons that omit 044 also degrade
|
||||
cleanly via a `detectQueueColumn`-guarded read path. Existing v0.4.0
|
||||
databases upgrade by running `rig daemon start` on the new daemon.
|
||||
- **`rig queue create` / `rig queue handoff` — `--summary`** —
|
||||
optional; missing summary emits a WARN, never a hard error
|
||||
(graceful migration). Hard-require is a future hardening.
|
||||
- **`rig send` default** — now refuses sends when the target pane is
|
||||
at a prompt. `--dangerously-interact --reason "..."` is the explicit
|
||||
override path.
|
||||
- **Cosmetic Project tab renames** — Topology → Workflow (test-id
|
||||
stable); Queue folds into Story.
|
||||
- **For-You feed** — the storytelling-preview band on
|
||||
`/for-you` is removed (its mission-progress rollup remains on
|
||||
Dashboard / Project).
|
||||
|
||||
## Known Limitations + Follow-ons
|
||||
|
||||
- **Skill-layer cut depth (slice 04 family)** — the canonical
|
||||
skill-layer cut still awaits a decision on the load-bearing skill
|
||||
set; the cut does not execute in this release. The 04.3 shipping
|
||||
cascade-drift checker is not in this cut.
|
||||
- **Convention drift control (slice 28)** — partially delivered;
|
||||
convention ratified + folded into the release-close gate, but the
|
||||
shipping product skill + audit-code are still in flight.
|
||||
- **Twin capture tooling (slice 11.2)** — the twin harness ships; the
|
||||
one-command capture wrapper is in flight.
|
||||
- **Workspace UX architecture (slice 15)** — the design-discovery
|
||||
scope is approved; the remaining mockups are in flight (they gate
|
||||
future UI slices, not 0.4.1 shipped surfaces).
|
||||
- **For-You terminal phone-UX (slice 27)** — the For-You restyle and
|
||||
real-data fidelity are shipped; the embedded terminal's phone-UX
|
||||
(keyboard / touch / width / performance) is a non-gating polish
|
||||
check, not yet phone-verified.
|
||||
- **`rig send` interactive-prompt guard — hook-primary path** — the
|
||||
fallback capture-pane guard is fully proven; the hook-primary
|
||||
`PermissionRequest` path lands with this release and rides its full
|
||||
proof on the next iteration.
|
||||
- **`rig auth` follow-on (B1 secret-boundary)** — the adversarial
|
||||
hardening already merged into `rig auth` closes the symlink +
|
||||
hardlink escapes; a deeper structured follow-on is tracked
|
||||
separately, not in this cut.
|
||||
- **Inherited cascade-metadata hygiene** — the 0.4.0 release
|
||||
carry-forward (skill-layer `missing_provenance` +
|
||||
`missing_verified` audit findings) remains the documented residue;
|
||||
bulk fix lives in a separate post-0.4.0 skill-hygiene work item.
|
||||
|
||||
## See Also
|
||||
|
||||
- `CHANGELOG.md` — the standard changelog entry for 0.4.1.
|
||||
- `docs/as-built/cli-reference.md` — the shipped CLI surface.
|
||||
- `docs/releases/v0.4.0.md` — the prior release.
|
||||
@@ -1,57 +0,0 @@
|
||||
# OpenRig v0.4.2
|
||||
|
||||
## Summary
|
||||
|
||||
OpenRig v0.4.2 is a targeted hotfix for the CLI `daemon-status` probe's
|
||||
false-negative window right after a `rig daemon start` / restart. On the
|
||||
prior 0.4.1 build, the probe issued a single `/healthz` fetch per
|
||||
`getDaemonStatus` branch; if the daemon process was up but the HTTP
|
||||
listener had not yet begun accepting, the single probe lost the race and
|
||||
`rig daemon status` reported a false "Daemon not running" /
|
||||
"healthz failed" even though `/healthz` was returning `200`.
|
||||
|
||||
The fix wraps the three `getDaemonStatus` `/healthz` branches in a
|
||||
status-probe-local bounded settle: max 5 attempts, 200ms backoff,
|
||||
hard-bounded by construction. A genuine-down still fails all attempts
|
||||
and is reported stopped / unhealthy after the budget — never masked,
|
||||
never an unbounded wait. `fetchDaemonProbe` and start / stop / checkPid
|
||||
timing are unchanged.
|
||||
|
||||
## What Changed
|
||||
|
||||
- **`rig daemon status` no longer false-negatives during the daemon's
|
||||
post-start listener-bind window.** The probe re-checks up to 5 times
|
||||
with a short backoff before it reports stopped, so a healthy daemon
|
||||
that is still binding its listener resolves as running / healthy
|
||||
instead of reporting a false down state.
|
||||
- **Genuine-down reporting is unchanged.** If the daemon really is not
|
||||
running, all attempts fail and the probe reports stopped or unhealthy
|
||||
after the bounded budget — no hang, no mask.
|
||||
|
||||
## Files Touched
|
||||
|
||||
- `packages/cli/src/daemon-lifecycle.ts` — three probe branches
|
||||
(pid-alive `/healthz`, no-state `/healthz`, and the injected-probe
|
||||
wrapper) now go through `probeHealthzWithSettle`.
|
||||
- `packages/cli/test/daemon-lifecycle.test.ts` — focused probe-layer
|
||||
tests: transient-then-healthy settles to running / healthy;
|
||||
pid-alive-but-never-answers stays `healthy: false`; genuine-down is
|
||||
reported stopped after the hard-bounded budget.
|
||||
|
||||
## Behavior + Compatibility
|
||||
|
||||
- **No CLI surface changes.** All commands, flags, and arguments are
|
||||
identical to `0.4.1`.
|
||||
- **No daemon / DB / migration changes.** Migration state is unchanged
|
||||
from `0.4.1`; no new schema migrations ship in this release.
|
||||
- **No dependency changes.** `package-lock.json` is refreshed for the
|
||||
version bumps only.
|
||||
|
||||
Existing v0.4.1 databases are unaffected. Upgrading is simply
|
||||
`npm install -g @openrig/[email protected]` (or a package refresh) and a normal
|
||||
`rig daemon` restart if the daemon is running.
|
||||
|
||||
## See Also
|
||||
|
||||
- `CHANGELOG.md` — the standard changelog entry for `0.4.2`.
|
||||
- `docs/releases/v0.4.1.md` — the prior release.
|
||||
@@ -1,171 +0,0 @@
|
||||
# OpenRig v0.4.3
|
||||
|
||||
## Summary — "rigs that survive"
|
||||
|
||||
OpenRig v0.4.3 makes rigs actually survive. Crash the daemon or the whole
|
||||
machine — turn the power off, not a graceful stop — and on reboot the
|
||||
seats come back to their **original** sessions, with their pre-crash
|
||||
markers recalled, zero fresh-prime. The proof is a real hard power-off
|
||||
capstone (hard power-off → reboot → `rig start` → both Claude
|
||||
and Codex seats resumed to their originating conversations). This is the
|
||||
load-bearing "rigs that survive" claim.
|
||||
|
||||
Alongside the survival backbone, the release ships the **deny-by-default
|
||||
`rig send` reversal**: `needs_input` (an actual interactive picker) is
|
||||
now the only hard send-refuse; unknown / stale / missing / busy all
|
||||
advise-and-send. The 0.4.1 3-layer guard was too strict in practice —
|
||||
0.4.2 hotfixed the daemon-status probe, and 0.4.3 corrects the send-guard
|
||||
posture so peer coordination no longer needs a `--dangerously-interact`
|
||||
bridge for routine sends. The genuine prompt block still stands.
|
||||
|
||||
Wave-2 UI lands rig-status + launch-control on the workspace, a
|
||||
switch-client view-retarget, and a real theming system (Vellum Dark
|
||||
opt-in; light stays byte-identical). Seat-handover full-cycle + seat-
|
||||
forking closeout complete the recovery story. Doctrine ships too:
|
||||
mission-slice-sop skill.
|
||||
|
||||
Existing v0.4.2 databases upgrade by running `rig daemon start` on the
|
||||
new daemon. Migrations 045, 046, and 047 are additive.
|
||||
|
||||
## Survival — the load-bearing set
|
||||
|
||||
- **Crash-restore resume-token ledger (FR-3 → FR-7)** — the seat's
|
||||
resume marker is captured on adoption (FR-3), refreshed on snapshot
|
||||
(FR-4), pinned to a restore target (FR-5), freshness-gated with a
|
||||
1-hour advisory threshold + `--fresh` re-verify (FR-6 + FR-6.1
|
||||
periodic re-stamp), and — critically — the restore path never
|
||||
silently fresh-primes a seat that had a resume marker (FR-7). Prior
|
||||
to FR-7, a restore that couldn't reach the token would degrade to a
|
||||
fresh-prime, losing the original session identity; that silent
|
||||
degrade is now eliminated.
|
||||
- **Fixture-home isolation guard** — a fresh-prime that would have
|
||||
clobbered a live rig's home dir is refused loudly, not silently
|
||||
swallowed.
|
||||
- **Liveness PID-verify** — the daemon distinguishes a live seat from a
|
||||
dead-PID ghost by verifying the process actually exists before
|
||||
labeling the seat running.
|
||||
- **Daemon event-loop health + terminal broker resilience** — the
|
||||
daemon publishes an event-loop-latency health signal; the
|
||||
`TerminalSessionBroker` recovers cleanly across daemon restarts.
|
||||
- **Startup-proof** — a seat proves it actually read its orientation
|
||||
material rather than skipping past it; a challenge-verified read
|
||||
path.
|
||||
- **Seat-handover full-cycle** — an outgoing seat can hand its captured
|
||||
context to a fresh successor; the resume marker carries automatically
|
||||
via FR-3; the loud-unwind path fires on both lanes when handoff
|
||||
fails.
|
||||
- **Seat-forking closeout** — the fork lifecycle terminates cleanly on
|
||||
the shared checkpoint; predecessors and successors are named + wired.
|
||||
|
||||
## The deny-by-default reversal (`rig send`)
|
||||
|
||||
The 0.4.1 3-layer guard was too aggressive at the fleet level: unknown /
|
||||
stale / missing / busy activity signals all default-blocked, which
|
||||
required constant `--dangerously-interact --reason "..."` overrides for
|
||||
routine peer coordination. 0.4.3 corrects this:
|
||||
|
||||
- **`needs_input` (a real interactive picker rendered on the target
|
||||
pane) is the only hard send-refuse.** The guard here is unchanged
|
||||
behavior at the actual footgun-point.
|
||||
- **Unknown / stale / missing / busy** now **advise-and-send** rather
|
||||
than block. Peer sends land; the operator sees the advisory in the
|
||||
send output.
|
||||
- **`--dangerously-interact --reason "..."`** override still exists for
|
||||
intentionally driving a prompted seat, unchanged.
|
||||
|
||||
Also improved: **Codex activity-signal hardening** — an idle Codex seat
|
||||
now takes normal sends; the genuine prompt block still holds; hook-trust
|
||||
autoclear lands as a fast-follow so a restored Codex seat clears its
|
||||
attention-gate on restore.
|
||||
|
||||
## `rig send` unified targeting
|
||||
|
||||
`rig send` grows explicit multi-recipient targeting — a recipient list +
|
||||
`--pod` + `--rig` — reusing the existing broadcast fan-out + per-
|
||||
recipient guard. Backward-compatible: single-recipient send is
|
||||
unchanged.
|
||||
|
||||
## Wave-2 UI + theming
|
||||
|
||||
- **Rig-status + launch-control UI** — the workspace surface for
|
||||
starting / stopping / recovering a rig lands. Combines the topology
|
||||
view with a launch modal for mixed-plan rigs.
|
||||
- **Switch-client view-retarget** — clicking through a switch-client
|
||||
action lands the operator on the correct target view without a stale
|
||||
breadcrumb.
|
||||
- **Dashboard theming — Vellum Dark opt-in** — a real theming
|
||||
primitive: `light` is the existing `:root` theme (byte-identical),
|
||||
`dark` is the first shipped alternate, and the substrate scales to
|
||||
N themes via the token-block + registry entry. Uses Tailwind
|
||||
`darkMode: 'selector'`. Light is unchanged.
|
||||
|
||||
## Recovery + operator-UX
|
||||
|
||||
- **Idle-gate watchdog** — an idle seat holding a claimable gate qitem
|
||||
gets woken with a bounded skip-recording so the queue doesn't back up
|
||||
behind a dormant seat.
|
||||
- **Session-admin mutation auth-guard** — the admin mutation surface is
|
||||
no longer reachable without the correct auth posture.
|
||||
- **`rig queue show` bounded body preview** — long queue-item bodies
|
||||
are truncated in the show view; the full body remains inspectable via
|
||||
the queue-item drawer.
|
||||
- **Manual configurable compaction trigger + same-seat guard** —
|
||||
Claude Code seats can be prompted to compact from outside the seat;
|
||||
the trigger refuses a same-seat mutation.
|
||||
- **Secret-boundary B1 hardening (`rig auth`)** — the `rig auth`
|
||||
secret boundary now opens the fd first + operates on the fd never
|
||||
re-resolving the path, closing the check-then-use gap for
|
||||
interruption / concurrent-legitimate-rig-process scenarios (the
|
||||
TOCTOU class is closed as a consequence). The `rig auth` file is a
|
||||
real credential; leak-hunt is real security, not theater.
|
||||
|
||||
## Doctrine + fast-follow
|
||||
|
||||
- **`mission-slice-sop` skill** ships — the per-file rules for
|
||||
`PROGRESS.md` / `PROOF.md` / `MISSION_NOTES.md` / `MISSION_BRIEF.md` /
|
||||
`README.md`, the SCAFFOLD/POPULATE/PROJECT/VERIFY lifecycle,
|
||||
hot-potato queue handoffs, and the `rig scope audit` backstop.
|
||||
- **Hook-trust autoclear (fast-follow)** — a restored Codex seat that
|
||||
hits its attention_required VM-local hook-trust gate now auto-clears
|
||||
the attention on the restore path, mirroring slice-10, for
|
||||
fully-unattended Codex restore.
|
||||
|
||||
## Behavior + Compatibility
|
||||
|
||||
- **Migrations** — additive only. `045_resume_verification`,
|
||||
`046_seat_identity_verdicts`, `047_events_node_type_index` land in
|
||||
this release. Existing v0.4.2 databases upgrade by running
|
||||
`rig daemon start` on the new daemon.
|
||||
- **`rig send` default posture change** — unknown / stale / missing /
|
||||
busy activity signals no longer default-block; only `needs_input`
|
||||
does. If you were relying on the 0.4.1 default-block posture, add an
|
||||
explicit guard on your call sites; the intent-signaling for peer
|
||||
coordination now lives in the fleet-standard advise-and-send path.
|
||||
- **`rig send` grammar** — multi-recipient list + `--pod` + `--rig`
|
||||
are additive; single-recipient calls are unchanged.
|
||||
- **Cosmetic Project surface** — Dashboard theming is opt-in via the
|
||||
UI toggle; light theme is byte-identical.
|
||||
|
||||
## Known Follow-ons
|
||||
|
||||
- **Slice-04 real-provider handover VM-marker** — code proven at
|
||||
runtime (unit + integration + loud-unwind both lanes); the real-
|
||||
provider end-to-end VM-round-trip is a **fast-follow proof capture**
|
||||
(VM-env limitation on prior provider auth). Not a claim gap; the
|
||||
load-bearing survival proof is the crash-restore capstone.
|
||||
- **`rig ps` consolidated-default + progressive disclosure** — captured
|
||||
for 0.4.4 (token-efficient-defaults family evolution).
|
||||
- **Deploy-identity: git SHA via `/healthz` + `rig --version`** — the
|
||||
version-truth-vs-commit-truth observability gap (captured for 0.4.4
|
||||
Discovery).
|
||||
- **Managed-hooks-via-`requirements.toml`** — the robust structural
|
||||
hook-trust re-arch (later fast-follow).
|
||||
- **Skill-layer cut depth (slice-25)** — awaits a decision on the
|
||||
load-bearing skill set; deferred.
|
||||
- **Dashboard glyph swap (slice-24)** — awaits icon pick; deferred.
|
||||
|
||||
## See Also
|
||||
|
||||
- `CHANGELOG.md` — the standard changelog entry for `0.4.3`.
|
||||
- `docs/releases/v0.4.2.md` — the prior release (daemon-status hotfix).
|
||||
- `docs/releases/v0.4.1.md` — the workspace observability overhaul.
|
||||
@@ -1,131 +0,0 @@
|
||||
# OpenRig v0.4.4
|
||||
|
||||
## Summary — Multi-host + Living Notes
|
||||
|
||||
OpenRig v0.4.4 lands the multi-host foundation: a shared rig topology
|
||||
can now span multiple hosts, with a staged spin-up flow, real cross-
|
||||
host file movement, and a consolidated For-You activity feed that
|
||||
merges signal across every host in the topology. The VPS product-
|
||||
factory story hardens for real multi-host operation.
|
||||
|
||||
Alongside the multi-host foundation, this release ships the **Living
|
||||
Notes signal layer** — a durable, agent-authored notes surface that
|
||||
threads INTENT → PLAN → DELIVERED down the mission tree, with a
|
||||
one-structure review contract that reads left-to-right as a single
|
||||
vertical stack (INTENT above, PLAN in the middle, DELIVERED at the
|
||||
bottom; delete-not-demote when a plan changes). Composer surfaces make
|
||||
authoring cheap; the review surface makes reading intent-versus-build
|
||||
one-glance.
|
||||
|
||||
Operator UX picks up **`rig ps` consolidated default** (the token-
|
||||
efficient-defaults family gains progressive disclosure that keeps the
|
||||
default view glanceable without hiding the fleet), an **agent altitude
|
||||
coordination panel** that surfaces multi-agent state at the right
|
||||
altitude for the operator, and the **operationalize-SDLC control
|
||||
plane** which pulls the release / delivery / lifecycle levers into a
|
||||
single control surface. As-built docs closeout catches everything up.
|
||||
|
||||
Migrations, if any, are additive. Existing v0.4.3 databases upgrade by
|
||||
running `rig daemon start` on the new daemon.
|
||||
|
||||
## What Shipped
|
||||
|
||||
### Multi-host foundation
|
||||
|
||||
- **Shareable whole-topology staged spin-up** — a rig topology can be
|
||||
brought up in stages across multiple hosts; the spec + the daemon
|
||||
coordinate to reach a green whole-fleet state without requiring a
|
||||
single-host bring-up. Prior to this release, a whole-topology spin-
|
||||
up assumed a single host.
|
||||
- **VPS product-factory multi-host hardening** — the shipped
|
||||
`openrig-user`/`openrig-architect` operator flows work correctly
|
||||
across VPS/self-hosted product-factory scenarios; multi-host
|
||||
handshake + registration hardens.
|
||||
- **Multi-host consolidated For-You feed** — the For-You feed
|
||||
aggregates activity across all registered hosts in the topology, not
|
||||
just the local daemon. The stream classifier + real-data fidelity
|
||||
from 0.4.3 apply per-host and merge upstream. A real-host feed-
|
||||
subscription capture ships as belt-and-suspenders proof (see
|
||||
Known Follow-ons).
|
||||
- **`rig file` cross-host movement** — files move across the
|
||||
topology's registered hosts via the `rig file` surface. Real
|
||||
registered-host two-host end-to-end round-trip proves the flow on
|
||||
top of the VM stand-ins already merged.
|
||||
|
||||
### Living Notes
|
||||
|
||||
- **Signal layer** — a durable, agent-authored notes surface at
|
||||
mission and slice altitude; INTENT / PLAN / DELIVERED entries thread
|
||||
down the mission tree with agent authorship + timestamps.
|
||||
- **Composer surfaces** — cheap authoring surfaces make Living Notes
|
||||
the first-class place agents record decisions, plans, and delivered
|
||||
work.
|
||||
- **One-structure review contract (§3.1) — corrective rebuild** — the
|
||||
Living Notes review surface reads left-to-right as a **single
|
||||
vertical stack** (INTENT above, PLAN + mockup in the middle,
|
||||
DELIVERED with paired proof at the bottom); a plan change **deletes**
|
||||
the old plan and writes a new one — never demotes / stacks multiple
|
||||
competing plans. The corrective rebuild replaced an earlier
|
||||
three-column layout after human review.
|
||||
|
||||
### Operator UX
|
||||
|
||||
- **`rig ps` consolidated default + progressive disclosure** — the
|
||||
default `rig ps` now consolidates the fleet's readable rows into a
|
||||
single glanceable default; progressive disclosure via `--full` /
|
||||
`-A` / per-scope filters keeps the rich per-node record retrievable.
|
||||
Follows the token-efficient-defaults family established at 0.4.0.
|
||||
- **Agent altitude coordination panel** — a coordination surface
|
||||
scoped to the right altitude (workspace / mission / slice) so the
|
||||
operator sees the actual coordination state without drowning in
|
||||
per-seat detail. Composes with the workspace observability tabs
|
||||
shipped at 0.4.1.
|
||||
|
||||
### Doctrine
|
||||
|
||||
- **Operationalize the SDLC control plane** — release / delivery /
|
||||
lifecycle levers pull into a single surface. The lanes that shipped
|
||||
0.4.1 → 0.4.3 (release-cut squash + bounded-diff, sidecar-operator
|
||||
host cutover, curation pass) are now first-class control-plane
|
||||
actions rather than lifecycle-tribal-wisdom.
|
||||
- **As-built docs closeout** — the as-built documentation family
|
||||
(`docs/as-built/architecture.md`, `docs/as-built/cli-reference.md`,
|
||||
codemaps) is caught up to what shipped through 0.4.4.
|
||||
|
||||
## Behavior + Compatibility
|
||||
|
||||
- **Migrations** — additive only. Existing v0.4.3 databases upgrade
|
||||
by running `rig daemon start` on the new daemon.
|
||||
- **Multi-host registration** — the multi-host handshake is
|
||||
backward-compatible with single-host deployments; single-host
|
||||
operation is unchanged.
|
||||
- **`rig ps` default view** — the consolidated default is a
|
||||
compact readable view; `--full` returns the v0.4.3 default shape.
|
||||
- **For-You feed** — multi-host feed aggregation is opt-in via
|
||||
registered-host membership; a single-host topology sees no
|
||||
behavior change.
|
||||
|
||||
## Known Follow-ons
|
||||
|
||||
- **R2 — iOS-Safari S20 (Living Notes composer)** — deferred to
|
||||
0.4.5 for iOS Safari verification.
|
||||
- **R4 — S18 symlink footgun** — routed to the 0.4.5+ backlog.
|
||||
- **`openrig-user` stale plugin copy + `whoami --all-hosts` silent
|
||||
host filter** — 0.4.5 candidates.
|
||||
- **Wider mission-template prose sweep** — post-cut sequencing.
|
||||
- **Belt-and-suspenders real-host proofs** — R13-1 (published-npm
|
||||
Linux install smoke + daemon-start / `/healthz` / WebSocket
|
||||
handshake), R1 (real registered-host two-host e2e for S13 + S18 on
|
||||
top of the merged VM stand-ins), and R3 (S15 real-host feed-
|
||||
subscription capture) are sequenced as post-publish lifecycle
|
||||
validation lanes. The shipped code was already proven via VM/SSH
|
||||
stand-ins per PM rulings; the real-host lanes are defense-in-depth
|
||||
belt-and-suspenders proofs, not release gates.
|
||||
|
||||
## See Also
|
||||
|
||||
- `CHANGELOG.md` — the standard changelog entry for `0.4.4`.
|
||||
- `docs/releases/v0.4.3.md` — the prior release ("rigs that
|
||||
survive").
|
||||
- `docs/releases/v0.4.2.md` — the daemon-status hotfix.
|
||||
- `docs/releases/v0.4.1.md` — the workspace observability overhaul.
|
||||
@@ -1,198 +0,0 @@
|
||||
# OpenRig v0.4.6
|
||||
|
||||
## Summary — Workflows + multi-host coordination + factory foundations
|
||||
|
||||
OpenRig v0.4.6 lands the deterministic workflow engine and the
|
||||
multi-host coordination model that runs on top of it. Workflows are
|
||||
now a first-class product surface: a rock-solid engine, a full-
|
||||
featured spec language, a workflow CLI, a workflow web UI, and an
|
||||
exception + human-gate maturity model that keeps a healthy run
|
||||
zero-interruption. On top of that engine, the self-driving factory
|
||||
starter ships as an MVP shipped starter (`rig up factory-rsi`) —
|
||||
one rig, seven seats, a self-driving `plan → implement → qa_check
|
||||
→ review → release` inner loop with dogfood decoupled and running
|
||||
out-of-band against the shipped product, feeding recorded findings
|
||||
into the next plan.
|
||||
|
||||
Multi-host coordination lands the full happy path. Hosts register
|
||||
and select through dashboard-visible cards; a remote host's
|
||||
workspace surfaces are readable from the local operator; queue
|
||||
items and hot-potato handoffs cross hosts explicitly through the
|
||||
registered transport (never a silent selection re-home); the direct
|
||||
coordination verbs (`rig send`, `rig capture`, `rig transcript`,
|
||||
`rig broadcast`) cross hosts CLI-direct via the shipped http
|
||||
transport branch with byte-verbatim ssh behavior preserved; a
|
||||
fleet-altitude attention band rolls up needs-attention across the
|
||||
whole registered fleet.
|
||||
|
||||
Foundations round out the release: a new agent runtime adapter (Pi)
|
||||
joining Claude/Codex as a first-class runtime, terminal provider
|
||||
first-class treatment across the terminal-facing surfaces, and
|
||||
daemon read-path hardening for the multi-host + workflow load with
|
||||
no functional behavior change.
|
||||
|
||||
Two new bundled skills ship canonical + plugin with byte-parity
|
||||
guard: `openrig-herdr` (rig terminal open/views/status model) and
|
||||
`openrig-cmux` (provider-agnostic delta).
|
||||
|
||||
Migrations are additive only: `049_workflow_instance_version`,
|
||||
`050_workflow_spec_json`, `051_workflow_resume`,
|
||||
`052_workflow_instance_bound_rig`, `053_sessions_node_id_index`,
|
||||
`054_queue_transitions_archive`. Existing v0.4.4 databases upgrade
|
||||
by running `rig daemon start` on the new daemon. (v0.4.5 was
|
||||
skipped; there is no cut between v0.4.4 and v0.4.6.)
|
||||
|
||||
## What Shipped
|
||||
|
||||
### Workflows
|
||||
|
||||
- **The rock-solid deterministic engine** — strict spec validation
|
||||
(unknown keys reject; unreachable steps and unguarded cycles
|
||||
fail); `loop_guards.max_hops` enforced at projection; waiting-
|
||||
exit replay absorption; per-instance keepalive watchdogs auto-
|
||||
armed in the routing transaction; startup sweep re-arms and
|
||||
surfaces stuck instances; `rig workflow continue` relabeled to
|
||||
its read-only inspector semantics.
|
||||
- **The full-featured spec language** — steps with role /
|
||||
target.rig / preferred_targets / next_hop.on / invariants /
|
||||
loop_guards / exception_routing / closure / gates / skill_refs /
|
||||
spawn_budget; strict-keyset validation; shipped-spec compat
|
||||
pinned by fixture round-trip.
|
||||
- **The workflow CLI** — new verbs `rig workflow run` (instantiate
|
||||
+ follow to terminal; exit 3 = workflow-failed distinct from
|
||||
transport 1/2), `rig workflow watch` (mid-flight attach),
|
||||
`rig workflow status` (needs-attention rollup), `rig workflow
|
||||
route` (frontier re-target in one transaction). Formatted
|
||||
`trace` / `list` / `show` human output; `--json` byte-identical
|
||||
to before. New guard rejects out-of-band terminal closure of a
|
||||
live workflow-frontier packet.
|
||||
- **The workflow web UI** — new
|
||||
Workflows/Instance/InstancesBand/TopologyGraph/InstanceTrailTimeline
|
||||
pages; SSE stream unscoped by rig; pure `buildLauncherViews` +
|
||||
`suggestLayout` + edge-handle assignment exports. UI acceptance
|
||||
is carried by per-cut real screenshots + the two-host
|
||||
integration proof; twin fixture backfill is routed as a
|
||||
non-blocking 0.4.7 hygiene fast-follow.
|
||||
- **The exception + human-gate model** — `rig workflow resume`
|
||||
verb (redrive a failed instance from its failed step, rebound,
|
||||
fresh capability-aware re-resolution, one fresh `max_hops`
|
||||
window); exceptions become durable attention items in the same
|
||||
transaction as the failure; maturity dial `orchestrator-first |
|
||||
human_only` per class / per workflow / per host; the attention
|
||||
band is workflow-aware; the happy-path guarantee is unchanged.
|
||||
|
||||
### Multi-host coordination
|
||||
|
||||
- **Add / select hosts + dashboard** — `HostConfigCard` +
|
||||
`HostIndicator` surfaces on the dashboard; `rig host select`
|
||||
persists a sticky selection consumed by the observe/interactive
|
||||
verbs; new `useHosts` / `useFleet` hooks.
|
||||
- **View remote workspace** — workspace observability tabs gain
|
||||
`--host <id>` scope; registry + bearer fans out per-host reads.
|
||||
Read-only.
|
||||
- **Cross-host queue routing** — `rig queue create / handoff /
|
||||
handoff-and-complete` gain `--host <id>` + host-qualified
|
||||
destination form `member@rig@<host>`. Explicit-only routing.
|
||||
At-least-once + idempotent via deterministic successor id;
|
||||
handoff creates successor FIRST + closes local SECOND; retries
|
||||
absorb on primary key. Failure honesty per host outcome.
|
||||
- **Cross-host agent coordination** — `rig send` + `rig capture`
|
||||
gain an http transport branch reaching the remote daemon's
|
||||
existing `/api/transport/send|capture` routes CLI-direct;
|
||||
`rig transcript` + `rig broadcast` gain their first cross-host
|
||||
affordance the same way. The `agent@rig@host` target form is
|
||||
CLI-edge sugar for session-target verbs. Byte-verbatim ssh
|
||||
behavior preserved for ssh-registered hosts; explicit `--host`
|
||||
> target sugar > selection; `send --verify` over http prints
|
||||
the REMOTE route's verdict verbatim.
|
||||
- **Fleet-attention altitude** — fleet-wide attention rollup via
|
||||
`FleetBand` + `FleetPage`; per-host status + drill-down.
|
||||
|
||||
### Factory
|
||||
|
||||
- **The workflow-to-rig binding layer** — bind a workflow to a rig
|
||||
at instantiation via `--rig`; roles resolve to seats by
|
||||
capability; capable-seat resolution honors managed-only,
|
||||
harness-pin-aware runtime match, least pending backlog,
|
||||
deterministic tiebreak; resolve-once, record-in-the-packet;
|
||||
roles bind to the stable seat coordinate `{pod}-{member}@{rig}`
|
||||
(agent handover behind the seat never strands the workflow).
|
||||
- **The self-driving factory starter (`factory-rsi`)** — new
|
||||
`rig up factory-rsi` starter; new `factory-rsi` builtin
|
||||
workflow with a `plan → implement → qa_check → review →
|
||||
release` inner loop sanctioned by `loop_guards.max_hops`;
|
||||
dogfood decoupled + running out-of-band against the shipped
|
||||
product with its findings feeding the next plan (the RSI edge,
|
||||
ungated in the MVP — refined in a later release); publish stays
|
||||
a human act via `release_signoff` gate.
|
||||
- **The member-exists advisory + cross-rig wrapping** —
|
||||
mis-routed workflow destinations caught loudly at instantiate;
|
||||
cross-rig wrapping workflows travel via the cross-host queue
|
||||
routing path.
|
||||
|
||||
### Runtime + terminal + read-path
|
||||
|
||||
- **Pi agent runtime adapter** — a new first-class runtime
|
||||
joining Claude/Codex; participates in all workflow / role /
|
||||
queue / send / capture surfaces exactly like the shipped
|
||||
runtimes.
|
||||
- **Terminal provider first-class treatment** — terminal provider
|
||||
first-class treatment across the terminal launcher,
|
||||
send/capture/broadcast, and the new `openrig-cmux` skill's
|
||||
`--provider cmux` seam with best-effort fallback.
|
||||
- **Daemon read-path hardening** — SSE stream backpressure
|
||||
guards, projection caches, additive indices for read-side query
|
||||
performance. No functional behavior change; the same reads
|
||||
return the same results, faster.
|
||||
|
||||
### New bundled skills
|
||||
|
||||
- **`openrig-herdr`** — the full rig terminal open/views/status
|
||||
model (verbs, view grammar, honest-partial reading, read-only
|
||||
policy, terminal-views.yaml schema). AGPL clean-room rail — no
|
||||
herdr source text vendored.
|
||||
- **`openrig-cmux`** — the provider-agnostic vs cmux-specific
|
||||
delta with shipped-integration open-or-focus rule.
|
||||
|
||||
Both ship canonical + bundled openrig-core plugin, byte-parity
|
||||
guarded.
|
||||
|
||||
## Migrations
|
||||
|
||||
Additive only:
|
||||
|
||||
- `049_workflow_instance_version` — optimistic concurrency on
|
||||
`workflow_instances`.
|
||||
- `050_workflow_spec_json` — full parsed spec cached on
|
||||
`workflow_specs`; legacy rows self-heal on next read-through.
|
||||
- `051_workflow_resume` — `resume_count` + `hops_baseline` on
|
||||
`workflow_instances`.
|
||||
- `052_workflow_instance_bound_rig` — nullable `bound_rig` TEXT
|
||||
on `workflow_instances`.
|
||||
- `053_sessions_node_id_index` — additive index.
|
||||
- `054_queue_transitions_archive` — archive table for read-side
|
||||
query performance.
|
||||
|
||||
Existing v0.4.4 databases upgrade by running `rig daemon start` on
|
||||
the new daemon.
|
||||
|
||||
## Known Follow-ons
|
||||
|
||||
- **Save-verb** did not land in 0.4.6; rides 0.4.7.
|
||||
- **Twin fixture backfill** for the new workflow + multi-host UI
|
||||
routes routed as a non-blocking 0.4.7 hygiene fast-follow; UI
|
||||
acceptance for the cut carried by per-cut real screenshots + the
|
||||
two-host integration proof.
|
||||
- **Continuous out-of-band dogfood runtime** — the factory-rsi
|
||||
RSI edge ships ungated in the MVP; the continuous mechanism is
|
||||
refined in a later release.
|
||||
- **Carry-forwards from 0.4.4**: `openrig-user` bundled plugin
|
||||
stale-copy sweep, `whoami --all-hosts` silent host filter,
|
||||
managed-stop SIGTERM-escalation brittleness, post-cutover
|
||||
reconcile-settle-visibility signal on `/healthz`.
|
||||
- **iOS Safari** (Living Notes composer verification) —
|
||||
carry-forward from 0.4.4.
|
||||
- **Wider mission-template prose sweep** — post-cut sequencing.
|
||||
|
||||
Full technical detail lives in
|
||||
[CHANGELOG.md](../../CHANGELOG.md#046---2026-07-09).
|
||||
@@ -1,64 +0,0 @@
|
||||
# OpenRig v0.4.7
|
||||
|
||||
> **⚠️ Milestone:** v0.4.7 is where the **web UI moves to maintenance mode**. The CLI is the primary product surface from this release forward; the web UI still ships and still works, but is no longer receiving new feature work. If you drive OpenRig from a browser today, plan a transition to the CLI (and, from v0.5.0 onward, the terminal TUI: `rig` / `rig tui`). See the UI section below for the specifics that ship in 0.4.7.
|
||||
|
||||
## Summary — Recovery honesty + starter bootstrap + skills wave + Slack connector + UI maintenance-mode
|
||||
|
||||
**Recovery honesty is the through-line.** On a resumed restore, the startup sequence now loads a seat's applicable skill preloads before the role-defining first message — so a resuming seat knows its skills before it starts working. Compaction recovery is honest: transcript ingest exposes degraded states explicitly, and a post-compact restore-and-audit is gated on the seat being idle so "restore-sent" actually means "delivered". Daemon liveness reporting is honest — a dead seat drops effective running to 0 and reports `attention_required`; `rig send` and `rig capture` return an explicit "session missing" error when the seat is gone. CLI probes report uncertainty honestly — an unconfirmable status returns `UNKNOWN` with no false start advice, and a confirmed-stopped seat fails with actionable guidance.
|
||||
|
||||
Migrations are additive only. Existing v0.4.6 databases upgrade by running `rig daemon start` on the new daemon.
|
||||
|
||||
## What Shipped
|
||||
|
||||
### Starter bootstrap
|
||||
|
||||
Product-team starter bootstrap is cleaner, and starter seats get a skill preload on both fresh-start and restore. Default culture loads at startup, and rig specs are audited at load time. **Rigs instantiated before v0.4.7 need re-instantiation** (or spec-level patching) to pick up the starter fixes — the loader and audit changes apply immediately, but starter-spec content lands at instantiation.
|
||||
|
||||
### Skills wave
|
||||
|
||||
The bundled skill layer gains public routing and a default projection, plus public-skill strip and mirror controls, plus a plugin fix that keeps the documented skill count honest. The bundled skill inventory grows substantially, from a handful to broad coverage across core, PM, pod, and process families.
|
||||
|
||||
### Slack connector + human queue
|
||||
|
||||
First-class Slack connector shape (CLI `rig slack` commands + supporting library). Hosted create crosses an inconclusive local probe to the real configured-daemon result.
|
||||
|
||||
### CLI contract honesty
|
||||
|
||||
`--json` errors, flag validation, and scoped overdue behavior are tightened for machine-readable use.
|
||||
|
||||
### UI — moved to maintenance mode
|
||||
|
||||
**The web UI is frozen at this release in maintenance mode.** The wording is CLI-primary — never "deprecated"; the UI still ships and still runs, but it is no longer receiving new feature work, and CLI/TUI is the primary surface going forward. What lands in v0.4.7 to make this explicit to users:
|
||||
|
||||
- A dismissible in-app banner in the web UI announcing the maintenance-mode status.
|
||||
- A `rig ui open` stderr notice at launch time, so operators driving the CLI see the status before they open the browser.
|
||||
- Documentation positioning updated across README and user-facing docs.
|
||||
|
||||
Existing v0.4.6 deployments keep working; nothing is removed. The substantive product investment shifts to the CLI and, from v0.5.0, the terminal TUI.
|
||||
|
||||
### Queue, topology, review polish
|
||||
|
||||
- Queue compact-list rows mark elided fields so "omitted" is distinguishable from "empty".
|
||||
- Nested Approve posts a missions-root-relative scope path.
|
||||
- Mission review card composition is polished.
|
||||
- Unverified delivered items read "artifact-recorded" rather than "nothing delivered".
|
||||
- The drawer file viewer resolves inline in-body images via the file-asset API.
|
||||
- Proof-of-work Markdown links open in the in-app drawer.
|
||||
- Docs guard encodes the root-placement rule for `docs/DESIGN.md`.
|
||||
|
||||
### Host sizing guidance
|
||||
|
||||
Recommended: add swap on the host, and plan for roughly ~2 GB RSS per seat as an observed baseline.
|
||||
|
||||
## Behavior + Compatibility
|
||||
|
||||
- **Migrations** — additive only. Existing v0.4.6 databases upgrade by running `rig daemon start` on the new daemon.
|
||||
- **Rig-spec starter behavior** — the loader and audit changes apply immediately; starter-spec content lands at rig instantiation. Rigs instantiated before v0.4.7 need re-instantiation (or spec-level patching) to pick up the starter fixes.
|
||||
- **Seat-liveness API** — consumers should key seat liveness off the honest lifecycle state (updated every few seconds) rather than the older session-status field, whose staleness cleanup is tracked for a subsequent release.
|
||||
- **Web UI posture** — frozen in maintenance mode; no CLI surface breakage. Nothing is removed from the UI at this release.
|
||||
|
||||
## See Also
|
||||
|
||||
- `CHANGELOG.md` — the `[0.4.7]` entry.
|
||||
- `docs/releases/v0.4.6.md` — the prior release (workflows + multi-host + factory).
|
||||
- GitHub Release: https://github.com/mvschwarz/openrig/releases/tag/v0.4.7
|
||||
@@ -1,57 +0,0 @@
|
||||
# OpenRig v0.4.8
|
||||
|
||||
## Summary — Permission-posture fast-follow
|
||||
|
||||
Launch posture is configurable, the deny set writes at a level that project-local approvals can't override, and dangerous operations are gated by explicit prefix rules that actually hold under the current harness.
|
||||
|
||||
Migrations are additive only. Existing v0.4.7 databases upgrade by running `rig daemon start` on the new daemon.
|
||||
|
||||
## What Shipped
|
||||
|
||||
### Configurable launch posture
|
||||
|
||||
The hardcoded `--permission-mode acceptEdits` launch flag is replaced by a configurable posture defaulting to `dontAsk`. This closes the class of freezes where an autonomous seat could get stuck on a modal permission prompt with nobody to click through it. `dontAsk` is the default because it matches what an autonomous seat can actually respond to; `acceptEdits` remains selectable when a seat needs the prior behavior; a deliberate `bypassPermissions` value is preserved untouched across writes.
|
||||
|
||||
### Deny set that project-local approvals can't override
|
||||
|
||||
The posture writes to user-level `~/.claude/settings.json` instead of the project-local approval file. **Deny wins over project-local approvals** as a result. Writes are additive (never destructive to sibling keys) and forward-migrate a legacy `acceptEdits` value into the new schema. A deliberate `bypassPermissions` value is preserved.
|
||||
|
||||
### Bounded-dangerous deny set
|
||||
|
||||
Four dangerous operations are gated by default: `git push`, `gh pr create`, `npm publish`, and `rig down`. `rig down` in particular is gated via the prefix rule `Bash(rig down:*)` — the current Claude harness (2.1.220) only supports prefix matches on Bash rules, and flag-only patterns provably don't gate target-first forms like `rig down <rig> --force`, so the prefix rule is the only shape that actually holds. Plain `rig down` is gated in v0.4.8; selective allowance (e.g. `rig down <rig>` for a specific target) is deferred to v0.5.0 server-side enforcement.
|
||||
|
||||
### `rig up` un-gated
|
||||
|
||||
The prior release's ask-gate on `rig up` is removed — `rig up` is a reversible operation and doesn't warrant an interactive gate.
|
||||
|
||||
### Permission-policy foundation (built-ins land in v0.5.0)
|
||||
|
||||
- **Harness-neutral policy schema.** The permission-policy spec is a harness-neutral surface with `default_posture`, `floor`, and `allow` / `ask` / `deny` expressed as **semantic actions** (`push_to_remote`, `force_push`, `delete_files`, `read_secrets`, `create_pr`, `publish_package`, and so on) rather than raw shell-command patterns.
|
||||
- **`rig setup --policy <name>`** — a new flag on `rig setup` records a permission-policy choice into an existing rig spec. Takes a built-in name or a path to a custom policy file. The **built-in policy files themselves land in v0.5.0**; v0.4.8 ships the framework that consumes them.
|
||||
- **Two surfaces.** The **launch-flag** surface (Claude `--permission-mode`, Codex sandbox / bypass flags, Pi `--approve` / `--no-approve`) is stable and set by OpenRig for you — this is where the floor and full-bypass YOLO live. The **config-file** surface (Claude `~/.claude/settings.json`, Codex `config.toml`) is where allow/ask/deny rules live; because harness rule grammars change frequently across versions, this surface is applied interactively by an agent-driven skill (that skill ships in v0.5.0 as `applying-a-permission-policy`).
|
||||
|
||||
## Deployment Note (operators read this)
|
||||
|
||||
For the posture writes to reach seats, **the daemon's `HOME` must equal the seat's tmux `HOME`**. This is a Claude 2.1.220 settings-path invariant that matters for the remote-host leg of any upgrade:
|
||||
|
||||
- On a local-only host, this is typically satisfied automatically.
|
||||
- On a remote-host upgrade, verify HOME parity between the daemon process and the tmux seat process before treating the upgrade as complete.
|
||||
|
||||
(v0.5.0 documents this as a Known Issue for Codex `HOME` divergence; the product fix ships in v0.5.1.)
|
||||
|
||||
## Superseded
|
||||
|
||||
An initial v0.4.8 attempt (with `dontAsk` baked as a **platform default** rather than an OpenRig-side default) was withdrawn on final review; the shipped v0.4.8 is a re-scoped permission-agnostic base plus a policy-spec system. Nothing from the withdrawn attempt shipped.
|
||||
|
||||
## Behavior + Compatibility
|
||||
|
||||
- **Migrations** — additive only. Existing v0.4.7 databases upgrade by running `rig daemon start` on the new daemon.
|
||||
- **Default launch posture** — changed from hardcoded `acceptEdits` to configurable, default `dontAsk`. If a seat needs the prior behavior, select `acceptEdits` explicitly.
|
||||
- **Deny-set write location** — user-level `~/.claude/settings.json`; the deny set wins over project-local approvals. Writes are additive.
|
||||
- **`rig up`** — no longer ask-gated; reversible operations don't warrant interactive gates.
|
||||
|
||||
## See Also
|
||||
|
||||
- `CHANGELOG.md` — the `[0.4.8]` entry.
|
||||
- `docs/releases/v0.4.7.md` — the prior release (recovery honesty + starter bootstrap + skills wave + Slack + UI maintenance-mode).
|
||||
- GitHub Release: https://github.com/mvschwarz/openrig/releases/tag/v0.4.8
|
||||
Loaded 100 of 2613 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user