From 7b31e739d2127cd5b87f42fd6504cd658363ace9 Mon Sep 17 00:00:00 2001 From: Neil <4138956+nwparker@users.noreply.github.com> Date: Tue, 13 Oct 2026 18:18:50 -0700 Subject: [PATCH] Fix Vercel recipe failures on stock macOS Bash (#28257) Guard empty argument-array expansion so the bundled setup recipe runs under Bash 3.2 with unset-variable checks. Preserve exact arguments and cleanup exit behavior; normalize only test fixture line endings. Co-authored-by: outof-place --- .../generate-bundled-skill-guides.test.mjs | 70 +++--- config/scripts/skill-recipe-shell.test.mjs | 208 ++++++++++++++---- .../references/provider-vercel.md | 29 +-- src/cli/bundled-skill-guides.ts | 4 +- 4 files changed, 219 insertions(+), 92 deletions(-) diff --git a/config/scripts/generate-bundled-skill-guides.test.mjs b/config/scripts/generate-bundled-skill-guides.test.mjs index 570e8598c59..43982a908ae 100644 --- a/config/scripts/generate-bundled-skill-guides.test.mjs +++ b/config/scripts/generate-bundled-skill-guides.test.mjs @@ -247,9 +247,11 @@ describe('bundled skill guide generator', () => { const marker = `` expect(guide.fullMarkdown.split(marker)).toHaveLength(2) expect(guide.fullMarkdown).toContain( - await readFile( - path.join(projectDir, 'skill-guides', guide.name, 'references', reference), - 'utf8' + normalizeMarkdown( + await readFile( + path.join(projectDir, 'skill-guides', guide.name, 'references', reference), + 'utf8' + ) ) ) } @@ -289,33 +291,43 @@ describe('bundled skill guide generator', () => { await expect(verifyArtifacts(first, projectDir)).resolves.toBeUndefined() }) - it('generates platform-identical output from CRLF guide sources', async () => { - const expected = await buildArtifacts(projectDir) - const root = await createFixture() - for (const name of CANONICAL_GUIDE_NAMES) { - const sourcePath = path.join(root, 'skill-guides', `${name}.md`) - const source = await readFile(sourcePath, 'utf8') - await writeFile(sourcePath, source.replaceAll('\n', '\r\n')) - } - for (const name of STUB_TOPICS) { - const stubPath = path.join(root, 'skill-stubs', `${name}.md`) - const stubSource = await readFile(stubPath, 'utf8') - await writeFile(stubPath, stubSource.replaceAll('\n', '\r\n')) - } - const sharedStubPath = path.join(root, ...SHARED_STUB_SOURCE.split('/')) - const sharedStubSource = await readFile(sharedStubPath, 'utf8') - await writeFile(sharedStubPath, sharedStubSource.replaceAll('\n', '\r\n')) - for (const [guide, reference] of GUIDE_REFERENCE_PATHS) { - const referencePath = path.join(root, 'skill-guides', guide, 'references', reference) - const source = await readFile(referencePath, 'utf8') - await writeFile(referencePath, source.replaceAll('\n', '\r\n')) - } + it.each([false, true])( + 'generates platform-identical output from CRLF guide sources (existing CRLF: %s)', + async (alreadyCrlf) => { + const expected = await buildArtifacts(projectDir) + const root = await createFixture() + if (alreadyCrlf) { + for (const [guide, reference] of GUIDE_REFERENCE_PATHS) { + const file = path.join(root, 'skill-guides', guide, 'references', reference) + const source = normalizeMarkdown(await readFile(file, 'utf8')) + await writeFile(file, source.replaceAll('\n', '\r\n')) + } + } + for (const name of CANONICAL_GUIDE_NAMES) { + const sourcePath = path.join(root, 'skill-guides', `${name}.md`) + const source = await readFile(sourcePath, 'utf8') + await writeFile(sourcePath, normalizeMarkdown(source).replaceAll('\n', '\r\n')) + } + for (const name of STUB_TOPICS) { + const stubPath = path.join(root, 'skill-stubs', `${name}.md`) + const stubSource = await readFile(stubPath, 'utf8') + await writeFile(stubPath, normalizeMarkdown(stubSource).replaceAll('\n', '\r\n')) + } + const sharedStubPath = path.join(root, ...SHARED_STUB_SOURCE.split('/')) + const sharedStubSource = await readFile(sharedStubPath, 'utf8') + await writeFile(sharedStubPath, normalizeMarkdown(sharedStubSource).replaceAll('\n', '\r\n')) + for (const [guide, reference] of GUIDE_REFERENCE_PATHS) { + const referencePath = path.join(root, 'skill-guides', guide, 'references', reference) + const source = await readFile(referencePath, 'utf8') + await writeFile(referencePath, normalizeMarkdown(source).replaceAll('\n', '\r\n')) + } - const actual = await buildArtifacts(root) - expect(actual.map((artifact) => artifact.content)).toEqual( - expected.map((artifact) => artifact.content) - ) - }) + const actual = await buildArtifacts(root) + expect(actual.map((artifact) => artifact.content)).toEqual( + expected.map((artifact) => artifact.content) + ) + } + ) it('pins guide sources, projections, and embedded output to LF in Git', async () => { const attributes = await readFile(path.join(projectDir, '.gitattributes'), 'utf8') diff --git a/config/scripts/skill-recipe-shell.test.mjs b/config/scripts/skill-recipe-shell.test.mjs index c31c65d5ee4..d15fe42ccdb 100644 --- a/config/scripts/skill-recipe-shell.test.mjs +++ b/config/scripts/skill-recipe-shell.test.mjs @@ -1,6 +1,8 @@ import { execFile } from 'node:child_process' -import { readFile } from 'node:fs/promises' -import { resolve } from 'node:path' +import { existsSync } from 'node:fs' +import { chmod, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { delimiter, join, resolve } from 'node:path' import { promisify } from 'node:util' import { describe, expect, it } from 'vitest' @@ -13,9 +15,9 @@ const vercel = await readFile(resolve(referenceRoot, 'provider-vercel.md'), 'utf const ssh = await readFile(resolve(referenceRoot, 'ssh-host.md'), 'utf8') const cleanup = vercel.match(/```bash\n(cleanup_snapshot\(\) \{[\s\S]*?\n\})\n```/u)?.[1] -async function runShell(script, env = {}) { +async function executeShell(shell, script, env = {}) { try { - const output = await run('bash', ['-c', script], { + const output = await run(shell, ['-c', script], { env: { ...process.env, ORCA_BACKGROUND_LAUNCH: '1', ...env } }) return { ...output, code: 0 } @@ -24,56 +26,114 @@ async function runShell(script, env = {}) { } } -describe.skipIf(process.platform === 'win32')('recipe shell examples', () => { - it.each(['base', 'auth'])('cleans the %s sandbox on failure and success', async (phase) => { - expect(cleanup).toBeDefined() - const trap = vercel.match(new RegExp(`trap 'cleanup_snapshot "\\$${phase}"' EXIT`, 'u'))?.[0] - expect(trap).toBeDefined() - expect(vercel.indexOf(trap)).toBeLessThan( - vercel.indexOf(`vercel sandbox create --name "$${phase}"`) - ) - for (const exitCode of [0, 7]) { - const result = await runShell(`set -euo pipefail +// Stock macOS Bash must run even when PATH starts with a newer Bash. +const shells = existsSync('/bin/bash') ? ['/bin/bash', 'bash'] : ['bash'] + +describe.skipIf(process.platform === 'win32').each(shells)( + 'recipe shell examples (%s)', + (shell) => { + const runShell = (script, env) => executeShell(shell, script, env) + + it.each(['base', 'auth'])('cleans the %s sandbox on failure and success', async (phase) => { + expect(cleanup).toBeDefined() + const trap = vercel.match(new RegExp(`trap 'cleanup_snapshot "\\$${phase}"' EXIT`, 'u'))?.[0] + expect(trap).toBeDefined() + expect(vercel.indexOf(trap)).toBeLessThan( + vercel.indexOf(`vercel sandbox create --name "$${phase}"`) + ) + for (const exitCode of [0, 7]) { + const result = await runShell(`set -euo pipefail ${cleanup} vercel_args=(--scope test-scope) ${phase}=unique-test-sandbox vercel() { printf '%s\\n' "$@"; } ${trap} exit ${exitCode}`) - expect(result.code).toBe(exitCode) - expect(result.stderr).toBe('sandbox\nremove\nunique-test-sandbox\n--scope\ntest-scope\n') - } - }) + expect(result.code).toBe(exitCode) + expect(result.stderr).toBe('sandbox\nremove\nunique-test-sandbox\n--scope\ntest-scope\n') + } + }) - it('reports failed cleanup even after an otherwise successful snapshot', async () => { - const result = await runShell(`set -euo pipefail + it('reports failed cleanup even after an otherwise successful snapshot', async () => { + const result = await runShell(`set -euo pipefail ${cleanup} vercel_args=() vercel() { return 9; } trap 'cleanup_snapshot unique-test-sandbox' EXIT exit 0`) - expect(result.code).toBe(1) - expect(result.stderr).toContain('Sandbox cleanup failed for unique-test-sandbox') - }) + expect(result.code).toBe(1) + expect(result.stderr).toContain('Sandbox cleanup failed for unique-test-sandbox') + }) - it('disables Git prompts when the Vercel token is absent', async () => { - const prefix = vercel.match( - /-- bash -lc 'set -euo pipefail; cd "\$ORCA_PROJECT_ROOT"; \\\n([\s\S]*?) git fetch/u - )?.[1] - expect(prefix).toBeDefined() - const result = await runShell( - `set -euo pipefail\nunset GH_TOKEN\n${prefix}\nprintf '%s' "$GIT_TERMINAL_PROMPT"` + it.each([ + { scope: '', project: '' }, + { scope: 'scope with spaces *', project: '' }, + { scope: '', project: 'project with spaces ?' }, + { scope: 'scope with spaces *', project: 'project with spaces ?' } + ])( + 'runs the full create recipe with scope "$scope" and project "$project"', + async ({ scope, project }) => { + const result = await runCreateRecipe(shell, { + VERCEL_SCOPE: scope, + VERCEL_PROJECT: project + }) + expect(result.code).toBe(0) + const output = JSON.parse(result.stdout) + expect(output.userData).toMatchObject({ + provider: 'vercel-sandbox', + resourceId: 'orca-fixture-123', + snapshotId: 'snap_fixture' + }) + expect(result.calls.map((args) => args.slice(0, 2))).toEqual([ + ['sandbox', 'create'], + ['sandbox', 'exec'], + ['sandbox', 'exec'] + ]) + const expectedFlags = [ + ...(scope ? ['--scope', scope] : []), + ...(project ? ['--project', project] : []) + ] + for (const args of result.calls) { + const start = args.findIndex((arg) => arg === '--scope' || arg === '--project') + if (expectedFlags.length) { + expect(args.slice(start, start + expectedFlags.length)).toEqual(expectedFlags) + } else { + expect(start).toBe(-1) + } + expect(args).not.toContain('') + } + } ) - expect(result.code).toBe(0) - expect(result.stdout).toBe('0') - }) - it('uses host credentials and refuses unverified SSH hosts without forwarding tokens', async () => { - const script = ssh.match(/```bash\n(#!\/usr\/bin\/env bash[\s\S]*?)\n```/u)?.[1] - expect(script).toBeDefined() - const sync = script.slice(0, script.indexOf('# 2. print')) - const result = await runShell( - `ssh() { printf '%s\\n' "$@"; } + it('removes a failed create with no optional flags', async () => { + const result = await runCreateRecipe(shell, { VERCEL_CREATE_EXIT: '7' }) + expect(result.code).toBe(7) + expect(result.calls.map((args) => args.slice(0, 2))).toEqual([ + ['sandbox', 'create'], + ['sandbox', 'remove'] + ]) + expect(result.calls[1]).toEqual(['sandbox', 'remove', 'orca-fixture-123']) + expect(result.stderr).not.toContain('unbound variable') + }) + + it('disables Git prompts when the Vercel token is absent', async () => { + const prefix = vercel.match( + /-- bash -lc 'set -euo pipefail; cd "\$ORCA_PROJECT_ROOT"; \\\n([\s\S]*?) git fetch/u + )?.[1] + expect(prefix).toBeDefined() + const result = await runShell( + `set -euo pipefail\nunset GH_TOKEN\n${prefix}\nprintf '%s' "$GIT_TERMINAL_PROMPT"` + ) + expect(result.code).toBe(0) + expect(result.stdout).toBe('0') + }) + + it('uses host credentials and refuses unverified SSH hosts without forwarding tokens', async () => { + const script = ssh.match(/```bash\n(#!\/usr\/bin\/env bash[\s\S]*?)\n```/u)?.[1] + expect(script).toBeDefined() + const sync = script.slice(0, script.indexOf('# 2. print')) + const result = await runShell( + `ssh() { printf '%s\\n' "$@"; } ssh_username=worker host=example.test ssh_port=2222 @@ -81,13 +141,65 @@ project_root='/remote/path with spaces' repo_url=https://example.test/org/repo.git repo_ref=main ${sync}`, - { GH_TOKEN: 'test-token-must-not-be-forwarded' } + { GH_TOKEN: 'test-token-must-not-be-forwarded' } + ) + expect(result.code).toBe(0) + expect(result.stderr).toContain('StrictHostKeyChecking=yes') + expect(result.stderr).toContain('BatchMode=yes') + expect(result.stderr).not.toContain('test-token-must-not-be-forwarded') + expect(result.stderr).not.toContain('GH_TOKEN=') + expect(script).toContain('export GIT_TERMINAL_PROMPT=0') + }) + } +) + +async function runCreateRecipe(shell, overrides) { + const script = vercel.match(/```bash\n(#!\/usr\/bin\/env bash[\s\S]*?)\n```/u)?.[1] + expect(script).toBeDefined() + const directory = await mkdtemp(join(tmpdir(), 'orca-vercel-recipe-')) + const bin = join(directory, 'bin') + const log = join(directory, 'calls.jsonl') + try { + await mkdir(bin) + const command = join(bin, 'vercel') + await writeFile( + command, + `#!/usr/bin/env node +const { appendFileSync } = require('node:fs') +const args = process.argv.slice(2) +appendFileSync(process.env.VERCEL_FIXTURE_LOG, JSON.stringify(args) + '\\n') +if (args[1] === 'create') { + if (process.env.VERCEL_CREATE_EXIT) process.exit(Number(process.env.VERCEL_CREATE_EXIT)) + console.log('https://fixture.vercel.run') +} else if (args[1] === 'exec' && args.includes('60s')) { + console.log(JSON.stringify({ userData: {} })) +} +` ) - expect(result.code).toBe(0) - expect(result.stderr).toContain('StrictHostKeyChecking=yes') - expect(result.stderr).toContain('BatchMode=yes') - expect(result.stderr).not.toContain('test-token-must-not-be-forwarded') - expect(result.stderr).not.toContain('GH_TOKEN=') - expect(script).toContain('export GIT_TERMINAL_PROMPT=0') - }) -}) + await chmod(command, 0o755) + const result = await executeShell( + shell, + `scope="$VERCEL_SCOPE"; project="$VERCEL_PROJECT" +snapshot_id=snap_fixture; port=6768; repo_url=https://example.test/repo.git; repo_ref=main; project_root='/fixture repo' +${script}`, + { + PATH: `${bin}${delimiter}${process.env.PATH}`, + VERCEL_FIXTURE_LOG: log, + VERCEL_SCOPE: '', + VERCEL_PROJECT: '', + VERCEL_CREATE_EXIT: '', + GH_TOKEN: 'fixture-token', + ORCA_RECIPE_ID: 'fixture', + ORCA_VM_INSTANCE_ID: '123', + ...overrides + } + ) + const calls = (await readFile(log, 'utf8')) + .trim() + .split('\n') + .map((line) => JSON.parse(line)) + return { ...result, calls } + } finally { + await rm(directory, { recursive: true, force: true }) + } +} diff --git a/skill-guides/orca-per-workspace-env/references/provider-vercel.md b/skill-guides/orca-per-workspace-env/references/provider-vercel.md index 0290c21c5ed..06377695e3a 100644 --- a/skill-guides/orca-per-workspace-env/references/provider-vercel.md +++ b/skill-guides/orca-per-workspace-env/references/provider-vercel.md @@ -14,11 +14,14 @@ The base and auth excerpts each belong to one `set -euo pipefail` script. Includ in both scripts and arm the trap before creating their temporary sandbox. Keep it armed through verification, snapshot creation, and writing state; cleanup failure must remain visible. +Use the guarded array expansion below so an empty `vercel_args` array works under `set -u` +on stock macOS Bash 3.2 while preserving each configured argument. + ```bash cleanup_snapshot() { snapshot_exit=$? trap - EXIT - if ! vercel sandbox remove "$1" "${vercel_args[@]}" >&2; then + if ! vercel sandbox remove "$1" ${vercel_args[@]+"${vercel_args[@]}"} >&2; then echo "Sandbox cleanup failed for $1; inspect and remove it before continuing" >&2 snapshot_exit=1 fi @@ -36,14 +39,14 @@ Provision, install tools and clone, build headless, then snapshot. # provision a fresh build sandbox (retain a couple of snapshots) trap 'cleanup_snapshot "$base"' EXIT vercel sandbox create --name "$base" --runtime node24 --timeout 30m --vcpus 4 --publish-port "$port" \ - --snapshot-expiration 30d --keep-last-snapshots 2 "${vercel_args[@]}" >&2 + --snapshot-expiration 30d --keep-last-snapshots 2 ${vercel_args[@]+"${vercel_args[@]}"} >&2 # remote build (long timeout): install pkgs+gh+pnpm+agent CLI, clone with GIT_ASKPASS (the helper's # \$1/\$GH_TOKEN escaping is load-bearing — see the guide's Credentials section — then # `rm -f /tmp/askpass.sh`), write the headless main-only build config (drop the renderer), dev setup, # build CLI + headless main, smoke-check -vercel sandbox exec "$base" "${vercel_args[@]}" --timeout 25m --env "GH_TOKEN=$gh_token" … -- bash -lc '…build…' >&2 +vercel sandbox exec "$base" ${vercel_args[@]+"${vercel_args[@]}"} --timeout 25m --env "GH_TOKEN=$gh_token" … -- bash -lc '…build…' >&2 # snapshot the STOPPED sandbox and parse the id from CLI output (fail if unparseable) -out="$(vercel sandbox snapshot "$base" --stop --expiration 30d "${vercel_args[@]}" 2>&1)"; printf '%s\n' "$out" >&2 +out="$(vercel sandbox snapshot "$base" --stop --expiration 30d ${vercel_args[@]+"${vercel_args[@]}"} 2>&1)"; printf '%s\n' "$out" >&2 snapshot_id="$(printf '%s\n' "$out" | sed -nE 's/.*(snap_[A-Za-z0-9]+).*/\1/p' | tail -1)" [ -n "$snapshot_id" ] || { echo "snapshot id missing" >&2; exit 1; } # merge { baseName, snapshotId, scope, project, port, repoUrl, repoRef, projectRoot } into state; print state JSON @@ -56,16 +59,16 @@ substitute the user's chosen agent's login and status verbs. ```bash trap 'cleanup_snapshot "$auth"' EXIT -vercel sandbox create --name "$auth" --snapshot "$snapshot_id" --timeout 30m --publish-port "$port" "${vercel_args[@]}" >&2 +vercel sandbox create --name "$auth" --snapshot "$snapshot_id" --timeout 30m --publish-port "$port" ${vercel_args[@]+"${vercel_args[@]}"} >&2 # The USER runs this in their own terminal and completes the URL/code on the HOST. -vercel sandbox exec --interactive --tty "$auth" "${vercel_args[@]}" -- bash -lc 'codex login --device-auth' +vercel sandbox exec --interactive --tty "$auth" ${vercel_args[@]+"${vercel_args[@]}"} -- bash -lc 'codex login --device-auth' ``` Verify by exit code. The remote command prints a sentinel instead of relying on the exit code, because a provider CLI may not propagate remote exit codes: ```bash -verdict="$(vercel sandbox exec "$auth" "${vercel_args[@]}" --timeout 30s \ +verdict="$(vercel sandbox exec "$auth" ${vercel_args[@]+"${vercel_args[@]}"} --timeout 30s \ -- bash -lc 'if codex login status >/dev/null 2>&1; then echo ORCA_AGENT_LOGGED_IN; else echo ORCA_AGENT_LOGGED_OUT; fi')" case "$verdict" in *ORCA_AGENT_LOGGED_IN*) ;; @@ -78,7 +81,7 @@ stderr folded in and match the agent's exact success line. Match a variable, not provider process cannot take SIGPIPE: ```bash -status="$(vercel sandbox exec "$auth" "${vercel_args[@]}" --timeout 30s -- bash -lc 'codex login status 2>&1')" +status="$(vercel sandbox exec "$auth" ${vercel_args[@]+"${vercel_args[@]}"} --timeout 30s -- bash -lc 'codex login status 2>&1')" grep -Eq 'Logged in using ChatGPT|Logged in via device' <<<"$status" \ || { echo "agent not logged in; not snapshotting" >&2; exit 1; } ``` @@ -86,7 +89,7 @@ grep -Eq 'Logged in using ChatGPT|Logged in via device' <<<"$status" \ Then re-snapshot and record the new id: ```bash -out="$(vercel sandbox snapshot "$auth" --stop --expiration 30d "${vercel_args[@]}" 2>&1)"; printf '%s\n' "$out" >&2 +out="$(vercel sandbox snapshot "$auth" --stop --expiration 30d ${vercel_args[@]+"${vercel_args[@]}"} 2>&1)"; printf '%s\n' "$out" >&2 new_id="$(printf '%s\n' "$out" | sed -nE 's/.*(snap_[A-Za-z0-9]+).*/\1/p' | tail -1)" [ -n "$new_id" ] || { echo "authenticated snapshot id missing" >&2; exit 1; } # overwrite state.snapshotId = new_id, record authSourceSnapshotId = snapshot_id; remove the auth sandbox @@ -109,19 +112,19 @@ max_recipe_id_length=$((128 - ${#instance_id} - 6)) # Preserve the unique insta name="orca-${recipe_id:0:max_recipe_id_length}-${instance_id}" # Arm cleanup BEFORE create so a failing create can't leak a half-built paid sandbox. -cleanup_on_error() { [ "$?" -ne 0 ] && vercel sandbox remove "$name" "${vercel_args[@]}" >/dev/null 2>&1 || true; } +cleanup_on_error() { [ "$?" -ne 0 ] && vercel sandbox remove "$name" ${vercel_args[@]+"${vercel_args[@]}"} >/dev/null 2>&1 || true; } trap cleanup_on_error EXIT # 1. boot from the authenticated snapshot, publish the serve port create_output="$(vercel sandbox create --name "$name" --snapshot "$snapshot_id" \ - --timeout 30m --publish-port "$port" "${vercel_args[@]}" 2>&1)"; printf '%s\n' "$create_output" >&2 + --timeout 30m --publish-port "$port" ${vercel_args[@]+"${vercel_args[@]}"} 2>&1)"; printf '%s\n' "$create_output" >&2 # Vercel prints the published https URL; derive the external wss:// pairing address from it public_url="$(printf '%s\n' "$create_output" | sed -nE 's#.*(https://[^[:space:]]+\.vercel\.run).*#\1#p' | head -1)" [ -n "$public_url" ] || { echo "no published URL in create output" >&2; exit 1; } pairing_ws="${public_url/https:\/\//wss://}" # 2. (remote) ensure the repo is at the right commit; rebuild only if the commit changed (cache marker) -vercel sandbox exec "$name" "${vercel_args[@]}" --timeout 20m \ +vercel sandbox exec "$name" ${vercel_args[@]+"${vercel_args[@]}"} --timeout 20m \ --env "GH_TOKEN=$gh_token" --env "ORCA_PROJECT_ROOT=$project_root" \ --env "ORCA_REPO_URL=$repo_url" --env "ORCA_REPO_REF=$repo_ref" \ -- bash -lc 'set -euo pipefail; cd "$ORCA_PROJECT_ROOT"; \ @@ -139,7 +142,7 @@ vercel sandbox exec "$name" "${vercel_args[@]}" --timeout 20m \ printf "%s" "$c" > .orca-built; }' >&2 # 3. (remote) start orca serve in the background, writing recipe JSON to a file; poll until it parses -recipe_json="$(vercel sandbox exec "$name" "${vercel_args[@]}" --timeout 60s \ +recipe_json="$(vercel sandbox exec "$name" ${vercel_args[@]+"${vercel_args[@]}"} --timeout 60s \ --env "ORCA_PORT=$port" --env "ORCA_PROJECT_ROOT=$project_root" --env "ORCA_PAIRING_ADDRESS=$pairing_ws" \ -- bash -lc 'set -euo pipefail; cd "$ORCA_PROJECT_ROOT"; rm -f /tmp/orca-recipe.json /tmp/orca-serve.log; \ nohup pnpm exec orca-dev serve --port "$ORCA_PORT" --project-root "$ORCA_PROJECT_ROOT" \ diff --git a/src/cli/bundled-skill-guides.ts b/src/cli/bundled-skill-guides.ts index bbbd7b18ea3..260603da16b 100644 --- a/src/cli/bundled-skill-guides.ts +++ b/src/cli/bundled-skill-guides.ts @@ -48,7 +48,7 @@ const ORCA_LINEAR_MARKDOWN = "---\nname: orca-linear\ndescription: >-\n Linear const ORCA_PER_WORKSPACE_ENV_MARKDOWN = "---\nname: orca-per-workspace-env\ndescription: >-\n Set up, review, debug, or validate an Orca per-workspace environment recipe: the\n on-demand, disposable runtime (cloud sandbox, VM, SSH host, or local container)\n Orca creates fresh for each workspace. Use to stand up a new recipe end to end,\n fix an `environmentRecipes` entry in `orca.yaml`, scaffold provider lifecycle\n scripts, or resolve an `orca vm recipe doctor` failure. Use `orca-cli` for\n ordinary worktree and workspace creation with no recipe involved.\n---\n\n# Per-Workspace Environments\n\n`ORCA` is a placeholder for the executable you resolved in the stub; substitute it before running.\nInside the lifecycle scripts the placeholder does not apply: `orca serve` written there runs on\nthe remote machine's own binary.\n\n## Autonomy envelope\n\nWithout asking again you may read the repo and its `orca.yaml`, detect provider CLIs and their\nlogin state, scaffold and edit files under `scripts/orca-vm/`, and run `ORCA vm recipe doctor`\nwithout `--provision`. Get an explicit OK before each paid step: the base snapshot, the auth\nsnapshot, and `--provision`. One OK covers the whole `--provision` fix-and-rerun loop. Stop for\nthe interactive agent login, which you cannot drive; the user runs it and tells you when it is\ndone. Never create an Orca workspace except for the step-10 test the user asked for. Do not create\nGit commits unless asked. Never choose a plan or region, invent a scope, project, or billing id, or\nwrite a credential into a script, `userData`, the state file, or a commit.\n\nPreserve actionable provider errors and the failing command, redact secrets, and clean up resources\ncreated by a failed step.\n\n## The branch that shapes everything\n\nIn **Orca-server** mode `create` runs `orca serve` in the environment and emits a `pairingCode`. In\n**SSH** mode `create` runs no server and emits a `connection.type:\"ssh\"` block Orca dials into.\nSettle this first; it changes the `create` output and half the templates.\n\nKeep Orca's checkout behavior unchanged by default: omit `checkoutMode`, emit schema version 1, and\nlet Orca create a linked worktree. Use `checkoutMode: provisioned-root` only when the user\nexplicitly wants one ephemeral machine to clone the finished workspace itself. That mode requires\ndirect SSH, an ordinary non-bare and non-sparse primary checkout at `projectRoot`, and schema\nversion 2.\n\n## 1. Setup workflow\n\nDrive these with the user. The order is fixed: the auth snapshot (step 6) boots from the base\nsnapshot (step 5), and `create` boots from the authenticated snapshot they produce. A\n**[CHECKPOINT]** label marks a step the autonomy envelope stops for.\n\n1. **Inspect the repo** for an existing `environmentRecipes` entry, `scripts/orca-vm/`, a state\n file, or setup notes. If a working recipe already exists, go straight to the doctor loop below\n instead of rebuilding.\n2. **Interview the user up front.** Gather these choices and confirm them back before scaffolding\n anything. Do not pick for them and do not guess.\n - **Connection mode:** an Orca server or SSH, as above. Settle it first.\n - **Checkout ownership:** do not ask by default. Only when the user requires the environment to\n create the exact final checkout, confirm `provisioned-root` and direct SSH; otherwise omit it.\n - **Provider:** Vercel Sandbox, Fly, Modal, an existing SSH host, and so on. For a non-obvious\n provider, also ask scope, project, region, and plan limits. Then read that provider's CLI or\n SDK docs, or ` --help`, before scaffolding: you need its exact create, exec, snapshot, and\n remove verbs. If a provider advertises `ssh`, check whether it exposes a real dialable SSH\n target (host, port, user, key or proxy command) or only a provider-mediated interactive shell.\n Orca's SSH mode needs the former.\n - **Coding-agent CLI and account:** which agent runs in the environment (`codex`, `claude`, and\n so on) and that the user has an account for it. It is logged in during step 6.\n - **Git auth:** the token source for cloning a private repo (`GH_TOKEN`, `GITHUB_TOKEN`, or\n `gh auth token`).\n3. **Check prerequisites** (section 2) and confirm the items above are in place before any paid\n step.\n4. **Scaffold the scripts and state file**, filling in the provider's real commands, and make them\n executable. The per-provider worked examples are in the conditional references below.\n5. **[CHECKPOINT] Build the base snapshot** (section 3). Paid and slow.\n6. **[CHECKPOINT] Authenticate the agent** (section 4). Interactive; the user follows a URL and code.\n7. **Wire the recipe** so `orca.yaml` points create, suspend, resume, and destroy at the scripts.\n Tell the user up front: the composer reads `environmentRecipes` from the primary checkout, so\n a recipe that lives only on a branch never appears as a \"Run on\" option. The doctor works on\n any branch; the picker needs `orca.yaml` on the primary branch.\n8. **Dry-run the doctor** — free and static.\n9. **[CHECKPOINT] Live self-test** — run the `--provision` loop until it passes.\n10. **[CHECKPOINT] Optional workspace test** — only if asked: create a workspace via the picker,\n then verify sleep, wake, and delete.\n\n## 2. Prerequisites\n\nThese are the user's responsibility. Verify what you can, ask for the rest, invent nothing, and\nsay which items you verified and which the user asserted.\n\n- **Cloud account and plan** that allows sandboxes or VMs. Ask.\n- **Provider CLI installed and authenticated** — detect with `command -v ` and check auth (for\n example `vercel whoami`). If it is missing, point at the provider's docs; do not log them in.\n- **Scope, project, and region** the environments live under. Ask; this flows into every script via\n state.\n- **Plan, timeout, and RAM caps.** Record them. Vercel's Hobby plan, for example, caps sandbox\n timeout at 45 minutes, which limits both the base build and the per-workspace runtime.\n- **Git token for private repos** (`GH_TOKEN`, `GITHUB_TOKEN`, or the provider's git auth, falling\n back to `gh auth token`).\n- **Coding-agent CLI choice** and an account for it.\n\n## 3. Base snapshot\n\nBuild once, snapshot, and every workspace boots from that image in seconds instead of rebuilding.\nProvisioning and building often takes 20 to 30 minutes.\n\n- Build the **headless Electron main only**, not the renderer, so it fits in plan RAM.\n- Use the environment image's package manager (`apt`, `dnf`, `apk`, per the base distro, not the\n provider brand).\n- Clone with the git token via `GIT_ASKPASS` (section 5).\n- Trap errors and remove the half-built environment, so a crash does not leave a paid resource\n running.\n- **Never snapshot a machine on which the Orca runtime has already run.** The first `orca serve`\n creates the runtime's user-data directory, and everything in it is baked into the image and shared\n by every environment booted from it: the pairing keypair and device-token registry\n (`orca-devices.json`, `orca-e2ee-keypair.json`), `agent-session-authority.key`, and the build\n box's logs, terminal history, and orchestration database. Two VMs from one such snapshot emitted\n identical `deviceToken` and `pairedDeviceId`. Snapshot before the runtime has ever run, or delete\n the resolved user-data directory first:\n `orca_user_data_path=\"${ORCA_USER_DATA_PATH:-${XDG_CONFIG_HOME:-$HOME/.config}/orca}\"`.\n Resolve symlinks and inspect that path before deleting it: it must be an absolute directory\n dedicated to Orca runtime data, never `/`, the home directory, or an ancestor of home. Refuse\n empty or relative paths. Remove only that verified directory, not an unchecked environment value.\n That matches Orca's Linux precedence for custom and default paths; deleting a named file list\n drifts as Orca adds state.\n- Snapshot the stopped environment, parse the snapshot id, and write it plus scope, project, port,\n and repo into state.\n\n## 4. Agent-auth snapshot\n\nThe base snapshot has the agent CLI installed but not logged in, and per-workspace environments are\nephemeral. Authenticate once and bake it into a second snapshot layer.\n\n1. Boot an environment from the base `snapshotId` in state.\n2. Run the agent's login interactively. **On a headless machine this must be the device-auth flow**\n (for example `codex login --device-auth`), never plain `codex login`: the default OAuth login\n starts a loopback callback server on a port the host browser cannot reach, so it hangs.\n Device-auth prints a URL and code the user opens on the host.\n3. Verify the login and refuse to snapshot an unauthenticated machine. **Prefer the status command's\n exit code**, because most agent CLIs exit non-zero when unauthenticated. If you match text\n instead, agent status often goes to stderr, so fold stderr first (`... 2>&1 | grep …`) and match\n the agent's exact success line. Never `grep -qi 'logged in'`, which also matches \"not logged in\"\n and would commit an unauthenticated image.\n4. Re-snapshot, parse the new id, overwrite `snapshotId` in state with the authenticated image, and\n record `authSourceSnapshotId`. Remove the auth environment.\n\nAuthenticate inside the runtime and snapshot that layer. Do not bind-mount or copy a host agent\nhome such as `~/.codex`: its sqlite state, hook approvals, caches, and host-specific config break\nin the runtime. If the agent's credentials are short-lived, tell the user the snapshot needs\nperiodic re-auth.\n\nYou cannot drive step 2. You have no TTY for `docker exec -it` or `ssh -t`, so the user runs the\nlogin in their own terminal and tells you when it finished. Verify and re-snapshot after that.\n\n> Harness adapter: in Claude Code the user can run that login in the session itself with the bang\n> prefix, `! `, including the required space after `!`. Other harnesses have no such\n> affordance; the portable rule is that the user runs it wherever they have a terminal.\n\nSection 3's rule still applies: if you ran `orca serve` on this machine to smoke-test it, delete\nthe runtime's user-data directory before re-snapshotting, or every workspace from this image\nshares one pairing identity.\n\n## 5. Credentials\n\n- Never commit secrets or put them in `userData`, recipe JSON, comments, docs, or the state file.\n- **Git token:** read it from `GH_TOKEN` or `GITHUB_TOKEN`, falling back to `gh auth token`. Pass it\n to the environment only via the provider's ephemeral `--env`. Inside the environment, use a\n `GIT_ASKPASS` helper with `x-access-token` rather than the token in the clone URL, plus\n `GIT_TERMINAL_PROMPT=0` so a missing token fails fast instead of hanging. When you write that\n helper from inside `bash -lc` under `set -u`, escape the positional argument and the token as\n `\\$1` and `\\$GH_TOKEN` so they land literally and resolve at git-runtime: an unescaped `$1` aborts\n with \"unbound variable\", and a literal `$GH_TOKEN` keeps the real token out of the written file.\n `rm -f` the helper after the clone or fetch.\n- **Provider auth:** rely on the provider CLI's logged-in session, not checked-in keys.\n- **Agent auth:** lives in the authenticated snapshot from section 4, never in a file you write.\n- State holds only non-secret wiring: snapshot ids, scope, project, port, repo URL and ref.\n\n## 6. State file\n\nA repo-local JSON file such as `scripts/orca-vm/-state.json` threads non-secret values\nbetween phases. Each script resolves a value as env var, then state, then a built-in fallback, and\nmerges its outputs back. The base snapshot writes `snapshotId`; the auth snapshot overwrites it with\nthe authenticated image; per-workspace `create` boots from `snapshotId`.\n\n```json\n{\n \"baseName\": \"orca-base\",\n \"snapshotId\": \"snap_authenticated_image_id\",\n \"authSourceSnapshotId\": \"snap_base_image_id\",\n \"scope\": \"\",\n \"project\": \"\",\n \"port\": 7331,\n \"repoUrl\": \"https://host/org/repo.git\",\n \"repoRef\": \"main\",\n \"projectRoot\": \"/abs/path/on/remote/repo\"\n}\n```\n\n## 7. Script shapes\n\nScaffold under `scripts/orca-vm/`. These are shapes; fill in the provider's real commands. **Every\nscript reserves stdout for its final JSON object and sends progress and errors to stderr.** A stray\n`echo` on stdout corrupts the result. Give each script a `json_value ` and `env_value `\nreader (env, then state, then fallback).\n\nThe local-side scripts (`create`, `suspend`, `resume`, `destroy`, and the hand-run snapshot and auth\nscripts) run on the user's desktop, so they must run on that OS: on macOS and Linux,\n`#!/usr/bin/env bash`, `set -euo pipefail`, quoted paths. Commands you `exec` inside the Linux\nenvironment are always bash.\n\n### 7a. Base snapshot (`-base-snapshot.sh`)\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\n# resolve base_name/repo_url/repo_ref/project_root/port/scope/project/timeout (env→state→fallback)\n# resolve gh token: GH_TOKEN | GITHUB_TOKEN | `gh auth token`\n# 1. provision an environment (timeout/vcpus/published port/snapshot retention); trap: remove on error\n# 2. remote exec (long timeout): install pkgs + gh + corepack/pnpm + agent CLI;\n# clone with GIT_ASKPASS(token); write headless main-only build config;\n# dev setup; pnpm install; build CLI; build headless electron main; smoke-check tools\n# 3. snapshot stopped environment; parse snapshot id (fail if unparseable)\n# 4. merge { baseName, snapshotId, projectRoot, repoUrl, repoRef, port, scope, project } into state\n# print only the state JSON to stdout\n```\n\nYou run this by hand, not via `orca.yaml`, after exporting the first-run inputs state does not have\nyet: provider scope and project, the repo URL and ref, and a git token. Later runs read them back.\n\n### 7b. Auth (`-base-auth.sh`)\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\n# read source snapshot from state.snapshotId (fail if absent); auth_name=\"${base_name}-auth\"\n# 1. boot an environment from the source snapshot; trap: remove on error\n# 2. INTERACTIVE/TTY remote exec: agent login with the device-auth flow. The user runs this and\n# reports back when it finishes.\n# 3. verify login by exit code, then refuse to snapshot if not logged in\n# 4. snapshot; parse new id\n# 5. merge { snapshotId:, authSourceSnapshotId: } into state; remove auth environment\n# print only the state JSON to stdout\n```\n\n### 7c. Create (`-create.sh`)\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\n# read authenticated snapshotId/scope/project/port/repo*/project_root (env→state→fallback)\n# fail clearly if snapshotId is missing (point back to the snapshot phases)\n# name = orca-${ORCA_RECIPE_ID}-${ORCA_VM_INSTANCE_ID} (sanitized, length-capped)\n# 1. boot from snapshotId with a published port; capture the public URL → pairing address\n# (an externally reachable wss:// URL); trap: remove the environment on error\n# 2. remote exec: ensure repo at desired commit; rebuild only if commit changed (cache marker)\n# 3. Orca-server mode only: remote exec starting orca serve and reading the recipe JSON it writes\n# 4. print one recipe-result JSON object to stdout\n```\n\n### 7d. Suspend, resume, destroy\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\npayload=\"$(cat)\" # Orca passes lifecycle JSON on stdin\nresource_id=\"$(node -e 'const d=JSON.parse(process.argv[1]); process.stdout.write(d.recipeResult?.userData?.resourceId ?? \"\")' \"$payload\")\"\n[ -n \"$resource_id\" ] || { echo \"No resource id in lifecycle payload\" >&2; exit 1; }\n# suspend: provider suspend \"$resource_id\"\n# resume: provider resume \"$resource_id\"; then RE-EMIT fresh recipe JSON (pairing may change)\n# destroy: provider remove \"$resource_id\" (or set destroy: none in orca.yaml)\n```\n\n### 7e. State file\n\nScaffold it with scope, project, and repo filled in and the snapshot ids empty.\n\n## 8. Recipe result contract\n\nDefine recipes in `orca.yaml`:\n\n```yaml\nenvironmentRecipes:\n - id: cloud-sandbox\n name: Cloud Sandbox\n create: ./scripts/orca-vm/cloud-sandbox-create.sh\n suspend: ./scripts/orca-vm/cloud-sandbox-suspend.sh\n resume: ./scripts/orca-vm/cloud-sandbox-resume.sh\n destroy: ./scripts/orca-vm/cloud-sandbox-destroy.sh\n```\n\n`create` is required, runs locally from the repo root, and prints exactly one JSON object on stdout.\n`suspend` and `resume` are optional and read the lifecycle payload on stdin; `resume` must print\nfresh recipe JSON because the pairing may have changed. `destroy` may be omitted only with\n`destroy: none`. The legacy keys `command` and `cleanup` still map to `create` and `destroy`.\n\nThe base result, which is what Orca-server mode prints:\n\n```json\n{\n \"schemaVersion\": 1,\n \"pairingCode\": \"orca-pairing-code-or-url\",\n \"projectRoot\": \"/absolute/path/to/repo/on/remote\",\n \"userData\": { \"provider\": \"example\", \"resourceId\": \"provider-resource-id\" }\n}\n```\n\n`pairingCode` and `projectRoot` are required; `schemaVersion` (`1`) and `userData` are optional.\nThree named deltas change that shape:\n\n- **`orca serve --recipe-json` output** is this same object without `userData`. Merge your own\n `userData` into it rather than rebuilding it.\n- **SSH mode** replaces `pairingCode` and `projectRoot` with a `connection` block whose `type` is\n `\"ssh\"`, and does not run `orca serve`. The exact target shape is in `references/ssh-host.md`.\n- **Provisioned root** applies only to direct SSH and only when the user explicitly asked for it. Add\n `checkoutMode: provisioned-root` to the recipe, require `ORCA_RECIPE_RESULT_SCHEMA_VERSION=2`, and\n emit `\"schemaVersion\": 2` with `\"checkoutMode\": \"provisioned-root\"`. Fail if the requested schema\n is not `2` rather than falling back to the ordinary shape. Details are in `references/ssh-host.md`.\n\n### The `orca serve` invocation\n\nInside the environment, in Orca-server mode, run exactly this. These flags are verified; do not\nimprovise them.\n\n```bash\norca serve \\\n --port \"$PORT\" \\\n --project-root \"$ABS_REPO_PATH_ON_REMOTE\" \\\n --pairing-address \"$EXTERNAL_WSS_URL\" \\\n --recipe-json\n```\n\nIn an environment built from source, run it as `pnpm exec orca-dev serve …` from the repo root;\n`orca-dev` is the in-repo entrypoint. Plain `orca serve …` is the same command when the built CLI is\non that machine's PATH, and the flags and output are identical either way. There is no `--host` flag,\nand `--project-root` must be an absolute directory on the remote.\n\n`pairingCode` embeds whatever you passed as `--pairing-address`, so pass the externally reachable\naddress there and never hand-edit the code. Tunneling and port mapping are the script's job. With\n`--recipe-json` the server keeps running, so redirect its stdout to a file and poll until the file\nparses as JSON; if the process dies first, dump its stderr log and fail.\n\n## 9. Doctor and the `--provision` loop\n\n`ORCA vm recipe doctor --repo-path --json` validates static wiring only; it boots\nnothing. It checks local-host execution, the repo path, that the recipe id exists, that the create,\ndestroy, suspend, and resume command paths resolve, that suspend and resume are paired, and that\neach script is executable (the POSIX exec bit, skipped on Windows).\n\n**The free gate is clear only with no `fail` and no `warn`.** A `warn` keeps `ok: true`, so `ok`\nalone proves nothing. Resolve each `warn`, or say why you accept it, before spending money on\n`--provision`.\n\n`--provision` (or its synonym `--connect`) runs the recipe end to end: `create`, validation of the\nreturned JSON, then `destroy`. Nothing is left running as long as `destroy` works.\n\nRun it as a loop: read the `provisionTranscript` in the failed result, fix the script, re-run, until\n`ok` is `true`. Do not wait for the user to paste errors. How to read the transcript is in\n`references/failure-modes.md`.\n\nThe self-test sees only what the scripts print, so confirm separately that state holds an\n**authenticated** `snapshotId` and that `destroy` is implemented and tested. With `destroy: none`\nthe self-test tears nothing down and you must clean up by hand.\n\n## Conditional references\n\nThis guide covers the interview, the phase order, and the doctor loop on its own. At a gate below,\nrun `ORCA skills get orca-per-workspace-env --reference references/.md` and read only that\ndocument; `--references` lists the names. Read the reference at the gate, not before. If the CLI\nrejects `--reference`, run `ORCA skills get orca-per-workspace-env --full` once instead: it returns\nthis guide plus every reference from the same CLI build, so read only the named one. If `--full` is\nrejected too, keep these rules, use the command's `--help`, and do not guess flags.\n\n| Action gate | Bundled reference |\n| ----------------------------------------------------------------------------------------- | ------------------------------- |\n| Writing the base-snapshot, auth, or create script for a snapshot-capable cloud provider | `references/provider-vercel.md` |\n| The recipe connects over SSH instead of starting `orca serve`, including provisioned root | `references/ssh-host.md` |\n| The environment is a local Docker container reached over SSH | `references/docker-ssh.md` |\n| The user's desktop is Windows and you are scaffolding local-side scripts | `references/windows-scripts.md` |\n| A doctor, provision, clone, login, or snapshot step failed | `references/failure-modes.md` |\n" // oxfmt-ignore -const ORCA_PER_WORKSPACE_ENV_FULL_MARKDOWN = "---\nname: orca-per-workspace-env\ndescription: >-\n Set up, review, debug, or validate an Orca per-workspace environment recipe: the\n on-demand, disposable runtime (cloud sandbox, VM, SSH host, or local container)\n Orca creates fresh for each workspace. Use to stand up a new recipe end to end,\n fix an `environmentRecipes` entry in `orca.yaml`, scaffold provider lifecycle\n scripts, or resolve an `orca vm recipe doctor` failure. Use `orca-cli` for\n ordinary worktree and workspace creation with no recipe involved.\n---\n\n# Per-Workspace Environments\n\n`ORCA` is a placeholder for the executable you resolved in the stub; substitute it before running.\nInside the lifecycle scripts the placeholder does not apply: `orca serve` written there runs on\nthe remote machine's own binary.\n\n## Autonomy envelope\n\nWithout asking again you may read the repo and its `orca.yaml`, detect provider CLIs and their\nlogin state, scaffold and edit files under `scripts/orca-vm/`, and run `ORCA vm recipe doctor`\nwithout `--provision`. Get an explicit OK before each paid step: the base snapshot, the auth\nsnapshot, and `--provision`. One OK covers the whole `--provision` fix-and-rerun loop. Stop for\nthe interactive agent login, which you cannot drive; the user runs it and tells you when it is\ndone. Never create an Orca workspace except for the step-10 test the user asked for. Do not create\nGit commits unless asked. Never choose a plan or region, invent a scope, project, or billing id, or\nwrite a credential into a script, `userData`, the state file, or a commit.\n\nPreserve actionable provider errors and the failing command, redact secrets, and clean up resources\ncreated by a failed step.\n\n## The branch that shapes everything\n\nIn **Orca-server** mode `create` runs `orca serve` in the environment and emits a `pairingCode`. In\n**SSH** mode `create` runs no server and emits a `connection.type:\"ssh\"` block Orca dials into.\nSettle this first; it changes the `create` output and half the templates.\n\nKeep Orca's checkout behavior unchanged by default: omit `checkoutMode`, emit schema version 1, and\nlet Orca create a linked worktree. Use `checkoutMode: provisioned-root` only when the user\nexplicitly wants one ephemeral machine to clone the finished workspace itself. That mode requires\ndirect SSH, an ordinary non-bare and non-sparse primary checkout at `projectRoot`, and schema\nversion 2.\n\n## 1. Setup workflow\n\nDrive these with the user. The order is fixed: the auth snapshot (step 6) boots from the base\nsnapshot (step 5), and `create` boots from the authenticated snapshot they produce. A\n**[CHECKPOINT]** label marks a step the autonomy envelope stops for.\n\n1. **Inspect the repo** for an existing `environmentRecipes` entry, `scripts/orca-vm/`, a state\n file, or setup notes. If a working recipe already exists, go straight to the doctor loop below\n instead of rebuilding.\n2. **Interview the user up front.** Gather these choices and confirm them back before scaffolding\n anything. Do not pick for them and do not guess.\n - **Connection mode:** an Orca server or SSH, as above. Settle it first.\n - **Checkout ownership:** do not ask by default. Only when the user requires the environment to\n create the exact final checkout, confirm `provisioned-root` and direct SSH; otherwise omit it.\n - **Provider:** Vercel Sandbox, Fly, Modal, an existing SSH host, and so on. For a non-obvious\n provider, also ask scope, project, region, and plan limits. Then read that provider's CLI or\n SDK docs, or ` --help`, before scaffolding: you need its exact create, exec, snapshot, and\n remove verbs. If a provider advertises `ssh`, check whether it exposes a real dialable SSH\n target (host, port, user, key or proxy command) or only a provider-mediated interactive shell.\n Orca's SSH mode needs the former.\n - **Coding-agent CLI and account:** which agent runs in the environment (`codex`, `claude`, and\n so on) and that the user has an account for it. It is logged in during step 6.\n - **Git auth:** the token source for cloning a private repo (`GH_TOKEN`, `GITHUB_TOKEN`, or\n `gh auth token`).\n3. **Check prerequisites** (section 2) and confirm the items above are in place before any paid\n step.\n4. **Scaffold the scripts and state file**, filling in the provider's real commands, and make them\n executable. The per-provider worked examples are in the conditional references below.\n5. **[CHECKPOINT] Build the base snapshot** (section 3). Paid and slow.\n6. **[CHECKPOINT] Authenticate the agent** (section 4). Interactive; the user follows a URL and code.\n7. **Wire the recipe** so `orca.yaml` points create, suspend, resume, and destroy at the scripts.\n Tell the user up front: the composer reads `environmentRecipes` from the primary checkout, so\n a recipe that lives only on a branch never appears as a \"Run on\" option. The doctor works on\n any branch; the picker needs `orca.yaml` on the primary branch.\n8. **Dry-run the doctor** — free and static.\n9. **[CHECKPOINT] Live self-test** — run the `--provision` loop until it passes.\n10. **[CHECKPOINT] Optional workspace test** — only if asked: create a workspace via the picker,\n then verify sleep, wake, and delete.\n\n## 2. Prerequisites\n\nThese are the user's responsibility. Verify what you can, ask for the rest, invent nothing, and\nsay which items you verified and which the user asserted.\n\n- **Cloud account and plan** that allows sandboxes or VMs. Ask.\n- **Provider CLI installed and authenticated** — detect with `command -v ` and check auth (for\n example `vercel whoami`). If it is missing, point at the provider's docs; do not log them in.\n- **Scope, project, and region** the environments live under. Ask; this flows into every script via\n state.\n- **Plan, timeout, and RAM caps.** Record them. Vercel's Hobby plan, for example, caps sandbox\n timeout at 45 minutes, which limits both the base build and the per-workspace runtime.\n- **Git token for private repos** (`GH_TOKEN`, `GITHUB_TOKEN`, or the provider's git auth, falling\n back to `gh auth token`).\n- **Coding-agent CLI choice** and an account for it.\n\n## 3. Base snapshot\n\nBuild once, snapshot, and every workspace boots from that image in seconds instead of rebuilding.\nProvisioning and building often takes 20 to 30 minutes.\n\n- Build the **headless Electron main only**, not the renderer, so it fits in plan RAM.\n- Use the environment image's package manager (`apt`, `dnf`, `apk`, per the base distro, not the\n provider brand).\n- Clone with the git token via `GIT_ASKPASS` (section 5).\n- Trap errors and remove the half-built environment, so a crash does not leave a paid resource\n running.\n- **Never snapshot a machine on which the Orca runtime has already run.** The first `orca serve`\n creates the runtime's user-data directory, and everything in it is baked into the image and shared\n by every environment booted from it: the pairing keypair and device-token registry\n (`orca-devices.json`, `orca-e2ee-keypair.json`), `agent-session-authority.key`, and the build\n box's logs, terminal history, and orchestration database. Two VMs from one such snapshot emitted\n identical `deviceToken` and `pairedDeviceId`. Snapshot before the runtime has ever run, or delete\n the resolved user-data directory first:\n `orca_user_data_path=\"${ORCA_USER_DATA_PATH:-${XDG_CONFIG_HOME:-$HOME/.config}/orca}\"`.\n Resolve symlinks and inspect that path before deleting it: it must be an absolute directory\n dedicated to Orca runtime data, never `/`, the home directory, or an ancestor of home. Refuse\n empty or relative paths. Remove only that verified directory, not an unchecked environment value.\n That matches Orca's Linux precedence for custom and default paths; deleting a named file list\n drifts as Orca adds state.\n- Snapshot the stopped environment, parse the snapshot id, and write it plus scope, project, port,\n and repo into state.\n\n## 4. Agent-auth snapshot\n\nThe base snapshot has the agent CLI installed but not logged in, and per-workspace environments are\nephemeral. Authenticate once and bake it into a second snapshot layer.\n\n1. Boot an environment from the base `snapshotId` in state.\n2. Run the agent's login interactively. **On a headless machine this must be the device-auth flow**\n (for example `codex login --device-auth`), never plain `codex login`: the default OAuth login\n starts a loopback callback server on a port the host browser cannot reach, so it hangs.\n Device-auth prints a URL and code the user opens on the host.\n3. Verify the login and refuse to snapshot an unauthenticated machine. **Prefer the status command's\n exit code**, because most agent CLIs exit non-zero when unauthenticated. If you match text\n instead, agent status often goes to stderr, so fold stderr first (`... 2>&1 | grep …`) and match\n the agent's exact success line. Never `grep -qi 'logged in'`, which also matches \"not logged in\"\n and would commit an unauthenticated image.\n4. Re-snapshot, parse the new id, overwrite `snapshotId` in state with the authenticated image, and\n record `authSourceSnapshotId`. Remove the auth environment.\n\nAuthenticate inside the runtime and snapshot that layer. Do not bind-mount or copy a host agent\nhome such as `~/.codex`: its sqlite state, hook approvals, caches, and host-specific config break\nin the runtime. If the agent's credentials are short-lived, tell the user the snapshot needs\nperiodic re-auth.\n\nYou cannot drive step 2. You have no TTY for `docker exec -it` or `ssh -t`, so the user runs the\nlogin in their own terminal and tells you when it finished. Verify and re-snapshot after that.\n\n> Harness adapter: in Claude Code the user can run that login in the session itself with the bang\n> prefix, `! `, including the required space after `!`. Other harnesses have no such\n> affordance; the portable rule is that the user runs it wherever they have a terminal.\n\nSection 3's rule still applies: if you ran `orca serve` on this machine to smoke-test it, delete\nthe runtime's user-data directory before re-snapshotting, or every workspace from this image\nshares one pairing identity.\n\n## 5. Credentials\n\n- Never commit secrets or put them in `userData`, recipe JSON, comments, docs, or the state file.\n- **Git token:** read it from `GH_TOKEN` or `GITHUB_TOKEN`, falling back to `gh auth token`. Pass it\n to the environment only via the provider's ephemeral `--env`. Inside the environment, use a\n `GIT_ASKPASS` helper with `x-access-token` rather than the token in the clone URL, plus\n `GIT_TERMINAL_PROMPT=0` so a missing token fails fast instead of hanging. When you write that\n helper from inside `bash -lc` under `set -u`, escape the positional argument and the token as\n `\\$1` and `\\$GH_TOKEN` so they land literally and resolve at git-runtime: an unescaped `$1` aborts\n with \"unbound variable\", and a literal `$GH_TOKEN` keeps the real token out of the written file.\n `rm -f` the helper after the clone or fetch.\n- **Provider auth:** rely on the provider CLI's logged-in session, not checked-in keys.\n- **Agent auth:** lives in the authenticated snapshot from section 4, never in a file you write.\n- State holds only non-secret wiring: snapshot ids, scope, project, port, repo URL and ref.\n\n## 6. State file\n\nA repo-local JSON file such as `scripts/orca-vm/-state.json` threads non-secret values\nbetween phases. Each script resolves a value as env var, then state, then a built-in fallback, and\nmerges its outputs back. The base snapshot writes `snapshotId`; the auth snapshot overwrites it with\nthe authenticated image; per-workspace `create` boots from `snapshotId`.\n\n```json\n{\n \"baseName\": \"orca-base\",\n \"snapshotId\": \"snap_authenticated_image_id\",\n \"authSourceSnapshotId\": \"snap_base_image_id\",\n \"scope\": \"\",\n \"project\": \"\",\n \"port\": 7331,\n \"repoUrl\": \"https://host/org/repo.git\",\n \"repoRef\": \"main\",\n \"projectRoot\": \"/abs/path/on/remote/repo\"\n}\n```\n\n## 7. Script shapes\n\nScaffold under `scripts/orca-vm/`. These are shapes; fill in the provider's real commands. **Every\nscript reserves stdout for its final JSON object and sends progress and errors to stderr.** A stray\n`echo` on stdout corrupts the result. Give each script a `json_value ` and `env_value `\nreader (env, then state, then fallback).\n\nThe local-side scripts (`create`, `suspend`, `resume`, `destroy`, and the hand-run snapshot and auth\nscripts) run on the user's desktop, so they must run on that OS: on macOS and Linux,\n`#!/usr/bin/env bash`, `set -euo pipefail`, quoted paths. Commands you `exec` inside the Linux\nenvironment are always bash.\n\n### 7a. Base snapshot (`-base-snapshot.sh`)\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\n# resolve base_name/repo_url/repo_ref/project_root/port/scope/project/timeout (env→state→fallback)\n# resolve gh token: GH_TOKEN | GITHUB_TOKEN | `gh auth token`\n# 1. provision an environment (timeout/vcpus/published port/snapshot retention); trap: remove on error\n# 2. remote exec (long timeout): install pkgs + gh + corepack/pnpm + agent CLI;\n# clone with GIT_ASKPASS(token); write headless main-only build config;\n# dev setup; pnpm install; build CLI; build headless electron main; smoke-check tools\n# 3. snapshot stopped environment; parse snapshot id (fail if unparseable)\n# 4. merge { baseName, snapshotId, projectRoot, repoUrl, repoRef, port, scope, project } into state\n# print only the state JSON to stdout\n```\n\nYou run this by hand, not via `orca.yaml`, after exporting the first-run inputs state does not have\nyet: provider scope and project, the repo URL and ref, and a git token. Later runs read them back.\n\n### 7b. Auth (`-base-auth.sh`)\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\n# read source snapshot from state.snapshotId (fail if absent); auth_name=\"${base_name}-auth\"\n# 1. boot an environment from the source snapshot; trap: remove on error\n# 2. INTERACTIVE/TTY remote exec: agent login with the device-auth flow. The user runs this and\n# reports back when it finishes.\n# 3. verify login by exit code, then refuse to snapshot if not logged in\n# 4. snapshot; parse new id\n# 5. merge { snapshotId:, authSourceSnapshotId: } into state; remove auth environment\n# print only the state JSON to stdout\n```\n\n### 7c. Create (`-create.sh`)\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\n# read authenticated snapshotId/scope/project/port/repo*/project_root (env→state→fallback)\n# fail clearly if snapshotId is missing (point back to the snapshot phases)\n# name = orca-${ORCA_RECIPE_ID}-${ORCA_VM_INSTANCE_ID} (sanitized, length-capped)\n# 1. boot from snapshotId with a published port; capture the public URL → pairing address\n# (an externally reachable wss:// URL); trap: remove the environment on error\n# 2. remote exec: ensure repo at desired commit; rebuild only if commit changed (cache marker)\n# 3. Orca-server mode only: remote exec starting orca serve and reading the recipe JSON it writes\n# 4. print one recipe-result JSON object to stdout\n```\n\n### 7d. Suspend, resume, destroy\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\npayload=\"$(cat)\" # Orca passes lifecycle JSON on stdin\nresource_id=\"$(node -e 'const d=JSON.parse(process.argv[1]); process.stdout.write(d.recipeResult?.userData?.resourceId ?? \"\")' \"$payload\")\"\n[ -n \"$resource_id\" ] || { echo \"No resource id in lifecycle payload\" >&2; exit 1; }\n# suspend: provider suspend \"$resource_id\"\n# resume: provider resume \"$resource_id\"; then RE-EMIT fresh recipe JSON (pairing may change)\n# destroy: provider remove \"$resource_id\" (or set destroy: none in orca.yaml)\n```\n\n### 7e. State file\n\nScaffold it with scope, project, and repo filled in and the snapshot ids empty.\n\n## 8. Recipe result contract\n\nDefine recipes in `orca.yaml`:\n\n```yaml\nenvironmentRecipes:\n - id: cloud-sandbox\n name: Cloud Sandbox\n create: ./scripts/orca-vm/cloud-sandbox-create.sh\n suspend: ./scripts/orca-vm/cloud-sandbox-suspend.sh\n resume: ./scripts/orca-vm/cloud-sandbox-resume.sh\n destroy: ./scripts/orca-vm/cloud-sandbox-destroy.sh\n```\n\n`create` is required, runs locally from the repo root, and prints exactly one JSON object on stdout.\n`suspend` and `resume` are optional and read the lifecycle payload on stdin; `resume` must print\nfresh recipe JSON because the pairing may have changed. `destroy` may be omitted only with\n`destroy: none`. The legacy keys `command` and `cleanup` still map to `create` and `destroy`.\n\nThe base result, which is what Orca-server mode prints:\n\n```json\n{\n \"schemaVersion\": 1,\n \"pairingCode\": \"orca-pairing-code-or-url\",\n \"projectRoot\": \"/absolute/path/to/repo/on/remote\",\n \"userData\": { \"provider\": \"example\", \"resourceId\": \"provider-resource-id\" }\n}\n```\n\n`pairingCode` and `projectRoot` are required; `schemaVersion` (`1`) and `userData` are optional.\nThree named deltas change that shape:\n\n- **`orca serve --recipe-json` output** is this same object without `userData`. Merge your own\n `userData` into it rather than rebuilding it.\n- **SSH mode** replaces `pairingCode` and `projectRoot` with a `connection` block whose `type` is\n `\"ssh\"`, and does not run `orca serve`. The exact target shape is in `references/ssh-host.md`.\n- **Provisioned root** applies only to direct SSH and only when the user explicitly asked for it. Add\n `checkoutMode: provisioned-root` to the recipe, require `ORCA_RECIPE_RESULT_SCHEMA_VERSION=2`, and\n emit `\"schemaVersion\": 2` with `\"checkoutMode\": \"provisioned-root\"`. Fail if the requested schema\n is not `2` rather than falling back to the ordinary shape. Details are in `references/ssh-host.md`.\n\n### The `orca serve` invocation\n\nInside the environment, in Orca-server mode, run exactly this. These flags are verified; do not\nimprovise them.\n\n```bash\norca serve \\\n --port \"$PORT\" \\\n --project-root \"$ABS_REPO_PATH_ON_REMOTE\" \\\n --pairing-address \"$EXTERNAL_WSS_URL\" \\\n --recipe-json\n```\n\nIn an environment built from source, run it as `pnpm exec orca-dev serve …` from the repo root;\n`orca-dev` is the in-repo entrypoint. Plain `orca serve …` is the same command when the built CLI is\non that machine's PATH, and the flags and output are identical either way. There is no `--host` flag,\nand `--project-root` must be an absolute directory on the remote.\n\n`pairingCode` embeds whatever you passed as `--pairing-address`, so pass the externally reachable\naddress there and never hand-edit the code. Tunneling and port mapping are the script's job. With\n`--recipe-json` the server keeps running, so redirect its stdout to a file and poll until the file\nparses as JSON; if the process dies first, dump its stderr log and fail.\n\n## 9. Doctor and the `--provision` loop\n\n`ORCA vm recipe doctor --repo-path --json` validates static wiring only; it boots\nnothing. It checks local-host execution, the repo path, that the recipe id exists, that the create,\ndestroy, suspend, and resume command paths resolve, that suspend and resume are paired, and that\neach script is executable (the POSIX exec bit, skipped on Windows).\n\n**The free gate is clear only with no `fail` and no `warn`.** A `warn` keeps `ok: true`, so `ok`\nalone proves nothing. Resolve each `warn`, or say why you accept it, before spending money on\n`--provision`.\n\n`--provision` (or its synonym `--connect`) runs the recipe end to end: `create`, validation of the\nreturned JSON, then `destroy`. Nothing is left running as long as `destroy` works.\n\nRun it as a loop: read the `provisionTranscript` in the failed result, fix the script, re-run, until\n`ok` is `true`. Do not wait for the user to paste errors. How to read the transcript is in\n`references/failure-modes.md`.\n\nThe self-test sees only what the scripts print, so confirm separately that state holds an\n**authenticated** `snapshotId` and that `destroy` is implemented and tested. With `destroy: none`\nthe self-test tears nothing down and you must clean up by hand.\n\n## Conditional references\n\nThis guide covers the interview, the phase order, and the doctor loop on its own. At a gate below,\nrun `ORCA skills get orca-per-workspace-env --reference references/.md` and read only that\ndocument; `--references` lists the names. Read the reference at the gate, not before. If the CLI\nrejects `--reference`, run `ORCA skills get orca-per-workspace-env --full` once instead: it returns\nthis guide plus every reference from the same CLI build, so read only the named one. If `--full` is\nrejected too, keep these rules, use the command's `--help`, and do not guess flags.\n\n| Action gate | Bundled reference |\n| ----------------------------------------------------------------------------------------- | ------------------------------- |\n| Writing the base-snapshot, auth, or create script for a snapshot-capable cloud provider | `references/provider-vercel.md` |\n| The recipe connects over SSH instead of starting `orca serve`, including provisioned root | `references/ssh-host.md` |\n| The environment is a local Docker container reached over SSH | `references/docker-ssh.md` |\n| The user's desktop is Windows and you are scaffolding local-side scripts | `references/windows-scripts.md` |\n| A doctor, provision, clone, login, or snapshot step failed | `references/failure-modes.md` |\n\n---\n\n# Bundled references\n\nThese references belong to the version-matched guide above. Read only the documents named by its action gates.\n\n\n\n# Local Docker over SSH\n\nLoad this when the environment is a local Docker container reached over SSH. It models an ephemeral\nSSH VM without cloud cost: build a base image with `sshd`, tools, repo prerequisites, and the agent\nCLI; run an interactive auth container once; then `docker commit` that container as the\nauthenticated image per-workspace `create` boots from. The emitted result is the SSH shape in\n`references/ssh-host.md`.\n\n- Publish container SSH to a random localhost port with `-p 127.0.0.1::22`, and emit\n `connection.type:\"ssh\"` with `host:\"127.0.0.1\"`, that port, `username`, `identityFile`, and\n `identitiesOnly:true`.\n- Generate a repo-local SSH key if needed, and gitignore the private and public key files.\n- Generate unique SSH host keys with `ssh-keygen -A` on each container's first start and retain\n them for that container's lifetime. Remove `/etc/ssh/ssh_host_*` from the base and auth images\n before reuse; never distribute one private host key across workspaces.\n- Before connecting, read the container's public host key through trusted local `docker exec` and\n record it under `[127.0.0.1]:` in the desktop's `known_hosts`. If a port was reused,\n replace only that endpoint's old entry after verifying the new container identity. Preserve\n entries for other workspaces; never disable host-key checking to bypass a mismatch.\n- The auth image is the Docker form of the agent-auth snapshot: the user runs the agent login inside\n the container, configures proxy env and config, approves hooks, and you commit once they report it\n finished.\n- Do not bind-mount or copy the host's full agent home into the image. Let each container keep\n writable agent state; only the committed auth image carries reusable authenticated state.\n- When committing from an interactive shell, force the runtime entrypoint back to `sshd`:\n `docker commit --change='ENTRYPOINT [\"/usr/local/bin/orca-docker-ssh-entrypoint\"]' …`.\n- `destroy` reads `recipeResult.userData.resourceId` and runs `docker rm -f \"$resource_id\"`.\n\n## Validation before wiring or live use\n\n```bash\ndocker image inspect \"$auth_image\" --format '{{json .Config.Entrypoint}}'\ndocker run -d --name \"$name\" -p 127.0.0.1::22 -e \"ORCA_SSH_PUBLIC_KEY=$pubkey\" \"$auth_image\"\ndocker ps -a --filter \"name=$name\"\ndocker logs \"$name\"\nssh -i \"$key\" -p \"$port\" -o IdentitiesOnly=yes -o StrictHostKeyChecking=yes user@127.0.0.1 'codex --version'\n```\n\nInspect the auth image entrypoint and do this startup-only `docker run` before the full clone and\ninstall path. If the container exits immediately, read its logs before the cleanup trap removes it;\nan image committed from an interactive shell with `ENTRYPOINT [\"bash\"]` is a common cause.\n\nValidate two containers: their public host keys must differ, and each must match its recorded\nendpoint before SSH succeeds. Restarting the same container preserves its key; reusing a deleted\ncontainer's port requires verifying and recording the replacement's key. Remove that endpoint's\nentry on destroy only if it still matches the destroyed container's recorded key.\n\n\n\n# Failure modes\n\nLoad this when a doctor, provision, clone, login, or snapshot step failed. Each entry maps a\nsymptom to its cause; the rule that prevents it lives in the guide next to the step.\n\n## Reading a failed `--provision` result\n\nThe JSON result carries a `provisionTranscript` with each stage's captured output, so you can\ndiagnose without asking the user for logs:\n\n```json\n{\n \"ok\": false,\n \"checks\": [{ \"id\": \"recipe.provision\", \"status\": \"fail\", \"message\": \"…\" }],\n \"provisionTranscript\": {\n \"provision\": { \"exitCode\": 0, \"signal\": null, \"stdout\": \"…\", \"stderr\": \"…\", \"parseError\": \"…\" },\n \"destroy\": { \"exitCode\": 0, \"signal\": null, \"stdout\": \"…\", \"stderr\": \"…\" }\n }\n}\n```\n\nStreams are redacted and capped at both ends, keeping the start and the failure. Two common reads:\n\n- A non-empty `stderr` with `exitCode 0` plus a `parseError` means `create` ran but printed something\n other than the single recipe-result JSON object on stdout. The offending stdout is in the\n transcript; the usual cause is a stray `echo`.\n- A non-zero `exitCode` is a provider or script failure, described in `stderr`.\n\n## Build and clone\n\n- **Build exceeds the plan timeout**, for example Vercel Hobby's 45 minutes. Use enough vCPUs and a\n timeout that covers the build, or split the work, or move to a higher plan. The same cap limits\n per-workspace runtime, so surface it to the user.\n- **Build exceeds plan RAM.** Building the headless main only, dropping the renderer, is the single\n biggest fit.\n- **Private-repo clone hangs or fails.** The token is wrong or missing. `GIT_ASKPASS` plus\n `GIT_TERMINAL_PROMPT=0` makes it fail fast instead of prompting.\n- **The `GIT_ASKPASS` helper aborts the clone with `$1: unbound variable`.** The `printf` or heredoc\n that wrote the helper inside `bash -lc` under `set -u` expanded `$1` and `$GH_TOKEN` at write time\n instead of leaving them for git-runtime. The same mistake writes the real token into the file.\n\n## Agent auth\n\n- **The agent verifies as \"not logged in\" despite a good login.** `codex login status` and similar\n print their success line to stderr, so a check that reads stdout only misses it.\n- **A headless agent login hangs.** Plain OAuth `login` started a loopback callback server on a port\n the host browser cannot reach.\n- **Agent auth did not persist.** Confirm `snapshotId` points at the authenticated snapshot rather\n than the base, and re-run the auth phase. If the agent's credentials are short-lived, the snapshot\n needs periodic re-auth; warn the user.\n- **Agent auth copied from the host breaks.** A bind-mounted or copied host agent home carries sqlite\n files that can be unwritable or host-specific, hooks that need approval again, and config that\n references local-only environment variables. Authenticate inside the runtime and snapshot or commit\n that layer instead.\n\n## Environment lifecycle\n\n- **`known_hosts` mismatch on local Docker.** A new container may reuse an old container's port.\n Read its public key through trusted local Docker access, verify the container identity, then\n replace only that endpoint's recorded key. Never reuse private host keys across workspace images.\n- **Snapshot expired or evicted.** `create` hit an unknown snapshot id. Re-run the base and auth\n snapshot phases and update `snapshotId` in state.\n- **Docker auth image exits immediately.** Read `docker image inspect … .Config.Entrypoint` and\n `docker logs`. An image committed from an interactive shell keeps that shell as its entrypoint.\n- **A paid resource leaked.** A long script created an environment and then failed without a trap\n that removes it.\n\n\n\n# Worked example — Vercel Sandbox\n\nLoad this when writing the base-snapshot, auth, or `create` script for a snapshot-capable cloud\nprovider. It fills section 7's skeletons with a real surface, `vercel sandbox\ncreate|exec|snapshot|remove`. Adapt the names and verify every flag against\n`vercel sandbox --help` for the user's CLI version.\n\nThis is the Orca-server connection mode: the recipe emits a pairing URL. If the user chose SSH in\nthe interview, use `references/ssh-host.md` instead.\n\n## Snapshot cleanup\n\nThe base and auth excerpts each belong to one `set -euo pipefail` script. Include this function\nin both scripts and arm the trap before creating their temporary sandbox. Keep it armed through\nverification, snapshot creation, and writing state; cleanup failure must remain visible.\n\n```bash\ncleanup_snapshot() {\n snapshot_exit=$?\n trap - EXIT\n if ! vercel sandbox remove \"$1\" \"${vercel_args[@]}\" >&2; then\n echo \"Sandbox cleanup failed for $1; inspect and remove it before continuing\" >&2\n snapshot_exit=1\n fi\n exit \"$snapshot_exit\"\n}\n```\n\nUse fresh sandbox names for these scripts so cleanup cannot remove an existing environment.\n\n## Base snapshot\n\nProvision, install tools and clone, build headless, then snapshot.\n\n```bash\n# provision a fresh build sandbox (retain a couple of snapshots)\ntrap 'cleanup_snapshot \"$base\"' EXIT\nvercel sandbox create --name \"$base\" --runtime node24 --timeout 30m --vcpus 4 --publish-port \"$port\" \\\n --snapshot-expiration 30d --keep-last-snapshots 2 \"${vercel_args[@]}\" >&2\n# remote build (long timeout): install pkgs+gh+pnpm+agent CLI, clone with GIT_ASKPASS (the helper's\n# \\$1/\\$GH_TOKEN escaping is load-bearing — see the guide's Credentials section — then\n# `rm -f /tmp/askpass.sh`), write the headless main-only build config (drop the renderer), dev setup,\n# build CLI + headless main, smoke-check\nvercel sandbox exec \"$base\" \"${vercel_args[@]}\" --timeout 25m --env \"GH_TOKEN=$gh_token\" … -- bash -lc '…build…' >&2\n# snapshot the STOPPED sandbox and parse the id from CLI output (fail if unparseable)\nout=\"$(vercel sandbox snapshot \"$base\" --stop --expiration 30d \"${vercel_args[@]}\" 2>&1)\"; printf '%s\\n' \"$out\" >&2\nsnapshot_id=\"$(printf '%s\\n' \"$out\" | sed -nE 's/.*(snap_[A-Za-z0-9]+).*/\\1/p' | tail -1)\"\n[ -n \"$snapshot_id\" ] || { echo \"snapshot id missing\" >&2; exit 1; }\n# merge { baseName, snapshotId, scope, project, port, repoUrl, repoRef, projectRoot } into state; print state JSON\n```\n\n## Agent-auth snapshot\n\nBoot the base, let the user log the agent in, verify, then re-snapshot. `codex` here is an example;\nsubstitute the user's chosen agent's login and status verbs.\n\n```bash\ntrap 'cleanup_snapshot \"$auth\"' EXIT\nvercel sandbox create --name \"$auth\" --snapshot \"$snapshot_id\" --timeout 30m --publish-port \"$port\" \"${vercel_args[@]}\" >&2\n# The USER runs this in their own terminal and completes the URL/code on the HOST.\nvercel sandbox exec --interactive --tty \"$auth\" \"${vercel_args[@]}\" -- bash -lc 'codex login --device-auth'\n```\n\nVerify by exit code. The remote command prints a sentinel instead of relying on the exit code,\nbecause a provider CLI may not propagate remote exit codes:\n\n```bash\nverdict=\"$(vercel sandbox exec \"$auth\" \"${vercel_args[@]}\" --timeout 30s \\\n -- bash -lc 'if codex login status >/dev/null 2>&1; then echo ORCA_AGENT_LOGGED_IN; else echo ORCA_AGENT_LOGGED_OUT; fi')\"\ncase \"$verdict\" in\n *ORCA_AGENT_LOGGED_IN*) ;;\n *) echo \"agent not logged in; not snapshotting\" >&2; exit 1 ;;\nesac\n```\n\nFallback for an agent whose `status` exit code says nothing about auth: capture the output with\nstderr folded in and match the agent's exact success line. Match a variable, not a pipe, so the\nprovider process cannot take SIGPIPE:\n\n```bash\nstatus=\"$(vercel sandbox exec \"$auth\" \"${vercel_args[@]}\" --timeout 30s -- bash -lc 'codex login status 2>&1')\"\ngrep -Eq 'Logged in using ChatGPT|Logged in via device' <<<\"$status\" \\\n || { echo \"agent not logged in; not snapshotting\" >&2; exit 1; }\n```\n\nThen re-snapshot and record the new id:\n\n```bash\nout=\"$(vercel sandbox snapshot \"$auth\" --stop --expiration 30d \"${vercel_args[@]}\" 2>&1)\"; printf '%s\\n' \"$out\" >&2\nnew_id=\"$(printf '%s\\n' \"$out\" | sed -nE 's/.*(snap_[A-Za-z0-9]+).*/\\1/p' | tail -1)\"\n[ -n \"$new_id\" ] || { echo \"authenticated snapshot id missing\" >&2; exit 1; }\n# overwrite state.snapshotId = new_id, record authSourceSnapshotId = snapshot_id; remove the auth sandbox\n```\n\n## Per-workspace `create`\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\n# resolve from env→state→fallback: snapshot_id, scope, project, port, repo_url, repo_ref, project_root\nvercel_args=(); [ -n \"$scope\" ] && vercel_args+=(--scope \"$scope\"); [ -n \"$project\" ] && vercel_args+=(--project \"$project\")\n[ -n \"$snapshot_id\" ] || { echo \"snapshotId missing — build the base and auth snapshots first\" >&2; exit 1; }\ngh_token=\"${GH_TOKEN:-${GITHUB_TOKEN:-$(command -v gh >/dev/null 2>&1 && gh auth token 2>/dev/null || true)}}\"\nrecipe_id=\"${ORCA_RECIPE_ID:-vercel-sandbox}\"\nrecipe_id=\"${recipe_id//./-}\" # Vercel names forbid dots.\ninstance_id=\"${ORCA_VM_INSTANCE_ID:-$(date +%s)}\"\nmax_recipe_id_length=$((128 - ${#instance_id} - 6)) # Preserve the unique instance suffix.\n[ \"$max_recipe_id_length\" -gt 0 ] || { echo \"ORCA_VM_INSTANCE_ID is too long for a Vercel sandbox name\" >&2; exit 1; }\nname=\"orca-${recipe_id:0:max_recipe_id_length}-${instance_id}\"\n\n# Arm cleanup BEFORE create so a failing create can't leak a half-built paid sandbox.\ncleanup_on_error() { [ \"$?\" -ne 0 ] && vercel sandbox remove \"$name\" \"${vercel_args[@]}\" >/dev/null 2>&1 || true; }\ntrap cleanup_on_error EXIT\n\n# 1. boot from the authenticated snapshot, publish the serve port\ncreate_output=\"$(vercel sandbox create --name \"$name\" --snapshot \"$snapshot_id\" \\\n --timeout 30m --publish-port \"$port\" \"${vercel_args[@]}\" 2>&1)\"; printf '%s\\n' \"$create_output\" >&2\n# Vercel prints the published https URL; derive the external wss:// pairing address from it\npublic_url=\"$(printf '%s\\n' \"$create_output\" | sed -nE 's#.*(https://[^[:space:]]+\\.vercel\\.run).*#\\1#p' | head -1)\"\n[ -n \"$public_url\" ] || { echo \"no published URL in create output\" >&2; exit 1; }\npairing_ws=\"${public_url/https:\\/\\//wss://}\"\n\n# 2. (remote) ensure the repo is at the right commit; rebuild only if the commit changed (cache marker)\nvercel sandbox exec \"$name\" \"${vercel_args[@]}\" --timeout 20m \\\n --env \"GH_TOKEN=$gh_token\" --env \"ORCA_PROJECT_ROOT=$project_root\" \\\n --env \"ORCA_REPO_URL=$repo_url\" --env \"ORCA_REPO_REF=$repo_ref\" \\\n -- bash -lc 'set -euo pipefail; cd \"$ORCA_PROJECT_ROOT\"; \\\n export GIT_TERMINAL_PROMPT=0; \\\n # Escaping is load-bearing here: re-test the fetch after any edit to the nested quoting.\n if [ -n \"${GH_TOKEN:-}\" ]; then \\\n printf \"%s\\n\" \"#!/usr/bin/env bash\" \"case \\\"\\$1\\\" in *Username*) echo x-access-token;; *Password*) echo \\\"\\$GH_TOKEN\\\";; esac\" > /tmp/askpass.sh; \\\n chmod 700 /tmp/askpass.sh; export GIT_ASKPASS=/tmp/askpass.sh; fi; \\\n git fetch origin \"$ORCA_REPO_REF\"; \\\n git checkout -B \"$ORCA_REPO_REF\" FETCH_HEAD; \\\n rm -f /tmp/askpass.sh; \\\n c=\"$(git rev-parse HEAD)\"; [ -f .orca-built ] && [ \"$(cat .orca-built)\" = \"$c\" ] || { \\\n pnpm install --prefer-offline && pnpm run build:cli && \\\n node config/scripts/run-electron-vite-build.mjs --config config/electron-vite.vm-serve.config.ts && \\\n printf \"%s\" \"$c\" > .orca-built; }' >&2\n\n# 3. (remote) start orca serve in the background, writing recipe JSON to a file; poll until it parses\nrecipe_json=\"$(vercel sandbox exec \"$name\" \"${vercel_args[@]}\" --timeout 60s \\\n --env \"ORCA_PORT=$port\" --env \"ORCA_PROJECT_ROOT=$project_root\" --env \"ORCA_PAIRING_ADDRESS=$pairing_ws\" \\\n -- bash -lc 'set -euo pipefail; cd \"$ORCA_PROJECT_ROOT\"; rm -f /tmp/orca-recipe.json /tmp/orca-serve.log; \\\n nohup pnpm exec orca-dev serve --port \"$ORCA_PORT\" --project-root \"$ORCA_PROJECT_ROOT\" \\\n --pairing-address \"$ORCA_PAIRING_ADDRESS\" --recipe-json >/tmp/orca-recipe.json 2>/tmp/orca-serve.log /dev/null 2>&1 && { cat /tmp/orca-recipe.json; exit 0; }; \\\n kill -0 \"$pid\" 2>/dev/null || { cat /tmp/orca-serve.log >&2; exit 1; }; sleep 0.25; \\\n done; cat /tmp/orca-serve.log >&2; echo \"serve recipe JSON timed out\" >&2; exit 1')\"\n\n# 4. print serve's JSON enriched with userData (single object on stdout)\nnode -e 'const p=JSON.parse(process.argv[1]); console.log(JSON.stringify({...p, schemaVersion:1,\n userData:{...p.userData, provider:\"vercel-sandbox\", resourceId:process.argv[2], snapshotId:process.argv[3]}}))' \\\n \"$recipe_json\" \"$name\" \"$snapshot_id\"\ntrap - EXIT\n```\n\n`suspend`, `resume`, and `destroy` run `vercel sandbox stop|...|remove \"$resource_id\"`, reading\n`userData.resourceId` from the lifecycle payload on stdin.\n\nThe `128` in `max_recipe_id_length` is Vercel's sandbox name cap. Confirm it against\n`vercel sandbox create --help` or Vercel's docs for the user's CLI version before relying on it; a\nwrong cap silently truncates recipe ids in resource names.\n\n\n\n# SSH connection mode, including provisioned root\n\nLoad this when the recipe connects over SSH instead of starting `orca serve`, and when the user has\nexplicitly asked for `checkoutMode: provisioned-root`.\n\nSSH mode is a different shape, not the Orca-server templates relabeled. `create` runs no\n`orca serve` and emits no `pairingCode`. Orca connects over its SSH relay, brings up the git and\nfilesystem providers, and imports the repo. The script only readies the host and prints the SSH\ndetails Orca dials.\n\n## The result shape\n\nOrca rejects anything else. Required fields only; add optionals from the next section as the\nnetwork needs them.\n\n```json\n{\n \"schemaVersion\": 1,\n \"connection\": {\n \"type\": \"ssh\",\n \"projectRoot\": \"/abs/path/to/repo/on/host\",\n \"target\": {\n \"label\": \"my-box\",\n \"host\": \"192.0.2.10\",\n \"port\": 22,\n \"username\": \"ubuntu\"\n }\n }\n}\n```\n\n`label`, `host`, `port`, and `username` are required. `projectRoot` is an absolute path on the host.\n\n## Which optional `target` fields to set\n\nThese describe how the user's desktop reaches the box; there is no `orca serve` URL in SSH mode.\n\n- A public IP or DNS name, or a Tailscale or VPN address, is the `host`; the SSH port is `port`,\n usually 22.\n- Key auth sets `identityFile`. Add `\"identitiesOnly\": true` when the agent holds many keys.\n- A bastion is reached through one of two fields: `jumpHost` takes a `user@host` ProxyJump\n target, and `proxyCommand` takes a full command such as an access proxy. **Set one, never both.** The schema\n accepts both, and the two consumers then disagree: one pushes `-J` and `-o ProxyCommand=` into the\n same argv, the other resolves `proxyCommand` and ignores `jumpHost` entirely.\n- A service port the workspace needs is an entry in `portForwards`. Each entry requires\n `localPort`, `remoteHost`, and `remotePort`, and takes an optional `label`. The entry schema is\n strict, so an invented key such as `local` or `remote` fails validation.\n- `relayGracePeriodSeconds` bounds how long Orca keeps the SSH relay alive after the workspace\n detaches. **`0` means unbounded**: the relay stays up until something explicitly terminates it, so\n it is the wrong value for a disposable runtime. Any other value must be between 60 and 604800\n seconds. A value between 1 and 59, such as `30`, is rejected and takes the whole recipe result\n with it.\n Omit the field unless the user asked for a specific reconnect grace window.\n\n## Toolchain and agent auth on a persistent host\n\nA persistent host is its own base image. Run the install steps and the agent's device-auth login\nover SSH once, by hand, before wiring the recipe. The login is interactive, for example\n`ssh -t user@host ' login --device-auth'`, so the user runs it. The host then stays ready\nacross workspaces.\n\nUse Git credentials already configured on the SSH host. For GitHub HTTPS repos, verify `gh auth\nstatus` on that host and run `gh auth setup-git` there if Git has no credential helper. Installed\n`gh` alone is not authentication. SSH URLs use the host's SSH keys; other providers use their own\ncredential setup. If credentials are missing, have the user configure them on the host. Do not\nforward a desktop token in the SSH command.\n\nBefore the first connection, verify the host key using the provider console or another trusted\nchannel and record it in the desktop's `known_hosts`. Do not trust an unverified `ssh-keyscan`\nresult. The noninteractive script below refuses unknown or changed keys.\n\n## The create script\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\n# resolve from env→state→fallback (default unset optionals to \"\"): ssh_username, host,\n# ssh_port (default 22), identity_file, jump_host, proxy_command, project_root, repo_url, repo_ref\n: \"${identity_file:=}\"; : \"${jump_host:=}\"; : \"${proxy_command:=}\" # avoid set -u aborts on optionals\nssh_target=\"${ssh_username}@${host}\"\nif [ -n \"$jump_host\" ] && [ -n \"$proxy_command\" ]; then\n echo \"set jump_host or proxy_command, not both\" >&2; exit 1\nfi\nssh_opts=(-p \"$ssh_port\" -o BatchMode=yes -o StrictHostKeyChecking=yes)\n[ -n \"$identity_file\" ] && ssh_opts+=(-i \"$identity_file\")\n[ -n \"$jump_host\" ] && ssh_opts+=(-J \"$jump_host\")\n[ -n \"$proxy_command\" ] && ssh_opts+=(-o \"ProxyCommand=$proxy_command\")\n\n# 1. ensure the repo is present and at the right commit on the host (NO orca serve here).\n# printf %q quotes every value for the remote shell, so a space or quote in a path or\n# ref cannot break out of the command.\nremote_sync='set -euo pipefail\n export GIT_TERMINAL_PROMPT=0\n [ -d \"$project_root/.git\" ] || git clone \"$repo_url\" \"$project_root\"\n cd \"$project_root\" && git fetch origin \"$repo_ref\" && git checkout -B \"$repo_ref\" FETCH_HEAD'\nssh \"${ssh_opts[@]}\" \"$ssh_target\" \"$(printf \\\n 'project_root=%q repo_url=%q repo_ref=%q bash -lc %q' \\\n \"$project_root\" \"$repo_url\" \"$repo_ref\" \"$remote_sync\")\" >&2\n\n# 2. print the SSH connection block (NO pairingCode, NO orca serve). host/port/username tell Orca's\n# relay how to dial in; identityFile/jumpHost/proxyCommand/portForwards are emitted when set.\nnode -e 'const [host,port,user,idf,jh,pc,root]=process.argv.slice(1);\n const target={ label:\"per-workspace-host\", host, port:Number(port), username:user };\n if(idf) target.identityFile=idf; if(jh) target.jumpHost=jh; if(pc) target.proxyCommand=pc;\n // add target.portForwards=[{localPort,remoteHost,remotePort}] here if the workspace needs them\n console.log(JSON.stringify({ schemaVersion:1, connection:{ type:\"ssh\", projectRoot:root, target } }))' \\\n \"$host\" \"$ssh_port\" \"$ssh_username\" \"$identity_file\" \"$jump_host\" \"$proxy_command\" \"$project_root\"\n```\n\nOn a persistent host there is usually nothing to tear down, so set `destroy: none` and omit suspend\nand resume. Orca still disconnects and reconnects its own SSH relay on sleep, wake, and delete, which\nis separate from these scripts.\n\nIf the SSH host is instead an ephemeral, snapshot-capable VM — the user's hypervisor, or a cloud VM\nwith image support — keep the base-image model from `references/provider-vercel.md` for\nprovisioning, but still emit the `connection.type:\"ssh\"` block above instead of starting\n`orca serve`.\n\n## Provisioned root\n\nFor an explicitly requested one-VM-per-workspace checkout, the create script reads\n`ORCA_RECIPE_RESULT_SCHEMA_VERSION`, `ORCA_REPO_URL`, `ORCA_REPO_REF`, `ORCA_REPO_REF_HEAD`, and\n`ORCA_REPO_BRANCH`. Use `ORCA_REPO_REF` to fetch the selected source, but create `ORCA_REPO_BRANCH`\nat the exact `ORCA_REPO_REF_HEAD` commit, because resolving the symbolic ref again can race with an\nupstream update. `ORCA_REPO_URL` and `ORCA_REPO_REF` are a matched fetch pair, and the URL is the\nremote Orca resolved the base ref against, which is not necessarily named `origin` on the desktop.\nFetch from the URL the pair supplies:\n\n```bash\n[ -n \"${ORCA_REPO_REF_HEAD:-}\" ] || { echo \"missing pinned source commit\" >&2; exit 1; }\ngit fetch \"$ORCA_REPO_URL\" \"$ORCA_REPO_REF\"\ngit cat-file -e \"${ORCA_REPO_REF_HEAD}^{commit}\"\ngit checkout -B \"$ORCA_REPO_BRANCH\" \"$ORCA_REPO_REF_HEAD\"\n```\n\nReturn that primary checkout at `projectRoot` and emit schema version 2:\n\n```json\n{\n \"schemaVersion\": 2,\n \"checkoutMode\": \"provisioned-root\",\n \"connection\": {\n \"type\": \"ssh\",\n \"projectRoot\": \"/abs/repo\",\n \"target\": { \"label\": \"my-box\", \"host\": \"192.0.2.10\", \"port\": 22, \"username\": \"ubuntu\" }\n }\n}\n```\n\n## Before declaring an SSH recipe done\n\nThe `--provision` self-test only sees what the scripts print, so smoke-test the exact emitted target\nas well: dial the host and port with the identity or proxy settings, run `pwd`, verify the repo path,\nand check the agent binary. If the recipe created a provider resource, also confirm `destroy`\nremoves it.\n\n\n\n# Windows local-side scripts\n\nLoad this when the user's desktop is Windows and you are scaffolding the local-side scripts. A bare\n`.sh` will not execute there. Either require WSL or Git Bash and point `orca.yaml` at a launcher such\nas `bash ./scripts/orca-vm/.sh` through a `.cmd` file, or scaffold PowerShell equivalents.\n\nThe remote-side commands you run inside the Linux environment stay bash regardless of the desktop OS.\n\n```powershell\n#requires -Version 5\n$ErrorActionPreference = 'Stop'\n# resolve env→state→fallback; run the provider CLI / ssh the same way;\n# capture provider output; build the result object for the chosen mode and write ONE line of JSON to stdout.\n# Orca-server mode: @{ schemaVersion=1; pairingCode=$pairingCode; projectRoot=$projectRoot; userData=@{...} }\n# SSH mode: @{ schemaVersion=1; connection=@{ type=\"ssh\"; projectRoot=$projectRoot;\n# target=@{ label=$label; host=$host; port=$port; username=$user } } }\n($result | ConvertTo-Json -Compress -Depth 6)\n# progress/errors → Write-Error / the error stream, never stdout.\n```\n\nThe doctor's executable-bit check is a POSIX concept and is skipped on Windows, so a script that is\nunusable on the user's machine for a different reason still has to be caught by the `--provision`\nself-test.\n" +const ORCA_PER_WORKSPACE_ENV_FULL_MARKDOWN = "---\nname: orca-per-workspace-env\ndescription: >-\n Set up, review, debug, or validate an Orca per-workspace environment recipe: the\n on-demand, disposable runtime (cloud sandbox, VM, SSH host, or local container)\n Orca creates fresh for each workspace. Use to stand up a new recipe end to end,\n fix an `environmentRecipes` entry in `orca.yaml`, scaffold provider lifecycle\n scripts, or resolve an `orca vm recipe doctor` failure. Use `orca-cli` for\n ordinary worktree and workspace creation with no recipe involved.\n---\n\n# Per-Workspace Environments\n\n`ORCA` is a placeholder for the executable you resolved in the stub; substitute it before running.\nInside the lifecycle scripts the placeholder does not apply: `orca serve` written there runs on\nthe remote machine's own binary.\n\n## Autonomy envelope\n\nWithout asking again you may read the repo and its `orca.yaml`, detect provider CLIs and their\nlogin state, scaffold and edit files under `scripts/orca-vm/`, and run `ORCA vm recipe doctor`\nwithout `--provision`. Get an explicit OK before each paid step: the base snapshot, the auth\nsnapshot, and `--provision`. One OK covers the whole `--provision` fix-and-rerun loop. Stop for\nthe interactive agent login, which you cannot drive; the user runs it and tells you when it is\ndone. Never create an Orca workspace except for the step-10 test the user asked for. Do not create\nGit commits unless asked. Never choose a plan or region, invent a scope, project, or billing id, or\nwrite a credential into a script, `userData`, the state file, or a commit.\n\nPreserve actionable provider errors and the failing command, redact secrets, and clean up resources\ncreated by a failed step.\n\n## The branch that shapes everything\n\nIn **Orca-server** mode `create` runs `orca serve` in the environment and emits a `pairingCode`. In\n**SSH** mode `create` runs no server and emits a `connection.type:\"ssh\"` block Orca dials into.\nSettle this first; it changes the `create` output and half the templates.\n\nKeep Orca's checkout behavior unchanged by default: omit `checkoutMode`, emit schema version 1, and\nlet Orca create a linked worktree. Use `checkoutMode: provisioned-root` only when the user\nexplicitly wants one ephemeral machine to clone the finished workspace itself. That mode requires\ndirect SSH, an ordinary non-bare and non-sparse primary checkout at `projectRoot`, and schema\nversion 2.\n\n## 1. Setup workflow\n\nDrive these with the user. The order is fixed: the auth snapshot (step 6) boots from the base\nsnapshot (step 5), and `create` boots from the authenticated snapshot they produce. A\n**[CHECKPOINT]** label marks a step the autonomy envelope stops for.\n\n1. **Inspect the repo** for an existing `environmentRecipes` entry, `scripts/orca-vm/`, a state\n file, or setup notes. If a working recipe already exists, go straight to the doctor loop below\n instead of rebuilding.\n2. **Interview the user up front.** Gather these choices and confirm them back before scaffolding\n anything. Do not pick for them and do not guess.\n - **Connection mode:** an Orca server or SSH, as above. Settle it first.\n - **Checkout ownership:** do not ask by default. Only when the user requires the environment to\n create the exact final checkout, confirm `provisioned-root` and direct SSH; otherwise omit it.\n - **Provider:** Vercel Sandbox, Fly, Modal, an existing SSH host, and so on. For a non-obvious\n provider, also ask scope, project, region, and plan limits. Then read that provider's CLI or\n SDK docs, or ` --help`, before scaffolding: you need its exact create, exec, snapshot, and\n remove verbs. If a provider advertises `ssh`, check whether it exposes a real dialable SSH\n target (host, port, user, key or proxy command) or only a provider-mediated interactive shell.\n Orca's SSH mode needs the former.\n - **Coding-agent CLI and account:** which agent runs in the environment (`codex`, `claude`, and\n so on) and that the user has an account for it. It is logged in during step 6.\n - **Git auth:** the token source for cloning a private repo (`GH_TOKEN`, `GITHUB_TOKEN`, or\n `gh auth token`).\n3. **Check prerequisites** (section 2) and confirm the items above are in place before any paid\n step.\n4. **Scaffold the scripts and state file**, filling in the provider's real commands, and make them\n executable. The per-provider worked examples are in the conditional references below.\n5. **[CHECKPOINT] Build the base snapshot** (section 3). Paid and slow.\n6. **[CHECKPOINT] Authenticate the agent** (section 4). Interactive; the user follows a URL and code.\n7. **Wire the recipe** so `orca.yaml` points create, suspend, resume, and destroy at the scripts.\n Tell the user up front: the composer reads `environmentRecipes` from the primary checkout, so\n a recipe that lives only on a branch never appears as a \"Run on\" option. The doctor works on\n any branch; the picker needs `orca.yaml` on the primary branch.\n8. **Dry-run the doctor** — free and static.\n9. **[CHECKPOINT] Live self-test** — run the `--provision` loop until it passes.\n10. **[CHECKPOINT] Optional workspace test** — only if asked: create a workspace via the picker,\n then verify sleep, wake, and delete.\n\n## 2. Prerequisites\n\nThese are the user's responsibility. Verify what you can, ask for the rest, invent nothing, and\nsay which items you verified and which the user asserted.\n\n- **Cloud account and plan** that allows sandboxes or VMs. Ask.\n- **Provider CLI installed and authenticated** — detect with `command -v ` and check auth (for\n example `vercel whoami`). If it is missing, point at the provider's docs; do not log them in.\n- **Scope, project, and region** the environments live under. Ask; this flows into every script via\n state.\n- **Plan, timeout, and RAM caps.** Record them. Vercel's Hobby plan, for example, caps sandbox\n timeout at 45 minutes, which limits both the base build and the per-workspace runtime.\n- **Git token for private repos** (`GH_TOKEN`, `GITHUB_TOKEN`, or the provider's git auth, falling\n back to `gh auth token`).\n- **Coding-agent CLI choice** and an account for it.\n\n## 3. Base snapshot\n\nBuild once, snapshot, and every workspace boots from that image in seconds instead of rebuilding.\nProvisioning and building often takes 20 to 30 minutes.\n\n- Build the **headless Electron main only**, not the renderer, so it fits in plan RAM.\n- Use the environment image's package manager (`apt`, `dnf`, `apk`, per the base distro, not the\n provider brand).\n- Clone with the git token via `GIT_ASKPASS` (section 5).\n- Trap errors and remove the half-built environment, so a crash does not leave a paid resource\n running.\n- **Never snapshot a machine on which the Orca runtime has already run.** The first `orca serve`\n creates the runtime's user-data directory, and everything in it is baked into the image and shared\n by every environment booted from it: the pairing keypair and device-token registry\n (`orca-devices.json`, `orca-e2ee-keypair.json`), `agent-session-authority.key`, and the build\n box's logs, terminal history, and orchestration database. Two VMs from one such snapshot emitted\n identical `deviceToken` and `pairedDeviceId`. Snapshot before the runtime has ever run, or delete\n the resolved user-data directory first:\n `orca_user_data_path=\"${ORCA_USER_DATA_PATH:-${XDG_CONFIG_HOME:-$HOME/.config}/orca}\"`.\n Resolve symlinks and inspect that path before deleting it: it must be an absolute directory\n dedicated to Orca runtime data, never `/`, the home directory, or an ancestor of home. Refuse\n empty or relative paths. Remove only that verified directory, not an unchecked environment value.\n That matches Orca's Linux precedence for custom and default paths; deleting a named file list\n drifts as Orca adds state.\n- Snapshot the stopped environment, parse the snapshot id, and write it plus scope, project, port,\n and repo into state.\n\n## 4. Agent-auth snapshot\n\nThe base snapshot has the agent CLI installed but not logged in, and per-workspace environments are\nephemeral. Authenticate once and bake it into a second snapshot layer.\n\n1. Boot an environment from the base `snapshotId` in state.\n2. Run the agent's login interactively. **On a headless machine this must be the device-auth flow**\n (for example `codex login --device-auth`), never plain `codex login`: the default OAuth login\n starts a loopback callback server on a port the host browser cannot reach, so it hangs.\n Device-auth prints a URL and code the user opens on the host.\n3. Verify the login and refuse to snapshot an unauthenticated machine. **Prefer the status command's\n exit code**, because most agent CLIs exit non-zero when unauthenticated. If you match text\n instead, agent status often goes to stderr, so fold stderr first (`... 2>&1 | grep …`) and match\n the agent's exact success line. Never `grep -qi 'logged in'`, which also matches \"not logged in\"\n and would commit an unauthenticated image.\n4. Re-snapshot, parse the new id, overwrite `snapshotId` in state with the authenticated image, and\n record `authSourceSnapshotId`. Remove the auth environment.\n\nAuthenticate inside the runtime and snapshot that layer. Do not bind-mount or copy a host agent\nhome such as `~/.codex`: its sqlite state, hook approvals, caches, and host-specific config break\nin the runtime. If the agent's credentials are short-lived, tell the user the snapshot needs\nperiodic re-auth.\n\nYou cannot drive step 2. You have no TTY for `docker exec -it` or `ssh -t`, so the user runs the\nlogin in their own terminal and tells you when it finished. Verify and re-snapshot after that.\n\n> Harness adapter: in Claude Code the user can run that login in the session itself with the bang\n> prefix, `! `, including the required space after `!`. Other harnesses have no such\n> affordance; the portable rule is that the user runs it wherever they have a terminal.\n\nSection 3's rule still applies: if you ran `orca serve` on this machine to smoke-test it, delete\nthe runtime's user-data directory before re-snapshotting, or every workspace from this image\nshares one pairing identity.\n\n## 5. Credentials\n\n- Never commit secrets or put them in `userData`, recipe JSON, comments, docs, or the state file.\n- **Git token:** read it from `GH_TOKEN` or `GITHUB_TOKEN`, falling back to `gh auth token`. Pass it\n to the environment only via the provider's ephemeral `--env`. Inside the environment, use a\n `GIT_ASKPASS` helper with `x-access-token` rather than the token in the clone URL, plus\n `GIT_TERMINAL_PROMPT=0` so a missing token fails fast instead of hanging. When you write that\n helper from inside `bash -lc` under `set -u`, escape the positional argument and the token as\n `\\$1` and `\\$GH_TOKEN` so they land literally and resolve at git-runtime: an unescaped `$1` aborts\n with \"unbound variable\", and a literal `$GH_TOKEN` keeps the real token out of the written file.\n `rm -f` the helper after the clone or fetch.\n- **Provider auth:** rely on the provider CLI's logged-in session, not checked-in keys.\n- **Agent auth:** lives in the authenticated snapshot from section 4, never in a file you write.\n- State holds only non-secret wiring: snapshot ids, scope, project, port, repo URL and ref.\n\n## 6. State file\n\nA repo-local JSON file such as `scripts/orca-vm/-state.json` threads non-secret values\nbetween phases. Each script resolves a value as env var, then state, then a built-in fallback, and\nmerges its outputs back. The base snapshot writes `snapshotId`; the auth snapshot overwrites it with\nthe authenticated image; per-workspace `create` boots from `snapshotId`.\n\n```json\n{\n \"baseName\": \"orca-base\",\n \"snapshotId\": \"snap_authenticated_image_id\",\n \"authSourceSnapshotId\": \"snap_base_image_id\",\n \"scope\": \"\",\n \"project\": \"\",\n \"port\": 7331,\n \"repoUrl\": \"https://host/org/repo.git\",\n \"repoRef\": \"main\",\n \"projectRoot\": \"/abs/path/on/remote/repo\"\n}\n```\n\n## 7. Script shapes\n\nScaffold under `scripts/orca-vm/`. These are shapes; fill in the provider's real commands. **Every\nscript reserves stdout for its final JSON object and sends progress and errors to stderr.** A stray\n`echo` on stdout corrupts the result. Give each script a `json_value ` and `env_value `\nreader (env, then state, then fallback).\n\nThe local-side scripts (`create`, `suspend`, `resume`, `destroy`, and the hand-run snapshot and auth\nscripts) run on the user's desktop, so they must run on that OS: on macOS and Linux,\n`#!/usr/bin/env bash`, `set -euo pipefail`, quoted paths. Commands you `exec` inside the Linux\nenvironment are always bash.\n\n### 7a. Base snapshot (`-base-snapshot.sh`)\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\n# resolve base_name/repo_url/repo_ref/project_root/port/scope/project/timeout (env→state→fallback)\n# resolve gh token: GH_TOKEN | GITHUB_TOKEN | `gh auth token`\n# 1. provision an environment (timeout/vcpus/published port/snapshot retention); trap: remove on error\n# 2. remote exec (long timeout): install pkgs + gh + corepack/pnpm + agent CLI;\n# clone with GIT_ASKPASS(token); write headless main-only build config;\n# dev setup; pnpm install; build CLI; build headless electron main; smoke-check tools\n# 3. snapshot stopped environment; parse snapshot id (fail if unparseable)\n# 4. merge { baseName, snapshotId, projectRoot, repoUrl, repoRef, port, scope, project } into state\n# print only the state JSON to stdout\n```\n\nYou run this by hand, not via `orca.yaml`, after exporting the first-run inputs state does not have\nyet: provider scope and project, the repo URL and ref, and a git token. Later runs read them back.\n\n### 7b. Auth (`-base-auth.sh`)\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\n# read source snapshot from state.snapshotId (fail if absent); auth_name=\"${base_name}-auth\"\n# 1. boot an environment from the source snapshot; trap: remove on error\n# 2. INTERACTIVE/TTY remote exec: agent login with the device-auth flow. The user runs this and\n# reports back when it finishes.\n# 3. verify login by exit code, then refuse to snapshot if not logged in\n# 4. snapshot; parse new id\n# 5. merge { snapshotId:, authSourceSnapshotId: } into state; remove auth environment\n# print only the state JSON to stdout\n```\n\n### 7c. Create (`-create.sh`)\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\n# read authenticated snapshotId/scope/project/port/repo*/project_root (env→state→fallback)\n# fail clearly if snapshotId is missing (point back to the snapshot phases)\n# name = orca-${ORCA_RECIPE_ID}-${ORCA_VM_INSTANCE_ID} (sanitized, length-capped)\n# 1. boot from snapshotId with a published port; capture the public URL → pairing address\n# (an externally reachable wss:// URL); trap: remove the environment on error\n# 2. remote exec: ensure repo at desired commit; rebuild only if commit changed (cache marker)\n# 3. Orca-server mode only: remote exec starting orca serve and reading the recipe JSON it writes\n# 4. print one recipe-result JSON object to stdout\n```\n\n### 7d. Suspend, resume, destroy\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\npayload=\"$(cat)\" # Orca passes lifecycle JSON on stdin\nresource_id=\"$(node -e 'const d=JSON.parse(process.argv[1]); process.stdout.write(d.recipeResult?.userData?.resourceId ?? \"\")' \"$payload\")\"\n[ -n \"$resource_id\" ] || { echo \"No resource id in lifecycle payload\" >&2; exit 1; }\n# suspend: provider suspend \"$resource_id\"\n# resume: provider resume \"$resource_id\"; then RE-EMIT fresh recipe JSON (pairing may change)\n# destroy: provider remove \"$resource_id\" (or set destroy: none in orca.yaml)\n```\n\n### 7e. State file\n\nScaffold it with scope, project, and repo filled in and the snapshot ids empty.\n\n## 8. Recipe result contract\n\nDefine recipes in `orca.yaml`:\n\n```yaml\nenvironmentRecipes:\n - id: cloud-sandbox\n name: Cloud Sandbox\n create: ./scripts/orca-vm/cloud-sandbox-create.sh\n suspend: ./scripts/orca-vm/cloud-sandbox-suspend.sh\n resume: ./scripts/orca-vm/cloud-sandbox-resume.sh\n destroy: ./scripts/orca-vm/cloud-sandbox-destroy.sh\n```\n\n`create` is required, runs locally from the repo root, and prints exactly one JSON object on stdout.\n`suspend` and `resume` are optional and read the lifecycle payload on stdin; `resume` must print\nfresh recipe JSON because the pairing may have changed. `destroy` may be omitted only with\n`destroy: none`. The legacy keys `command` and `cleanup` still map to `create` and `destroy`.\n\nThe base result, which is what Orca-server mode prints:\n\n```json\n{\n \"schemaVersion\": 1,\n \"pairingCode\": \"orca-pairing-code-or-url\",\n \"projectRoot\": \"/absolute/path/to/repo/on/remote\",\n \"userData\": { \"provider\": \"example\", \"resourceId\": \"provider-resource-id\" }\n}\n```\n\n`pairingCode` and `projectRoot` are required; `schemaVersion` (`1`) and `userData` are optional.\nThree named deltas change that shape:\n\n- **`orca serve --recipe-json` output** is this same object without `userData`. Merge your own\n `userData` into it rather than rebuilding it.\n- **SSH mode** replaces `pairingCode` and `projectRoot` with a `connection` block whose `type` is\n `\"ssh\"`, and does not run `orca serve`. The exact target shape is in `references/ssh-host.md`.\n- **Provisioned root** applies only to direct SSH and only when the user explicitly asked for it. Add\n `checkoutMode: provisioned-root` to the recipe, require `ORCA_RECIPE_RESULT_SCHEMA_VERSION=2`, and\n emit `\"schemaVersion\": 2` with `\"checkoutMode\": \"provisioned-root\"`. Fail if the requested schema\n is not `2` rather than falling back to the ordinary shape. Details are in `references/ssh-host.md`.\n\n### The `orca serve` invocation\n\nInside the environment, in Orca-server mode, run exactly this. These flags are verified; do not\nimprovise them.\n\n```bash\norca serve \\\n --port \"$PORT\" \\\n --project-root \"$ABS_REPO_PATH_ON_REMOTE\" \\\n --pairing-address \"$EXTERNAL_WSS_URL\" \\\n --recipe-json\n```\n\nIn an environment built from source, run it as `pnpm exec orca-dev serve …` from the repo root;\n`orca-dev` is the in-repo entrypoint. Plain `orca serve …` is the same command when the built CLI is\non that machine's PATH, and the flags and output are identical either way. There is no `--host` flag,\nand `--project-root` must be an absolute directory on the remote.\n\n`pairingCode` embeds whatever you passed as `--pairing-address`, so pass the externally reachable\naddress there and never hand-edit the code. Tunneling and port mapping are the script's job. With\n`--recipe-json` the server keeps running, so redirect its stdout to a file and poll until the file\nparses as JSON; if the process dies first, dump its stderr log and fail.\n\n## 9. Doctor and the `--provision` loop\n\n`ORCA vm recipe doctor --repo-path --json` validates static wiring only; it boots\nnothing. It checks local-host execution, the repo path, that the recipe id exists, that the create,\ndestroy, suspend, and resume command paths resolve, that suspend and resume are paired, and that\neach script is executable (the POSIX exec bit, skipped on Windows).\n\n**The free gate is clear only with no `fail` and no `warn`.** A `warn` keeps `ok: true`, so `ok`\nalone proves nothing. Resolve each `warn`, or say why you accept it, before spending money on\n`--provision`.\n\n`--provision` (or its synonym `--connect`) runs the recipe end to end: `create`, validation of the\nreturned JSON, then `destroy`. Nothing is left running as long as `destroy` works.\n\nRun it as a loop: read the `provisionTranscript` in the failed result, fix the script, re-run, until\n`ok` is `true`. Do not wait for the user to paste errors. How to read the transcript is in\n`references/failure-modes.md`.\n\nThe self-test sees only what the scripts print, so confirm separately that state holds an\n**authenticated** `snapshotId` and that `destroy` is implemented and tested. With `destroy: none`\nthe self-test tears nothing down and you must clean up by hand.\n\n## Conditional references\n\nThis guide covers the interview, the phase order, and the doctor loop on its own. At a gate below,\nrun `ORCA skills get orca-per-workspace-env --reference references/.md` and read only that\ndocument; `--references` lists the names. Read the reference at the gate, not before. If the CLI\nrejects `--reference`, run `ORCA skills get orca-per-workspace-env --full` once instead: it returns\nthis guide plus every reference from the same CLI build, so read only the named one. If `--full` is\nrejected too, keep these rules, use the command's `--help`, and do not guess flags.\n\n| Action gate | Bundled reference |\n| ----------------------------------------------------------------------------------------- | ------------------------------- |\n| Writing the base-snapshot, auth, or create script for a snapshot-capable cloud provider | `references/provider-vercel.md` |\n| The recipe connects over SSH instead of starting `orca serve`, including provisioned root | `references/ssh-host.md` |\n| The environment is a local Docker container reached over SSH | `references/docker-ssh.md` |\n| The user's desktop is Windows and you are scaffolding local-side scripts | `references/windows-scripts.md` |\n| A doctor, provision, clone, login, or snapshot step failed | `references/failure-modes.md` |\n\n---\n\n# Bundled references\n\nThese references belong to the version-matched guide above. Read only the documents named by its action gates.\n\n\n\n# Local Docker over SSH\n\nLoad this when the environment is a local Docker container reached over SSH. It models an ephemeral\nSSH VM without cloud cost: build a base image with `sshd`, tools, repo prerequisites, and the agent\nCLI; run an interactive auth container once; then `docker commit` that container as the\nauthenticated image per-workspace `create` boots from. The emitted result is the SSH shape in\n`references/ssh-host.md`.\n\n- Publish container SSH to a random localhost port with `-p 127.0.0.1::22`, and emit\n `connection.type:\"ssh\"` with `host:\"127.0.0.1\"`, that port, `username`, `identityFile`, and\n `identitiesOnly:true`.\n- Generate a repo-local SSH key if needed, and gitignore the private and public key files.\n- Generate unique SSH host keys with `ssh-keygen -A` on each container's first start and retain\n them for that container's lifetime. Remove `/etc/ssh/ssh_host_*` from the base and auth images\n before reuse; never distribute one private host key across workspaces.\n- Before connecting, read the container's public host key through trusted local `docker exec` and\n record it under `[127.0.0.1]:` in the desktop's `known_hosts`. If a port was reused,\n replace only that endpoint's old entry after verifying the new container identity. Preserve\n entries for other workspaces; never disable host-key checking to bypass a mismatch.\n- The auth image is the Docker form of the agent-auth snapshot: the user runs the agent login inside\n the container, configures proxy env and config, approves hooks, and you commit once they report it\n finished.\n- Do not bind-mount or copy the host's full agent home into the image. Let each container keep\n writable agent state; only the committed auth image carries reusable authenticated state.\n- When committing from an interactive shell, force the runtime entrypoint back to `sshd`:\n `docker commit --change='ENTRYPOINT [\"/usr/local/bin/orca-docker-ssh-entrypoint\"]' …`.\n- `destroy` reads `recipeResult.userData.resourceId` and runs `docker rm -f \"$resource_id\"`.\n\n## Validation before wiring or live use\n\n```bash\ndocker image inspect \"$auth_image\" --format '{{json .Config.Entrypoint}}'\ndocker run -d --name \"$name\" -p 127.0.0.1::22 -e \"ORCA_SSH_PUBLIC_KEY=$pubkey\" \"$auth_image\"\ndocker ps -a --filter \"name=$name\"\ndocker logs \"$name\"\nssh -i \"$key\" -p \"$port\" -o IdentitiesOnly=yes -o StrictHostKeyChecking=yes user@127.0.0.1 'codex --version'\n```\n\nInspect the auth image entrypoint and do this startup-only `docker run` before the full clone and\ninstall path. If the container exits immediately, read its logs before the cleanup trap removes it;\nan image committed from an interactive shell with `ENTRYPOINT [\"bash\"]` is a common cause.\n\nValidate two containers: their public host keys must differ, and each must match its recorded\nendpoint before SSH succeeds. Restarting the same container preserves its key; reusing a deleted\ncontainer's port requires verifying and recording the replacement's key. Remove that endpoint's\nentry on destroy only if it still matches the destroyed container's recorded key.\n\n\n\n# Failure modes\n\nLoad this when a doctor, provision, clone, login, or snapshot step failed. Each entry maps a\nsymptom to its cause; the rule that prevents it lives in the guide next to the step.\n\n## Reading a failed `--provision` result\n\nThe JSON result carries a `provisionTranscript` with each stage's captured output, so you can\ndiagnose without asking the user for logs:\n\n```json\n{\n \"ok\": false,\n \"checks\": [{ \"id\": \"recipe.provision\", \"status\": \"fail\", \"message\": \"…\" }],\n \"provisionTranscript\": {\n \"provision\": { \"exitCode\": 0, \"signal\": null, \"stdout\": \"…\", \"stderr\": \"…\", \"parseError\": \"…\" },\n \"destroy\": { \"exitCode\": 0, \"signal\": null, \"stdout\": \"…\", \"stderr\": \"…\" }\n }\n}\n```\n\nStreams are redacted and capped at both ends, keeping the start and the failure. Two common reads:\n\n- A non-empty `stderr` with `exitCode 0` plus a `parseError` means `create` ran but printed something\n other than the single recipe-result JSON object on stdout. The offending stdout is in the\n transcript; the usual cause is a stray `echo`.\n- A non-zero `exitCode` is a provider or script failure, described in `stderr`.\n\n## Build and clone\n\n- **Build exceeds the plan timeout**, for example Vercel Hobby's 45 minutes. Use enough vCPUs and a\n timeout that covers the build, or split the work, or move to a higher plan. The same cap limits\n per-workspace runtime, so surface it to the user.\n- **Build exceeds plan RAM.** Building the headless main only, dropping the renderer, is the single\n biggest fit.\n- **Private-repo clone hangs or fails.** The token is wrong or missing. `GIT_ASKPASS` plus\n `GIT_TERMINAL_PROMPT=0` makes it fail fast instead of prompting.\n- **The `GIT_ASKPASS` helper aborts the clone with `$1: unbound variable`.** The `printf` or heredoc\n that wrote the helper inside `bash -lc` under `set -u` expanded `$1` and `$GH_TOKEN` at write time\n instead of leaving them for git-runtime. The same mistake writes the real token into the file.\n\n## Agent auth\n\n- **The agent verifies as \"not logged in\" despite a good login.** `codex login status` and similar\n print their success line to stderr, so a check that reads stdout only misses it.\n- **A headless agent login hangs.** Plain OAuth `login` started a loopback callback server on a port\n the host browser cannot reach.\n- **Agent auth did not persist.** Confirm `snapshotId` points at the authenticated snapshot rather\n than the base, and re-run the auth phase. If the agent's credentials are short-lived, the snapshot\n needs periodic re-auth; warn the user.\n- **Agent auth copied from the host breaks.** A bind-mounted or copied host agent home carries sqlite\n files that can be unwritable or host-specific, hooks that need approval again, and config that\n references local-only environment variables. Authenticate inside the runtime and snapshot or commit\n that layer instead.\n\n## Environment lifecycle\n\n- **`known_hosts` mismatch on local Docker.** A new container may reuse an old container's port.\n Read its public key through trusted local Docker access, verify the container identity, then\n replace only that endpoint's recorded key. Never reuse private host keys across workspace images.\n- **Snapshot expired or evicted.** `create` hit an unknown snapshot id. Re-run the base and auth\n snapshot phases and update `snapshotId` in state.\n- **Docker auth image exits immediately.** Read `docker image inspect … .Config.Entrypoint` and\n `docker logs`. An image committed from an interactive shell keeps that shell as its entrypoint.\n- **A paid resource leaked.** A long script created an environment and then failed without a trap\n that removes it.\n\n\n\n# Worked example — Vercel Sandbox\n\nLoad this when writing the base-snapshot, auth, or `create` script for a snapshot-capable cloud\nprovider. It fills section 7's skeletons with a real surface, `vercel sandbox\ncreate|exec|snapshot|remove`. Adapt the names and verify every flag against\n`vercel sandbox --help` for the user's CLI version.\n\nThis is the Orca-server connection mode: the recipe emits a pairing URL. If the user chose SSH in\nthe interview, use `references/ssh-host.md` instead.\n\n## Snapshot cleanup\n\nThe base and auth excerpts each belong to one `set -euo pipefail` script. Include this function\nin both scripts and arm the trap before creating their temporary sandbox. Keep it armed through\nverification, snapshot creation, and writing state; cleanup failure must remain visible.\n\nUse the guarded array expansion below so an empty `vercel_args` array works under `set -u`\non stock macOS Bash 3.2 while preserving each configured argument.\n\n```bash\ncleanup_snapshot() {\n snapshot_exit=$?\n trap - EXIT\n if ! vercel sandbox remove \"$1\" ${vercel_args[@]+\"${vercel_args[@]}\"} >&2; then\n echo \"Sandbox cleanup failed for $1; inspect and remove it before continuing\" >&2\n snapshot_exit=1\n fi\n exit \"$snapshot_exit\"\n}\n```\n\nUse fresh sandbox names for these scripts so cleanup cannot remove an existing environment.\n\n## Base snapshot\n\nProvision, install tools and clone, build headless, then snapshot.\n\n```bash\n# provision a fresh build sandbox (retain a couple of snapshots)\ntrap 'cleanup_snapshot \"$base\"' EXIT\nvercel sandbox create --name \"$base\" --runtime node24 --timeout 30m --vcpus 4 --publish-port \"$port\" \\\n --snapshot-expiration 30d --keep-last-snapshots 2 ${vercel_args[@]+\"${vercel_args[@]}\"} >&2\n# remote build (long timeout): install pkgs+gh+pnpm+agent CLI, clone with GIT_ASKPASS (the helper's\n# \\$1/\\$GH_TOKEN escaping is load-bearing — see the guide's Credentials section — then\n# `rm -f /tmp/askpass.sh`), write the headless main-only build config (drop the renderer), dev setup,\n# build CLI + headless main, smoke-check\nvercel sandbox exec \"$base\" ${vercel_args[@]+\"${vercel_args[@]}\"} --timeout 25m --env \"GH_TOKEN=$gh_token\" … -- bash -lc '…build…' >&2\n# snapshot the STOPPED sandbox and parse the id from CLI output (fail if unparseable)\nout=\"$(vercel sandbox snapshot \"$base\" --stop --expiration 30d ${vercel_args[@]+\"${vercel_args[@]}\"} 2>&1)\"; printf '%s\\n' \"$out\" >&2\nsnapshot_id=\"$(printf '%s\\n' \"$out\" | sed -nE 's/.*(snap_[A-Za-z0-9]+).*/\\1/p' | tail -1)\"\n[ -n \"$snapshot_id\" ] || { echo \"snapshot id missing\" >&2; exit 1; }\n# merge { baseName, snapshotId, scope, project, port, repoUrl, repoRef, projectRoot } into state; print state JSON\n```\n\n## Agent-auth snapshot\n\nBoot the base, let the user log the agent in, verify, then re-snapshot. `codex` here is an example;\nsubstitute the user's chosen agent's login and status verbs.\n\n```bash\ntrap 'cleanup_snapshot \"$auth\"' EXIT\nvercel sandbox create --name \"$auth\" --snapshot \"$snapshot_id\" --timeout 30m --publish-port \"$port\" ${vercel_args[@]+\"${vercel_args[@]}\"} >&2\n# The USER runs this in their own terminal and completes the URL/code on the HOST.\nvercel sandbox exec --interactive --tty \"$auth\" ${vercel_args[@]+\"${vercel_args[@]}\"} -- bash -lc 'codex login --device-auth'\n```\n\nVerify by exit code. The remote command prints a sentinel instead of relying on the exit code,\nbecause a provider CLI may not propagate remote exit codes:\n\n```bash\nverdict=\"$(vercel sandbox exec \"$auth\" ${vercel_args[@]+\"${vercel_args[@]}\"} --timeout 30s \\\n -- bash -lc 'if codex login status >/dev/null 2>&1; then echo ORCA_AGENT_LOGGED_IN; else echo ORCA_AGENT_LOGGED_OUT; fi')\"\ncase \"$verdict\" in\n *ORCA_AGENT_LOGGED_IN*) ;;\n *) echo \"agent not logged in; not snapshotting\" >&2; exit 1 ;;\nesac\n```\n\nFallback for an agent whose `status` exit code says nothing about auth: capture the output with\nstderr folded in and match the agent's exact success line. Match a variable, not a pipe, so the\nprovider process cannot take SIGPIPE:\n\n```bash\nstatus=\"$(vercel sandbox exec \"$auth\" ${vercel_args[@]+\"${vercel_args[@]}\"} --timeout 30s -- bash -lc 'codex login status 2>&1')\"\ngrep -Eq 'Logged in using ChatGPT|Logged in via device' <<<\"$status\" \\\n || { echo \"agent not logged in; not snapshotting\" >&2; exit 1; }\n```\n\nThen re-snapshot and record the new id:\n\n```bash\nout=\"$(vercel sandbox snapshot \"$auth\" --stop --expiration 30d ${vercel_args[@]+\"${vercel_args[@]}\"} 2>&1)\"; printf '%s\\n' \"$out\" >&2\nnew_id=\"$(printf '%s\\n' \"$out\" | sed -nE 's/.*(snap_[A-Za-z0-9]+).*/\\1/p' | tail -1)\"\n[ -n \"$new_id\" ] || { echo \"authenticated snapshot id missing\" >&2; exit 1; }\n# overwrite state.snapshotId = new_id, record authSourceSnapshotId = snapshot_id; remove the auth sandbox\n```\n\n## Per-workspace `create`\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\n# resolve from env→state→fallback: snapshot_id, scope, project, port, repo_url, repo_ref, project_root\nvercel_args=(); [ -n \"$scope\" ] && vercel_args+=(--scope \"$scope\"); [ -n \"$project\" ] && vercel_args+=(--project \"$project\")\n[ -n \"$snapshot_id\" ] || { echo \"snapshotId missing — build the base and auth snapshots first\" >&2; exit 1; }\ngh_token=\"${GH_TOKEN:-${GITHUB_TOKEN:-$(command -v gh >/dev/null 2>&1 && gh auth token 2>/dev/null || true)}}\"\nrecipe_id=\"${ORCA_RECIPE_ID:-vercel-sandbox}\"\nrecipe_id=\"${recipe_id//./-}\" # Vercel names forbid dots.\ninstance_id=\"${ORCA_VM_INSTANCE_ID:-$(date +%s)}\"\nmax_recipe_id_length=$((128 - ${#instance_id} - 6)) # Preserve the unique instance suffix.\n[ \"$max_recipe_id_length\" -gt 0 ] || { echo \"ORCA_VM_INSTANCE_ID is too long for a Vercel sandbox name\" >&2; exit 1; }\nname=\"orca-${recipe_id:0:max_recipe_id_length}-${instance_id}\"\n\n# Arm cleanup BEFORE create so a failing create can't leak a half-built paid sandbox.\ncleanup_on_error() { [ \"$?\" -ne 0 ] && vercel sandbox remove \"$name\" ${vercel_args[@]+\"${vercel_args[@]}\"} >/dev/null 2>&1 || true; }\ntrap cleanup_on_error EXIT\n\n# 1. boot from the authenticated snapshot, publish the serve port\ncreate_output=\"$(vercel sandbox create --name \"$name\" --snapshot \"$snapshot_id\" \\\n --timeout 30m --publish-port \"$port\" ${vercel_args[@]+\"${vercel_args[@]}\"} 2>&1)\"; printf '%s\\n' \"$create_output\" >&2\n# Vercel prints the published https URL; derive the external wss:// pairing address from it\npublic_url=\"$(printf '%s\\n' \"$create_output\" | sed -nE 's#.*(https://[^[:space:]]+\\.vercel\\.run).*#\\1#p' | head -1)\"\n[ -n \"$public_url\" ] || { echo \"no published URL in create output\" >&2; exit 1; }\npairing_ws=\"${public_url/https:\\/\\//wss://}\"\n\n# 2. (remote) ensure the repo is at the right commit; rebuild only if the commit changed (cache marker)\nvercel sandbox exec \"$name\" ${vercel_args[@]+\"${vercel_args[@]}\"} --timeout 20m \\\n --env \"GH_TOKEN=$gh_token\" --env \"ORCA_PROJECT_ROOT=$project_root\" \\\n --env \"ORCA_REPO_URL=$repo_url\" --env \"ORCA_REPO_REF=$repo_ref\" \\\n -- bash -lc 'set -euo pipefail; cd \"$ORCA_PROJECT_ROOT\"; \\\n export GIT_TERMINAL_PROMPT=0; \\\n # Escaping is load-bearing here: re-test the fetch after any edit to the nested quoting.\n if [ -n \"${GH_TOKEN:-}\" ]; then \\\n printf \"%s\\n\" \"#!/usr/bin/env bash\" \"case \\\"\\$1\\\" in *Username*) echo x-access-token;; *Password*) echo \\\"\\$GH_TOKEN\\\";; esac\" > /tmp/askpass.sh; \\\n chmod 700 /tmp/askpass.sh; export GIT_ASKPASS=/tmp/askpass.sh; fi; \\\n git fetch origin \"$ORCA_REPO_REF\"; \\\n git checkout -B \"$ORCA_REPO_REF\" FETCH_HEAD; \\\n rm -f /tmp/askpass.sh; \\\n c=\"$(git rev-parse HEAD)\"; [ -f .orca-built ] && [ \"$(cat .orca-built)\" = \"$c\" ] || { \\\n pnpm install --prefer-offline && pnpm run build:cli && \\\n node config/scripts/run-electron-vite-build.mjs --config config/electron-vite.vm-serve.config.ts && \\\n printf \"%s\" \"$c\" > .orca-built; }' >&2\n\n# 3. (remote) start orca serve in the background, writing recipe JSON to a file; poll until it parses\nrecipe_json=\"$(vercel sandbox exec \"$name\" ${vercel_args[@]+\"${vercel_args[@]}\"} --timeout 60s \\\n --env \"ORCA_PORT=$port\" --env \"ORCA_PROJECT_ROOT=$project_root\" --env \"ORCA_PAIRING_ADDRESS=$pairing_ws\" \\\n -- bash -lc 'set -euo pipefail; cd \"$ORCA_PROJECT_ROOT\"; rm -f /tmp/orca-recipe.json /tmp/orca-serve.log; \\\n nohup pnpm exec orca-dev serve --port \"$ORCA_PORT\" --project-root \"$ORCA_PROJECT_ROOT\" \\\n --pairing-address \"$ORCA_PAIRING_ADDRESS\" --recipe-json >/tmp/orca-recipe.json 2>/tmp/orca-serve.log /dev/null 2>&1 && { cat /tmp/orca-recipe.json; exit 0; }; \\\n kill -0 \"$pid\" 2>/dev/null || { cat /tmp/orca-serve.log >&2; exit 1; }; sleep 0.25; \\\n done; cat /tmp/orca-serve.log >&2; echo \"serve recipe JSON timed out\" >&2; exit 1')\"\n\n# 4. print serve's JSON enriched with userData (single object on stdout)\nnode -e 'const p=JSON.parse(process.argv[1]); console.log(JSON.stringify({...p, schemaVersion:1,\n userData:{...p.userData, provider:\"vercel-sandbox\", resourceId:process.argv[2], snapshotId:process.argv[3]}}))' \\\n \"$recipe_json\" \"$name\" \"$snapshot_id\"\ntrap - EXIT\n```\n\n`suspend`, `resume`, and `destroy` run `vercel sandbox stop|...|remove \"$resource_id\"`, reading\n`userData.resourceId` from the lifecycle payload on stdin.\n\nThe `128` in `max_recipe_id_length` is Vercel's sandbox name cap. Confirm it against\n`vercel sandbox create --help` or Vercel's docs for the user's CLI version before relying on it; a\nwrong cap silently truncates recipe ids in resource names.\n\n\n\n# SSH connection mode, including provisioned root\n\nLoad this when the recipe connects over SSH instead of starting `orca serve`, and when the user has\nexplicitly asked for `checkoutMode: provisioned-root`.\n\nSSH mode is a different shape, not the Orca-server templates relabeled. `create` runs no\n`orca serve` and emits no `pairingCode`. Orca connects over its SSH relay, brings up the git and\nfilesystem providers, and imports the repo. The script only readies the host and prints the SSH\ndetails Orca dials.\n\n## The result shape\n\nOrca rejects anything else. Required fields only; add optionals from the next section as the\nnetwork needs them.\n\n```json\n{\n \"schemaVersion\": 1,\n \"connection\": {\n \"type\": \"ssh\",\n \"projectRoot\": \"/abs/path/to/repo/on/host\",\n \"target\": {\n \"label\": \"my-box\",\n \"host\": \"192.0.2.10\",\n \"port\": 22,\n \"username\": \"ubuntu\"\n }\n }\n}\n```\n\n`label`, `host`, `port`, and `username` are required. `projectRoot` is an absolute path on the host.\n\n## Which optional `target` fields to set\n\nThese describe how the user's desktop reaches the box; there is no `orca serve` URL in SSH mode.\n\n- A public IP or DNS name, or a Tailscale or VPN address, is the `host`; the SSH port is `port`,\n usually 22.\n- Key auth sets `identityFile`. Add `\"identitiesOnly\": true` when the agent holds many keys.\n- A bastion is reached through one of two fields: `jumpHost` takes a `user@host` ProxyJump\n target, and `proxyCommand` takes a full command such as an access proxy. **Set one, never both.** The schema\n accepts both, and the two consumers then disagree: one pushes `-J` and `-o ProxyCommand=` into the\n same argv, the other resolves `proxyCommand` and ignores `jumpHost` entirely.\n- A service port the workspace needs is an entry in `portForwards`. Each entry requires\n `localPort`, `remoteHost`, and `remotePort`, and takes an optional `label`. The entry schema is\n strict, so an invented key such as `local` or `remote` fails validation.\n- `relayGracePeriodSeconds` bounds how long Orca keeps the SSH relay alive after the workspace\n detaches. **`0` means unbounded**: the relay stays up until something explicitly terminates it, so\n it is the wrong value for a disposable runtime. Any other value must be between 60 and 604800\n seconds. A value between 1 and 59, such as `30`, is rejected and takes the whole recipe result\n with it.\n Omit the field unless the user asked for a specific reconnect grace window.\n\n## Toolchain and agent auth on a persistent host\n\nA persistent host is its own base image. Run the install steps and the agent's device-auth login\nover SSH once, by hand, before wiring the recipe. The login is interactive, for example\n`ssh -t user@host ' login --device-auth'`, so the user runs it. The host then stays ready\nacross workspaces.\n\nUse Git credentials already configured on the SSH host. For GitHub HTTPS repos, verify `gh auth\nstatus` on that host and run `gh auth setup-git` there if Git has no credential helper. Installed\n`gh` alone is not authentication. SSH URLs use the host's SSH keys; other providers use their own\ncredential setup. If credentials are missing, have the user configure them on the host. Do not\nforward a desktop token in the SSH command.\n\nBefore the first connection, verify the host key using the provider console or another trusted\nchannel and record it in the desktop's `known_hosts`. Do not trust an unverified `ssh-keyscan`\nresult. The noninteractive script below refuses unknown or changed keys.\n\n## The create script\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\n# resolve from env→state→fallback (default unset optionals to \"\"): ssh_username, host,\n# ssh_port (default 22), identity_file, jump_host, proxy_command, project_root, repo_url, repo_ref\n: \"${identity_file:=}\"; : \"${jump_host:=}\"; : \"${proxy_command:=}\" # avoid set -u aborts on optionals\nssh_target=\"${ssh_username}@${host}\"\nif [ -n \"$jump_host\" ] && [ -n \"$proxy_command\" ]; then\n echo \"set jump_host or proxy_command, not both\" >&2; exit 1\nfi\nssh_opts=(-p \"$ssh_port\" -o BatchMode=yes -o StrictHostKeyChecking=yes)\n[ -n \"$identity_file\" ] && ssh_opts+=(-i \"$identity_file\")\n[ -n \"$jump_host\" ] && ssh_opts+=(-J \"$jump_host\")\n[ -n \"$proxy_command\" ] && ssh_opts+=(-o \"ProxyCommand=$proxy_command\")\n\n# 1. ensure the repo is present and at the right commit on the host (NO orca serve here).\n# printf %q quotes every value for the remote shell, so a space or quote in a path or\n# ref cannot break out of the command.\nremote_sync='set -euo pipefail\n export GIT_TERMINAL_PROMPT=0\n [ -d \"$project_root/.git\" ] || git clone \"$repo_url\" \"$project_root\"\n cd \"$project_root\" && git fetch origin \"$repo_ref\" && git checkout -B \"$repo_ref\" FETCH_HEAD'\nssh \"${ssh_opts[@]}\" \"$ssh_target\" \"$(printf \\\n 'project_root=%q repo_url=%q repo_ref=%q bash -lc %q' \\\n \"$project_root\" \"$repo_url\" \"$repo_ref\" \"$remote_sync\")\" >&2\n\n# 2. print the SSH connection block (NO pairingCode, NO orca serve). host/port/username tell Orca's\n# relay how to dial in; identityFile/jumpHost/proxyCommand/portForwards are emitted when set.\nnode -e 'const [host,port,user,idf,jh,pc,root]=process.argv.slice(1);\n const target={ label:\"per-workspace-host\", host, port:Number(port), username:user };\n if(idf) target.identityFile=idf; if(jh) target.jumpHost=jh; if(pc) target.proxyCommand=pc;\n // add target.portForwards=[{localPort,remoteHost,remotePort}] here if the workspace needs them\n console.log(JSON.stringify({ schemaVersion:1, connection:{ type:\"ssh\", projectRoot:root, target } }))' \\\n \"$host\" \"$ssh_port\" \"$ssh_username\" \"$identity_file\" \"$jump_host\" \"$proxy_command\" \"$project_root\"\n```\n\nOn a persistent host there is usually nothing to tear down, so set `destroy: none` and omit suspend\nand resume. Orca still disconnects and reconnects its own SSH relay on sleep, wake, and delete, which\nis separate from these scripts.\n\nIf the SSH host is instead an ephemeral, snapshot-capable VM — the user's hypervisor, or a cloud VM\nwith image support — keep the base-image model from `references/provider-vercel.md` for\nprovisioning, but still emit the `connection.type:\"ssh\"` block above instead of starting\n`orca serve`.\n\n## Provisioned root\n\nFor an explicitly requested one-VM-per-workspace checkout, the create script reads\n`ORCA_RECIPE_RESULT_SCHEMA_VERSION`, `ORCA_REPO_URL`, `ORCA_REPO_REF`, `ORCA_REPO_REF_HEAD`, and\n`ORCA_REPO_BRANCH`. Use `ORCA_REPO_REF` to fetch the selected source, but create `ORCA_REPO_BRANCH`\nat the exact `ORCA_REPO_REF_HEAD` commit, because resolving the symbolic ref again can race with an\nupstream update. `ORCA_REPO_URL` and `ORCA_REPO_REF` are a matched fetch pair, and the URL is the\nremote Orca resolved the base ref against, which is not necessarily named `origin` on the desktop.\nFetch from the URL the pair supplies:\n\n```bash\n[ -n \"${ORCA_REPO_REF_HEAD:-}\" ] || { echo \"missing pinned source commit\" >&2; exit 1; }\ngit fetch \"$ORCA_REPO_URL\" \"$ORCA_REPO_REF\"\ngit cat-file -e \"${ORCA_REPO_REF_HEAD}^{commit}\"\ngit checkout -B \"$ORCA_REPO_BRANCH\" \"$ORCA_REPO_REF_HEAD\"\n```\n\nReturn that primary checkout at `projectRoot` and emit schema version 2:\n\n```json\n{\n \"schemaVersion\": 2,\n \"checkoutMode\": \"provisioned-root\",\n \"connection\": {\n \"type\": \"ssh\",\n \"projectRoot\": \"/abs/repo\",\n \"target\": { \"label\": \"my-box\", \"host\": \"192.0.2.10\", \"port\": 22, \"username\": \"ubuntu\" }\n }\n}\n```\n\n## Before declaring an SSH recipe done\n\nThe `--provision` self-test only sees what the scripts print, so smoke-test the exact emitted target\nas well: dial the host and port with the identity or proxy settings, run `pwd`, verify the repo path,\nand check the agent binary. If the recipe created a provider resource, also confirm `destroy`\nremoves it.\n\n\n\n# Windows local-side scripts\n\nLoad this when the user's desktop is Windows and you are scaffolding the local-side scripts. A bare\n`.sh` will not execute there. Either require WSL or Git Bash and point `orca.yaml` at a launcher such\nas `bash ./scripts/orca-vm/.sh` through a `.cmd` file, or scaffold PowerShell equivalents.\n\nThe remote-side commands you run inside the Linux environment stay bash regardless of the desktop OS.\n\n```powershell\n#requires -Version 5\n$ErrorActionPreference = 'Stop'\n# resolve env→state→fallback; run the provider CLI / ssh the same way;\n# capture provider output; build the result object for the chosen mode and write ONE line of JSON to stdout.\n# Orca-server mode: @{ schemaVersion=1; pairingCode=$pairingCode; projectRoot=$projectRoot; userData=@{...} }\n# SSH mode: @{ schemaVersion=1; connection=@{ type=\"ssh\"; projectRoot=$projectRoot;\n# target=@{ label=$label; host=$host; port=$port; username=$user } } }\n($result | ConvertTo-Json -Compress -Depth 6)\n# progress/errors → Write-Error / the error stream, never stdout.\n```\n\nThe doctor's executable-bit check is a POSIX concept and is skipped on Windows, so a script that is\nunusable on the user's machine for a different reason still has to be caught by the `--provision`\nself-test.\n" // oxfmt-ignore const ORCA_PER_WORKSPACE_ENV_DOCKER_SSH_REFERENCE_MARKDOWN = "# Local Docker over SSH\n\nLoad this when the environment is a local Docker container reached over SSH. It models an ephemeral\nSSH VM without cloud cost: build a base image with `sshd`, tools, repo prerequisites, and the agent\nCLI; run an interactive auth container once; then `docker commit` that container as the\nauthenticated image per-workspace `create` boots from. The emitted result is the SSH shape in\n`references/ssh-host.md`.\n\n- Publish container SSH to a random localhost port with `-p 127.0.0.1::22`, and emit\n `connection.type:\"ssh\"` with `host:\"127.0.0.1\"`, that port, `username`, `identityFile`, and\n `identitiesOnly:true`.\n- Generate a repo-local SSH key if needed, and gitignore the private and public key files.\n- Generate unique SSH host keys with `ssh-keygen -A` on each container's first start and retain\n them for that container's lifetime. Remove `/etc/ssh/ssh_host_*` from the base and auth images\n before reuse; never distribute one private host key across workspaces.\n- Before connecting, read the container's public host key through trusted local `docker exec` and\n record it under `[127.0.0.1]:` in the desktop's `known_hosts`. If a port was reused,\n replace only that endpoint's old entry after verifying the new container identity. Preserve\n entries for other workspaces; never disable host-key checking to bypass a mismatch.\n- The auth image is the Docker form of the agent-auth snapshot: the user runs the agent login inside\n the container, configures proxy env and config, approves hooks, and you commit once they report it\n finished.\n- Do not bind-mount or copy the host's full agent home into the image. Let each container keep\n writable agent state; only the committed auth image carries reusable authenticated state.\n- When committing from an interactive shell, force the runtime entrypoint back to `sshd`:\n `docker commit --change='ENTRYPOINT [\"/usr/local/bin/orca-docker-ssh-entrypoint\"]' …`.\n- `destroy` reads `recipeResult.userData.resourceId` and runs `docker rm -f \"$resource_id\"`.\n\n## Validation before wiring or live use\n\n```bash\ndocker image inspect \"$auth_image\" --format '{{json .Config.Entrypoint}}'\ndocker run -d --name \"$name\" -p 127.0.0.1::22 -e \"ORCA_SSH_PUBLIC_KEY=$pubkey\" \"$auth_image\"\ndocker ps -a --filter \"name=$name\"\ndocker logs \"$name\"\nssh -i \"$key\" -p \"$port\" -o IdentitiesOnly=yes -o StrictHostKeyChecking=yes user@127.0.0.1 'codex --version'\n```\n\nInspect the auth image entrypoint and do this startup-only `docker run` before the full clone and\ninstall path. If the container exits immediately, read its logs before the cleanup trap removes it;\nan image committed from an interactive shell with `ENTRYPOINT [\"bash\"]` is a common cause.\n\nValidate two containers: their public host keys must differ, and each must match its recorded\nendpoint before SSH succeeds. Restarting the same container preserves its key; reusing a deleted\ncontainer's port requires verifying and recording the replacement's key. Remove that endpoint's\nentry on destroy only if it still matches the destroyed container's recorded key.\n" @@ -57,7 +57,7 @@ const ORCA_PER_WORKSPACE_ENV_DOCKER_SSH_REFERENCE_MARKDOWN = "# Local Docker ove const ORCA_PER_WORKSPACE_ENV_FAILURE_MODES_REFERENCE_MARKDOWN = "# Failure modes\n\nLoad this when a doctor, provision, clone, login, or snapshot step failed. Each entry maps a\nsymptom to its cause; the rule that prevents it lives in the guide next to the step.\n\n## Reading a failed `--provision` result\n\nThe JSON result carries a `provisionTranscript` with each stage's captured output, so you can\ndiagnose without asking the user for logs:\n\n```json\n{\n \"ok\": false,\n \"checks\": [{ \"id\": \"recipe.provision\", \"status\": \"fail\", \"message\": \"…\" }],\n \"provisionTranscript\": {\n \"provision\": { \"exitCode\": 0, \"signal\": null, \"stdout\": \"…\", \"stderr\": \"…\", \"parseError\": \"…\" },\n \"destroy\": { \"exitCode\": 0, \"signal\": null, \"stdout\": \"…\", \"stderr\": \"…\" }\n }\n}\n```\n\nStreams are redacted and capped at both ends, keeping the start and the failure. Two common reads:\n\n- A non-empty `stderr` with `exitCode 0` plus a `parseError` means `create` ran but printed something\n other than the single recipe-result JSON object on stdout. The offending stdout is in the\n transcript; the usual cause is a stray `echo`.\n- A non-zero `exitCode` is a provider or script failure, described in `stderr`.\n\n## Build and clone\n\n- **Build exceeds the plan timeout**, for example Vercel Hobby's 45 minutes. Use enough vCPUs and a\n timeout that covers the build, or split the work, or move to a higher plan. The same cap limits\n per-workspace runtime, so surface it to the user.\n- **Build exceeds plan RAM.** Building the headless main only, dropping the renderer, is the single\n biggest fit.\n- **Private-repo clone hangs or fails.** The token is wrong or missing. `GIT_ASKPASS` plus\n `GIT_TERMINAL_PROMPT=0` makes it fail fast instead of prompting.\n- **The `GIT_ASKPASS` helper aborts the clone with `$1: unbound variable`.** The `printf` or heredoc\n that wrote the helper inside `bash -lc` under `set -u` expanded `$1` and `$GH_TOKEN` at write time\n instead of leaving them for git-runtime. The same mistake writes the real token into the file.\n\n## Agent auth\n\n- **The agent verifies as \"not logged in\" despite a good login.** `codex login status` and similar\n print their success line to stderr, so a check that reads stdout only misses it.\n- **A headless agent login hangs.** Plain OAuth `login` started a loopback callback server on a port\n the host browser cannot reach.\n- **Agent auth did not persist.** Confirm `snapshotId` points at the authenticated snapshot rather\n than the base, and re-run the auth phase. If the agent's credentials are short-lived, the snapshot\n needs periodic re-auth; warn the user.\n- **Agent auth copied from the host breaks.** A bind-mounted or copied host agent home carries sqlite\n files that can be unwritable or host-specific, hooks that need approval again, and config that\n references local-only environment variables. Authenticate inside the runtime and snapshot or commit\n that layer instead.\n\n## Environment lifecycle\n\n- **`known_hosts` mismatch on local Docker.** A new container may reuse an old container's port.\n Read its public key through trusted local Docker access, verify the container identity, then\n replace only that endpoint's recorded key. Never reuse private host keys across workspace images.\n- **Snapshot expired or evicted.** `create` hit an unknown snapshot id. Re-run the base and auth\n snapshot phases and update `snapshotId` in state.\n- **Docker auth image exits immediately.** Read `docker image inspect … .Config.Entrypoint` and\n `docker logs`. An image committed from an interactive shell keeps that shell as its entrypoint.\n- **A paid resource leaked.** A long script created an environment and then failed without a trap\n that removes it.\n" // oxfmt-ignore -const ORCA_PER_WORKSPACE_ENV_PROVIDER_VERCEL_REFERENCE_MARKDOWN = "# Worked example — Vercel Sandbox\n\nLoad this when writing the base-snapshot, auth, or `create` script for a snapshot-capable cloud\nprovider. It fills section 7's skeletons with a real surface, `vercel sandbox\ncreate|exec|snapshot|remove`. Adapt the names and verify every flag against\n`vercel sandbox --help` for the user's CLI version.\n\nThis is the Orca-server connection mode: the recipe emits a pairing URL. If the user chose SSH in\nthe interview, use `references/ssh-host.md` instead.\n\n## Snapshot cleanup\n\nThe base and auth excerpts each belong to one `set -euo pipefail` script. Include this function\nin both scripts and arm the trap before creating their temporary sandbox. Keep it armed through\nverification, snapshot creation, and writing state; cleanup failure must remain visible.\n\n```bash\ncleanup_snapshot() {\n snapshot_exit=$?\n trap - EXIT\n if ! vercel sandbox remove \"$1\" \"${vercel_args[@]}\" >&2; then\n echo \"Sandbox cleanup failed for $1; inspect and remove it before continuing\" >&2\n snapshot_exit=1\n fi\n exit \"$snapshot_exit\"\n}\n```\n\nUse fresh sandbox names for these scripts so cleanup cannot remove an existing environment.\n\n## Base snapshot\n\nProvision, install tools and clone, build headless, then snapshot.\n\n```bash\n# provision a fresh build sandbox (retain a couple of snapshots)\ntrap 'cleanup_snapshot \"$base\"' EXIT\nvercel sandbox create --name \"$base\" --runtime node24 --timeout 30m --vcpus 4 --publish-port \"$port\" \\\n --snapshot-expiration 30d --keep-last-snapshots 2 \"${vercel_args[@]}\" >&2\n# remote build (long timeout): install pkgs+gh+pnpm+agent CLI, clone with GIT_ASKPASS (the helper's\n# \\$1/\\$GH_TOKEN escaping is load-bearing — see the guide's Credentials section — then\n# `rm -f /tmp/askpass.sh`), write the headless main-only build config (drop the renderer), dev setup,\n# build CLI + headless main, smoke-check\nvercel sandbox exec \"$base\" \"${vercel_args[@]}\" --timeout 25m --env \"GH_TOKEN=$gh_token\" … -- bash -lc '…build…' >&2\n# snapshot the STOPPED sandbox and parse the id from CLI output (fail if unparseable)\nout=\"$(vercel sandbox snapshot \"$base\" --stop --expiration 30d \"${vercel_args[@]}\" 2>&1)\"; printf '%s\\n' \"$out\" >&2\nsnapshot_id=\"$(printf '%s\\n' \"$out\" | sed -nE 's/.*(snap_[A-Za-z0-9]+).*/\\1/p' | tail -1)\"\n[ -n \"$snapshot_id\" ] || { echo \"snapshot id missing\" >&2; exit 1; }\n# merge { baseName, snapshotId, scope, project, port, repoUrl, repoRef, projectRoot } into state; print state JSON\n```\n\n## Agent-auth snapshot\n\nBoot the base, let the user log the agent in, verify, then re-snapshot. `codex` here is an example;\nsubstitute the user's chosen agent's login and status verbs.\n\n```bash\ntrap 'cleanup_snapshot \"$auth\"' EXIT\nvercel sandbox create --name \"$auth\" --snapshot \"$snapshot_id\" --timeout 30m --publish-port \"$port\" \"${vercel_args[@]}\" >&2\n# The USER runs this in their own terminal and completes the URL/code on the HOST.\nvercel sandbox exec --interactive --tty \"$auth\" \"${vercel_args[@]}\" -- bash -lc 'codex login --device-auth'\n```\n\nVerify by exit code. The remote command prints a sentinel instead of relying on the exit code,\nbecause a provider CLI may not propagate remote exit codes:\n\n```bash\nverdict=\"$(vercel sandbox exec \"$auth\" \"${vercel_args[@]}\" --timeout 30s \\\n -- bash -lc 'if codex login status >/dev/null 2>&1; then echo ORCA_AGENT_LOGGED_IN; else echo ORCA_AGENT_LOGGED_OUT; fi')\"\ncase \"$verdict\" in\n *ORCA_AGENT_LOGGED_IN*) ;;\n *) echo \"agent not logged in; not snapshotting\" >&2; exit 1 ;;\nesac\n```\n\nFallback for an agent whose `status` exit code says nothing about auth: capture the output with\nstderr folded in and match the agent's exact success line. Match a variable, not a pipe, so the\nprovider process cannot take SIGPIPE:\n\n```bash\nstatus=\"$(vercel sandbox exec \"$auth\" \"${vercel_args[@]}\" --timeout 30s -- bash -lc 'codex login status 2>&1')\"\ngrep -Eq 'Logged in using ChatGPT|Logged in via device' <<<\"$status\" \\\n || { echo \"agent not logged in; not snapshotting\" >&2; exit 1; }\n```\n\nThen re-snapshot and record the new id:\n\n```bash\nout=\"$(vercel sandbox snapshot \"$auth\" --stop --expiration 30d \"${vercel_args[@]}\" 2>&1)\"; printf '%s\\n' \"$out\" >&2\nnew_id=\"$(printf '%s\\n' \"$out\" | sed -nE 's/.*(snap_[A-Za-z0-9]+).*/\\1/p' | tail -1)\"\n[ -n \"$new_id\" ] || { echo \"authenticated snapshot id missing\" >&2; exit 1; }\n# overwrite state.snapshotId = new_id, record authSourceSnapshotId = snapshot_id; remove the auth sandbox\n```\n\n## Per-workspace `create`\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\n# resolve from env→state→fallback: snapshot_id, scope, project, port, repo_url, repo_ref, project_root\nvercel_args=(); [ -n \"$scope\" ] && vercel_args+=(--scope \"$scope\"); [ -n \"$project\" ] && vercel_args+=(--project \"$project\")\n[ -n \"$snapshot_id\" ] || { echo \"snapshotId missing — build the base and auth snapshots first\" >&2; exit 1; }\ngh_token=\"${GH_TOKEN:-${GITHUB_TOKEN:-$(command -v gh >/dev/null 2>&1 && gh auth token 2>/dev/null || true)}}\"\nrecipe_id=\"${ORCA_RECIPE_ID:-vercel-sandbox}\"\nrecipe_id=\"${recipe_id//./-}\" # Vercel names forbid dots.\ninstance_id=\"${ORCA_VM_INSTANCE_ID:-$(date +%s)}\"\nmax_recipe_id_length=$((128 - ${#instance_id} - 6)) # Preserve the unique instance suffix.\n[ \"$max_recipe_id_length\" -gt 0 ] || { echo \"ORCA_VM_INSTANCE_ID is too long for a Vercel sandbox name\" >&2; exit 1; }\nname=\"orca-${recipe_id:0:max_recipe_id_length}-${instance_id}\"\n\n# Arm cleanup BEFORE create so a failing create can't leak a half-built paid sandbox.\ncleanup_on_error() { [ \"$?\" -ne 0 ] && vercel sandbox remove \"$name\" \"${vercel_args[@]}\" >/dev/null 2>&1 || true; }\ntrap cleanup_on_error EXIT\n\n# 1. boot from the authenticated snapshot, publish the serve port\ncreate_output=\"$(vercel sandbox create --name \"$name\" --snapshot \"$snapshot_id\" \\\n --timeout 30m --publish-port \"$port\" \"${vercel_args[@]}\" 2>&1)\"; printf '%s\\n' \"$create_output\" >&2\n# Vercel prints the published https URL; derive the external wss:// pairing address from it\npublic_url=\"$(printf '%s\\n' \"$create_output\" | sed -nE 's#.*(https://[^[:space:]]+\\.vercel\\.run).*#\\1#p' | head -1)\"\n[ -n \"$public_url\" ] || { echo \"no published URL in create output\" >&2; exit 1; }\npairing_ws=\"${public_url/https:\\/\\//wss://}\"\n\n# 2. (remote) ensure the repo is at the right commit; rebuild only if the commit changed (cache marker)\nvercel sandbox exec \"$name\" \"${vercel_args[@]}\" --timeout 20m \\\n --env \"GH_TOKEN=$gh_token\" --env \"ORCA_PROJECT_ROOT=$project_root\" \\\n --env \"ORCA_REPO_URL=$repo_url\" --env \"ORCA_REPO_REF=$repo_ref\" \\\n -- bash -lc 'set -euo pipefail; cd \"$ORCA_PROJECT_ROOT\"; \\\n export GIT_TERMINAL_PROMPT=0; \\\n # Escaping is load-bearing here: re-test the fetch after any edit to the nested quoting.\n if [ -n \"${GH_TOKEN:-}\" ]; then \\\n printf \"%s\\n\" \"#!/usr/bin/env bash\" \"case \\\"\\$1\\\" in *Username*) echo x-access-token;; *Password*) echo \\\"\\$GH_TOKEN\\\";; esac\" > /tmp/askpass.sh; \\\n chmod 700 /tmp/askpass.sh; export GIT_ASKPASS=/tmp/askpass.sh; fi; \\\n git fetch origin \"$ORCA_REPO_REF\"; \\\n git checkout -B \"$ORCA_REPO_REF\" FETCH_HEAD; \\\n rm -f /tmp/askpass.sh; \\\n c=\"$(git rev-parse HEAD)\"; [ -f .orca-built ] && [ \"$(cat .orca-built)\" = \"$c\" ] || { \\\n pnpm install --prefer-offline && pnpm run build:cli && \\\n node config/scripts/run-electron-vite-build.mjs --config config/electron-vite.vm-serve.config.ts && \\\n printf \"%s\" \"$c\" > .orca-built; }' >&2\n\n# 3. (remote) start orca serve in the background, writing recipe JSON to a file; poll until it parses\nrecipe_json=\"$(vercel sandbox exec \"$name\" \"${vercel_args[@]}\" --timeout 60s \\\n --env \"ORCA_PORT=$port\" --env \"ORCA_PROJECT_ROOT=$project_root\" --env \"ORCA_PAIRING_ADDRESS=$pairing_ws\" \\\n -- bash -lc 'set -euo pipefail; cd \"$ORCA_PROJECT_ROOT\"; rm -f /tmp/orca-recipe.json /tmp/orca-serve.log; \\\n nohup pnpm exec orca-dev serve --port \"$ORCA_PORT\" --project-root \"$ORCA_PROJECT_ROOT\" \\\n --pairing-address \"$ORCA_PAIRING_ADDRESS\" --recipe-json >/tmp/orca-recipe.json 2>/tmp/orca-serve.log /dev/null 2>&1 && { cat /tmp/orca-recipe.json; exit 0; }; \\\n kill -0 \"$pid\" 2>/dev/null || { cat /tmp/orca-serve.log >&2; exit 1; }; sleep 0.25; \\\n done; cat /tmp/orca-serve.log >&2; echo \"serve recipe JSON timed out\" >&2; exit 1')\"\n\n# 4. print serve's JSON enriched with userData (single object on stdout)\nnode -e 'const p=JSON.parse(process.argv[1]); console.log(JSON.stringify({...p, schemaVersion:1,\n userData:{...p.userData, provider:\"vercel-sandbox\", resourceId:process.argv[2], snapshotId:process.argv[3]}}))' \\\n \"$recipe_json\" \"$name\" \"$snapshot_id\"\ntrap - EXIT\n```\n\n`suspend`, `resume`, and `destroy` run `vercel sandbox stop|...|remove \"$resource_id\"`, reading\n`userData.resourceId` from the lifecycle payload on stdin.\n\nThe `128` in `max_recipe_id_length` is Vercel's sandbox name cap. Confirm it against\n`vercel sandbox create --help` or Vercel's docs for the user's CLI version before relying on it; a\nwrong cap silently truncates recipe ids in resource names.\n" +const ORCA_PER_WORKSPACE_ENV_PROVIDER_VERCEL_REFERENCE_MARKDOWN = "# Worked example — Vercel Sandbox\n\nLoad this when writing the base-snapshot, auth, or `create` script for a snapshot-capable cloud\nprovider. It fills section 7's skeletons with a real surface, `vercel sandbox\ncreate|exec|snapshot|remove`. Adapt the names and verify every flag against\n`vercel sandbox --help` for the user's CLI version.\n\nThis is the Orca-server connection mode: the recipe emits a pairing URL. If the user chose SSH in\nthe interview, use `references/ssh-host.md` instead.\n\n## Snapshot cleanup\n\nThe base and auth excerpts each belong to one `set -euo pipefail` script. Include this function\nin both scripts and arm the trap before creating their temporary sandbox. Keep it armed through\nverification, snapshot creation, and writing state; cleanup failure must remain visible.\n\nUse the guarded array expansion below so an empty `vercel_args` array works under `set -u`\non stock macOS Bash 3.2 while preserving each configured argument.\n\n```bash\ncleanup_snapshot() {\n snapshot_exit=$?\n trap - EXIT\n if ! vercel sandbox remove \"$1\" ${vercel_args[@]+\"${vercel_args[@]}\"} >&2; then\n echo \"Sandbox cleanup failed for $1; inspect and remove it before continuing\" >&2\n snapshot_exit=1\n fi\n exit \"$snapshot_exit\"\n}\n```\n\nUse fresh sandbox names for these scripts so cleanup cannot remove an existing environment.\n\n## Base snapshot\n\nProvision, install tools and clone, build headless, then snapshot.\n\n```bash\n# provision a fresh build sandbox (retain a couple of snapshots)\ntrap 'cleanup_snapshot \"$base\"' EXIT\nvercel sandbox create --name \"$base\" --runtime node24 --timeout 30m --vcpus 4 --publish-port \"$port\" \\\n --snapshot-expiration 30d --keep-last-snapshots 2 ${vercel_args[@]+\"${vercel_args[@]}\"} >&2\n# remote build (long timeout): install pkgs+gh+pnpm+agent CLI, clone with GIT_ASKPASS (the helper's\n# \\$1/\\$GH_TOKEN escaping is load-bearing — see the guide's Credentials section — then\n# `rm -f /tmp/askpass.sh`), write the headless main-only build config (drop the renderer), dev setup,\n# build CLI + headless main, smoke-check\nvercel sandbox exec \"$base\" ${vercel_args[@]+\"${vercel_args[@]}\"} --timeout 25m --env \"GH_TOKEN=$gh_token\" … -- bash -lc '…build…' >&2\n# snapshot the STOPPED sandbox and parse the id from CLI output (fail if unparseable)\nout=\"$(vercel sandbox snapshot \"$base\" --stop --expiration 30d ${vercel_args[@]+\"${vercel_args[@]}\"} 2>&1)\"; printf '%s\\n' \"$out\" >&2\nsnapshot_id=\"$(printf '%s\\n' \"$out\" | sed -nE 's/.*(snap_[A-Za-z0-9]+).*/\\1/p' | tail -1)\"\n[ -n \"$snapshot_id\" ] || { echo \"snapshot id missing\" >&2; exit 1; }\n# merge { baseName, snapshotId, scope, project, port, repoUrl, repoRef, projectRoot } into state; print state JSON\n```\n\n## Agent-auth snapshot\n\nBoot the base, let the user log the agent in, verify, then re-snapshot. `codex` here is an example;\nsubstitute the user's chosen agent's login and status verbs.\n\n```bash\ntrap 'cleanup_snapshot \"$auth\"' EXIT\nvercel sandbox create --name \"$auth\" --snapshot \"$snapshot_id\" --timeout 30m --publish-port \"$port\" ${vercel_args[@]+\"${vercel_args[@]}\"} >&2\n# The USER runs this in their own terminal and completes the URL/code on the HOST.\nvercel sandbox exec --interactive --tty \"$auth\" ${vercel_args[@]+\"${vercel_args[@]}\"} -- bash -lc 'codex login --device-auth'\n```\n\nVerify by exit code. The remote command prints a sentinel instead of relying on the exit code,\nbecause a provider CLI may not propagate remote exit codes:\n\n```bash\nverdict=\"$(vercel sandbox exec \"$auth\" ${vercel_args[@]+\"${vercel_args[@]}\"} --timeout 30s \\\n -- bash -lc 'if codex login status >/dev/null 2>&1; then echo ORCA_AGENT_LOGGED_IN; else echo ORCA_AGENT_LOGGED_OUT; fi')\"\ncase \"$verdict\" in\n *ORCA_AGENT_LOGGED_IN*) ;;\n *) echo \"agent not logged in; not snapshotting\" >&2; exit 1 ;;\nesac\n```\n\nFallback for an agent whose `status` exit code says nothing about auth: capture the output with\nstderr folded in and match the agent's exact success line. Match a variable, not a pipe, so the\nprovider process cannot take SIGPIPE:\n\n```bash\nstatus=\"$(vercel sandbox exec \"$auth\" ${vercel_args[@]+\"${vercel_args[@]}\"} --timeout 30s -- bash -lc 'codex login status 2>&1')\"\ngrep -Eq 'Logged in using ChatGPT|Logged in via device' <<<\"$status\" \\\n || { echo \"agent not logged in; not snapshotting\" >&2; exit 1; }\n```\n\nThen re-snapshot and record the new id:\n\n```bash\nout=\"$(vercel sandbox snapshot \"$auth\" --stop --expiration 30d ${vercel_args[@]+\"${vercel_args[@]}\"} 2>&1)\"; printf '%s\\n' \"$out\" >&2\nnew_id=\"$(printf '%s\\n' \"$out\" | sed -nE 's/.*(snap_[A-Za-z0-9]+).*/\\1/p' | tail -1)\"\n[ -n \"$new_id\" ] || { echo \"authenticated snapshot id missing\" >&2; exit 1; }\n# overwrite state.snapshotId = new_id, record authSourceSnapshotId = snapshot_id; remove the auth sandbox\n```\n\n## Per-workspace `create`\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\n# resolve from env→state→fallback: snapshot_id, scope, project, port, repo_url, repo_ref, project_root\nvercel_args=(); [ -n \"$scope\" ] && vercel_args+=(--scope \"$scope\"); [ -n \"$project\" ] && vercel_args+=(--project \"$project\")\n[ -n \"$snapshot_id\" ] || { echo \"snapshotId missing — build the base and auth snapshots first\" >&2; exit 1; }\ngh_token=\"${GH_TOKEN:-${GITHUB_TOKEN:-$(command -v gh >/dev/null 2>&1 && gh auth token 2>/dev/null || true)}}\"\nrecipe_id=\"${ORCA_RECIPE_ID:-vercel-sandbox}\"\nrecipe_id=\"${recipe_id//./-}\" # Vercel names forbid dots.\ninstance_id=\"${ORCA_VM_INSTANCE_ID:-$(date +%s)}\"\nmax_recipe_id_length=$((128 - ${#instance_id} - 6)) # Preserve the unique instance suffix.\n[ \"$max_recipe_id_length\" -gt 0 ] || { echo \"ORCA_VM_INSTANCE_ID is too long for a Vercel sandbox name\" >&2; exit 1; }\nname=\"orca-${recipe_id:0:max_recipe_id_length}-${instance_id}\"\n\n# Arm cleanup BEFORE create so a failing create can't leak a half-built paid sandbox.\ncleanup_on_error() { [ \"$?\" -ne 0 ] && vercel sandbox remove \"$name\" ${vercel_args[@]+\"${vercel_args[@]}\"} >/dev/null 2>&1 || true; }\ntrap cleanup_on_error EXIT\n\n# 1. boot from the authenticated snapshot, publish the serve port\ncreate_output=\"$(vercel sandbox create --name \"$name\" --snapshot \"$snapshot_id\" \\\n --timeout 30m --publish-port \"$port\" ${vercel_args[@]+\"${vercel_args[@]}\"} 2>&1)\"; printf '%s\\n' \"$create_output\" >&2\n# Vercel prints the published https URL; derive the external wss:// pairing address from it\npublic_url=\"$(printf '%s\\n' \"$create_output\" | sed -nE 's#.*(https://[^[:space:]]+\\.vercel\\.run).*#\\1#p' | head -1)\"\n[ -n \"$public_url\" ] || { echo \"no published URL in create output\" >&2; exit 1; }\npairing_ws=\"${public_url/https:\\/\\//wss://}\"\n\n# 2. (remote) ensure the repo is at the right commit; rebuild only if the commit changed (cache marker)\nvercel sandbox exec \"$name\" ${vercel_args[@]+\"${vercel_args[@]}\"} --timeout 20m \\\n --env \"GH_TOKEN=$gh_token\" --env \"ORCA_PROJECT_ROOT=$project_root\" \\\n --env \"ORCA_REPO_URL=$repo_url\" --env \"ORCA_REPO_REF=$repo_ref\" \\\n -- bash -lc 'set -euo pipefail; cd \"$ORCA_PROJECT_ROOT\"; \\\n export GIT_TERMINAL_PROMPT=0; \\\n # Escaping is load-bearing here: re-test the fetch after any edit to the nested quoting.\n if [ -n \"${GH_TOKEN:-}\" ]; then \\\n printf \"%s\\n\" \"#!/usr/bin/env bash\" \"case \\\"\\$1\\\" in *Username*) echo x-access-token;; *Password*) echo \\\"\\$GH_TOKEN\\\";; esac\" > /tmp/askpass.sh; \\\n chmod 700 /tmp/askpass.sh; export GIT_ASKPASS=/tmp/askpass.sh; fi; \\\n git fetch origin \"$ORCA_REPO_REF\"; \\\n git checkout -B \"$ORCA_REPO_REF\" FETCH_HEAD; \\\n rm -f /tmp/askpass.sh; \\\n c=\"$(git rev-parse HEAD)\"; [ -f .orca-built ] && [ \"$(cat .orca-built)\" = \"$c\" ] || { \\\n pnpm install --prefer-offline && pnpm run build:cli && \\\n node config/scripts/run-electron-vite-build.mjs --config config/electron-vite.vm-serve.config.ts && \\\n printf \"%s\" \"$c\" > .orca-built; }' >&2\n\n# 3. (remote) start orca serve in the background, writing recipe JSON to a file; poll until it parses\nrecipe_json=\"$(vercel sandbox exec \"$name\" ${vercel_args[@]+\"${vercel_args[@]}\"} --timeout 60s \\\n --env \"ORCA_PORT=$port\" --env \"ORCA_PROJECT_ROOT=$project_root\" --env \"ORCA_PAIRING_ADDRESS=$pairing_ws\" \\\n -- bash -lc 'set -euo pipefail; cd \"$ORCA_PROJECT_ROOT\"; rm -f /tmp/orca-recipe.json /tmp/orca-serve.log; \\\n nohup pnpm exec orca-dev serve --port \"$ORCA_PORT\" --project-root \"$ORCA_PROJECT_ROOT\" \\\n --pairing-address \"$ORCA_PAIRING_ADDRESS\" --recipe-json >/tmp/orca-recipe.json 2>/tmp/orca-serve.log /dev/null 2>&1 && { cat /tmp/orca-recipe.json; exit 0; }; \\\n kill -0 \"$pid\" 2>/dev/null || { cat /tmp/orca-serve.log >&2; exit 1; }; sleep 0.25; \\\n done; cat /tmp/orca-serve.log >&2; echo \"serve recipe JSON timed out\" >&2; exit 1')\"\n\n# 4. print serve's JSON enriched with userData (single object on stdout)\nnode -e 'const p=JSON.parse(process.argv[1]); console.log(JSON.stringify({...p, schemaVersion:1,\n userData:{...p.userData, provider:\"vercel-sandbox\", resourceId:process.argv[2], snapshotId:process.argv[3]}}))' \\\n \"$recipe_json\" \"$name\" \"$snapshot_id\"\ntrap - EXIT\n```\n\n`suspend`, `resume`, and `destroy` run `vercel sandbox stop|...|remove \"$resource_id\"`, reading\n`userData.resourceId` from the lifecycle payload on stdin.\n\nThe `128` in `max_recipe_id_length` is Vercel's sandbox name cap. Confirm it against\n`vercel sandbox create --help` or Vercel's docs for the user's CLI version before relying on it; a\nwrong cap silently truncates recipe ids in resource names.\n" // oxfmt-ignore const ORCA_PER_WORKSPACE_ENV_SSH_HOST_REFERENCE_MARKDOWN = "# SSH connection mode, including provisioned root\n\nLoad this when the recipe connects over SSH instead of starting `orca serve`, and when the user has\nexplicitly asked for `checkoutMode: provisioned-root`.\n\nSSH mode is a different shape, not the Orca-server templates relabeled. `create` runs no\n`orca serve` and emits no `pairingCode`. Orca connects over its SSH relay, brings up the git and\nfilesystem providers, and imports the repo. The script only readies the host and prints the SSH\ndetails Orca dials.\n\n## The result shape\n\nOrca rejects anything else. Required fields only; add optionals from the next section as the\nnetwork needs them.\n\n```json\n{\n \"schemaVersion\": 1,\n \"connection\": {\n \"type\": \"ssh\",\n \"projectRoot\": \"/abs/path/to/repo/on/host\",\n \"target\": {\n \"label\": \"my-box\",\n \"host\": \"192.0.2.10\",\n \"port\": 22,\n \"username\": \"ubuntu\"\n }\n }\n}\n```\n\n`label`, `host`, `port`, and `username` are required. `projectRoot` is an absolute path on the host.\n\n## Which optional `target` fields to set\n\nThese describe how the user's desktop reaches the box; there is no `orca serve` URL in SSH mode.\n\n- A public IP or DNS name, or a Tailscale or VPN address, is the `host`; the SSH port is `port`,\n usually 22.\n- Key auth sets `identityFile`. Add `\"identitiesOnly\": true` when the agent holds many keys.\n- A bastion is reached through one of two fields: `jumpHost` takes a `user@host` ProxyJump\n target, and `proxyCommand` takes a full command such as an access proxy. **Set one, never both.** The schema\n accepts both, and the two consumers then disagree: one pushes `-J` and `-o ProxyCommand=` into the\n same argv, the other resolves `proxyCommand` and ignores `jumpHost` entirely.\n- A service port the workspace needs is an entry in `portForwards`. Each entry requires\n `localPort`, `remoteHost`, and `remotePort`, and takes an optional `label`. The entry schema is\n strict, so an invented key such as `local` or `remote` fails validation.\n- `relayGracePeriodSeconds` bounds how long Orca keeps the SSH relay alive after the workspace\n detaches. **`0` means unbounded**: the relay stays up until something explicitly terminates it, so\n it is the wrong value for a disposable runtime. Any other value must be between 60 and 604800\n seconds. A value between 1 and 59, such as `30`, is rejected and takes the whole recipe result\n with it.\n Omit the field unless the user asked for a specific reconnect grace window.\n\n## Toolchain and agent auth on a persistent host\n\nA persistent host is its own base image. Run the install steps and the agent's device-auth login\nover SSH once, by hand, before wiring the recipe. The login is interactive, for example\n`ssh -t user@host ' login --device-auth'`, so the user runs it. The host then stays ready\nacross workspaces.\n\nUse Git credentials already configured on the SSH host. For GitHub HTTPS repos, verify `gh auth\nstatus` on that host and run `gh auth setup-git` there if Git has no credential helper. Installed\n`gh` alone is not authentication. SSH URLs use the host's SSH keys; other providers use their own\ncredential setup. If credentials are missing, have the user configure them on the host. Do not\nforward a desktop token in the SSH command.\n\nBefore the first connection, verify the host key using the provider console or another trusted\nchannel and record it in the desktop's `known_hosts`. Do not trust an unverified `ssh-keyscan`\nresult. The noninteractive script below refuses unknown or changed keys.\n\n## The create script\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\n# resolve from env→state→fallback (default unset optionals to \"\"): ssh_username, host,\n# ssh_port (default 22), identity_file, jump_host, proxy_command, project_root, repo_url, repo_ref\n: \"${identity_file:=}\"; : \"${jump_host:=}\"; : \"${proxy_command:=}\" # avoid set -u aborts on optionals\nssh_target=\"${ssh_username}@${host}\"\nif [ -n \"$jump_host\" ] && [ -n \"$proxy_command\" ]; then\n echo \"set jump_host or proxy_command, not both\" >&2; exit 1\nfi\nssh_opts=(-p \"$ssh_port\" -o BatchMode=yes -o StrictHostKeyChecking=yes)\n[ -n \"$identity_file\" ] && ssh_opts+=(-i \"$identity_file\")\n[ -n \"$jump_host\" ] && ssh_opts+=(-J \"$jump_host\")\n[ -n \"$proxy_command\" ] && ssh_opts+=(-o \"ProxyCommand=$proxy_command\")\n\n# 1. ensure the repo is present and at the right commit on the host (NO orca serve here).\n# printf %q quotes every value for the remote shell, so a space or quote in a path or\n# ref cannot break out of the command.\nremote_sync='set -euo pipefail\n export GIT_TERMINAL_PROMPT=0\n [ -d \"$project_root/.git\" ] || git clone \"$repo_url\" \"$project_root\"\n cd \"$project_root\" && git fetch origin \"$repo_ref\" && git checkout -B \"$repo_ref\" FETCH_HEAD'\nssh \"${ssh_opts[@]}\" \"$ssh_target\" \"$(printf \\\n 'project_root=%q repo_url=%q repo_ref=%q bash -lc %q' \\\n \"$project_root\" \"$repo_url\" \"$repo_ref\" \"$remote_sync\")\" >&2\n\n# 2. print the SSH connection block (NO pairingCode, NO orca serve). host/port/username tell Orca's\n# relay how to dial in; identityFile/jumpHost/proxyCommand/portForwards are emitted when set.\nnode -e 'const [host,port,user,idf,jh,pc,root]=process.argv.slice(1);\n const target={ label:\"per-workspace-host\", host, port:Number(port), username:user };\n if(idf) target.identityFile=idf; if(jh) target.jumpHost=jh; if(pc) target.proxyCommand=pc;\n // add target.portForwards=[{localPort,remoteHost,remotePort}] here if the workspace needs them\n console.log(JSON.stringify({ schemaVersion:1, connection:{ type:\"ssh\", projectRoot:root, target } }))' \\\n \"$host\" \"$ssh_port\" \"$ssh_username\" \"$identity_file\" \"$jump_host\" \"$proxy_command\" \"$project_root\"\n```\n\nOn a persistent host there is usually nothing to tear down, so set `destroy: none` and omit suspend\nand resume. Orca still disconnects and reconnects its own SSH relay on sleep, wake, and delete, which\nis separate from these scripts.\n\nIf the SSH host is instead an ephemeral, snapshot-capable VM — the user's hypervisor, or a cloud VM\nwith image support — keep the base-image model from `references/provider-vercel.md` for\nprovisioning, but still emit the `connection.type:\"ssh\"` block above instead of starting\n`orca serve`.\n\n## Provisioned root\n\nFor an explicitly requested one-VM-per-workspace checkout, the create script reads\n`ORCA_RECIPE_RESULT_SCHEMA_VERSION`, `ORCA_REPO_URL`, `ORCA_REPO_REF`, `ORCA_REPO_REF_HEAD`, and\n`ORCA_REPO_BRANCH`. Use `ORCA_REPO_REF` to fetch the selected source, but create `ORCA_REPO_BRANCH`\nat the exact `ORCA_REPO_REF_HEAD` commit, because resolving the symbolic ref again can race with an\nupstream update. `ORCA_REPO_URL` and `ORCA_REPO_REF` are a matched fetch pair, and the URL is the\nremote Orca resolved the base ref against, which is not necessarily named `origin` on the desktop.\nFetch from the URL the pair supplies:\n\n```bash\n[ -n \"${ORCA_REPO_REF_HEAD:-}\" ] || { echo \"missing pinned source commit\" >&2; exit 1; }\ngit fetch \"$ORCA_REPO_URL\" \"$ORCA_REPO_REF\"\ngit cat-file -e \"${ORCA_REPO_REF_HEAD}^{commit}\"\ngit checkout -B \"$ORCA_REPO_BRANCH\" \"$ORCA_REPO_REF_HEAD\"\n```\n\nReturn that primary checkout at `projectRoot` and emit schema version 2:\n\n```json\n{\n \"schemaVersion\": 2,\n \"checkoutMode\": \"provisioned-root\",\n \"connection\": {\n \"type\": \"ssh\",\n \"projectRoot\": \"/abs/repo\",\n \"target\": { \"label\": \"my-box\", \"host\": \"192.0.2.10\", \"port\": 22, \"username\": \"ubuntu\" }\n }\n}\n```\n\n## Before declaring an SSH recipe done\n\nThe `--provision` self-test only sees what the scripts print, so smoke-test the exact emitted target\nas well: dial the host and port with the identity or proxy settings, run `pwd`, verify the repo path,\nand check the agent binary. If the recipe created a provider resource, also confirm `destroy`\nremoves it.\n"