* fix(browser): stop agent clicks from opening the system file picker
An agent click on a file input opened the macOS Open panel, which brought
Orca's window forward over the app the user was in. Page actions now catch
the picker the way upload does and tell the agent to use upload.
* fix(browser): enable Page, cancel the picker, and clean up outside host scope
* fix(browser): limit picker blocking to input delivery and bound its setup
* perf(browser): skip picker blocking for actions without user activation
* fix(browser): bound picker interception cleanup on a hung page
* fix(browser): bound the picker interception setup as a whole
Prints the notes the user left on a browser tab and has not sent, the same text the tab's Copy button gives (--json returns them). Reads the saved session, so it works for closed-and-restored tabs; SSH hosts reach it through the desktop browser bridge. A page drawn by a paired desktop reports that its notes stay there.
* fix(plugins): drop a plugin's approval when its catalog moves it to another repository
* plugins: revokePluginConsent refuses when the plugin service is not running
* cli: orca plugin install/update ask again when a plugin moves to another repository, for every plugin kind
Antigravity automations refused --extra-agent-args, so unattended agy jobs
could only use the model and effort from agy's global settings.json. Allow
--model and --effort through the existing allowlist; permission, mode, and
other flags stay refused.
Part of #35234 (STA-12678).
* fix(automations): accept Pi model and thinking extra arguments
* fix(automations): keep Pi provider pins and refuse unpinned inline keys
* fix(automations): match Pi value options to its argument parser
* fix(automations): refuse Pi model overrides beside unscoped inline keys
* test(automations): cover Pi's last-provider-wins key pin
* fix(automations): refuse any Pi custom Command text with --api-key
* fix(automations): drop the Pi inline-key pin guard
Pi already sends an unpinned inline key to the chosen model's provider and warns;
the user typed both the key and the model, so Orca does not refuse it.
* fix(browser): a split tab create joins a browser pane already beside the caller
* fix(browser): the joined page is the pane's visible tab
* fix(browser): a split with an unknown caller still splits beside the active pane
* feat(browser): guard page commands with an expected URL
* fix(browser): refuse an empty --expect-url and check it on dialogs and the forwarding desktop
* fix(browser): recheck the expected URL right before keys go out
* refactor(browser): drop duplicate session type, dialog alias and per-capability sidecar fields
* chore(browser): satisfy the changed-code gates for the expected URL guard
* Allow automation CLI setup choices for new workspaces
* Explain automation --setup refusals and read back the saved choice
Name why --setup is refused and what to pass, show the setup choice in
text output, document --setup in the CLI guide, fail when a host drops
the choice, and cover the app-open Terminal dispatch.
* Refuse automation --setup on hosts that can't keep it, and fence the edit's mode
Explicit --setup now needs the host's new setup-choice capability, checked
before any write; commands without --setup are unchanged. An edit whose
setup choice relies on the current new-per-run mode sends a mode
precondition the store checks against the saved record, so a concurrent
switch to an existing worktree refuses the whole edit. Text output shows
the saved choice or "not set", the existing-workspace refusal offers a
remedy that works for every input, and the after-write readback is gone.
* Make the too-old --setup message true for edit and cover a saved setup edit
Omitting --setup on edit keeps the saved choice, so the refusal now says
to run the command without --setup. A new test saves a --setup run edit
through the controller into the store and reads it back after reload.
- shot <key|dir> --scenario <name> renders the panel in that check scenario through the check
runner (a separate Node process on a mock host and mounted worker), sends the validated drawn
tree to a new plugins.shotReplay, and captures it in a throwaway preview surface: no guest,
no live host, no real storage or settings, no real worker, images as placeholders. Window
hidden or minimized only; --act, --environment and bridged shells refused; an older host
answers method_not_found (runtime_unsupported) rather than doing a live shot.
- dev watch's shot event carries pendingRequests.
* feat(plugins): dev watch asks for first-load approval in a terminal; acronym-aware names
- In an interactive terminal without --json, a first dev watch load that needs approval shows
the grants (as plugin inspect prints them) and asks Approve and load? [y/N]; yes reloads with
the host's fingerprint and keeps watching. --json and non-TTY runs keep the exit-3 flow.
- create keeps known acronyms uppercase when it derives a name from the id (pr-queue → PR Queue).
* fix(plugins): a declined dev watch approval prints only the re-run command
The person just read the grants in the prompt, so the exit-3 error no longer repeats them:
Not approved. To approve later, run: <command>.
* feat(plugins): shots wait for the worker; --act restores the panel; Table and Tree acts
- A shot settles once the panel has no plugin.request or host call in flight and no new tree for
a quiet spell (capped at 3 s), so a cold worker's skeleton is not captured; pendingRequests
reports what was still pending.
- After --act and the capture, the guest restores every plugin-written atom it had before (new
ui.snapshot/ui.restore; persisted atoms re-persist) and Orca remounts its drawn controls;
restored: true|false. Worker-side effects are not rolled back.
- --act gains the kit's slide, sort, selectRows, activateRow, loadMore, expand, collapse,
selectItem and activateItem.
- Docs: the dev watch first-load prompt; shot settle, restore and the new verbs.
* fix(plugins): a shot waits for the theme repaint and retries a bare capture
Linux CI captured a dark --theme shot as a bare background (2 colors). The renderer now waits
until the document shows the asked color scheme and paints, adds a frame after a --width
resize, and main recaptures a panel image that is still a background and a border (two colors
or fewer) up to 8 times, 150 ms apart, before returning it. Html panels keep their guest
composite.
* fix(plugins): capture the main window with stayHidden
webContents.capturePage(rect, { stayHidden: true }) keeps a hidden window rendering for the
capture, as the components gallery screenshots do. The repaint wait stays, and the bare-capture
retry stays as a fallback.
* feat(plugins): orca plugin dev request; --template worker-panel
- orca plugin dev request <dir|key> <name> [--data] [--panel] [--timeout-ms] calls a dev
plugin's orca.panels.handle handler through the real panel bridge (plugins.devRequest) and
prints the answer; handler errors become plugin_request_failed with the worker's code.
- orca plugin create --template worker-panel scaffolds a build-less trusted-worker plugin: a
components panel, src/worker.ts, a shared src/protocol.ts contract, and panel and worker tests
that pass under orca plugin test and type-check with tsc.
* feat(plugins): shot --act, shots in the plugin folder, quieter logs
- orca plugin shot --act '<json>' presses, types, selects and toggles in the live components
panel (the test kit's queries and acts, through Orca's own controls and onEvent) before the
capture, waiting for each to settle. Only that plugin's panel, only with Orca's window hidden
or minimized; html panels refused; acts are not user gestures. Results in actions[].
- shot run inside a plugin folder defaults to its .orca/shots, like dev watch --shot.
- dev watch prints identical [frame] lines once per reload with a count; logged stacks drop
<anonymous>/native frames; the floating workspace button hides during a capture.
- Skill: worker-panel template in the decision table, dev request, shot --act, and a gotcha
that a worker save drops its in-memory state.
* feat(plugins): dev emit also reaches the plugin's open panels
orca plugin dev emit now publishes through the panel bridge to that dev plugin's open panels
that subscribed with orca.on, under the same approval and capability rules as the worker, and
reports delivered.panels. The bridge's publishEvent takes an optional pluginKey filter and
returns how many panels heard it. A panel-only plugin no longer needs a worker; an event
nothing listens for is refused.
* docs(skills): trim the plugin authoring guide; details move to references
The main guide drops from 299 to 121 lines: the decision table, build-less rules, core loop
(create → dev watch --check --shot → read the PNG → test → check → release-entry), approval
and top gotchas. Test/check and orca/testing (panels and workers), dev watch events, shot,
open and dev emit move to a hand-written references/workflow.md; the panel/worker/data and
agent status recipes to references/recipes.md, each with a read-when row. The guide test now
also scans hand-written references for commands and caps the main guide at 150 lines.
* feat(plugins): orca plugin open and shot; dev watch --shot
- orca plugin open <key> [--panel|--editor] shows a panel in the right sidebar or a file in the
plugin's custom editor, by changing renderer state only (no focus or window raise).
- orca plugin shot <key> [--panel] [--theme] [--width] [--out] [--json] waits for the panel's
current code to draw, then crops webContents.capturePage to the panel (html guests included),
with background throttling off while hidden. --width and --theme are temporary in-memory
overrides; the PNG returns base64 (5 MiB cap), so --environment works.
- dev watch --shot <dir> writes a PNG per panel after the load and each good reload.
- The authoring skill's loop is now dev watch --check --shot → read the PNG → plugin test.
* fix(plugins): shots never disturb a visible Orca
- shot --theme is skipped while the Orca window is on screen (themeApplied: false with a
themeReason); the override applies only to a hidden or minimized window.
- dev watch --shot opens the first panel (or --shot-panel <id>) once, then shoots it with
ifShown: if the user moved the sidebar away it emits one shot_skipped instead of switching.
* fix(plugins): dev loop dogfood fixes; orca plugin dev emit
- dev watch: approval re-run command drops watch-only flags and old --approve; a folder added
by a refused load is owned by the next approved load (Ctrl-C unloads it); check events
carry the plugin's status (no green while pending/errored); reloaded prints before that
reload's logs; --json errors are one NDJSON line.
- Errors: log, banner and check share source-mapped positions (a line-1 prelude hands sucrase
mappings to the components runtime); check dedupes issues and locates syntax errors;
Orca runtime frames and the error module's bogus location are dropped from logs.
- .orca/types tsconfig sets preserveSymlinks (tsc 7 loaded typings twice under /tmp).
- Templates' READMEs use dev watch.
- orca plugin dev emit <dir|key> <event> [--data] sends a test event to a dev plugin's worker
through the real delivery rules (plugins.devEmit).
* test(plugins): fixed timestamp in the dev emit test
* fix(plugins): shot captures an html panel's guest itself
On Linux the main window's capturePage leaves a <webview> guest blank. The renderer now reports
the guest's rect, and main captures the guest's own webContents and draws it over the window
capture at that rect (raw bitmaps, nativeImage only). Components panels are drawn by the host,
so the window capture alone stays right for them.
* refactor(plugins): keep plugin-service and main-process-plugins under max-lines
After rebasing onto #37013 both files crossed 300 lines. The guest log sink moves into the
desktop view binding (bindPluginDesktopViews), and plugin-service tightens emitEvent and its
event-delivery imports.
* feat(plugins): build-less TypeScript workers
A worker's main may be .ts/.mts. The plugin host installs module.registerHooks scoped to the
plugin folder: .ts files are transpiled with the frames' sucrase options (lines kept, inline
source map, source maps on), relative imports fall back to the frames' candidate files, and a
value import of the type-only 'orca/worker' fails with a clear error. Needs engines.orca
>=1.4.246.
* feat(plugins): components panels hot reload with their state
- In dev folders a save swaps only the hidden guest: keyed memory atoms are handed to the new
guest (ui.retain → ui.hydrate memory), dropped when an atom's version changes.
- A save that fails to load keeps the last good render and shows an inline file:line:col
error banner; the next good save clears it. A subtle Reloaded mark follows a reload.
- Transpile and import errors carry line and column; dev worker restarts keep storage.
* feat(plugins): orca plugin dev watch
One command for the inner loop: refreshes .orca/types, dev-loads the folder, follows its frame
and worker logs (plugins.getLogs gains an optional cursor), prints reloads (optional
devChangeCount on list entries) and status changes, and unloads on Ctrl-C. --json streams
NDJSON events for agents.
* feat(skills): orca-plugin-authoring bundled skill guide
A guide for agents to build Orca plugins end to end (decision table, build-less rules, the
dev watch loop, test/check, validate, release-entry, approvals, gotchas) with references
generated from the component catalog, host API table, event schemas, manifest schema and CLI
specs, checked for drift. Fixes the components template's Reset to set(count, 0).
* feat(plugins): orca plugin dev watch --check; test kit details in the authoring skill
- --check runs orca plugin check after the load and after each reload (one at a time; saves
made meanwhile fold into one rerun) and prints each panel's render or errors inline, as a
`check` event with --json. Local folders only, since it runs the plugin's code here.
- The orca-plugin-authoring guide's Test and check section now documents orca plugin test and
check from #36969 exactly (JSON results, exit codes, test placement, the orca/testing kit and
its common mistakes), and the loop uses dev watch --check.
* refactor(plugins): move the components renderer's timing and helper constants to their own module
* feat(plugins): orca/testing kit, `orca plugin test` and `orca plugin check`
- `orca/testing` mounts a components panel in plain Node (node:test, vitest, bun) with the real
runtime and Orca's own tree validator: find by text/role/label/testId, press/type/submit/toggle/
select that resolve once the panel settles, tree() snapshots, errors (with stacks) and warnings,
persisted state (with stored() for migrations), emit/setVisible/rerender, and unmount running
setup cleanup. It re-exports node:test and strict assert so tests type-check without @types/node.
- mockHost refuses what Orca refuses with the same codes (surface, capability from the manifest,
params, a gesture method without a press), checks configured results against the host API, and
records calls.
- `orca plugin test [dir]` discovers *.test.ts(x) and runs them with node:test through Node module
hooks that resolve `orca` like the guest's import map and transpile/resolve sources exactly as
Orca's build-less loader, or with the plugin's own vitest via a generated config.
- `orca plugin check [dir]` validates, then renders each components panel once and reports what it
threw (file:line), layouts Orca would refuse, and props it would drop.
- The kit, hooks and register entry ship minified beside orca-runtime.mjs and are unpacked from asar;
typings land in .orca/types/orca-testing. The components template and hello-tsx get sample tests.
- ui.error carries an optional stack; a new runtime starts every atom from its initial value; the
hydration fallback timer is cleared once hydrated.
* plugins: run plugin test/check on a system Node or Orca's own, and warn they are unsandboxed
* test(plugins): run the shipped example plugin tests from the unit suite
* feat(plugins): build-less TS/TSX plugins, typings and authoring tools
- Plugin frames transpile .ts/.tsx/.mts/.jsx on load (sucrase on a shared worker thread with a
2 s budget, cached in main), resolve relative imports to exact files, and refuse bare
package imports by name. Components and html panel/editor entries may be .ts/.tsx.
- orca plugin types writes typings for the components orca module, window.orca, worker
activate(orca), host.call and events into .orca/types, from one host-typings generator.
- orca plugin create --template components; templates omit publisher and target 1.4.246.
- orca plugin release-entry, dev inspect and restart; validate:plugin checks named files.
- Guest console errors reach orca plugin logs; dev workers restart on edits; the dev watcher
ignores .git, .orca and node_modules; Git and folder installs cannot replace catalog installs.
- examples/plugins/hello-tsx, docs, and the plugin-buildless-tsx e2e spec.
* ci: run the Windows parity probes with one tsgo checker
tsconfig.node peaks near 22 GB with tsgo's default four checkers (each holds its own types)
and about 16 GB with one; the 16 GB Windows runner paged the native probe past its 900 s
timeout once this branch's package.json change triggered the job. One checker gives the
same diagnostics (verified locally with --parity-only); the timing benchmark is unchanged.
* fix(plugins): wire the plugin service on a headless serve, and turn plugins on from the CLI
* test(plugins): build the switch test's RPC context inline after main dropped the shared helper
---------
Co-authored-by: Justas Brazauskas <brazauskasjustas@gmail.com>
* feat(cli): open a browser tab in a split pane with `tab create --split`
`orca tab create` could only add a tab to an existing pane, so an agent
had no way to put a page beside its terminal. `--split <right|left|down|up>`
creates a new pane next to the calling terminal (ORCA_TAB_ID), falling back
to the active pane, and opens the page there without taking focus.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UNtbMA9iVj9T4rBUjn5u6W
* refactor(browser): share one type for the tab-create IPC payload
The preload listener, its callback, the preload API contract and main's
sender each declared the payload separately, and the listener copy had
already drifted from the new split fields.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(browser): open the CLI split pane and its tab in one step
Creating an empty group and then filling it fails when main owns the
layout, because the window's group doesn't exist until main's frame
lands. createBrowserTab's split option carries both to whichever owner
draws them, so the rollback for a half-made pane goes away.
SSH hosts already cannot choose a new tab's group, so their CLI's split
is stripped like targetGroupId.
* fix(browser): split in the caller's workspace and refuse splits that can't happen
A CLI run outside its workspace's directory sends no workspace, so the
renderer fell back to the active one and missed the caller's terminal.
The caller's tab now picks the workspace when none was named.
An SSH host's split and an empty --split= both turned into a plain tab
reported as success; both are refused instead.
---------
Co-authored-by: Kalvin Mizzi <kalvin@mizzi.com>
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* feat(browser): list restored tabs in tab list and load them on demand
After a restart Orca restores browser tabs lazily: a tab gets a page only once
the user opens it. tab list only reported tabs with a live page, so an agent in
a worktree with 26 restored tabs saw one and concluded there were none.
tab list now reads the tab bar from the session snapshot the renderer already
publishes on every tab change, and reports every tab in tab-bar order. Tabs
without a page carry loaded: false. tab switch and tab close --index resolve
indexes against the same list, and switching to an unloaded tab loads it in
the background first. Waking a page now also waits for its first load to
finish, so the next command does not read a blank page.
Headless serve keeps every page live, so it lists as before.
* fix(browser): list the tab bar even when Orca has no window open
With the window closed the app keeps running and its restored tabs still exist,
so tab list should report them. Headless snapshots are built from live pages
only, and the merge dedupes those, so dropping the window check lists nothing
extra there.
* fix(browser): list an id held by a live page and a client page once
* fix(browser): wait for the first load of a tab headless serve wakes
Headless serve starts a restored page and returned at once, so the next
command could read a blank page mid-load. It now waits for the first load,
as the window path already did.
* refactor(browser): keep the tab listing beside the browser tab catalog
Main moved the runtime browser commands into runtime/browser/ since this was
written. Also drops a window lookup the catalog no longer uses, and corrects the
headless note: those snapshots list saved pages that have not started yet.
* fix(browser): keep paired-server mirrors out of tab list and close indexed rows like --page
A window also publishes the browser tabs it mirrors from paired runtimes,
which this host can never load, so the tab bar is read only for workspaces
this host owns. tab close --index now closes the listed row exactly as
--page does, keeping its worktree, so an unstarted headless tab is retired
instead of reported closed and left saved. With nothing active, the first
live page is marked current again, matching where a pageless command goes.
* fix(browser): wait for first load only on tab switch, and show tab indexes from the listing
Every --page command wakes an unloaded page, including the tab show a
remote browser pane awaits before streaming, so waiting up to 10 s for the
first load there held the stream back. Only tab switch waits now. tab show
reports a tab's index from the same listing tab list and close use.
* fix(browser): list restored tabs in an SSH host's bridged workspace, and reject fractional close indexes
An SSH host's workspace can have no repo row on the desktop, yet its pages
render in the desktop window, so the bridge's scoped workspace counts as
this host's own. A non-integer --index no longer falls through to closing
the active tab.
* test(browser): give the restored-tabs e2e's timeout and lease wait their reasons
* test(browser): read restored-tabs RPC results through the shared e2e reader
Reuses the browser e2e rpc helper instead of a local Reflect.get copy, and
types the listing test's snapshot rows.
* fix(browser): index tab show in the caller's scope, as tab list does
* fix(browser): report an out-of-range close index as browser_tab_not_found
Matches tab switch, so agents can recover by re-listing. The restored-tabs
e2e now asserts the raw loaded value instead of coercing a missing one.
---------
Co-authored-by: fanzzzd <fanzzzd@outlook.com>
* feat(browser): upload through picker buttons in any frame
* fix(browser): catch pickers the page opens for a frame button and click SVG controls
* docs(cli): note server-hosted pages need the file input ref for upload
* test(browser): assert both picker interceptions are released
* refactor(browser): flatten picker upload and arm frame sessions in parallel
* test(browser): emit picker events through a real emitter instead of Reflect.apply
* feat(browser): let agents drive popup windows like OAuth sign-in as pages
window.open popups that keep their opener stay native windows, but the
agent bridge now lists each one in tab list as popup-<n> with its opener,
so --page, tab switch and tab close reach it. When a popup the agent
switched into closes, its next command lands on the opener.
* fix(browser): reach popups over SSH, through the Electron sidecar, and by implicit tab close
* fix(browser): keep sidecar popups ordered after tabs and handing back to their opener
* fix(browser): skip the tab wake-up wait for popups and keep the agent's claim when a popup hands back
* fix(browser): refresh the opener's claim on hand-back and settle tab close after the popup is gone
* refactor(browser): share routing retarget and idle-window helpers for popup hand-back
* refactor(browser): move popup routing helpers into bridge state to keep tabs under its line cap
* test(browser): expect the popup's url and title in its snapshot result
* feat(browser): typed snapshot flags and screenshots saved as files for agents
orca snapshot takes --interactive, --compact, --depth, --selector, --urls,
--delta and --full, passed to agent-browser on every route. The header
now shows the page title and URL. orca screenshot and full-screenshot save
the image where the CLI runs and print its path, in CSS pixels, with
--if-changed and --annotate. Flag help for exec, wait and download is
written for those commands, and the orca-cli guide sends web pages to
Orca's browser unless the user picked another tool.
* fix(browser): scale screenshots by the scrollbar-free axis and keep snapshot metadata behind SSH admission
* fix(browser): upscale low-DPR screenshots and wrap a torn-down tab's screenshot error
* fix(browser): give each screenshot its own file and keep typed screenshot errors
* refactor(browser): share the agent-browser screenshot reader between Electron and orcad
* refactor(browser): move snapshot and screenshot params under the line cap
* fix(browser): let agents and users answer page alert, confirm and prompt dialogs on their page
* fix(browser): watch a replacement guest for dialogs and ignore the opening keypress
* fix(browser): ignore a repeated Enter in a guarded prompt field
* fix(browser): fill, select, upload and type act on the agent's element or fail
* refactor(browser): move agent key commands into their own bridge layer; fix test sender call
* fix(skills): republish under an existing skill bundle name as a new version
Look up the caller's package by bundle name before packaging so a re-share
reuses its package id, and explain a name a teammate already holds instead of
a generic failure. Also stop classifying cloud request failures as filesystem
failures (same fix as #20848).
Fixes#20770
* fix(skills): keep the cloud request error importable without Electron
The runtime now classifies SkillCloudRequestError, and orcad has no Electron.
* fix(skills): map a held name only at lookup; leave classification to #20848
A finalize 409 after a signed-out preview is the user's own name, so it falls
back to the generic publish failure instead of blaming a teammate.
* fix(skills): say the skill name is in use instead of blaming a teammate
Orca has no team UI, so the copy states only what the server told us.
* Let automations pass extra agent arguments on each run
Automations could only use the host's default agent Arguments, so a
per-automation choice such as a different model needed a settings change
that affected every run. Automations can now save extra arguments that
are appended to the host's defaults on each fresh run. Extras are
allowlisted to model, effort, and Claude's --add-dir, and are refused for
permission, config, prompt, and session options.
- Add the field through the CLI (`automations create/edit
--extra-agent-args`), the RPC contract, the automation store, and the
editor's Advanced section, with validation at save and at launch.
- Merge extras over the defaults by replacing a model or effort option
the defaults already set, then re-tokenize to confirm the launch argv
matches what was validated.
- Gate writes behind a new runtime capability, and refuse to save or
migrate extras to a host that would silently drop them.
- Require a fresh session, since reused sessions cannot take new
arguments.
* Simplify automation argument validation and launch handling
* improve the extra args display
* fix translation
* Validate automation extra args during ORCA migration
Dormant automations imported from the migration manifest skipped the extra-args check. A disallowed flag, or Reuse combined with extra args, could persist and then fail every later run. The manifest parser now rejects those rows.
Also move the automation runtime capability constants into `automation-runtime-capabilities.ts`. `protocol-version.ts` re-exports them, so existing imports keep working.
* add more demo with effort
* skills: rewrite the seven non-orchestration guides to one outcome-first standard
Every guide leads with Result / Done / Safe failure, states conditions instead of case lists, keeps one done bar and one autonomy envelope, and loads references at the point of use via `skills get <topic> --full`. orca-cli drops from 424 to 260 always-loaded lines with three references; orca-per-workspace-env from 794 to 397 with five.
Defects fixed in shipped guides: `emulator camera` (no such command), iOS `permissions` (backend refuses it), Android pane described as in development, `relayGracePeriodSeconds: 0` documented as immediate teardown (it is unbounded), doctor `ok: true` hiding `warn`, an SSH exemplar setting both `jumpHost` and `proxyCommand`, a provisioned-root fetch from `origin`, and the Linear unconfirmed-write rule keyed on four verbs when ten emit it.
The resolver ladder, placeholder rule, and older-binary fallback shared by every installable SKILL.md now come from one skill-stubs/_shared/cli-resolution.md fragment composed by the generator, which also bundles per-guide references into --full. New guards: every ORCA invocation and flag resolves against COMMAND_SPECS, descriptions carry no angle-bracket tokens, reference routing is checked both ways, and an always-loaded size ratchet (300 lines) that guides may leave but never join.
* skills: address review on the SSH recipe and the parity guard
- ssh-host create script: route the bootstrap ssh through the chosen jump host or proxy command, refuse both at once, use StrictHostKeyChecking=accept-new instead of a blind ssh-keyscan append, and pass gh_token/project_root/repo_url/repo_ref to the remote bash via printf %q so a quote in a value cannot break out of the command.
- per-workspace-env envelope: the step-10 workspace test the user asked for is no longer forbidden by the same paragraph.
- linear guides: name the full verb, ORCA linear list-issues.
- parity guard: a prefix reference such as ORCA linear --help or ORCA emulator --webcam now has its flags checked against every command under that prefix; only an exact path or an explicit ... was checked before.
* skills: tighten prose in the seven rewritten guides
Shorter outcome spines, one idea per sentence, no restated rationale after a rule. No rule, command, or pinned phrase changes; 47 net lines fewer across the guides and references.
* skills: route orca-cli and per-workspace-env gates through --reference
Both guides told agents to load --full at a gate because the per-reference
selector did not exist when they were written. Now that main serves
`skills get <topic> --reference references/<file>.md`, load only the
named file and keep --full as the fallback for an older CLI, matching the
orchestration kernel.
* skills: drop outcome-spine boilerplate from the CLI-wrapper guides
The Result/Done/Safe-failure preambles and Next Action closers restated
rules the body already carries. Agents stop fine without them, and for
a CLI wrapper the command surface is the guide. Keeps the one substantive
rule computer-use's Done block added (never report unverified as success)
inside Action Rules. orchestration and per-workspace-env keep theirs:
those are multi-step workflows where the done bar is load-bearing.
(cherry picked from commit 44a74baf73)
* skills: trim the guides and stubs to what agents actually need
- Drop the Result/Done/Safe-failure preambles and Next Action closers from
the six CLI-wrapper guides; the one substantive rule (never report an
unverified computer-use action as success) moves into Action Rules.
- Drop the 'guide may be stale, trust --help' lines: the guide is served by
the binary that runs the commands, so it cannot be stale relative to it.
- Drop the status --json / open --json preflight from every guide; the stub
no-guessing paragraph now says to start Orca only when a command reports
it is not running.
- Cut the ORCA placeholder paragraph in each guide to one line that points
back at the stub's resolution.
- Trim the orchestration, orca-cli, and computer-use descriptions to trigger
phrases plus one line of scope.
- Remove the older-binary fallback section from every stub (and its two
shared blocks); a binary without skills get gets one sentence.
- Remove the guide size ratchet test.
* skills: apply independent review cleanup
* skills: clarify guide loading and Linear command discovery
* skills: harden environment recipe examples
* test: complete branch rename journal doubles
* skills: clarify custom Codex launch and refresh model example
* test: deduplicate journal fix now present on main
<!-- orca-pr-loc -->
<!-- Programmatic LoC summary. Do not edit by hand; rewritten on every commit. -->
| | Files | Added | Deleted | Net |
| :--- | ---: | ---: | ---: | ---: |
| Test | 6 | $\color{#1a7f37}{\Huge{\mathbf{+}}}$544 | $\color{#cf222e}{\Huge{\mathbf{−}}}$49 | $\color{#1a7f37}{\Huge{\mathbf{+}}}$495 |
| Prod | 36 | $\color{#1a7f37}{\Huge{\mathbf{+}}}$1719 | $\color{#cf222e}{\Huge{\mathbf{−}}}$1703 | $\color{#1a7f37}{\Huge{\mathbf{+}}}$16 |
<!-- /orca-pr-loc -->
## ELI5
Orca ships eight skill guides that agents read before running the CLI. Seven of them (everything except `orchestration`, which #16904 rewrites) were command catalogs that had drifted from the binary. This PR rewrites them so an agent reads the outcome, the done bar, and the safe-failure rule first, loads reference material only at the step that needs it, and never sees a command or flag the installed CLI does not define.
## What changed
- **Seven guides rewritten** to one standard: outcome spine first (Result / Done / Safe failure), conditions instead of case lists, one done bar, one autonomy envelope, references loaded at the point of use via `skills get <topic> --full`, every runnable invocation spelled `ORCA`. `orca-cli` is 424→260 always-loaded lines with three references (browser, automations, publishing); `orca-per-workspace-env` is 794→397 with five (provider-vercel, ssh-host, docker-ssh, windows-scripts, failure-modes).
- **Defects fixed in shipped guides:** `emulator camera` (no such command), iOS `permissions` (backend refuses it), Android pane described as "in development" (shipped in June), `relayGracePeriodSeconds: 0` documented as immediate teardown (it is unbounded), doctor `ok: true` hiding `warn`, an SSH exemplar setting both `jumpHost` and `proxyCommand`, a provisioned-root fetch from `origin`, the Linear unconfirmed-write rule keyed on four verbs when ten emit it. Linear and emulator descriptions dropped embedded commands and angle-bracket placeholders (651→329, 732→404 chars).
- **Generator bundles references.** `skill-guides/<name>/references/*.md` is appended to `--full`; `skills get` help says compact by default, full with references.
- **Stubs single-authored.** The resolver ladder, placeholder rule, and older-binary fallback shared by all eight installable `SKILL.md` files come from one `skill-stubs/_shared/cli-resolution.md` fragment composed by the generator. Projections were byte-identical before the content fixes.
- **Guards:** every `ORCA <cmd>` and flag in every guide and reference resolves against `COMMAND_SPECS` (this found the camera defect); descriptions ≤1024 chars with no angle-bracket tokens; reference routing checked both directions; an always-loaded size ratchet (300 lines) that guides may leave but never join. `orchestration` (440 lines on main) is recorded as an exception until #16904 lands its kernel.
## Relationship to #16904
Split out of #16904 so that PR carries only the orchestration guide. On main, `terminal send` has no `--wait-submit` / `--retry-request` and the orchestration kernel still carries the resolver ladder and worktree-selector rule, so this branch pins `accepted: true` for handoff receipts and leaves the orchestration pins where main has them. The merge in either direction is mechanical: #16904 rebased on this becomes a one-file `orchestration.md` change plus dropping the two exceptions.
## Standard
Compound Engineering's portable skill-authoring guidance (outcome spine, conditions not cases, pinned fragile commands with an ordered hatch, references at point of use). NVIDIA SkillEvaluator Tier 1 (`schema,pii,license,quality,unicode,lint`) was run on every guide; its deterministic checks pass, its template nudges (Instructions/Examples sections, 50–150 char descriptions) do not apply to Orca's stub architecture and were not applied.
## Testing
- `pnpm typecheck:tsc:cli` clean; `check:code-quality:changed` and `check:react-doctor:changed` 0 findings
- `pnpm verify:bundled-skill-guides` and skill-bundle manifest verify clean
- vitest over `config/scripts`, `src/cli/skill-guide-cli-parity.test.ts`, `src/cli/skills.test.ts`, `src/cli/specs/skills.test.ts`, `src/cli/help.test.ts`, `src/main/skills`: 240 files / 2,019 pass
- Live smoke on the built CLI of every `skills get <topic>` and `--full`, every emulator, linear, and vm verb named in the guides, and every projection's resolver, GNOME warning, and bounded fallback (done on the #16904 branch before the split; the guide bodies are identical here except the send-receipt vocabulary noted above)
## Deferred product decisions
Merging `orca-emulator` and `orca-emulator-android` into one skill with a platform branch; collapsing `linear-tickets` to a guide alias; a `skills get --reference <name>` selector so a gate table can load one file; a fresh-agent routing eval before trimming the `orca-cli` (1,015 chars) and `orchestration` descriptions, whose quoted triggers each fixed a routing misroute.
Kelvin Amoaba
Neil
Jinwoo Hong
Brennan Benson
Jinjing