Rote Shell

rote-shell

All rote-<name> references in this document — including every name in the Handoff Contract — are companion skills, never CLI commands (rote-shell is not rote shell). Invoke them through the runtime's skill mechanism; only literal rote … commands run in a terminal.

Use rote for shell and CLI work when the result should become workspace memory: commands, outputs, files, logs, process lifecycle, dependencies, and play replay. Raw shell is still fine for tiny inspection commands, but work that matters should pass through rote so it can be queried, audited, and crystallized.

Load the shell guidance when you need the complete command model:

rote guidance shell essential

First Decision

Choose the narrowest rote primitive that preserves evidence:

• one-shot command: rote proc run -- <program> [args...]
• stdin from a file: rote proc run --stdin-file input.txt -- <program>
• declared output file: rote proc run --capture-file label:path -- <program>
• moving file/log: rote proc stream follow --file logs/server.log --until READY
• long-running process: rote proc run --background --ready-log READY -- <program>
• process stream: rote proc stream follow-process proc-1 --stream stdout --until READY
• terminal-sensitive command: rote proc pty run -- <program> [args...]
• dependency preflight: rote deps check deps.toml
• legacy TypeScript replay: rote deno run --allow-all ~/.rote/flows/<name>/main.ts
• declarative or presentation replay: rote play run ~/.rote/flows/<name>/main.ts param=value

Do not replace these with ad hoc command > file, tail -f, or ps | grep when the evidence should be durable. Rote already stores typed responses, artifacts, hashes, offsets, process leases, and command-log provenance.

Hard default: if command output feeds a final answer, user artifact, play body, or later reasoning step, it is not disposable. Use rote proc and then query the saved response.

Build and dev-loop tooling is the exception, whatever the language toolchain: compilers, test runners, formatters, linters, type checkers, package managers, and task runners run as plain shell by default. Wrap such a run in rote proc only after the user agrees it should become durable workspace evidence.

Chaining is acceptable when each meaningful shell process is captured by rote proc. For example, rote proc run ... && rote proc run ... preserves process nodes in the workspace DAG. Do not promote raw pipes or chained lifecycle commands as the default route. Adapter setup, workspace init/session setup, pending-play lifecycle, release, index, and registry operations are clearer as separate commands unless the runtime explicitly prints a combined command.

Adapter-First Boundary

rote proc is not an adapter substitute. If the task needs provider/API data, such as records, tickets, PRs, issues, markets, trades, CRM rows, calendar events, or database objects, return to rote-task-routing and use adapter search/install/probe/call first. Do not fetch provider REST endpoints through curl, Python, Node, a custom SDK, or inline HTTP scripts unless play search, explore, catalog search, and adapter probes have failed to produce a rote path.

Shell work starts after routing selects local command evidence, or after adapter/browser evidence has been captured and a local command needs to process it. Provider-native CLIs are shell work only when the CLI itself is the requested source or the router selected it as fallback after adapter checks.

Handoff Contract

• Use when: local CLI commands, files, logs, process lifecycle, dependency checks, generated artifacts, or shell-derived play replay need rote memory.
• Preconditions: rote can run; a task intent and working directory are known; browser/API state that must feed the command has been materialized as a saved response, snapshot, slice, or file.
• Owns: rote proc primitive selection, process evidence capture, dependency preflight, background lease handling, and shell SDK guidance.
• Hands off to: rote-flow-crystallization first for reusable process evidence; rote-flow-authoring after an approved crystallization plan; rote-typescript-transformations, rote-troubleshooting, rote-browse, and rote as their concerns arise.
• Returns to: rote or the delegating companion with commands run, response IDs, process leases, captured artifacts, result, reusability signal, cleanup state, and next recommended skill.
• Stop when: the shell result is delivered, dependency provisioning needs user approval, a process cleanup or credential prompt blocks, browser/API ownership is required, or reusable play authoring takes over.
• Completion signal: queried process evidence, captured files/artifacts, resolved background leases, dependency check status, and a save gate of pending, accepted, discarded, or not applicable.

Handoff Packet

Consume this packet from rote, rote-browse, rote-workspace, or a delegated skill:

