Files
Jinwoo Hong fb322046e8 skills: rewrite and trim the seven non-orchestration guides (#19128)
* 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
2026-09-07 00:03:48 -04:00

3.0 KiB

Local Docker over SSH

Load this when the environment is a local Docker container reached over SSH. It models an ephemeral SSH VM without cloud cost: build a base image with sshd, tools, repo prerequisites, and the agent CLI; run an interactive auth container once; then docker commit that container as the authenticated image per-workspace create boots from. The emitted result is the SSH shape in references/ssh-host.md.

  • Publish container SSH to a random localhost port with -p 127.0.0.1::22, and emit connection.type:"ssh" with host:"127.0.0.1", that port, username, identityFile, and identitiesOnly:true.
  • Generate a repo-local SSH key if needed, and gitignore the private and public key files.
  • Generate unique SSH host keys with ssh-keygen -A on each container's first start and retain them for that container's lifetime. Remove /etc/ssh/ssh_host_* from the base and auth images before reuse; never distribute one private host key across workspaces.
  • Before connecting, read the container's public host key through trusted local docker exec and record it under [127.0.0.1]:<published-port> in the desktop's known_hosts. If a port was reused, replace only that endpoint's old entry after verifying the new container identity. Preserve entries for other workspaces; never disable host-key checking to bypass a mismatch.
  • The auth image is the Docker form of the agent-auth snapshot: the user runs the agent login inside the container, configures proxy env and config, approves hooks, and you commit once they report it finished.
  • Do not bind-mount or copy the host's full agent home into the image. Let each container keep writable agent state; only the committed auth image carries reusable authenticated state.
  • When committing from an interactive shell, force the runtime entrypoint back to sshd: docker commit --change='ENTRYPOINT ["/usr/local/bin/orca-docker-ssh-entrypoint"]' ….
  • destroy reads recipeResult.userData.resourceId and runs docker rm -f "$resource_id".

Validation before wiring or live use

docker image inspect "$auth_image" --format '{{json .Config.Entrypoint}}'
docker run -d --name "$name" -p 127.0.0.1::22 -e "ORCA_SSH_PUBLIC_KEY=$pubkey" "$auth_image"
docker ps -a --filter "name=$name"
docker logs "$name"
ssh -i "$key" -p "$port" -o IdentitiesOnly=yes -o StrictHostKeyChecking=yes user@127.0.0.1 'codex --version'

Inspect the auth image entrypoint and do this startup-only docker run before the full clone and install path. If the container exits immediately, read its logs before the cleanup trap removes it; an image committed from an interactive shell with ENTRYPOINT ["bash"] is a common cause.

Validate two containers: their public host keys must differ, and each must match its recorded endpoint before SSH succeeds. Restarting the same container preserves its key; reusing a deleted container's port requires verifying and recording the replacement's key. Remove that endpoint's entry on destroy only if it still matches the destroyed container's recorded key.