---
name: autonomous-run
description: Prepare, start, inspect, resume, or stop a finite local overnight coding run after a human has accepted a Wayfinder terminal spec; coordinates a declared Claude/Codex maker and independent checker without pushing, merging, or writing to external systems.
compatibility: Requires Python 3.11+, git, Claude Code and Codex CLIs, plus sandbox-exec on macOS or bubblewrap on Linux.
---

# Autonomous run — bounded overnight execution

This skill is for a **finite approved implementation**, not a recurring watcher. For recurring
work use the autonomous-loops profile. For unresolved product or architecture decisions, run
Wayfinder first.

## Hard gate

Do not begin implementation unless all of these are true:

1. The terminal spec is committed under `docs/specs/` with `status: accepted`, `accepted_by`, and
   `accepted_at`. An agent may author only `status: draft`.
2. A separate implementation-ticket ID is named. The decision ticket is not executable work.
3. The operator explicitly invokes or authorizes `start`. Producing or checking a spec never
   self-authorizes implementation.

Linear and every other external system still follow the installed write-consent rule. The v1
controller has no external-write adapter at all.

## Prepare the contract

Use `.agentsmith/autonomous-run.py` in an installed project; the source checkout uses
`scripts/autonomous-run.py`. The installed template is
`.harness/templates/autonomous-run.json` (the harness source checkout uses
`templates/autonomous-run.json`):

```text
python3 .agentsmith/autonomous-run.py prepare --run-id <short-id> --spec docs/specs/<name>.md --ticket <implementation-ticket> --maker codex --checker claude --template .harness/templates/autonomous-run.json
```

This creates a non-executable draft until both roles have explicit model and effort settings.
Review its exact allowed/denied paths, verifier, models, attempt cap,
wall-clock limit, budgets, and optional `scope.resources` keys such as `port:3000` or
`db:local/test`. Resource keys coordinate cooperating local runs; they do not replace operating-
system port binding or database isolation. Commit the manifest before execution; the controller
refuses an uncommitted contract. Concurrent worktrees share writable Git metadata needed for local
commits, so this guard prevents accidental collisions between cooperating runs; it is not a
security boundary for mutually untrusted makers.

## Start and supervise

Only after explicit operator authorization:

```text
python3 .agentsmith/autonomous-run.py start .harness/runs/<short-id>.json
```

The controller creates an isolated local branch/worktree, launches a fresh maker, validates its
receipt, scope and Git transition, then creates a disposable detached worktree for the sandboxed
deterministic verifier and a fresh checker. A rejection becomes the next maker's input. Three
failed attempts, invalid state, denied scope, immutable-deadline or reported-budget exhaustion,
Git metadata drift, protected verification edits, or checker mutation escalates instead of widening authority. Verification
fails closed unless macOS `sandbox-exec` or Linux `bubblewrap` is available.

Existing baseline tests, the accepted spec, runtime launchers, and verification policy are protected
even with broad maker scope, and moving or renaming one of them counts as changing it. A moved
file counts as two changed paths, the old one and the new one; both must be inside the allowed
scope. Add custom acceptance inputs via `verify.protected_paths`; changing
protected inputs requires separate operator review outside this run. New regression tests remain
allowed. Both roles receive trusted-path write restrictions through their native policies; Codex uses a
strict named filesystem profile, and Claude combines Bash denyWrite with file-tool Edit denials.
Native clients and the host remain trusted. Checkers inspect the controller verifier evidence.

Before `start` creates local Git or state artifacts, and before `resume` restarts work, the
controller serializes a repository-local collision scan. Ancestor/descendant fixed prefixes from
`scope.allowed_paths` conflict; a glob with no fixed prefix reserves the repository; identical
resource keys conflict. Live malformed state fails closed, while stopped or demonstrably dead
controllers no longer reserve their scopes.

Use `status <id>`, `stop <id>`, or `resume <id>`. Stop/resume retains the worktree and audit state.
Resume revalidates a checkpointed candidate and reruns verification/checking in the same attempt.
Dirty or unreceipted maker commits require operator review. Raw logs survive controller crashes;
earlier invocations are archived. Report `usage_accounting_incomplete` when a crash leaves
unreported spend unknown. A surviving role process group must be stopped before recovery.
An accepted run ends at a local commit for human review: never push, open a PR, merge, deploy,
rewrite history, or write to Linear from this workflow.

## Report

Give the run ID, status, attempt count, branch/worktree, accepted commit or escalation reason, and
the actual verification evidence. State explicitly that external actions were not taken.