• Origin skill: rote, rote-browse, rote-workspace, or the delegated skill that handed off.
• User intent: the exact shell-visible result or artifact requested.
• Workspace path: current rote workspace path, or proposed workspace name.
• Working directory: directory where local commands should run.
• Input evidence: saved responses, browser snapshots/slices, files, or adapter results to consume.
• Requirements: the command output, files/logs, output artifact, and verification checks that must survive handoff.
• Allowed commands: exact local CLIs or rote proc primitives expected.
• Stop conditions: missing dependency, prompt/credential request, unsafe mutation, cleanup failure, or user approval needed.
• Return fields: commands run, response IDs, process leases, captured artifacts, cleanup state, result, reusability signal, save gate, and next recommended skill.

Handoff Summary

Write or return this summary when shell work must survive handoff, compaction, or background waits:

# Rote Shell Handoff Summary

- Active skill: `rote-shell`
- Origin skill: `rote` or `rote-...`
- User intent: ...
- Workspace path: ...
- Working directory: ...
- Commands run: ...
- Cached responses: ...
- Process leases: ...
- Captured artifacts: ...
- Requirements: ...
- Current gate: shell execution, dependency approval, background wait, cleanup, save gate, or blocker
- Result: ...
- Save gate: pending, accepted, discarded, or not applicable
- Next skill: `rote-flow-crystallization`, `rote-flow-authoring`, `rote-troubleshooting`, `rote`, or none
- Blockers: ...
- Completion signal: ...

Browser Intent Router

If the user says "browse", "open this site", "attach to my browser", "use the page", "click", "type", "snapshot", "extract from the page", "extract social profiles", "Gmail in browser", or otherwise asks for live web UI state, stop shell routing and invoke /rote-browse.

Do not satisfy browser intent with rote proc run, raw Playwright, native web search, WebFetch, open, curl, or a saved non-browser play unless the user explicitly switches substrate. Native search may help discover a URL only when the user asked for search/discovery or the browser route cannot identify a URL; it is not a substitute for browsing and extracting the page with rote.

Browse intent has precedence over the domain noun. For example, "browse my calendar", "browse Gmail", "browse HubSpot", or "browse Salesforce" means the user wants browser-state access even though those domains may also have APIs. You may still run rote play search "<intent>" first, but only use an adapter/play if it is installed, healthy, and completes the request. If the adapter/play is missing, stale, unauthenticated, or fails setup, do not ask the user to build an adapter before trying the browser route. Hand off to /rote-browse and use an existing headed browser when the task depends on the user's logged-in profile.

For public profile extraction, such as "browse each committer's social profile", use GitHub/CLI/API data to collect candidate URLs and identities, then use /rote-browse to visit and extract the public pages. Do not replace that browse step with native web search summaries.

Default browser decision:

• Existing login, Gmail, SSO, MFA, extensions, active tabs, or profile state: ask to attach to an existing headed browser.
• Public read-only page, CI, or replay-like work: ask whether headless new-session is acceptable.
• The user says "browse" without choosing mode: ask headed vs headless; if headed, ask attach-existing vs new rote-managed headed browser.

For active browser attach, hand off to /rote-browse and use its sequence:

rote browser attach setup --method extension --browser chrome
rote browse <url> --headed --attach-existing --new-tab --no-prompt --no-snapshot
rote browse wait --selector '<ready-selector>' --timeout 30 --quiet-ms 750
rote browse snapshot

For browser plus shell work, keep both in the same workspace. Use /rote-browse for page leases, snapshots, slices, refs, auth state, and readiness. Use /rote-shell only after browser state has been materialized as a saved response, snapshot, slice, or file that a local CLI should process.

Current Capability Map

Use only shipped commands. Do not invent aliases from the roadmap.

Deferred or not shipped as commands yet:

• rote proc attach
• rote proc log
• explicit detach
• persistent PTY sessions: start, send, snapshot, stop, attach
• non-log readiness probes such as HTTP, TCP, file, or command probes
• direct OS-pipe stream handles before background output reaches log artifacts
• non-Unix process-group cleanup guarantees

