@openrig/cli 0.5.8 → 0.5.10

package/daemon/context-packs/skills/agent-operated-workflows/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: agent-operated-workflows
+description: >-
+  Use when a bounded real-world procedure has a deterministic happy path but brownfield, variable,
+  or partially knowable state; when an operation must resume from verified evidence; or when deciding
+  whether agent judgment or ordinary code should own a procedure's control loop.
+metadata:
+  openrig:
+    stage: provisional
+    audience: any agent operating or designing a bounded procedure
+    sibling_skills:
+      - agent-operated-software
+      - openrig-user
+      - systematic-debugging
+---
+
+# Agent-Operated Workflows
+
+An **Agent-Operated Workflow** is a bounded procedure whose control loop belongs to an agent. The
+agent observes, interprets, sequences bounded actions, verifies their effects, adapts, and escalates
+genuine ambiguity. Deterministic code remains the exact substrate; it does not pretend to understand
+every state of a brownfield world.
+
+## Name the architecture before using it
+
+- **AI-enabled software:** application code owns the control loop and calls a model as one capability.
+- **Agent-Operated Workflow:** an agent owns one bounded procedure with a start and stop condition.
+- **Agent-Operated Software:** an OpenRig agent or rig participates in an ongoing application's live
+  backend or control loop. It may run many workflows; see `agent-operated-software`.
+
+Calling a model is not enough. A deterministic program that consults a model still owns its loop.
+
+## Decide whether the agent earns the loop
+
+Use an agent when the happy path is deterministic but the environment is brownfield, variable,
+partially knowable, or disproportionately expensive to model exhaustively. The judgment is in
+discovering what is true and choosing the next safe act.
+
+Prefer ordinary code when the state space is closed and code is simpler and more reliable than
+judgment. A parser, fixed data transformation, or fully enumerated state machine does not become
+better because an agent drives it.
+
+## Keep ownership explicit
+
+| Owner | Responsibility |
+|---|---|
+| Runbook | owns policy, the mental model, checkpoints, stop conditions, and escalation rules |
+| Deterministic tools | own context gathering and bounded exact actions |
+| Agent | owns interpretation, sequencing, adaptation, and effect verification |
+| Human | owns destructive ambiguity and product policy |
+
+The runbook guides judgment; tools enforce the invariants that must not be arguable.
+
+## Operate
+
+1. Establish identity, durable state, the runbook, and the promised outcome.
+2. Inspect with side-effect-free reads or an explicit plan mode.
+3. Choose one bounded action from observed state; do not mechanically replay the happy path.
+4. Verify the effect at the consumer or state surface that could prove it wrong.
+5. Record an observable checkpoint before moving on, so another agent can resume.
+6. Continue, stop at the declared condition, or escalate with evidence and the decision needed.
+
+An interrupted or timed-out mutation is **indeterminate**, never failed by assumption and never safe
+to retry blind. Where a compatibility period is safer, separate reversible preparation from the
+destructive finalizer. Idempotence is a claim to prove per action, not a label for the whole run.
+
+## Build
+
+Expose composable verbs, not an optimistic end-to-end controller. Help is inert. Read and plan modes
+are explicit. Mutations are narrow and independently readable. A failure should say what was
+observed, why the tool stopped, what remains unchanged, the safe next choices, and where its evidence
+lives. Keep checkpoints durable, effects observable, and recovery possible without private developer
+knowledge.
+
+A capability composition is a reusable recipe; this is the execution architecture that operates
+capabilities toward an outcome. Promote a proven workflow to the composition shelf only after use.
+
+**Reference implementation:** Release 0.5.9 Slice 05 is the first **Agent-Operated Migration**. Its
+runbook and helpers remain there; this skill carries the reusable contract, not a duplicate procedure.

package/daemon/context-packs/skills/agent-operated-workflows/manifest.yaml

@@ -0,0 +1,10 @@
+# GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
+# Package-time projection of a canonical skill; regenerated every build.
+name: "agent-operated-workflows"
+version: "0.5.10"
+taxonomy: "skills"
+purpose: "Use when a bounded real-world procedure has a deterministic happy path but brownfield, variable, or partially knowable state; when an operation must resume from verified evidence; or when deciding whether agent judgment or ordinary code should own a procedure's control loop."
+files:
+  - path: "SKILL.md"
+    role: "instruction"
+    summary: "Use when a bounded real-world procedure has a deterministic happy path but brownfield, variable, or partially knowable state; when an operation must resume from verified evidence; or when deciding whether agent judgment or ordinary code should own a procedure's control loop."

