The seven non-orchestration guide rewrites, the shared stub fragment, and their guards move to a separate PR. The orca-cli cross-guide pin follows the worktree-selector rule into the orchestration placement reference.
Apply the Change findings from the skill review.
Correctness:
- relayGracePeriodSeconds now states that 0 is unbounded (the relay stays up
until explicitly terminated) and names the accepted domain, 0 or 60..604800
from EphemeralVmRecipeSshTargetSchema. Removed from the SSH exemplar so the
omitted default and a written value cannot disagree.
- The SSH exemplar carries only the required fields. jumpHost/proxyCommand
exclusivity is stated once, where the choice is made.
- The provisioned-root snippet fetches "$ORCA_REPO_URL", the remote Orca
resolved the base ref against, not origin.
- portForwards entries name localPort/remoteHost/remotePort and optional label
against the strict SavedPortForwardSchema.
- The free doctor gate is clear only with no fail and no warn; buildDoctorResult
leaves ok true with warnings.
- The worked auth check uses the status command's exit code by default via a
sentinel, since a provider CLI need not propagate a remote exit code. The grep
recipe stays as the named fallback and matches a shell variable, so no
pipefail/SIGPIPE hazard remains.
Structure:
- One outcome spine with a joined done bar, and one autonomy envelope replacing
the four money restatements, the five checkpoint rationales, and Boundaries.
- Quick-start deleted; the numbered sequence is the single copy.
- Kernel keeps what must fire without a read; the four worked examples and the
failure modes move to skill-guides/orca-per-workspace-env/references/.
- Description replaced with the review's proposal; the ORCA placeholder rule is
stated once and the Claude Code bang prefix is fenced as a harness adapter.
The generator test's reference assertions are generalized per guide, and the
Vercel name-building pins are repointed to the file that now carries them.
Emulator: drop the camera-injection verb (it does not exist in
src/cli/specs/emulator.ts), drop iOS permissions (the iOS backend
declares permissions: false so the bridge throws emulator_unsupported),
fix the Android permissions positional order and remove the nonexistent
list op, and delete the stale 'visual pane in development' status and
the 'once the attach/active flow lands' qualifier. State the wrapped-verb
and backend-capability conditions once, add an outcome spine, and drop
the ASCII diagrams and identity prose.
Linear: delete the 27-line Common Commands mirror of --help, replace the
verb-keyed unconfirmed-write rules with the payload-keyed condition that
covers every write verb, add a skill-level done bar for all five
branches, and move examples onto the ORCA placeholder.
All four descriptions rewritten off body-owned detail.
The resolver ladder, the ORCA placeholder rule, the no-guessing paragraph,
and the older-binary fallback frame were authored eight times each and had
already drifted where they were re-copied. Move them into one fragment,
skill-stubs/_shared/cli-resolution.md, and have each per-topic stub mark
where they land with `<!-- shared: <id> -->`.
The projected skills/<name>/SKILL.md is byte-identical for all eight topics,
so no manifest revision moves.
Applies the Change findings from the orca-cli / computer-use skill review.
orca-cli guide:
- Delete the duplicated mobile-emulator tail and the second `Next Action`; the
emulator now routes through one conditional-references row.
- State the handoff done bar once, and state the `terminal wait` gate with its
failure direction beside the recipe: `terminal wait` prints an ordinary result
envelope on timeout and signals the unsatisfied wait only through the exit
code, so an agent could send a brief into a half-started TUI.
- State the one-agent-handle invariant once in Worktrees; the Terminals copy and
the two restatements are gone.
- Drop the executable-resolution ladder the discovery stub owns and keep one
placeholder rule, in the shape `skill-guides/orchestration.md` uses.
- Move the reconstructible command catalogs (browser, automations, artifact and
skill publishing) behind `skills get orca-cli --full`; the routing paragraph,
the untrusted-page-content rule and the artifact publish gate stay inline.
- 424 always-loaded lines to 260.
computer-use guide: promote the verification vocabulary to a done bar, and drop
its copy of the resolver ladder.
Repointed the generator's resolver-phrase assertions for these two guides to the
stub projections that now own the ladder, and generalized the bundled-reference
assertions beyond orchestration.
Applies the Change findings from the orchestration skill review.
- Outcome names the next consumer (the requesting user) and the turn-end report
contract, and states the positive-proof condition once beside Safe failure.
- The three wait/release gates cite that condition instead of carrying divergent
case lists.
- Drops the kernel's third copy of the worker_done command; the runtime preamble
owns it at the point of use and worker-contract.md owns it behind the gate.
- Drops messaging-and-gates.md's duplicate coordinator delivery loop block; the
paragraph below it already states the --terminal delta as a condition.
- worker-start gets an ordered failure hatch naming failedStage and
residualResources.
- Conditional references describes what --full returns instead of promising
selective loading; the worker-contract gate row states the condition the kernel
does not decide.
- Moves the worktree-selector form to placement-and-remote.md, where an exact
selector is consumed, and aligns worker-contract.md on the kernel's
capability-first question-TUI wording.
Pins move with the facts: the worker_done flag spellings to worker-contract.md's
recipe case, the worktree-id form to the placement reference.
The two v32 recovery columns sat in the unversioned post-v6 list, so every
shipped database stamped below 32 failed the completeness check, resolved its
start version to the v6 floor, and replayed the whole chain; on a real v30
profile the v23 resource backfill then synthesized 68 phantom retained workers.
Versioning the entries at 32 starts that database at 30.
Also puts the superseded-Attempt fence back ahead of the pane guard: a paneless
loser cannot run-use either, so the stop signal must win over the rebind advice.
The superseded-Attempt fence ran ahead of the stable_pane_required guard, so a
terminal that had only lost its pane binding was told it had been re-attached and
to stop, and lost the run-use recovery data. The fence message and the worker
contract now also cover the no-successor case they already fired on.
The worker contract calls an empty check a checkpoint rather than a failure, so
a fenced worker had no sentence telling it that consumer_fenced, not silence, is
how it learns the Task moved. Pinned next to the existing consumer_fenced pin.
The pre-wait readDelivery used the generation snapshotted at call start with no
re-read, unlike the post-wait guard. A re-attach landing on either await above
it (the direct-mail snapshot route, or the mailbox revalidation) therefore
created a Delivery at the pre-bump generation. Nothing re-fences an outstanding
Delivery except the next re-attach, so from then on the legitimate worker's
getOrCreateMailboxDelivery saw an outstanding Delivery at a generation that is
not its own and threw consumer_fenced on every later check.
Re-read live inside readDelivery, which covers both call sites. Also pins the
three mutants a review sweep found surviving: dropping the post-wait re-read,
and pinning either the local or the federated consumer generation to 0.
After worker-abandon plus worker-start --retry-of onto another terminal, the old
worker's check found no active Dispatch and no bound Run, had a live pane so
stable_pane_required never fired, and fell through to its direct mailbox with
{count: 0}. That is byte-identical to "no mail", which the worker contract calls
a checkpoint rather than a failure, so the loser kept editing files the new
owner now owned until its worker_done was rejected.
A consuming check whose handle's latest Dispatch settled as failed or
circuit_broken now raises consumer_fenced. A completed Attempt is not fenced:
that terminal is free again and may still receive direct mail. Retries need no
separate successor lookup — every settle that makes an Attempt retry-eligible
(abandon, stop, fail) also drives its Dispatch row to failed or circuit_broken.
--peek and --all stay open so the terminal can still inspect its own inbox.
orchestration.check resolved the caller's Dispatch by handle first, so a stale
worker process still holding the row's assignee_handle read and acked the
mailbox of the pane the Dispatch had been re-attached to. The v36 consumer
generation cannot see this: check-worker reads the generation from the live row,
so the loser always presents the current one.
Refuse the mailbox to a caller whose pane is not equivalent to the row's
assignee_pane_key, both where identity is resolved and on the mid-call
revalidation. Every mode is fenced, including --peek: this caller is not the
mailbox's consumer at all, so it must not read the new owner's instructions.
The comparison is skipped when the caller has no pane or the row never recorded
one, and a PTY restart keeps the same leaf id, so a legitimately restarted
worker is still served.
A coordinator that ran dispatch --to its own terminal became its own depth-1
assignee, so every later worker-start from it failed the nesting cap and only an
undocumented worker-abandon restored it. Dispatch rows recorded the assignee but
never the creator, so depth could not tell bookkeeping from delegation; v37 adds
creator_handle/creator_pane_key and a row whose recorded creator is its own
assignee is no longer a nesting parent or a child's creator Attempt. Pre-v37 rows
carry no creator and keep counting. The depth cap also reached the CLI as
runtime_error with its next steps dropped, because its code was missing from the
structured passthrough set.
isTransient and isMissing both matched disposed, so the two read as
disjoint while one silently shadowed the other. A disposed endpoint is
genuinely both, and only the host observation decides which; pin the
certified-exit outcome that had no coverage.
A coordinator that never loads a reference read unverifiable for every
--on <environment> worker. Fits the existing wrap, so the 202-line budget
is unchanged.
The attention context passed no workerStage and no resource releaseState to
projectLiveness, so a released worker's pane could classify live from a
stale agent status while worker-list called the same dispatch exited.
exposeDispatchContext renamed task_id to taskId, and every shipped CLI
prints value.dispatch.task_id, so an older paired CLI against an updated
host printed task=undefined. Publish both spellings. exposeWorker's dropped
columns have no reader in main's src/cli, which reads only state and stage.
For a healthy in-progress worker the projection returns nextAction
{kind:'inspect', argv:['orchestration','worker-show','--dispatch',<same id>]}
with attention.requiresAction false, and the kernel told the coordinator to
follow the literal argv. Raises the kernel line budget 200 -> 202: the
paragraph had zero slack and no existing guidance was worth cutting.
projectFleetWorker reads only the local push-fed status snapshot, so a worker
started --on <environment> carried the host's real observation next to a
fabricated projection: unverifiable liveness, host.kind local, and a
worker-show self-loop. Apply the host observation the same way
worker-list --include-remote does, and let the host verdict re-derive
nextAction so a proven remote exit no longer reads as inspect. The federated
branch moves to its own module to stay under max-lines.
An attempt created by plain orchestration.dispatch has no worker_dispatches row,
so the retry precondition rejected it outright while the same abandon-then-retry
route worked for a worker-start attempt. Abandon leaves both kinds blocked, so
the Task stranded with no route back. The settled check now reads the Dispatch
row when there is no worker row.
check --types without --wait returned an unmatched type. wakeTypes is an
existence probe in getOrCreateMailboxDelivery; the batch query that
follows has no type predicate, so a Delivery is never filtered. Behavior
is correct; only the guide and --help were silent.
The stall path told coordinators to enumerate with plain worker-list, but
a worker started --on <environment> reads unverifiable without
--include-remote. Also names page.nextCursor for fleets past 100 rows.
The no-recognized-agent rejection advised dispatching without --inject and
sending the prompt manually, which is exactly what the coordinator guard
forbids, so the same self-target input got opposite instructions depending on
whether an agent happened to be detected in the pane. The coordinator guard now
runs first. The flat dispatch-authority mock in manual-dispatch-observation gave
the coordinator handle the worker's pane, which authority never does per handle.
ask printed a bare {answer, messageId} on success but the standard
{id, ok, error, _meta} on failure, so an agent reading result got
undefined. Routes success through printResult.
The assignee side of the --inject coordinator guard prefers
getOrchestrationDispatchAuthority().paneKey while the caller side used only
getTerminalPaneKey(), which returns null for a handle whose record carries
another runtime id or that is reachable only through the window-graph leaf. A
legacy-adopted coordinator reaches the guard with callerPane === null, so the
pane arm went inert and an alias handle for the coordinator's own pane took the
injected preamble.
A live, running worker with nothing pending fell through to the inspect
bucket, so worker-show's own receipt told the coordinator to run worker-show
on the same Dispatch. A healthy running worker owes no next action.
An unproven stop wrote stage=process_exited with termination_reason=unknown,
and the fleet projection read that stage alone as a death certificate, so
worker-list and worker-show published liveness=exited and nextAction=recover
for a possibly-live agent. Only certify the stage when the cause was observed.
worker-list is the enumerating command the guides point at, but its text
rows omitted projection.nextAction.argv, so non-JSON callers could not
follow the documented loop. worker-show already prints it.
exposeRun had zero coverage: emptying INTERNAL_RUN_COLUMNS left every
suite green. Adds a unit pin on the column set plus an RPC-level pin
through orchestration.runCreate.
* Shorten orchestration skill description under the Agent Skills 1024-char limit
The folded description was 1038 chars, so spec-conforming installers such
as SkillStar rejected the bundled orchestration skill. Drop the two clauses
already covered elsewhere in the same description: "decomposing work across
agents" (implied by "structured multi-agent coordination") and "automation
of the browser embedded inside Orca" (restated by the locked `orca-cli`
embedded-pages sentence). Every routing trigger asserted by
orchestration-skill-guidance.test.mjs, the orca-cli handoff boundary, and
the Computer Use boundary are unchanged. Result: 958 chars.
Add config/scripts/skill-description-length.test.mjs, which parses every
skills/*/SKILL.md frontmatter with `yaml` and fails on an empty or >1024
char description, so the regression cannot return. orca-cli sits at 1015
and is left as is.
Fixes#17935
* Keep the embedded browser in the orchestration description's orca-cli routing
Restores the word "browser" in the orca-cli sentence ("and the Orca embedded
browser") so agents scanning for it still route embedded-browser control to
orca-cli. Description is 985 chars, 39 under the spec limit.
Jinwoo-H
Jinwoo Hong