If a task needs a deferred feature, say so and use the nearest shipped primitive instead. For example, use rote proc wait for finite tracked jobs, use rote proc stream follow-process ... --until <pattern> for log observation or readiness, and use rote proc status plus rote proc stop instead of raw ps/kill when the process is tracked.

TypeScript SDK Pattern Map

For explicit legacy no-steps TypeScript plays, use first-class SDK wrappers instead of hand-assembling command arrays. Recorded finite commands default to typed process.exec steps via workspace export; the SDK surface below is for the shell capabilities the step language does not cover — PTY interaction, and background leases/streams with concurrent mid-lease work:

Use rote.shell().<method> when you want the shell namespace explicitly; the top-level rote.<method> forms are convenience aliases for authored plays.

Do not invent SDK methods for deferred roadmap items. There is no rote.detach, persistent PTY send, or direct OS-pipe stream handle yet. The current detach-like pattern is a tracked background lease with stdout/stderr files, execWait, followProcess, execStatus, and execStop.

Reading an exec result — every read is awaited; stdout/stderr are stream handles, not strings:

const proc = await rote.exec({ argv: ["git", "status", "--short"], deps: ["git"] });
const text = await proc.stdout.text();   // stderr mirror: proc.stderr.text()
const exit = await proc.exit();          // { kind: "code", code } | { kind: "signal", … }
if (exit.kind !== "code" || exit.code !== 0) {
  throw new Error(`git failed: ${await proc.stderr.text()}`);
}
const files = await proc.files();        // captured file artifacts ([] unless capture requested)

For declarative process.exec, use the Process Exit Contract in rote grammar steps and follow rote guidance play testing for coverage fixtures. Do not replace failures with exit-zero stdout sentinels. When a pipeline is unavoidable, use bash -o pipefail -c, not /bin/sh plus set -o pipefail.

rote.execMany preserves workspace response ordering by running process requests serially. For several different independent commands, generate sibling process.exec steps with no depends_on between them; for one command over many values, generate declarative frontmatter steps: with type: process.exec, for_each, and max_concurrency so the DAG runner owns the scheduling and provenance.

For long-running finite jobs in authored TypeScript, prefer execBackgroundAndJoin or job.join when there is useful adapter, browser, process, file, or explicit stream work to do while the lease runs. The callback creates normal semantic DAG evidence; the final proc wait is the join point. Do not generate heartbeat or polling loops as DAG work. rote.execBackground(...) already prints the lease and poll commands to stderr. Do not duplicate that announcement in crystallized plays. Use announce: false only for deliberately quiet plays.

Crystallization Router

When recorded shell exploration is reusable, hand its evidence to rote-flow-crystallization before exporting. That skill distills the reusable procedure into a semantic plan and resolves save approval; do not treat transcript order as the play design. After approval, pass the plan to rote-flow-authoring; authoring materializes it with rote workspace export <path> using no shape flags. The default artifact is schema-v1 steps plus presentation: typed process.exec effects in steps: and a steps_with_presentation body.

The export is a draft synthesized from one recording: replace recorded literal argv values (paths, repos, dates) with $param tokens, prune spurious inferred parameters:, and align its steps with the approved plan before lint. Use --format steps only when the user wants a steps-only report. Adapterless template/frontmatter/pending commands still require a real adapter, so never invent one for process-only work. Step syntax belongs to rote grammar steps.

Use an explicit legacy no-steps shell body only when the workflow needs shell control flow or runtime interaction the step language does not support, or when the user asks for one. On this substrate that means PTY interaction and background leases/streams with concurrent mid-lease work; "dynamic" on its own is not a trigger. rote-flow-authoring owns the general representability test:

Crystallize causality, not waiting. Do not encode heartbeat loops, repeated status polling, or sleep/retry scaffolding as business DAG nodes. Those are observation mechanics. The reusable play should expose semantic actions and joins: start work, observe meaningful artifacts or streams, wait for completion, then summarize.

Before authoring a process-backed TypeScript play, read:

rote guidance typescript play-creation