package/daemon/context-packs/skills/applying-a-permission-policy/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "applying-a-permission-policy"
-version: "0.5.8"
+version: "0.5.10"
 taxonomy: "skills"
 purpose: "Use when a permission policy is attached to a rig/seat (rig.yaml permission_policy:), or a user asks you to apply one, and you must translate that harness-neutral policy into the target harness's LIVE permission config — Claude settings.json / Codex config.toml / Pi run flags. Agent-driven and interactive: you read the policy, ground yourself in YOUR harness version, show the diff, and ask before writing. NOT for defining policies (that's the policy spec) and NOT a set-and-forget updater."
 files:

package/daemon/context-packs/skills/claude-compaction-restore/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "claude-compaction-restore"
-version: "0.5.8"
+version: "0.5.10"
 taxonomy: "skills"
 purpose: "Use when a Claude Code session has just compacted, is about to compact, reached context limit, resumed after /compact, or needs to rebuild its working mental model from Claude JSONL transcripts and touched files."
 files:

package/daemon/context-packs/skills/core/agent-starters/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "agent-starters"
-version: "0.5.8"
+version: "0.5.10"
 taxonomy: "skills"
 purpose: "Use when creating, refreshing, packaging, inspecting, promoting, or deprecating a named per-seat starting point — Agent Starter manifest authoring, the 6-state lifecycle (captured → named → inspectable → used → promoted → deprecated), provenance honesty, and refusal rules. NOT a VM image; a managed starting point composed from agent role + startup context + optional native session source + provenance."
 files:

package/daemon/context-packs/skills/core/agent-startup-and-context-ingestion/SKILL.md

@@ -58,13 +58,28 @@ is scattered or stale, agents execute the wrong thing very efficiently.
 3. **A startup file becomes a dumping ground and loses the map-to-canonical-sources role.** Startup should point AT canonical sources; it shouldn't TRY to be one.
 4. **The orchestrator transmits implementation instructions without preserving product intent.** Instructions decay; intent travels.
 
-## Proof standard
+## Task-scoped startup
+
+Run `rig whoami --json`, then resolve `project.yaml -> mission.yaml -> active
+slice.yaml -> selected component or wave map -> addressed context`. The complete
+lookup and precedence rule is `docs/reference/product-journey-sdlc.md#resolve-the-selected-path`
+(installed: `$OPENRIG_HOME/reference/product-journey-sdlc.md#resolve-the-selected-path`).
+Read the selected addresses and source needed for this task; skills available in
+your profile are capabilities, not a mandatory reading list. No composition means
+light Part A. Role names and idle seats add no gates. Explicit rigor and authored
+wave boundaries retain their named checks.
+
+Startup files are address maps, not universal reading mandates. Do not preload
+unrelated planning/review doctrine or require per-file ACKs and quizzes. Skill
+availability is distinct from loading its full body. An old packet does not choose
+the current work. Missing selected context is a named gap to resolve.
 
-Startup proof should:
+## Proof standard
 
-1. **Launch or refresh** a seat
-2. **Inspect** what it actually read
-3. **Verify** it can state the current role, mode, active constraints, and next handoff convention **in its own words**
+In a disposable fresh session, observe the actual reads and resulting next action.
+Test no-selection, explicit rigor, and wave-boundary cases. An edit is not evidence
+that an already-running seat adopted it; adoption needs an authorized refresh or
+next-launch observation. Do not clear or re-prime a live seat merely to test prose.
 
 ## Cross-runtime startup paths (5; do not collapse)
 
@@ -102,7 +117,7 @@ culture / pod / member / operator) handles the layering.
 
 ## See also
 
