@openrig/cli 0.7.0 → 0.7.1

package/daemon/docs/reference/a2a-agents.md

@@ -0,0 +1,343 @@
+# Handing work between OpenRig and A2A agents
+
+An OpenRig seat can give a queue row's task to an outside A2A agent. In the other direction, an A2A server can
+front a seat's queue and return its answer as an artifact. These are compositions of the
+[official Python SDK](https://github.com/a2aproject/a2a-python) and existing `rig queue` commands, not a
+`rig a2a` command or a daemon endpoint. The scripts below are examples you run and own.
+
+OpenRig does not configure the outside agent's permissions, model or credentials. Choose a peer and task content
+you are authorized to share. The peer's result is its report, not acceptance of the work by your team.
+
+## Before either recipe
+
+Use a working OpenRig installation and an existing seat. `rig whoami --json` identifies your seat;
+`rig ps --nodes --rig <rig>` shows the receiving seat's canonical session name. If you need a team first, use
+[getting started](getting-started.md). Keep the daemon and provider environment you already use.
+
+In a scratch folder, make a Python environment (Python 3.10 or newer, with `venv` and `pip` available):
+
+```sh
+python3 -m venv .venv
+.venv/bin/python -m pip install 'a2a-sdk[http-server]==1.1.0' httpx uvicorn
+```
+
+The examples pin the SDK version used in the pipe trials; they are not a recommendation to downgrade another
+application. The official SDK 1.1.0 paths were exercised in both directions. Other 1.x versions were not tested.
+Recheck the API and cancellation behavior when changing versions.
+
+Pydantic AI 2.60.0 with FastA2A 2.1.1 did not interoperate with these SDK 1.1.0 recipes in the tested setup:
+FastA2A's inbound typed client returned `result={}` even though the SDK front, with 0.3 compatibility enabled,
+sent task, artifact and completed records in its raw SSE stream. Outbound, the official SDK raised a protobuf
+parse error at the FastA2A task's `status.timestamp`; the full wire timestamp was not retained. When mixing
+frameworks, compare the raw stream's task IDs, artifact and final status with the typed client's output.
+An HTTP 200 or an empty typed result is not proof that the task succeeded. Retain the evidence before retrying.
+
+Save this helper as `queue_io.py`:
+
+```python
+import asyncio
+import json
+
+async def rig(*args):
+    child = await asyncio.create_subprocess_exec(
+        'rig', *args, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE)
+    out, err = await child.communicate()
+    if child.returncode:
+        raise RuntimeError(f'rig {args[:2]} exited {child.returncode}: {err.decode()} {out.decode()}')
+    return json.loads(out)
+```
+
+It inherits the caller's OpenRig environment. Run queue operations in the intended seat's environment; set
+`OPENRIG_URL` only when deliberately selecting another daemon. A timed-out write is uncertain: read its row and
+transitions before trying again. Do not silently send the task a second time.
+
+## Outbound: a queue task goes to an A2A peer
+
+You need the peer's base URL and a row assigned to your seat. For a no-model peer, the official
+[Hello World sample](https://github.com/a2aproject/a2a-samples/tree/6603ba3f2c31a7ef33e70b9d8b5b5f8be42ac9a3/samples/python/agents/helloworld)
+returns an echo artifact. Its README explains startup; it does not implement the input-required and cancellation
+controls described later. Use a peer that supports those operations when testing them.
+
+Save as `a2a_client.py`. This client also works without an OpenRig row, for the inbound recipe below.
+Streaming reads have no deadline so quiet worker waits keep their stream; connection, write and pool waits are bounded to 10 seconds.
+Stop the local wait with Ctrl-C or a caller-owned overall deadline; this does not confirm cancellation, so keep the task/context IDs and cancel through the peer when it is reachable.
+
+```python
+import asyncio
+import json
+import os
+import uuid
+from pathlib import Path
+import httpx
+from a2a.client import A2ACardResolver, ClientConfig, create_client
+from a2a.helpers import new_text_message
+from a2a.types import Role, SendMessageRequest
+from google.protobuf.json_format import MessageToDict
+from queue_io import rig
+
+async def main():
+    row_id = os.environ.get('A2A_ROW')
+    text = os.environ.get('A2A_TEXT')
+    if row_id:
+        row = await rig('queue', 'show', row_id, '--full', '--json')
+        identity = await rig('whoami', '--json')
+        if row['destinationSession'] != identity['identity']['sessionName']:
+            raise RuntimeError('Choose a row assigned to this seat.')
+        if row['state'] == 'pending':
+            await rig('queue', 'claim', row_id, '--json')
+            row = await rig('queue', 'show', row_id, '--full', '--json')
+        if row['state'] != 'in-progress':
+            raise RuntimeError('The row is not in progress; inspect it before sending.')
+        if text is None:
+            text = row['body']
+    if text is None:
+        raise RuntimeError('Set A2A_TEXT or A2A_ROW.')
+    message = new_text_message(text, role=Role.ROLE_USER)
+    if os.environ.get('A2A_CONTEXT'):
+        message.context_id = os.environ['A2A_CONTEXT']
+    if os.environ.get('A2A_TASK'):
+        message.task_id = os.environ['A2A_TASK']
+    log_path = Path(f'a2a-{uuid.uuid4()}.jsonl').resolve()
+    state, bound = 'UNKNOWN', False
+    with log_path.open('x') as log:
+        async with httpx.AsyncClient() as http:
+            card = await A2ACardResolver(httpx_client=http, base_url=os.environ['A2A_URL']).get_agent_card()
+        log.write(json.dumps({'card': MessageToDict(card), 'message': MessageToDict(message)}) + '\n')
+        log.flush()
+        client = await create_client(agent=card, client_config=ClientConfig(
+            streaming=True, httpx_client=httpx.AsyncClient(timeout=httpx.Timeout(10.0, read=None))))
+        try:
+            async for chunk in client.send_message(SendMessageRequest(message=message)):
+                event = MessageToDict(chunk)  # SDK 1.1.0 yields StreamResponse, not a tuple.
+                log.write(json.dumps(event) + '\n')
+                log.flush()
+                print(json.dumps(event), flush=True)
+                task = event.get('task')
+                if task and row_id and not bound:
+                    await rig('queue', 'update', row_id, '--note',
+                        f"A2A peer={card.name} task={task['id']} context={task['contextId']} log={log_path}", '--json')
+                    bound = True
+                status = (task or event.get('statusUpdate') or {}).get('status', {})
+                state = status.get('state', state)
+        finally:
+            await client.close()
+    if row_id:
+        await rig('queue', 'update', row_id, '--note', f'A2A reported {state}; full result/events: {log_path}', '--json')
+    print(f'Reported state: {state}; saved events: {log_path}')
+
+asyncio.run(main())
+```
+
+Run it from your seat, replacing the row and peer URL:
+
+```sh
+export A2A_URL=http://127.0.0.1:9999
+export A2A_ROW=<your-row-id>
+.venv/bin/python a2a_client.py
+```
+
+Read the saved `artifactUpdate` parts and final status. Put the useful result on the **same** row, using a note
+while work continues or a resolution when you deliberately close it. The script leaves the row owned and open:
+
+```sh
+rig queue update "$A2A_ROW" --note 'A2A result: <answer, artifact reference, and any limits>' --json
+# Only when your work on the row is actually finished:
+rig queue update "$A2A_ROW" --state done --closure-reason no-follow-on --resolution '<your assessed outcome>' --json
+```
+
+If the stream fails, retain its exception and log. The peer may still be working; inspect the known task before
+resending. When the task asks for input, set `A2A_TASK` and `A2A_CONTEXT` to its recorded IDs and `A2A_TEXT` to the
+answer, then run the client again. For a new follow-up, unset `A2A_TASK` and keep `A2A_CONTEXT`: a completed task
+is not reopened. Unset `A2A_TEXT` when the next outbound task should again use its row body.
+
+## Inbound: an A2A client reaches an OpenRig seat
+
+Run the following server in a custodian seat's environment, with `A2A_SEAT` set to the existing worker seat's
+canonical session name. The worker is a separate participant: it watches its queue, claims the row, does the work
+and writes a resolution. A deterministic shell worker is enough to test this path; a model is optional.
+
+Save as `a2a_front.py` beside `queue_io.py`:
+
+```python
+import asyncio
+import json
+import os
+import uvicorn
+from starlette.applications import Starlette
+from a2a.helpers import get_message_text, new_task_from_user_message, new_text_message, new_text_part
+from a2a.server.agent_execution import AgentExecutor
+from a2a.server.request_handlers import DefaultRequestHandler
+from a2a.server.routes import create_agent_card_routes, create_jsonrpc_routes
+from a2a.server.tasks import InMemoryTaskStore, TaskUpdater
+from a2a.types import AgentCapabilities, AgentCard, AgentInterface, AgentSkill
+from queue_io import rig
+
+seat = os.environ['A2A_SEAT']
+rows, canceling, published = {}, set(), {}
+
+class Front(AgentExecutor):
+    async def execute(self, context, events):
+        task = context.current_task or new_task_from_user_message(context.message)
+        if not context.current_task:
+            await events.enqueue_event(task)
+        update = TaskUpdater(events, task.id, task.context_id)
+        published[task.id] = asyncio.Event()
+        try:
+            text = get_message_text(context.message)
+            if task.id not in rows:
+                row_id = 'qitem-a2a-' + task.id
+                body = json.dumps({'taskId': task.id, 'contextId': task.context_id, 'request': text})
+                await rig('queue', 'create', '--id', row_id, '--destination', seat, '--body', body,
+                    '--summary', 'Inbound A2A task', '--no-nudge', '--full', '--json')
+                rows[task.id] = row_id
+            else:
+                row_id = rows[task.id]
+                await rig('queue', 'update', row_id, '--note', 'A2A answer: ' + text, '--json')
+            working = False
+            while True:
+                row = await rig('queue', 'show', row_id, '--full', '--json')
+                if task.id in canceling:
+                    await asyncio.Future()  # cancel() owns the terminal event.
+                if row['state'] == 'done':
+                    if not row.get('resolution'):
+                        await update.failed(new_text_message('Row closed without a result resolution.'))
+                    else:
+                        await update.add_artifact([new_text_part(row['resolution'])], name='seat-result')
+                        await update.complete(new_text_message('Seat closed row ' + row_id))
+                    return
+                if row['state'] in ('failed', 'denied', 'handed-off'):
+                    await update.failed(new_text_message(row.get('resolution') or ('Row ' + row['state'])))
+                    return
+                if row['state'] == 'canceled':
+                    await update.cancel(new_text_message('Queue row canceled.'))
+                    return
+                if row['state'] == 'in-progress' and not working:
+                    await update.start_work(new_text_message('Seat claimed ' + row_id))
+                    working = True
+                history = await rig('queue', 'transitions', row_id, '--full', '--json')
+                notes = [t.get('transitionNote') or '' for t in history]
+                conversation = [n for n in notes if n.startswith(('A2A question: ', 'A2A answer: '))]
+                if conversation and conversation[-1].startswith('A2A question: '):
+                    await update.requires_input(new_text_message(conversation[-1][14:]))
+                    return
+                await asyncio.sleep(1)
+        except asyncio.CancelledError:
+            if task.id in canceling:
+                await published[task.id].wait()  # See SDK 1.1.0 cancellation note below.
+            raise
+        except Exception as error:
+            await update.failed(new_text_message(str(error)))
+
+    async def cancel(self, context, events):
+        canceling.add(context.task_id)
+        try:
+            row_id = rows[context.task_id]
+            await rig('queue', 'update', row_id, '--state', 'canceled', '--resolution',
+                'A2A client requested cancellation; worker stop not yet confirmed.', '--json')
+            await TaskUpdater(events, context.task_id, context.context_id).cancel(
+                new_text_message('Queue cancellation committed; worker stop is a separate observation.'))
+        finally:
+            published[context.task_id].set()
+
+card = AgentCard(name='OpenRig queue: ' + seat, version='example-1',
+    description='A worker seat returns its queue resolution.',
+    default_input_modes=['text/plain'], default_output_modes=['text/plain'],
+    capabilities=AgentCapabilities(streaming=True),
+    supported_interfaces=[AgentInterface(protocol_binding='JSONRPC', url='http://127.0.0.1:19092', protocol_version='1.0')],
+    skills=[AgentSkill(id='queue-work', name='Queue work', description='Work assigned to ' + seat, tags=['queue'])])
+handler = DefaultRequestHandler(agent_executor=Front(), task_store=InMemoryTaskStore(), agent_card=card)
+app = Starlette(routes=[*create_agent_card_routes(card), *create_jsonrpc_routes(handler, '/')])
+uvicorn.run(app, host='127.0.0.1', port=19092)
+```
+
+Start the front, then use a second terminal for the outside client:
+
+```sh
+# Custodian terminal:
+export A2A_SEAT=<worker-session-from-rig-ps>
+.venv/bin/python a2a_front.py
+
+# Client terminal, in the folder with the example scripts and venv:
+unset A2A_ROW A2A_TASK A2A_CONTEXT
+export A2A_URL=http://127.0.0.1:19092
+export A2A_TEXT='Return the words hello from the receiving seat.'
+.venv/bin/python a2a_client.py
+```
+
+The client waits while the worker does its part. In the **worker's own environment**, inspect and claim the row:
+
+```sh
+rig queue list --owned --full --json
+export ROW=<the-new-qitem-a2a-id>
+rig queue show "$ROW" --full --json
+rig queue claim "$ROW" --json
+rig queue update "$ROW" --state done --closure-reason no-follow-on --resolution 'hello from the receiving seat' --json
+```
+
+The client should receive that exact resolution as an artifact, followed by completed. Compare the artifact with
+`rig queue show "$ROW" --full --json`, including the task/context IDs in the row body. The sample uses `--no-nudge`:
+the worker must be watching its queue; merely starting the front does not start or wake an agent.
+
+For input-required, the worker instead records `--note 'A2A question: <question>'` and leaves the row in progress.
+The client reruns with the same `A2A_TASK`, `A2A_CONTEXT` and its answer as `A2A_TEXT`. The worker reads the
+`A2A answer: ` transition with `rig queue transitions "$ROW" --full --json`, then finishes that row. These prefixes
+are this example's small convention, not built-in OpenRig fields. A new follow-up omits the completed task ID and
+keeps the context ID; it produces a new row.
+
+## Cancel and read the outcome honestly
+
+For a protocol-1.0 JSON-RPC peer, a direct control request includes `A2A-Version: 1.0`. For example, after the task
+is bound and working (substitute its ID; use `GetTask` with the same parameters to inspect it):
+
+```sh
+curl -sS "$A2A_URL" -H 'Content-Type: application/json' -H 'A2A-Version: 1.0' \
+  --data '{"jsonrpc":"2.0","id":"cancel-1","method":"CancelTask","params":{"id":"<task-id>"}}'
+```
+
+Read the JSON body and task state, not just HTTP status. A pipe trial received HTTP 200 carrying JSON-RPC
+`-32009 VERSION_NOT_SUPPORTED` when the version header was omitted. That was an error, not a completed task.
+The SDK handles versioned calls; raw requests must follow the peer's advertised interface and
+[protocol version rules](https://a2a-protocol.org/v1.0.0/specification/).
+
+SDK 1.1.0's default V2 handler cancels the running producer **before** awaiting the executor's `cancel` callback.
+If that callback awaits a queue write, the producer can close the event channel first. The inbound trial then
+returned stale working state even though the row was canceled. The event in the example keeps that producer
+alive until the callback publishes its outcome. This is specific to the exercised ordering; see the
+[pinned SDK implementation](https://github.com/a2aproject/a2a-python/blob/v1.1.0/src/a2a/server/agent_execution/active_task.py).
+Test it again when changing SDK versions, including an awaited external write rather than an immediate callback.
+
+Keep these facts separate:
+
+| A2A observation | What it means for the queue or worker |
+|---|---|
+| Submitted | The A2A front accepted a task; a row may not yet be created. |
+| Working | This front observed the receiving seat's claim. |
+| Input-required | A question needs answering; this example leaves the row in-progress. |
+| Completed + artifact | The worker's stored result was returned; your assessment still belongs to you. |
+| Canceled | This inbound front committed queue cancellation; an outside peer's cancellation says nothing about your outbound row. Verify separately that the worker noticed and stopped. |
+| Failed / JSON-RPC error | Retain the actual error and any row effect; do not report success. |
+| Disconnect / timeout | The last known state remains all you know. Inspect before retrying. |
+
+There is no one-to-one A2A/queue state mapping. The example does not follow handoffs to another row, so it reports
+that limit instead of pretending the successor's work completed. Stopping the front only detaches clients; it does
+not cancel its queue rows or stop their workers. Cancel or hand off outstanding work deliberately before stopping
+your server. Acknowledged cancellation does not establish that a model provider stopped spending.
+
+## What was exercised, and what remains open
+
+The initial trials used an OpenRig 0.7.0 candidate and SDK 1.1.0 on Linux. Outbound discovery, streamed output and
+artifacts used the official Hello World sample. Deterministic peers covered input-required, cancellation, failure
+and concurrency. Inbound used a private daemon and a separate no-model queue worker: five artifacts matched the
+stored resolutions, two tasks overlapped without crossing IDs, and completed-task reuse left the old result
+unchanged. The successful cancellation check also observed the worker stop, beyond receiving the protocol reply.
+
+A later inbound check used an official SDK 1.1.0 client and front, an OpenRig queue row, and Pi 1.4.0 running
+`openai/gpt-4o-mini`. One marker answer reached the row's resolution and the client's completed artifact. A
+custodian performed the queue writes; model tools were disabled. That run used a 120-second streaming read
+timeout and prompt RPC event draining, changed together. It did not separately test the unbounded read used above.
+
+These results do not establish model quality or provider billing. Other framework versions, model tool use,
+public deployment and authentication, stream reconnect, durable bridge restart, and cancellation before row
+binding were not exercised. The inbound example holds A2A tasks and their row mapping in memory: keep it running for the conversation;
+after a crash, inspect retained OpenRig rows before any replacement run. It binds loopback and supplies no public
+authentication layer. Use it on your own machine or a trusted private path, not as an unauthenticated public gateway.

package/daemon/docs/reference/acp-agents.md

@@ -0,0 +1,77 @@
+# Handing work to an ACP agent
+
+`rig acp run` gives one queue row's task to an agent that speaks the
+[Agent Client Protocol](https://agentclientprotocol.com) (ACP), such as OpenClaw's `openclaw acp`, and records what
+happened on that same row. The seat that runs it is the row's custodian; the agent is recorded as the executor.
+
+```sh
+rig acp run <qitemId> --cwd <work folder> -- <the agent's ACP command> [args...]
+```
+
+The row's notes get, in order:
+- **the binding:** the agent's name and version, the ACP protocol version, whether it can load sessions, and the session;
+- **progress,** about once a minute (tool calls so far, output so far); the full transcript is in the run's log file, named on the row;
+- **each permission request and its answer** (below);
+- **the outcome:** `completed`, `stopped` (for example `max_tokens`), `cancelled`, `failed` or `unknown`, with the
+  agent's output;
+- **what happened to the agent's processes** after the run ended.
+
+The outcome is the agent's report, not a judgment of the work. The row stays open and yours: read the result, then
+close it or hand it on with your own resolution, as you would any other.
+
+## When the agent asks permission
+
+OpenRig holds no permission policy of its own. The agent's own settings decide what it asks, and an owner decides
+the answer. Each request becomes a queue row to `--permissions-to` (this seat by default), listing the action, its
+target, the options the agent offered and the run, session and request it belongs to. Answer on that row with the
+option's id:
+
+```sh
+rig queue update <permission row> --state done --closure-reason no-follow-on --resolution allow-once
+```
+
+Answer on the permission row itself; don't hand it off, because the run waits on that row. The answer goes back to
+that one request, once. The turn waits for it; there's no deadline. An answer that isn't one
+of the offered options is noted and the question is asked again. If the turn is cancelled first, the permission row
+is closed as stale and nothing is sent. Whoever answers can follow their own written policy; that choice is theirs.
+
+## Cancel, detach and stop
+
+These are different things, and the row keeps them apart:
+- **Cancel** (Ctrl-C, or `rig acp cancel <runId>` from another terminal) asks the agent to stop its turn. The row
+  records when it was requested and when the agent acknowledged it. Whether the model provider stopped work, and what
+  it cost, stays **unknown** unless you check the provider's own usage.
+- **Detach** (a second Ctrl-C, or the run ending normally) closes the agent's connection. That doesn't stop
+  the agent's runtime.
+- **Stop:** when the run ends, it reports whether any process carrying the run's environment marker remains:
+  `settled` (none), `incomplete` (with their process ids) or `unknown` (the process table couldn't be read). Only
+  processes that inherited the marker are seen, so one the agent started with a cleared environment, or through a
+  service manager, isn't. It never touches a process it didn't launch. To stop what's left, use the runtime's
+  own stop command, through `rig acp stop <runId> -- <that command>` so the result lands on the row.
+
+A gateway the agent connects to but didn't start, such as OpenClaw's Gateway, isn't a process of the run. Leave a
+shared one running; stop your own with its own command.
+
+## Reading the outcome
+
+- `completed`: the agent ended its turn with output.
+- `unknown`: the turn ended, but nothing shows the work happened. That covers an `end_turn` with no output and no or
+  zero usage (an agent can end a turn this way after its provider refused the request), an `end_turn` whose text
+  reports an interruption (OpenClaw's `[OpenClaw interruption]`), and a connection that closed before the turn ended.
+  Check the agent's own log before you treat it as done.
+- `failed`: the agent returned an error. The row keeps its original code, message and data.
+- `cancelled`, `stopped`: as above.
+
+## Notes for specific agents
+
+- **OpenClaw:** `openclaw acp` is a bridge to a running OpenClaw Gateway, so start the Gateway first, then run, for
+  example, `rig acp run <row> -- openclaw acp --url ws://127.0.0.1:18789 --token-file <file>`. Its permission requests
+  come from the Gateway's exec approvals.
+- **Continuing a session:** `--load-session <id>` continues an earlier session when the agent advertises loading. If it
+  doesn't, or the load fails, the run reports that and starts nothing new.
+
+## Limits
+
+- One run is one turn for one row.
+- The client offers the agent no file-system or terminal methods; the agent works in its own environment.
+- Spend is whatever the agent's provider charges; OpenRig doesn't measure it.

package/daemon/docs/reference/agent-spec.md

@@ -177,6 +177,7 @@ defaults:
 | `runtime` | string | no | — | Default runtime for this agent. Precedence: the rig spec member's `runtime`, then the profile's `preferences.runtime`, then this, then `claude-code`. |
 | `model` | string | no | — | Default model, with the same precedence. |
 | `effort` | string | no | — | Default reasoning effort, with the same precedence. Claude gets `--effort`, Codex `-c model_reasoning_effort=…`, Pi `--thinking <level>` (Pi's levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`; passed as written). A blank or non-string value is ignored with an advisory. |
+| `advisor` | string | no | — | Default Claude Advisor model, with the same precedence. Passed as the session-scoped `--advisor` flag, independently of the primary model; never written to shared Claude settings. Blank or non-string values are ignored with an advisory. Other runtimes ignore it. |
 | `lifecycle` | Lifecycle | no | see below | Lifecycle behavior defaults. |
 
 ### Lifecycle Defaults
@@ -259,10 +260,11 @@ profiles:
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
 | `summary` | string | no | — | Profile description. Spec review surfaces read a profile `description` instead. |
-| `preferences` | object | no | — | Runtime/model/effort preferences for this profile. |
+| `preferences` | object | no | — | Runtime/model/effort/Advisor preferences for this profile. |
 | `preferences.runtime` | string | no | — | Preferred runtime. |
 | `preferences.model` | string | no | — | Preferred model. |
 | `preferences.effort` | string | no | — | Preferred reasoning effort. |
+| `preferences.advisor` | string | no | — | Preferred Claude Advisor model; overrides `defaults.advisor` and can be overridden by the member. |
 | `uses` | Uses | no | all empty | Selects which declared resources are active for this profile. |
 | `startup` | StartupBlock | no | — | Profile-level startup files and actions. Merged with agent-level startup via layering. |
 | `lifecycle` | Lifecycle | no | — | Profile-level lifecycle overrides. `restore_policy` can only narrow (`resume_if_possible` → `relaunch_fresh` → `checkpoint_only`); `compaction_strategy` and `mechanic` take the most specific value (defaults, then profile, then member). |
@@ -288,7 +290,7 @@ The `uses` categories are: `skills`, `guidance`, `subagents`, `plugins`, `runtim
 empty list, is refused: hooks ship inside plugins.
 
 **Skills resolve more widely than other resources.** For Claude Code and Codex seats, a skill ID that no declared
-resource provides is looked up at launch in the seat's runtime skill folder (`<cwd>/.claude/skills` or
+resource provides is looked up at launch in the project's runtime skill folder in the seat's cwd (`<cwd>/.claude/skills` or
 `<cwd>/.agents/skills`), then the `skills/` folder beside the RigSpec, then the home skill folder, then the managed
 skills root. Pi looks only in the `skills/` folder beside the RigSpec. OMP does no filesystem discovery, so its
 `uses.skills` references need declared resources. A discovered skill's ID is its `SKILL.md` frontmatter `name`, and a declared resource wins over a discovered skill with the
@@ -368,10 +370,10 @@ version.
 
 | Category | Fields | Description |
 |----------|--------|-------------|
-| `skills` | `id`, `path` | Skill directories containing a SKILL.md. Projected by the runtime adapter: Claude to `<cwd>/.claude/skills/<id>`, Codex to `<cwd>/.agents/skills/<id>`, Pi and OMP to the seat's own agent directory under OpenRig's state. |
+| `skills` | `id`, `path` | Skill directories containing a SKILL.md. Projected by the runtime adapter. Claude and Codex seats get them in the seat's own storage, `<OpenRig home>/state/seats/<rig id>/<logical seat>/<runtime>/`, outside the project: Claude to `plugin/skills/<id>` in the seat's generated plugin, where they show as `openrig:<id>`, and Codex to `skills/<id>` beside the seat's skill catalog. A Claude or Codex seat without that storage gets `<cwd>/.claude/skills/<id>` or `<cwd>/.agents/skills/<id>`. Pi and OMP project to the seat's own agent directory under OpenRig's state. |
 | `guidance` | `id`, `path`, `target`*, `merge`* | Guidance files, merged as a managed block (see "Guidance Resources"). |
 | `subagents` | `id`, `path` | Subagent definitions. Claude copies them to `<cwd>/.claude/agents/`, Codex to `<cwd>/.agents/`; Pi and OMP don't project them. |
-| `plugins` | `id`, `source`, `plugin_type`* | Local plugin directories; selected with `uses.plugins`. `source.kind` must be `local`. `plugin_type` is `claude`, `codex` or `auto` (default): Claude projects a plugin to `<cwd>/.claude/plugins/<id>` when it is `claude`, or `auto` with a `.claude-plugin/plugin.json`; Codex projects to `<cwd>/.codex/plugins/<id>` when it is `codex`, or `auto` with a `.codex-plugin/plugin.json`. Pi and OMP don't project plugins. Neither Claude Code nor Codex reads skills from that plugin folder, so when a seat is instantiated a selected plugin's skills are also projected into the seat's skill folder (`.claude/skills/<name>` or `.agents/skills/<name>`) under their plain names. A folder already there with the same name, ignoring letter case, that OpenRig doesn't own is left alone; unless it already holds the same bytes, launch warns `plugin_skill_kept`. A skill the seat already selects by that name (from its profile, the System World or the project) keeps that source, an edited OpenRig-owned copy is kept with `plugin_skill_kept`, a retained plugin copy whose remembered source can no longer be projected is also kept with `plugin_skill_kept` (a seat selecting that plugin refreshes it at its next launch), and if the plugin skills can't be projected the seat launches without them and warns `plugin_skills_not_projected`. Hooks ship inside plugins. |
+| `plugins` | `id`, `source`, `plugin_type`* | Local plugin directories; selected with `uses.plugins`. `source.kind` must be `local`. `plugin_type` is `claude`, `codex` or `auto` (default): Claude projects a plugin to `<cwd>/.claude/plugins/<id>` when it is `claude`, or `auto` with a `.claude-plugin/plugin.json`; Codex projects to `<cwd>/.codex/plugins/<id>` when it is `codex`, or `auto` with a `.codex-plugin/plugin.json`. Pi and OMP don't project plugins. Neither Claude Code nor Codex reads skills from that plugin folder, so when a seat is instantiated a selected plugin's skills are also projected into the seat's skill folder under their plain names: the seat's own storage (see `skills`), or `.claude/skills/<name>` or `.agents/skills/<name>` for a seat without it. A folder already there with the same name, ignoring letter case, that OpenRig doesn't own is left alone; unless it already holds the same bytes, launch warns `plugin_skill_kept`. A skill the seat already selects by that name (from its profile, the System World or the project) keeps that source, an edited OpenRig-owned copy is kept with `plugin_skill_kept`, a retained plugin copy whose remembered source can no longer be projected is also kept with `plugin_skill_kept` (a seat selecting that plugin refreshes it at its next launch), and if the plugin skills can't be projected the seat launches without them and warns `plugin_skills_not_projected`. Hooks ship inside plugins. |
 | `runtime_resources` | `id`, `path`, `runtime`, `type` | Runtime-specific resources. `runtime` and `type` are required. An entry whose `runtime` isn't the seat's runtime is skipped. Pi and OMP project none. |
 
 *Fields marked with `*` are optional.
@@ -459,7 +461,7 @@ restore behavior, and the distinction between readiness and verified proof.
 
 | Hint | When Delivered | Mechanism |
 |------|---------------|-----------|
-| `auto` | Depends on the file | A path ending in `SKILL.md`, or content beginning with `# SKILL`, is `skill_install`; otherwise a `.md` file is `guidance_merge`, and any other file is `send_text` |
+| `auto` | Depends on the file | A seat's own role (a file marked `orientation: role`, or at a `guidance/role.md` path) is `send_text`, so pod-mates never overwrite each other's role in the shared file. A seat launched before this rule keeps the hint saved at its launch, which restore (`rig up <rig>`), `rig seat launch --fresh` and handover replay, until the rig is instantiated from its spec again: `rig down <rig>`, then `rig up <spec file>`, which starts a new generation with fresh conversations. Otherwise a path ending in `SKILL.md`, or content beginning with `# SKILL`, is `skill_install`; a `.md` file is `guidance_merge`; and any other file is `send_text` |
 | `guidance_merge` | Before harness boot | Merged into CLAUDE.md/AGENTS.md as managed block |
 | `skill_install` | Before harness boot | Installed to runtime skill directory |
 | `send_text` | After harness is ready | Sent as text to agent terminal via tmux |

package/daemon/docs/reference/agent-startup-guide.md

@@ -321,6 +321,12 @@ not the destination's file contents.)
 - `rig seat launch <seat> --fresh --stop --reason <text>`, which starts a blank conversation; or
 - `rig handover <seat> --source rebuild --reason <text>`, which carries durable context.
 
+For Codex rebuilds, OpenRig also carries a complete supported native permission policy read from the live
+predecessor's own conversation and process, without adding fresh-launch grants. A later recorded seat permission
+or policy choice, or a differing declared successor profile, takes precedence. Missing, stale or unsupported observations keep the existing launch
+behaviour and are reported as unverified in the handover result; requested modes and profiles alone don't prove
+preservation. The result reports what was emitted, not native successor equivalence.
+
 **Adopt it promptly.** The saved directory doesn't move the running process, but background work can use it before
 adoption. Saved configuration isn't the live process's directory, and these examples aren't the only consumers. For a
 running Claude seat:
@@ -517,6 +523,46 @@ remain shared.
 
 **Terminal seats** (`builtin:terminal`) get no agent or profile layers and no startup proof.
 
+### Claude compaction preparation directory
+
+Managed Claude compaction asks the seat to write a restore map before `/compact`. By default,
+OpenRig uses `<cwd>/.openrig/compaction/preparation/`, falling back to its instance home when
+that directory cannot be prepared. A filesystem write check cannot establish whether Claude's
+file-edit permissions allow the seat to write there.
+
+If the launch workspace is denied by Claude's permissions, select an absolute preparation root:
+
+```sh
+rig config set policies.claude_compaction.preparation_root /absolute/path/to/restore-maps
+```
+
+Grant the seat file-edit access to that root in its Claude configuration. OpenRig does not change
+Claude permissions; choose a directory outside any matching deny rule. The corresponding environment
+variable is `OPENRIG_POLICIES_CLAUDE_COMPACTION_PREPARATION_ROOT`.
+
+New manual and automatic attempts use `<root>/<session>/<attempt-id>/RESTORE-MAP.md`; an in-flight
+attempt keeps its original path through the post-compaction restore request. The root gets an
+exclusive `.gitignore` containing `*`, and the daemon publishes the marked `.tmp` file with an
+atomic rename. Use a dedicated root: a conflicting
+ignore file or an unwritable configured directory stops preparation with
+`preparation_directory_unavailable`, visible in `rig compact <session> --state`, without choosing
+another location. Fix the directory and explicitly retry. `--skip-map` still skips the map once.
+
+Reset with `rig config reset policies.claude_compaction.preparation_root` to restore the default.
+The setting applies to new attempts without restarting the daemon.
+
+The managed `/compact` command keeps its 600-character budget. When the selected map path or
+the attempt's compaction instruction does not fit, the existing restore request carries it;
+it never substitutes a newer preparation root or instruction. An explicitly selected root's
+published map is also named in that request when the path fit in `/compact`. The default root
+keeps the existing command/restore handoff. Under `--skip-map`, restore still recognizes an
+optional map completed at that attempt's path, or says that no map was required.
+
+The compaction preparation and command-submission tests cover manual and automatic attempts,
+long paths and instructions, settings changed during preparation, directory failures and
+late maps after cancellation or expiry. They use synthetic delivery and filesystem fixtures;
+they do not prove a live Claude session's permission choices or compaction behavior.
+
 ### Codex compaction and sizing
 
 OpenRig's managed compaction is for Claude Code seats only, by design. That covers `rig compact`, the

package/daemon/docs/reference/agent-state-taxonomy.md

@@ -41,6 +41,24 @@ state. Attention/alarm values likewise stay in their own machinery (`attentionCo
 Both herdr and omnigent converged on this exclusion, with warning comments on the
 collision in both codebases.
 
+### Per-seat attention in the node inventory
+
+`rig ps --nodes` carries the daemon's `needsAttention` result, using the same predicate
+as the rig's `attentionCount`. It also serves `arbitratedNeedsInput`: `true` for observed
+input, `false` for an observed clear, and `null` when no authoritative needs-input source
+answered. `needsInputEvidence` retains that source's rung and observation time, or `null`.
+A zero prompt count alone is not an observed clear. Absent arbitration evidence leaves
+the existing live-hook fallback in effect; lifecycle, startup, held and error signals
+can independently raise attention. A false attention flag means no known trigger, not
+proof that an unobserved input box is clear.
+
+The compact human table's ATTN column renders `yes`, `no`, or `?` when the flag is
+unavailable. Compact JSON retains `needsAttention`; use `--full` or
+`--fields needsAttention,arbitratedNeedsInput,needsInputEvidence` with `--json` for the
+provenance. The TUI uses the served flag for attention glyphs and totals, and shows the
+needs-input evidence in seat detail, including a hook-only prompt. With an older daemon,
+attention stays unknown while its existing prompt, startup and error hints remain visible.
+
 ## Derived diagnoses — computed at read time, never stored
 
 - **PARKED** — the disease: `(activity = idle-at-prompt OR needs-input pending) ×
@@ -106,7 +124,13 @@ time-bounded evidence. Rungs, top down, with each rung's retirement condition:
   without `agent_end`) leaves the seat working up to the 15 s window, then unknown, never idle. After a
   daemon restart, a runner seat takes its last recorded boundary from the hook store, for its
   current session and occupant generation only, so an idle seat still reads idle before it
-  posts again.
+  posts again, provided that report is fresh: a pi runner's idle boundary states an interval
+  (below) and lapses to unknown once it is older than two of them.
+  A pi runner also posts an idle `Stop` (`idle_heartbeat`) every three minutes while it waits, and states that
+  interval as `livenessSeconds` on every `Stop`: a newly ready runner reads idle at once, and an idle boundary that
+  carries an interval holds for two of them, then lapses to unknown, so a runner killed without saying so stops reading
+  idle. Silence never clears a pending attention prompt, and a runner that states no interval (omp, an older pi
+  runner) keeps the hold-until-the-next-boundary behaviour.
 
 Partial-coverage honesty: a source with partial lifecycle coverage gets identity-only
 trust, unless its inventory declares it positive-only. A positive-only source can report
@@ -132,7 +156,8 @@ LIFECYCLE); see the
 - **Attention codes:** `trust_gate`, `hook_trust_gate`, `update_gate`, `login_required`,
   `mcp_gate`, `bypass_consent_gate`, `codex_auth_refusal`, `codex_client_incompatible`.
 - **Restore outcome:** `resumed`, `fresh-primed`, `awaiting-decision`, `attention_required`,
-  `failed` (plus `rebuilt`, `operator_recovered` and the legacy `fresh`).
+  `failed` (plus `rebuilt`, `operator_recovered` and the legacy `fresh`). A seat joined with
+  `rig attach` as an external CLI reads `left_attached`: restore leaves it as it is.
 
 ## Rejected oracles — dated receipts (2026-08-26), so nobody re-derives them expensively
 

package/daemon/docs/reference/checked-seat-stop.md

@@ -0,0 +1,11 @@
+# Checked seat stop (HTTP)
+
+Read `GET /api/seat/stop-precondition/:seatRef` immediately before an operator-confirmed stop. A successful response has this shape:
+
+```json
+{"contract":"seat-stop.v1","expected":{"nodeId":"<node ID>","sessionId":"<latest session ID or null>"}}
+```
+
+Pass `expected` unchanged in the body of the existing `POST /api/seat/stop/:seatRef`, alongside `reason` and optional `operator`. The contract marker lets clients detect support. `expected` is optional; a request without it retains the existing stop behavior. A malformed explicit value returns HTTP 400. A null session ID can describe an empty seat, but stopping it returns `no_session`.
+
+Checked stop requires the delivery guard. It refuses a changed node, latest session, binding or occupant before a terminal effect with HTTP 409 `selection_changed`. If the selection changes after client detach, the response reports `partialEffect: true` and no kill is sent. A kill failure or a failure to save stop state after a kill reports `stop_uncertain`; inspect the seat before retrying. Success retains the usual `seat`, `sessionName` and `sessionId` fields.

package/daemon/docs/reference/community-harness-examples/cursor/cursor.yaml

@@ -0,0 +1,13 @@
+# Install as $OPENRIG_HOME/community-harnesses/cursor.yaml, with openrig-cursor-launch on the seat's PATH.
+format: 1
+name: cursor
+command: openrig-cursor-launch
+maintainer: Your name or team
+limits:
+  - startup assisted; check the pane and submit any staged identity text
+  - resume reads a chat as missing unless its store is in the seat's Cursor config folder, under the seat's working directory
+  - no guidance, skills or startup files are placed
+  - needs-input and approval prompts are read from the screen only
+launch_result: true
+resume: true
+startup_assisted: true