That guide owns frontmatter, FlowOutput, release QA, and the shell SDK wrapper contract. rote guidance shell essential owns the dependency manifest.

Play Runtime Boundary

rote proc run is for exploration, not reusable play bodies.

• Process-backed TypeScript plays must not call rote init internally.
• Crystallized TypeScript plays must not shell out to rote proc run.
• During exploration, rote proc run records evidence; inside reusable plays, use SDK wrappers or process.exec steps.
• Use shell SDK exec only for task commands, not lifecycle bootstrapping.

Strategy Pattern Library

Map the user's vague request to the smallest shipped pattern that preserves evidence:

--dry-run, --resume, --force-resume, and --max-concurrency are DAG runner controls for frontmatter steps: plays. They are not universal rote proc run flags. For a single command, use the tool's own dry-run/check mode when available.

Workspace Setup

CLI work must happen inside a rote workspace. Command runners rarely preserve cwd between steps, so prefix each workspace-scoped command with the resolved cd <workspace-path> && (one logical step):

rote init cli-work --seq --force
cd ${ROTE_HOME:-$HOME/.rote}/workspaces/cli-work && rote model set <model> --provider <provider> --confirmed-current
cd ${ROTE_HOME:-$HOME/.rote}/workspaces/cli-work && rote workspace sandbox cli-work off

If the runtime does not expose the current model and provider and no command requires identity, record that they were unknown; do not fabricate model metadata.

Keep commands simple and literal. Avoid shell control operators, command substitution, and long && chains unless the user explicitly needs shell semantics (the resolved cd <workspace-path> && rote … prefix is the standing exception). Prefer direct argv:

rote proc run -- rg TODO docs

Use shell parsing only when it is the real subject of the work:

rote proc run -- sh -c 'printf "alpha\n" | tr a-z A-Z'

If parsing transforms evidence for a report or play, keep it inside a tracked command and capture the inputs/outputs. Do not rely on terminal scrollback, untracked temp files, or raw pipelines as the only record.

Query After Every Meaningful Step

Treat every @N as the handle for what just happened. The handle is saved evidence, not always the raw business payload. Route by type.

After a command finishes, read @@result first:

• response_id is the saved evidence handle
• response_kind tells you how to query the evidence
• primary_query, primary_stdout_query, primary_stderr_query, or artifact_query are exact typed queries for the saved response
• @@next remains the immediate next-action guide

For one-shot process output, prefer the typed query fields from @@result:

rote query @1 '.stdout.text' -r
rote query @1 '.stderr.text' -r
rote query @1 '.status.exit' -r
rote query @1 '.files' -r
rote query @2 '.cleanup' -r

Use @proc addresses when inspecting process responses:

rote query @proc.last.stdout '.text' -r
rote query @proc.1.exit '.' -r
rote query @proc.last.transcript '.text' -r

When @@result gives an exact query such as rote query @proc.4.transcript '.text' -r, prefer it over @proc.last if any other command may run before you query. Use rote @N . for full provenance inspection, not as a shortcut for stdout or PTY transcript text.

Do not summarize from terminal scrollback when a structured query exists.

Files And Artifacts

Declare file inputs and outputs instead of relying on memory:

rote proc run \
  --stdin-file input.txt \
  --capture-file summary:out/summary.txt \
  -- python3 scripts/summarize.py

This records stdin provenance, file change state, media type, hashes when available, and artifact paths under .rote/artifacts/processes/@N/.

Background Processes

Start servers as leases, not mystery PIDs:

rote proc run --background --ready-log "Listening" --ready-timeout-ms 10000 -- npm run dev
rote proc status proc-1
rote proc stream follow-process proc-1 --stream stdout --until "GET /health"
rote proc stop proc-1
rote query @3 '.cleanup' -r

On Unix, rote starts background commands in a process group and stops the group with TERM followed by KILL if needed. Inspect .cleanup before claiming a process stopped.

Long-Running Finite Jobs

For long-running but finite commands, use a tracked background lease instead of an untracked detach. rote proc detach is not shipped yet. The current detached-like primitive is:

