| name | atlas-resume |
| description | Use at session start (and after compaction) to resume an interrupted kimi-atlas 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 (/kimi-atlas:atlas-resume) whenever you suspect an unfinished run —
this manual invocation is the MANDATORY, load-bearing recovery path, never merely a backup to an
assumed-working hook. A SessionStart hook (hooks/session-resume.sh) also exists and prints a
pointer when it finds an unfinished .atlas/*/state.json; a live probe against a real Claude Code
CLI empirically confirmed that hook's stdout does land in a started session's context (see
probe/probe_cc_sessionstart_injection.sh), but only for the startup source, on one CLI version,
via one throwaway scratch plugin — not a guarantee across every build, every one of the hook's five
registered sources, or every real user's plugin-loading configuration. Do not wait for that pointer
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. kimi-atlas keeps its authoritative run state on
disk (never in context), because the full orchestrator prompt is not guaranteed to survive
compaction. This skill body IS re-injected at session start and after compaction, so it is the
reliable pointer back to that on-disk state. On the 256K models a multi-node run compacts often (the
root reads every node's return into its own context), but on the 1M k3/Kimi-3 model 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 at 1M.
What to do at session start
Script-call convention — every script call in this file (both paths below) runs as
python3 -c "from scripts import <mod>; …". The Claude Code SessionStart hook
(hooks/init-env.sh) already exports PYTHONPATH (set to ${ATLAS_PLUGIN_ROOT}, the plugin
root, and nothing else, so from scripts import <mod> resolves against the plugin rather than
against any directory the environment names; the ambient value is replaced, not
appended, and is preserved separately as ATLAS_ORIG_PYTHONPATH for the target's own build),
PYTHONSAFEPATH=1 and PYTHONNOUSERSITE=1, all for the REST OF THE SESSION, before this skill's own body ever runs — this skill itself fires
at session start, so there is no earlier point a per-invocation prefix could be protecting
against. PYTHONSAFEPATH=1 remains mandatory in that exported environment: the working directory
here is the user's own project, and without it that directory would outrank PYTHONPATH, letting
the project replace scripts/ctxstore.py or scripts/resume.py with its own. PYTHONNOUSERSITE=1
closes the channel the other two do not reach: site imports usercustomize from the user site
directory at startup, so a usercustomize.py planted through an ambient $PYTHONUSERBASE runs
inside the interpreter before any of this skill's own code does. The claim stops there, narrower
than it used to read: $PYTHONHOME relocates the stdlib itself and is still open
session-wide, so "cannot be steered by whatever the environment held" would be false — three of
the four resolution channels are closed, not all four. Do not add a
per-invocation prefix back: Kimi CLI's ${KIMI_SKILL_DIR} token has no Claude Code equivalent and
is unbound here, so a reintroduced prefix would shadow the session's correct values with a broken
relative path instead of reinforcing them.
-
Look in the current working directory only. If there is no .atlas/ here, do nothing —
stop silently and proceed with the session normally.
-
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. Read 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. Write 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 /kimi-atlas:atlas-weave 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. Read the ledger, do not restart. Read 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.
5s. Resume from the last recorded stage. Re-enter the /kimi-atlas:atlas state machine at the stage
after the last one recorded done, in the same run (same run_id). Do not start a new
run, re-run completed stages, or re-capture intent. 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
If anything is ambiguous or 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.
