Atlas Resume

---
name: atlas-resume
description: Use at session start (and after compaction) to resume an interrupted atlas-orchestrator run — whether a single-change `atlas` run or a multi-node `atlas-weave` graph run. If the cwd holds an unfinished `.atlas/<run_id>/` ledger, pick up from the durable on-disk state instead of restarting. Safe no-op when there is no `.atlas/` here.
---

# atlas-resume — on-disk run resumption (F1 / P11)

**Invoke this skill directly whenever you suspect an unfinished run — this manual invocation is
the MANDATORY, load-bearing recovery path.** In the Codex port there is **no SessionStart hook
and no automatic pointer** (the Claude Code port's `hooks/session-resume.sh` does not exist here),
so this manual invocation is the *only* recovery path — never merely a backup to an
assumed-working hook. Do not wait for any automatic signal to appear before resuming by hand; run
this skill on suspicion alone.

This is a **pure instruction**. It injects **no live state** — it only tells you *where the durable
ledger lives on disk* so you can find it yourself. atlas-orchestrator keeps its authoritative run state on
disk (never in context), because the full orchestrator prompt is **not guaranteed to survive
compaction**. Explicitly reload this skill after compaction or interruption; it is the
reliable pointer back to that on-disk state. On smaller-context models a multi-node run compacts often (the
root reads every node's return into its own context), but **on large-context models compaction is
RARE** — this resumption then covers turn-kills and crashes more than compaction. It stays
load-bearing (correctness must survive it either way), just no longer the common path on those models.

## What to do at session start

## Codex host bindings

Resolve the installed plugin root from this skill's actual loaded file path: ascend until
`scripts/codex_roles.py` and `references/schemas.json` both exist. Never derive it from the
target's git root. Record that absolute path and one UUID run id in the run ledger; reuse
the id on every call and after resume. Shell exports do not survive separate Codex calls.

For EVERY shared Python invocation below, replace the command's `python3` prefix with:
`python3 -I "<plugin-root>/scripts/codex_roles.py" core --run-id "<run-id>" --`.
The wrapper launches the same Python program with pinned plugin imports, safe path,
no user site, scrubbed PYTHONHOME, and the target's original PYTHONPATH recorded.
Pass shell variables as literal resolved values on each call; quoted heredoc Python bodies
also require the resolved run-id substitution. Never import the core before this wrapper.

Use the available native `exec_command` tool for shell reads and builds (`login=false`).
For long operations launch once, retain its session_id, and poll with `write_stdin`;
a returned running session is not failure. The shared 1500-second runcheck deadline
remains authoritative. Never re-run a still-running build.

`run_codex_role(role=..., prompt=...)` below denotes this operation, NOT a tool:
save the packet verbatim to a scratch file outside review_root using native
`apply_patch` (prefix each added line with +), then execute
`python3 -I "<plugin-root>/scripts/codex_roles.py" <role> --review-root "<review-root>" --packet "<packet-path>"`.
Capture stdout, which contains ONLY the final role message; a nonzero exit is a failed role.
Optionally add `--model "<user-selected-model>" --effort "<user-selected-effort>"`;
there is no hardcoded model candidate or quality claim. Apply the same overrides to any
of the seven roles. Never evaluate the command-builder JSON through a shell.

The runner explicitly loads the packaged role as developer_instructions; neither plugin
manifests nor native spawn load it. read-only roles always use the exec runner's read-only
sandbox, never native spawn. Only elite-coder gets workspace-write. Existing CODEX_HOME
ChatGPT login is reused; no API key/provider is supplied. Apps, plugins, escalation, and
nested agents are disabled in every child. Root alone persists JSON via ctxstore.

Use native user interaction only where available and suitable; otherwise ask plainly and
end the turn awaiting the answer. A missing user interaction tool is never implicit confirmation.
Persistence base is always .atlas in the target, including non-git targets.

1. **Look in the current working directory only.** If there is **no `.atlas/` here, do nothing** —
   stop silently and proceed with the session normally.

2. **Decide graph-run vs single-change.** A **graph run** is one whose `.atlas/<run_id>/` holds a
   `plan.dag.json` (the `atlas-weave` outer machine). A **single-change run** has only the
   `atlas` ledger (`state.json`, no DAG). Discover the runs on disk (each `.atlas/*/` with its
   `state.json` `current_state` + mtime + whether a `plan.dag.json` exists), then:

### Graph run (atlas-weave) — re-derive the frontier by pure projection

3g. **Select the graph ROOT run.** Call `resume.select_graph_run(runs, session_id)` with the on-disk
    run descriptors (`{run_id, has_dag, state, mtime}`). It returns the non-terminal run that carries a
    DAG and is **not** a task sub-run (`resume.is_task_subrun` skips any `${SESSION}/tasks/<id>`
    sub-run), preferring the current session, else the newest by `(mtime, run_id)`. If it returns
    `None`, there is no resumable graph run — fall through to the single-change path or stop.

4g. **Reset the orphaned frontier.** exec_command `plan.dag.json`; `dag = resume.resume(dag)` — this resets
    every orphaned `RUNNING` job (its inner-atlas agent died with the turn) back to `PENDING` and
    clears its lease, WITHOUT `attempts++` and WITHOUT refunding gas (a compaction is not an agent
    failure, and the interrupted dispatch already spent its fuel — so re-dispatch stays gas-bounded
    and the run still provably halts). Terminal (`DONE`/`FAILED`) and `PENDING` jobs are untouched;
    no node is dropped. apply_patch the reset DAG back with `ctxstore.write_artifact_atomic`.

5g. **Discard in-flight receipts (the lease no-rotation rule).** The lease token
    `f"{job_id}#{attempts}"` does NOT rotate across this reset (attempts is unchanged), so a receipt
    from the killed turn would still pass `scheduler.lease_valid` against the re-dispatched attempt —
    **ignore any such receipt.** Only receipts produced *after* this resume count.

6g. **Reset dirty worktrees.** Any per-node or union worktree left half-written by the killed turn is
    untrusted — remove it (`uniontree.cleanup` / `git worktree remove --force`); the re-dispatched
    node will re-create a clean one at its baseline.

7g. **Re-enter the outer machine.** Resume the **atlas-weave** machine at **SCHEDULE** (the frontier is now
    re-derived) with the **same** `run_id` and the same frozen packet + `success_criteria` (never
    re-derive them). Continue draining the pool → INTEGRATE → AGGREGATE → OUTPUT. Honor every gate:
    never auto-apply the union; stop at the OUTPUT gate exactly as a fresh run would.

### Single-change run (atlas) — the original path

3s. **Find the newest unfinished run** among `.atlas/*/state.json` with `current_state != "OUTPUT"`.
    If every run is at `OUTPUT` (or none exists), **do nothing** and proceed normally.

4s. **exec_command the ledger, do not restart.** exec_command the immutable `intent` + frozen `success_criteria`
    (never re-derive), the `stages` ledger + `current_state`, `refine_passes`, `verify_cmd`,
    `scope_paths`, `baseline_sha`, and `log.jsonl`.

Before 5s, inspect the selected run's structured `clarify_resolution`. If TRIAGED is not done and `triage_ready(load(raw))` is false, resume CLARIFY as described below instead of taking the successor of its last ledger entry. CLARIFY is persisted before waiting; its `done` ledger marker records durable interview progress, not user confirmation. Do not skip pending frontier questions or confirmation because this marker exists.

5s. **Resume from the last recorded stage.** Re-enter the **atlas** state machine at the stage
    **after** the last one recorded `done`, in the **same** run (same `run_id`) — **with the one
    exception below**. Do not start a new
    run, re-run completed stages, or re-capture intent.

    > **`REFINE` is the one entry whose successor is NOT the next `STAGES` member.** A last recorded
    > `REFINE` means the gate already decided `REFINE?=True`, so resume by **re-entering the refine
    > loop at `CODED`, never `OUTPUT`** — re-dispatch the coder, then `VERIFIED`. Resuming at
    > `OUTPUT` would print a status computed from the verdict that decision had already superseded:
    > the forced pass never ran, and the run reports ✅ for a tree nothing re-verified. Reaching
    > `OUTPUT` directly from a trailing `REFINE` is legal **only** on the degraded could-not-verify
    > path (the coder could not be re-run at all), and that path requires `budget_exhausted = True`
    > at OUTPUT — i.e. ⚠️ UNVERIFIED, never a green. `floorsynth.stale_verdict_defects` blocks the
    > shape either way, so a resume that skips `CODED` cannot be laundered into a ✅.
    >
    > *(A2: copied verbatim from the Claude Code orchestrator skill, which has carried this
    > prohibition all along. This file did not — and a resume skill is read precisely when context
    > was lost. `REFINE → CODED` is already legal in `fsm.py`; no new `advance()` is involved.)* The pass counter is the count of `REFINE`
    entries in the ledger, read from disk, never from memory.

6s. **Honor the run's gates.** Never auto-apply to a real tree; stop at the pre-CODE approval gate and
    the OUTPUT gate exactly as the `atlas` orchestrator would.

## Safety

A malformed structured interview in an otherwise selected run requires recovery; it is not permission to abandon its unanswered decisions or treat it as confirmed. For other cases, if a ledger/DAG is unreadable, treat this as "no resumable run" and proceed
normally — resumption is best-effort and must never block or corrupt a fresh session.

## Resume an interrupted CLARIFY interview

For the selected single-change run, read `clarify_resolution` before choosing the next stage. A structured interview resumes through `scripts.grilling_state.load(raw)`: restore its tree, settled answers, recorded rounds, and stored frontier. Continue the same full frontier with recommendations; pending exploration blocks only dependent nodes. After answers use `record_round(state, frontier_ids, answer_strings)`, reshape open branches via `set_tree`, fold settled answers into still-mutable packet fields and revalidate them, and persist the actual `dump(state)` through `ctxstore.advance(..., "CLARIFY", updates={"clarify_resolution": grilling_state.dump(state)})`. Never insert user text into Python source or replace this data with a placeholder.

If all branches are settled but `confirmed` is false, obtain explicit human confirmation of shared understanding. Only the actual reply permits `confirm(state, user_confirmed=True)`; persist it before TRIAGED. `triage_ready(state)` and the shared ctxstore gate prevent freezing an unfinished interview. A headless run remains UNVERIFIED. Malformed or unknown structured records require recovery; never silently reinterpret them as an answered interview. Historical plaintext resolutions retain their previous path.