rote proc run \
  --background \
  --stdout-file logs/job.stdout.log \
  --stderr-file logs/job.stderr.log \
  -- cargo test --all-targets --all-features

rote proc status proc-1
rote proc wait proc-1 --timeout-ms 600000 --poll-ms 1000
rote proc stream follow-process proc-1 --stream stdout --from-start --max-bytes 65536
rote proc stream follow-process proc-1 --stream stderr --from-start --max-bytes 65536

Use this when the command is non-interactive, can safely continue while the agent does other work, and its stdout/stderr are enough to monitor progress. Use proc wait to establish completion and exit status. Use follow-process to inspect output, not as the primary completion detector. Keep the lease id (proc-1) in the task notes and query status before making claims about completion if wait has not finished.

In authored TypeScript, prefer the semantic join helper:

const joined = await rote.execBackgroundAndJoin(
  { argv: ["cargo", "test"], deps: ["cargo"] },
  async (job) => {
    const checks = await rote.exec({ argv: ["gh", "pr", "checks"], deps: ["gh"] });
    const stderr = await job.follow("stderr", { fromStart: true, maxBytes: 65536 });
    return { checks, stderr };
  },
  { timeoutMs: 600_000, pollMs: 1_000, stopOnWorkError: true },
);

The callback's work becomes semantic DAG evidence. The wait remains the completion join. Poll/heartbeat internals do not become graph nodes.

Do not background a command when it may prompt for credentials, OTP, passphrase, license acceptance, or confirmation. rote proc pty run can capture a bounded one-shot terminal transcript, but it does not provide persistent attach. Ongoing interactive jobs should run foreground or be postponed until the user can drive the prompt.

One-Shot PTY

Use PTY only when terminal behavior is the point: commands that check isatty, render progress differently on terminals, or can be driven with bounded scripted input.

rote proc pty run --cols 100 --rows 30 -- script-that-checks-tty
rote proc pty run --input "yes\n" -- interactive-but-scriptable-command
rote query @proc.last.transcript '.text' -r

Do not pass secrets through --input; terminal echo may record them in the transcript. Do not use PTY for persistent REPLs or long human-driven sessions until start/send/snapshot/stop support exists.

In a legacy play body, rote.ptyRun returns the same evidence, typed:

const proc = await rote.ptyRun({ argv: ["sh", "-c", "test -t 1 && echo interactive || echo piped"], cols: 100, rows: 30 });
const transcript = await proc.transcript.text(); // raw transcript, ANSI escapes included
const exit = await proc.exit();                  // { kind: "code", code } | { kind: "signal", … }
if (exit.kind !== "code" || exit.code !== 0) throw new Error("capture failed");

Request fields are argv, input or stdinFile (not both), cols, rows, and timeoutMs. There is no cwd option — the command runs in the executor's current directory, which is the workspace directory once Rote.workspace() is open. Pass directories to the tool itself (git -C "$root", sh -c 'cd "$1" && …' sh "$dir") instead of relying on the play's launch directory. Lint mode stubs proc.exit() ({ kind: "code", code: 0 }) and proc.transcript.text() (""), so PTY reads need no isLintMode() guard.

Treat release and publish commands as high risk. For examples like cargo release, npm publish, gh release create, or deploy commands:

1. Run dependency preflight first.
2. Run the tool's dry-run/check mode first when available.
3. Show the planned mutation and ask the user for approval before the real run.
4. Prefer foreground for final irreversible publish steps unless the user explicitly approves tracked background execution.
5. If background execution is approved, capture stdout/stderr to files, follow process streams, and keep the play draft until completion evidence is captured.
6. Do not stop a release/publish process unless the user asks; interruption can leave external state partially mutated.

Decision rule:

• short and non-interactive: foreground rote proc run
• long and non-interactive: tracked rote proc run --background
• long-running service: tracked rote proc run --background --ready-log ...
• interactive: foreground or wait for PTY/attach support
• irreversible release/publish: dry-run, user approval, then foreground unless tracked background is explicitly requested

Dependency Manifests

