docs(orchestration): make coordinator recovery agent-explicit

config/scripts/orchestration-skill-guidance.test.mjs

@@ -59,7 +59,9 @@ describe('orchestration skill guidance', () => {
     expect(authority).toContain('per-Run authority')
     expect(authority).toContain('not an operating-system or global Orca privilege')
     expect(authority).toContain('`run-use` is an authority claim, not a read-only selection')
-    expect(authority).toContain('fenced failures report only `live` or `unverifiable`')
+    expect(authority).toContain('`coordinatorStatus` is `live` or `unverifiable`')
+    expect(authority).toContain('`claimantStatus` is `changed`')
+    expect(authority).toContain('rejects the claim with `effectsApplied: false`')
     expect(authority).toContain('a proven `exited` incumbent permits the claim to succeed')
     expect(authority).toContain('`live`')
     expect(authority).toContain('`unverifiable`')
@@ -75,6 +77,7 @@ describe('orchestration skill guidance', () => {
     expect(authority).toContain('check')
     expect(authority).toContain('run-show --id <run_id> --json')
     expect(authority).toContain('binding.currentConsumer')
+    expect(authority).toContain('never proves that the Run is unowned')
     expect(authority).toContain('stop or exit the owning coordinator process')
     expect(skill).not.toContain('unless impersonating another terminal')
     expect(skill).toContain(

skill-guides/orchestration.md

@@ -105,7 +105,9 @@ Orca orchestration is agent-operated. A Run therefore has one current coordinato
 
 The single-writer rule prevents two agents from changing Task, Dispatch, worker, or gate state concurrently and prevents two consumers from acknowledging different views of the same FIFO Delivery. The current coordinator may create and update Tasks (`task-create`, `task-update`), start or dispatch workers (`worker-start`, `dispatch`), create and resolve gates (`gate-create`, `gate-resolve`), answer worker questions (`reply`), and consume or acknowledge Run mail (`check`). Explicit `run-show`, `task-list --run`, inbox, and peek calls remain read-only for non-owners and headless callers.
 
-`run-use` is an authority claim, not a read-only selection. Read `error.data.coordinatorStatus` and `error.data.nextSteps` from `--json` failures; fenced failures report only `live` or `unverifiable` because a proven `exited` incumbent permits the claim to succeed. Never infer authority from a terminal handle alone.
+`run-use` is an authority claim, not a read-only selection. When a transfer is intended, make one claim from the stable replacement agent terminal with `orca orchestration run-use --id <run_id> --json`; do not guess whether its process is a remint or spoof the owner with `--from`. Orca either preserves same-process authority, grants replacement authority after proving exit, or rejects the claim with `effectsApplied: false`.
+
+On rejection, read `error.data.coordinatorStatus`, `claimantStatus`, `nextSteps`, and any exact command-argument fields. `coordinatorStatus` is `live` or `unverifiable` because a proven `exited` incumbent permits the claim to succeed. If `claimantStatus` is `changed`, the invoking agent changed during proof; follow the returned retry arguments once from one stable process instead of treating it as a network verdict or retrying blindly. Never infer authority from a terminal handle alone.
 
 - Same coordinator process, reminted handle: authority and any outstanding Delivery are preserved without advancing the consumer generation.
 - Different process and `live` incumbent: `consumer_fenced`; continue from the owning coordinator terminal. To transfer intentionally, stop or exit the owning coordinator process before retrying from its replacement.
@@ -119,7 +121,7 @@ orca orchestration run-show --id <run_id> --json
 orca orchestration task-list --run <run_id> --json
 ```
 
-`binding.currentConsumer` is `true` only for the current coordinator. `false` permits inspection, not coordinator mutations or consuming `check` calls.
+`binding.currentConsumer` is `true` only for the current coordinator. `false` permits inspection, not coordinator mutations or consuming `check` calls, and never proves that the Run is unowned.
 
 No live-to-live transfer command exists. A seamless live handoff would require a separate owner-authorized protocol; do not simulate one by retrying, changing `--from`, or replacing a terminal handle. `--takeover-legacy` is not a force override for ordinary Runs: it is limited to the automatically adopted legacy Run described above.
 
@@ -222,7 +224,9 @@ Two limits worth knowing:
 
 - **It is a guardrail, not a security boundary.** A caller that declares another terminal's
   handle while its own launch evidence is unverifiable (an ordinary restored terminal, for
-  example) can be counted as that terminal instead. Orca does not treat workers as hostile.
+  example) can be counted as that terminal instead. This affects only nesting-depth
+  classification; it never grants coordinator or Dispatch authority. Orca does not treat
+  workers as hostile.
 - **It applies while a Dispatch is active.** After `worker_done`, or after a coordinator
   settles the task, the terminal is no longer a worker and is counted as a root again. The
   process may still be alive; that is the documented boundary, not an accident.

src/cli/specs/orchestration.ts

@@ -22,8 +22,9 @@ export const ORCHESTRATION_COMMAND_SPECS: CommandSpec[] = [
     allowedFlags: [...GLOBAL_FLAGS, 'id', 'from', 'takeover-legacy', 'retry-request'],
     notes: [
       'Rebinding the same live coordinator preserves authority and Delivery. A different coordinator succeeds only when the owning host proves the prior coordinator exited.',
-      'A live or unverifiable owner returns consumer_fenced with structured recovery steps. Do not retry blindly or treat loss of contact as exit.',
-      '--takeover-legacy is only for the automatically adopted legacy Run; it is not a force override for ordinary Runs.'
+      'From the intended replacement agent, one run-use is the safe decision point: success preserves or transfers authority; rejection applies no effects and returns coordinatorStatus, claimantStatus, and exact recovery steps.',
+      'A live or unverifiable owner returns consumer_fenced. Do not retry blindly, treat loss of contact as exit, infer an unowned Run from currentConsumer: false, or use --from to copy the owner handle.',
+      '--takeover-legacy explicitly replaces only the automatically adopted legacy Run coordinator. It is not a force override for ordinary Runs and must not be used while the legacy coordinator is actively coordinating.'
     ]
   },
   {