-- `mission-slice-sop` skill — the universal operating procedure for working a mission/slice (the canonical SPEC.md, NOTES.md, PROGRESS.md, PROOF.md, and proof/ surfaces); every agent should reach for it at startup, so this general reading contract points at it here (do NOT duplicate the SOP into seat-specific startup files).
+- `mission-slice-sop` — load when starting assigned mission/slice work; the light artifact and handoff procedure for SPEC.md, NOTES.md, PROGRESS.md and proof. It does not choose the SDLC for the task.
 - `writing-skills-for-openrig` skill — authoring discipline for skill content (what doesn't belong in startup)
 - `forming-an-openrig-mental-model` skill — orientation for new agents
 - `session-compaction-and-restore` skill — restore-time startup ingestion

package/daemon/context-packs/skills/core/agent-startup-and-context-ingestion/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "agent-startup-and-context-ingestion"
-version: "0.5.8"
+version: "0.5.10"
 taxonomy: "skills"
 purpose: "Use when designing or auditing how an agent becomes useful after launch — AGENTS.md overlays, role files, skills, rig specs, workflow specs, startup checklists, refocus messages, \"rig context\" surface. Covers the 4 failure modes that make startup context fail (old rig spec misses current operating mode; current agents never told about new guidance; startup file as dumping ground; orchestrator transmits implementation without preserving product intent)."
 files:

package/daemon/context-packs/skills/core/cross-host-rig-commands/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "cross-host-rig-commands"
-version: "0.5.8"
+version: "0.5.10"
 taxonomy: "skills"
 purpose: "Use when issuing `rig` commands against a remote host via `--host <id>` flag (single-hop SSH to a host declared in `~/.openrig/hosts.yaml`). Covers the 4 structured failure modes (ssh-unreachable / permission-gate / remote-daemon-unreachable / remote-command-failed), the `--verify` honest pass-through (SSH success is NOT verify success), and the host-registry shape. v0 supports `rig send / capture / ps / whoami --host <id>`."
 files:

package/daemon/context-packs/skills/core/human-in-the-loop/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "human-in-the-loop"
-version: "0.5.8"
+version: "0.5.10"
 taxonomy: "skills"
 purpose: "Use when classifying a slice closeout (auto-continue / human gate / park), routing a real decision to a human, or designing a human queue/dashboard surface. Treats humans as durable network participants with attention surfaces, queues, and decision records — escalation lands as a durable attention item, not a chat message. Approval is NOT required for every clean closeout; the default RSI conveyor continues unless an explicit human gate is reached."
 files:

package/daemon/context-packs/skills/core/messaging-the-human/SKILL.md

@@ -1,98 +1,85 @@
 ---
 name: messaging-the-human
-description: "Use when a human decision, access grant, external action, or escalation must survive the operator's absence, or when an orchestrator or PM has a judgment-worthy update for the operator."
+description: "Use when project policy calls for a human decision or update, a human delivery is pending or failed, or a reply must resume the right work."
 metadata:
   cli_surfaces_referenced:
-    - gateway human add
     - gateway human list
-    - queue block
-    - queue handoff
+    - gateway human show
+    - queue create
     - queue transitions
+    - queue block
     - send
   openrig:
     stage: provisional
     audience: all agents
     sibling_skills:
       - queue-handoff
-      - human-in-the-loop
       - openrig-user
 ---
 
 # Messaging the Human
 
-The human is an addressable participant, but their attention is scarce and they
-may not be at a terminal. Anything that must survive their absence needs a
-durable queue row; the gateway turns the human blocker on that row into the
-external notification.
-
-Any seat may contact the human directly for a real escalation. Orchestrators
-and product managers may also send updates they judge the human would want to
-know. Do not add a routing intermediary merely because of your role.
+Project World supplies **when and why** to contact a human. This skill supplies
+transport-neutral mechanics; installing it does not create an approval gate or
+choose a connector. If policy leaves a material decision ambiguous, identify the
+missing authority. Do not convert a solvable technical failure into a human gate.
 
-## The supported route
+## Discover, check, send, inspect
 
-First discover the registered human identity. Never invent or remember an
-address:
+Discover the registered participants and inspect the chosen human:
 
 ```bash
 rig gateway human list --json
+rig gateway human show <entityId> --json
 ```
 
-Use `humans[].entityId` to derive the durable blocker as `<entityId>@host`.
-The entity id must use the human-seat prefix (`human` or `human-...`); if it
-does not, stop and repair the registration rather than guessing. The returned
-`humans[].address` is the gateway delivery address, not the `--on` value. If no
-unambiguous registered human is returned, stop: registration is lifecycle work
-(`rig gateway human add --help`), not an address to guess.
+Use the returned `address` (`<entityId>@external`), not a username, remembered
+seat, connector handle, or guessed kernel address. Where several humans exist,
+use the decision ownership in Project World. An absent or ambiguous registration
+needs a named registration correction, not a fallback address.
 
-Keep the work row owned by the agent who must resume it, then park that row on
-the registered human:
+Check readiness: configured, enabled, active, ready, reason, and next action.
+`indeterminate` is not ready. Follow the reported next inspection; do not enable
+or reconfigure a connector merely to make the check pass.
+
+Write the decision, evidence, and continuation in a body file. The sole outbound
+human-message primitive is:
 
 ```bash
-rig queue block <qitem-id> --on <entityId>@host \
-  --summary "<decision owed>" \
-  --evidence-ref "<durable artifact the human should judge>" \
-  --continuation "<what resumes after the answer>"
+rig queue create --destination <entityId>@external \
+  --summary "<decision or update>" --body-file <packet-file> \
+  --evidence-ref <durable-evidence> --verify --json
 ```
 
-The gateway resolves the registered human to the configured connector, sends
-the Slack notification, and records its receipt on the same row. Confirm the
-effect from the append-only history:
+If an existing agent-owned row must wait, block it on the **new live qitem ID**
+(`rig queue block <work-id> --on <human-qitem-id> ...`), not on the human address.
+Completion of the human qitem resumes its dependants. Blocking on the human as
+well would issue another notification for the same decision.
+
+The row persists before bounded delivery verification. Read its qitem ID and
+verification result; `posted` proves connector posting, **not human readership**.
+`transport-failed`, `never-posted`, or a pending/indeterminate result leaves the
+row intact. Inspect that same row and its next action; never create a second row
+or blindly resend because verification timed out.
 
 ```bash
 rig queue transitions <qitem-id>
 ```
 
-The row is the obligation and the audit trail. Slack is the attention leg. A
-reply resolves the durable blocker and wakes the row owner; it does not create
-a second private work stream.
-
-## When to use it
-
-Escalate directly when only the human can supply the missing capability:
-
-- a decision or irreversible judgment only they own;
-- access, credentials, authority, or capacity only they can grant;
-- an external action only they can perform;
-- a security-class or provider/model-fallback event they need to know about.
-
-Orchestrators and product managers may additionally send meaningful milestone,
-environment, or completion updates. Prefer signal over routine narration.
-
-## Boundaries
+A correlated reply binds to that exact human and qitem and records the resolution
+that resumes the owner. Check the recorded result before claiming the decision
+arrived; a delivery receipt alone is not acceptance.
 
-- `rig send` sends text to an agent's terminal. It is not the Slack route and
-  does not create a durable human obligation.
-- An unregistered or ambiguous human identity must fail loudly. Register or
-  repair the identity; never downgrade it to an agent seat or a guessed
-  `@external` address.
-- Agent-to-agent work that needs closure uses `rig queue handoff`, not this
-  human-blocker path.
-- Deferred work that is not imminent belongs in the mission workspace, not on
-  the queue.
+## Existing blockers and other channels
 
-## Writing the escalation
+An existing agent-owned row may be blocked on `<entityId>@host`. That is an
+internal custody label resolved through the human registry to the same external
+participant; it is not a second delivery address. Keep the owner and continuation
+on that row. Inspect its existing delivery receipt before considering another
+request, so a legacy blocker does not produce a duplicate message. Never derive
+`@host` from the current rig name.
 
-Lead with what is blocked and the exact decision or action needed. Point at the
-durable evidence instead of pasting a second copy, and name the continuation so
-the system can resume the right work when the answer arrives.
+`rig send` reaches an agent's terminal only. It is not a human transport or a
+durable human obligation. Agent-to-agent work uses the queue handoff path.
+Connector-specific configuration and handles belong to registry/readiness tools,
+not to project-independent message instructions.

package/daemon/context-packs/skills/core/messaging-the-human/manifest.yaml

@@ -1,10 +1,10 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "messaging-the-human"
-version: "0.5.8"
+version: "0.5.10"
 taxonomy: "skills"
-purpose: "Use when a human decision, access grant, external action, or escalation must survive the operator's absence, or when an orchestrator or PM has a judgment-worthy update for the operator."
+purpose: "Use when project policy calls for a human decision or update, a human delivery is pending or failed, or a reply must resume the right work."
 files:
   - path: "SKILL.md"
     role: "instruction"
-    summary: "Use when a human decision, access grant, external action, or escalation must survive the operator's absence, or when an orchestrator or PM has a judgment-worthy update for the operator."
+    summary: "Use when project policy calls for a human decision or update, a human delivery is pending or failed, or a reply must resume the right work."

package/daemon/context-packs/skills/core/openrig-architect/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "openrig-architect"
-version: "0.5.8"
+version: "0.5.10"
 taxonomy: "skills"
 purpose: "Use when designing multi-agent topologies that run ON OpenRig — authoring RigSpec and AgentSpec files for new rigs, creating agent startup content (guidance / skills / culture), or diagnosing why a launched rig's agents aren't behaving as intended. NOT for changing OpenRig itself (use openrig-builder); NOT for ordinary CLI operation of an existing rig (use openrig-user). Covers the full authoring lifecycle from user intent to validated, launchable rig."
 files:

package/daemon/context-packs/skills/core/openrig-cmux/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "openrig-cmux"
-version: "0.5.8"
+version: "0.5.10"
 taxonomy: "skills"
 purpose: "Use when opening OpenRig fleet terminals into cmux — turning a rig, pod, mission, slice, or saved view into live agent tiles via `rig terminal --provider cmux`, or driving cmux on an agent's request. Same OpenRig view semantics as openrig-herdr (the verbs, honest-partial/degrade, read-only cross-rig, scroll/copy, same-size-only duplicates); cmux is the **best-effort** provider (herdr is the default and the proof-gated one). Prefer openrig-herdr unless cmux is specifically wanted."
 files:

package/daemon/context-packs/skills/core/openrig-herdr/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "openrig-herdr"
-version: "0.5.8"
+version: "0.5.10"
 taxonomy: "skills"
 purpose: "Use when opening OpenRig fleet terminals as a herdr wall — turning a rig, pod, mission, slice, or saved view into live interactive agent tiles via `rig terminal`, watching another rig read-only, or driving herdr on an agent's request (\"open all my rigs + a mission as views\"). Covers the `rig terminal open|views|status` verbs, the honest-partial/degrade reading of the result, the read-only-by-construction rail for cross-rig views, scroll/copy out of the box, and the same-size-only duplicate-pane "
 files:

package/daemon/context-packs/skills/core/openrig-skills/SKILL.md

@@ -13,7 +13,7 @@ You're running inside OpenRig. OpenRig ships a set of **skills** — small docum
 
 ## How OpenRig context works (30 seconds)
 
-Skills are **progressive disclosure**: a skill's *name + description* sit in your context ambiently (the "hot tier"); its *body* loads only when you open it. So you don't pre-read everything — you pattern-match a skill's "when" to your moment, then open just that one. This file is the index over the whole shipped set. (For the full model of building/operating agent software, open `software-for-agents`.)
+Skills are **progressive disclosure**: a skill's *name + description* sit in your context ambiently (the "hot tier"); its *body* loads only when you open it. So you don't pre-read everything — you pattern-match a skill's "when" to your moment, then open just that one. This file is the index over the whole shipped set. (For bounded procedures, open `agent-operated-workflows`; for ongoing agent-backed applications, open `agent-operated-software`.)
 
 Every row below names **how to reach the skill** — already-hot, or an exact load path. No row is a dead end.
 
@@ -63,7 +63,9 @@ These are auto-delivered to every rig; their name+description are already in you
 - **retiring-and-inheriting-a-seat** — you're planning a seat transition and need to retire the current occupant into a fresh successor without losing continuity.
 - **mission-slice-sop** — you're working a mission/slice (the SDLC: intent → mini-requirements + proof contract → build → QA → proof). The operating manual.
 - **messaging-the-human** — composing a message to the human. Plain language, no insider jargon.
-- **software-for-agents** — you want the full first-load model of how agent software is built and operated here.
+- **agent-operated-workflows** — a bounded real-world procedure needs an agent to interpret state and operate exact tools, or you are deciding whether ordinary code should own the loop.
+- **agent-operated-software** — you are designing or operating an ongoing application whose live backend includes OpenRig agents.
+- **software-for-agents** — compatibility redirect for the former `agent-operated-software` name; remove in 0.6.0.
 - **openrig-skills** — this index (you're reading it). Always loaded; the entry point to everything below.
 
 ### Load when your role or task calls for it (repo-shipped, profile-selected)

package/daemon/context-packs/skills/core/openrig-skills/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "openrig-skills"
-version: "0.5.8"
+version: "0.5.10"
 taxonomy: "skills"
 purpose: "Use when you're operating OpenRig and need the right skill or context for fleet recovery, seat handover, new-seat orientation, a watchdog wake, cross-host reach to an agent on another machine, rig packaging, an OpenRig upgrade, systematic debugging, queue triage, or implementation planning; also use when you don't know what applies or nothing is projected on cold boot."
 files:

package/daemon/context-packs/skills/core/openrig-upgrade/SKILL.md

@@ -113,6 +113,87 @@ The helper never deletes a live file and never overwrites a local modification.
 Local deletions, live-only files, target removals, and ambiguous types are
 reported for the agent to resolve. Re-run the plan after any manual resolution.
 
+### Migrate a pre-0.5.9 instance layout
+
+Version 0.5.9 puts context-usage telemetry in
+`$OPENRIG_HOME/state/context-usage`, provider telemetry in
+`state/provider-usage`, the addressable library under `context/`, and the
+default System World at `context/system/system-world.yaml`. Existing 0.5.8
+homes cross that boundary through an **Agent-Operated Migration**: the target
+runtime reads canonical-first with legacy-fallback while all new writes use the
+canonical state roots. An explicitly configured custom context-library root
+stays stable throughout activation.
+
+The helper supplies bounded, inspectable operations. The agent owns their
+sequence and the target-runtime activation between them. With an exact
+protected preimage path, first inspect and then prepare canonical directories,
+the default System World, and a config pin to the existing library. Preparation
+does not copy telemetry, rewrite live collector settings, or run lifecycle
+actions:
+
+`--help` prints the phase grammar without inventorying the instance. With no
+phase flag the helper intentionally runs the read-only plan; unknown options
+fail nonzero before plan or mutation.
+
+```bash
+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 "$OPENRIG_HOME/backups/layout-0.5.9-before"
+```
+
+Activate the exact target runtime using the ordinary upgrade workflow. Then
+wait until every bounded post-apply legacy tail is followed by newer paired
+new-root samples for that same seat. This proves temporal convergence
+without blanket process replacement; a later legacy write remains a hard stop.
+Capture the verification JSON; copied old sidecars are not evidence:
+
+```bash
+node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
+  --home "$OPENRIG_HOME" \
+  --verify \
+  --preimage "$OPENRIG_HOME/backups/layout-0.5.9-before" \
+  > /safe/path/layout-0.5.9-verify.json
+```
+
+Only a successful receipt authorizes the separately invoked non-destructive
+finalizer. It copies an unconfigured legacy library into the canonical root
+without overwriting anything; a custom context-library root remains stable:
+
+```bash
+node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
+  --home "$OPENRIG_HOME" \
+  --apply-library \
+  --preimage "$OPENRIG_HOME/backups/layout-0.5.9-before" \
+  --verification /safe/path/layout-0.5.9-verify.json
+```
+
+Stop on every reported issue: malformed or foreign telemetry, a reserved-path
+conflict, a library collision, config drift, resumed legacy writes, byte drift,
+or a missing fresh dual sample all require the named repair before continuing.
+Verification binds the exact accepted tail bytes to their paired-newer samples;
+the finalizer revalidates them immediately before switching config. The helper
+never removes the legacy telemetry or library. Their later retirement is a
+separate agent decision after stable runtime, writer, reader, and recovery proof.
+It does not stop/start the daemon, launch a seat, touch the database, or decide
+whether the upgrade proceeds.
+
+To recover, restore the prior runtime as the agent-led workflow requires, then
+reverse only helper-owned config, System World, empty-directory, and copied
+library effects. Real state samples and both legacy recovery sources remain for
+inspection:
+
+```bash
+node "$SKILL_DIR/scripts/migrate-telemetry-state-0.5.9.mjs" \
+  --home "$OPENRIG_HOME" \
+  --rollback "$OPENRIG_HOME/backups/layout-0.5.9-before"
+```
+
 ## Agent-led continuity upgrade
 
 This is a decision guide, not a command recipe. Adapt paths and checks to the

package/daemon/context-packs/skills/core/openrig-upgrade/manifest.yaml

@@ -1,7 +1,7 @@
 # GENERATED by scripts/generate-context-packs.mjs — DO NOT EDIT.
 # Package-time projection of a canonical skill; regenerated every build.
 name: "openrig-upgrade"
-version: "0.5.8"
+version: "0.5.10"
 taxonomy: "skills"
 purpose: "Use when an agent is preparing or performing an OpenRig CLI/daemon upgrade and must preserve live seats, verify each mutation, or reconcile managed plugin and skill files without overwriting local work."
 files:
@@ -12,5 +12,7 @@ files:
     role: "reference"
   - path: "scripts/inspect-upgrade.mjs"
     role: "reference"
+  - path: "scripts/migrate-telemetry-state-0.5.9.mjs"
+    role: "reference"
   - path: "scripts/refresh-managed-plugin.mjs"
     role: "reference"