When a task depends on local tools, create or update ~/.rote/flows/<name>/deps.toml before replay. This is not optional for crystallized TypeScript plays: if the play calls rote.exec({ argv }) for git, gh, cargo, python, node, jq, rg, or any other local executable, the play directory must include a matching dependency manifest before the play is marked released.

rote guidance shell essential (Dependency Manifests) owns the manifest shape and the install-approval script: tools, install candidates, [files], version requirements, and readiness probes. Write the file from there.

Run preflight before work, and again after any install:

cd ~/.rote/flows/<name>
rote deps check deps.toml

If it reports missing required tools, stop and elicit an install decision from the user before continuing: show the missing tool, why the play needs it, and the lowest-risk install scope available. Prefer project-local or rote-managed installs over global package manager installs, and only install globally when the user explicitly approves that scope. Never mark the play released while required dependencies are still missing, or while any required tool has no install candidate — preflight passes on a present tool either way, so a green rote deps check does not clear this gate.

Mixed Workflows

For API plus CLI work, use the adapter for typed API calls and rote proc run for local CLI facts. Example shape:

rote POST /github '{"method":"GET","path":"/repos/$owner/$repo"}' -t -s
rote proc run -- gh repo view "$owner/$repo" --json name,visibility
rote query @1 '.' -r
rote query @2 '.stdout.text' -r

The $owner/$repo above are exploration-time shell/workspace substitutions. In a crystallized play's steps:, $param tokens are resolved by the DAG runner from the play's declared parameters: — a different mechanism with the same spelling. Recorded rote proc run commands carry no tokens at all (literal argv), which is why exported drafts need the literals generalized.

For browser plus CLI work, use rote-browse for page state and rote-shell for local processing of snapshots/artifacts. Do not drop into raw Playwright or raw shell when a rote primitive can preserve the evidence.

Adapter, process.exec, and typed browser.navigate|extract|click|type actions are first-class steps: effects. Default crystallization places them in one effect DAG and gives the presentation body their completed, partial, checkpoint-restored, failed, skipped, or blocked observations through the presentation SDK. Browser extracts stay bounded projections, and stateful browser actions keep the ordering and runtime/auth dependencies recorded by rote-browse.

Crystallization Handoff

After a CLI workflow produces the requested result, run reuse triage before the final answer. If it is reusable or plausibly reusable, hand the captured evidence to rote-flow-crystallization; do not turn the command transcript directly into a play. Before final presentation, ensure the root skill's cd <workspace-path> && rote ls gate has run; it is the deterministic source of the pending-stub warning. Return the workspace path, response IDs, captured files, process dependencies, and the semantic result each command established.

After that skill returns an approved crystallization plan, hand it to rote-flow-authoring. This skill remains the specialist for process dependencies, PTY/background escape capabilities, and shell SDK details, but authoring owns materialization, testing, lint, release, and cleanup. Authoring executes process-only adapterless workspace export; mixed work follows the pending scaffold route selected by crystallization. Never invent an adapter for process-only work.

Replay commands remain shape-specific:

# Any play with frontmatter steps
rote play run ~/.rote/flows/<name>/main.ts param=value

# Explicit legacy body with no steps
rote deno run --allow-all ~/.rote/flows/<name>/main.ts [args]

Read rote guidance play crystallization for the plan, rote guidance play shape for the DAG, and rote guidance play testing for verification. Use rote grammar steps for exact syntax and return here only for shell-specific implementation detail.

Step Reference Rules For Mixed DAGs

In steps: plays, @step{.path} resolves against the unwrapped step response body, not the persisted @N envelope on disk. For example:

@repo_adapter{.full_name}

Presentation code must still tolerate legacy adapter envelope residue when normalizing old cached observations, but new @step references never navigate that envelope. For process steps, the response body is process.exec, so downstream steps can reference fields such as .stdout.text or captured file metadata. Keep process.exec argv, stdin paths, and capture paths scalar after resolution. Do not pass large adapter/browser payloads through argv when a file bridge or a small scalar projection is clearer.

$param tokens resolve in the same fields (argv elements, adapter params: values, stdin and capture paths) from the play's declared parameters:. An unresolved $name passes through as a literal, and $item/$item_index are reserved for for_each fan-out.