resume

AgenTeam Resume

Resume an interrupted pipeline run. Detects stale runs, verifies the

last incomplete stage before continuing, and lets the user choose how

to proceed.

Process

1. Detect Resumable Runs

python3 <runtime>/agenteam_rt.py resume-detect

Parse the JSON output:

• No resumable runs (resumable_runs is empty):

Tell the user: "No interrupted runs found." Stop.

• One resumable run:

Show summary: run_id, task, interrupted stage, last update time.

Proceed to step 2.

• Multiple resumable runs:

List all with run_id, task, stage, and age (time since last_update).

Ask the user which to resume. Proceed with their choice.

2. Get Resume Plan

python3 <runtime>/agenteam_rt.py resume-plan --run-id <run_id>

This returns a structured plan with all the information needed to

decide how to resume: pipeline_mode, config drift status, interrupted

stage details (verify, gate, baseline), completed and remaining stages.

3. Pipeline Mode Check

Read pipeline_mode from the resume plan:

• standalone: Continue with the verify-first flow below (step 4+).

• hotl: This run was managed by HOTL's execution engine. Tell the

user: "This is a HOTL-managed run. Resume with /hotl:resume <workflow-file>

instead." Stop. AgenTeam does not resume HOTL-managed runs — HOTL owns

the step-level state and verify-first logic for those runs.

• dispatch-only: Dispatch-only runs have no pipeline to resume.

Tell the user: "Dispatch-only runs have no pipeline to resume.

Re-assign tasks with @<Role> <task>." Stop.

4. Config Drift Check

If config_hash_match is false:

• Warn: "Config has changed since this run started (agenteam.yaml was

modified). The run will use the original stage definitions from when

it was created. Continue anyway? (yes/no)"

• If the user says no: stop.
• If yes: continue. Run-scoped commands use state snapshots, so config

drift is safe — but the user should know.

5. Verify-First

Check interrupted_stage from the resume plan:

If has_verify is true AND verify_safe is true:

Run the verify command to check if the interrupted work actually

completed:

bash <plugin-dir>/scripts/verify-stage.sh run "<verify_command>" --cwd "<cwd>"

• Verify passes: The interrupted stage's work is actually done.

Transition the stage forward:

  python3 <runtime>/agenteam_rt.py transition --run-id <run_id> \
    --stage <stage> --to passed

Then follow normal gating flow:

• If has_gate is true: transition to gated, present gate to user.
• If has_gate is false: transition to completed, continue to

next stage.

Emit resume event:

  python3 <runtime>/agenteam_rt.py event append --run-id <run_id> \
    --type stage_resumed --stage <stage> \
    --data '{"verify_result": "pass", "action": "advance"}'

• Verify fails: Present choice (step 6).

If has_verify is false OR verify_safe is false:

Skip verify-first. Go directly to choice (step 6).

6. Choice

Show the user a resume summary:

• Stage name, current status, last update time
• If verify was run: show the result

Offer three options:

• Resume persisted attempt (preferred): Inspect the interrupted stage's

latest attempts[] record. If it has a thread_id, continue through the

runtime harness:

  python3 <runtime>/agenteam_rt.py run --run-id <run_id>

The runner issues codex exec resume <thread_id> -, preserves the attempt

chain, and continues the stored retry budget. Do not launch a second agent

while the recorded PID is live.

• Re-dispatch: Use only when no resumable thread_id exists and prior

side effects have been verified. A fresh redispatch requires explicit approval.

  python3 <runtime>/agenteam_rt.py transition --run-id <run_id> \
    --stage <stage> --to dispatched
  python3 <runtime>/agenteam_rt.py event append --run-id <run_id> \
    --type stage_resumed --stage <stage> \
    --data '{"verify_result": "fail", "action": "redispatch"}'

Then launch subagents and continue the pipeline from this stage.

• Preserve and replay: Query the stage baseline without changing the

checkout:

  python3 <runtime>/agenteam_rt.py stage-baseline --run-id <run_id> \
    --stage <stage> --action rollback

If allowed is true, save the current diff to

.agenteam/runs/<run_id>/<stage>/resume-recovery.patch. Offer to create a

new clean branch/worktree from the baseline and replay there. Never discard

or rewrite the current dirty checkout automatically.

If allowed is false: tell user rollback is not available in this

isolation mode.

• Stop: End the run.

  python3 <runtime>/agenteam_rt.py event append --run-id <run_id> \
    --type run_finished --data '{"status": "stopped"}'

7. Continue Pipeline

After resuming the interrupted stage (via verify-pass advance or

re-dispatch), continue through the remaining stages using the same

standalone pipeline flow from skills/run/SKILL.md step 6.

The remaining stages are listed in the resume plan's remaining_stages

array. Process each one in order through the standard dispatch → verify

→ gate → handoff flow.

During continuation, report thread_id, last heartbeat, heartbeat age, wall

and idle budget remaining, attempt/retry counts, and stop reason. Runtime state

is the source of truth; chat messages are not checkpoints.

Headless Policy

When CI=true or no TTY detected:

• Skip run selection (if multiple, use the most recent stale run)
• Skip config drift confirmation (proceed with warning to stderr)
• Verify-first always runs (if safe)
• If verify passes → continue automatically
• If verify fails → emit run_finished with status: failed and

reason: "resume-verify-failed-headless". Do not prompt.

• stopped is user-chosen; failed is system-determined

Runtime Path Resolution

Resolve the AgenTeam runtime:

1. If running from the plugin directory: ./runtime/agenteam_rt.py
2. If installed as a Codex plugin: <plugin-install-path>/runtime/agenteam_rt.py

Resolve scripts:

1. If running from the plugin directory: ./scripts/
2. If installed as a Codex plugin: <plugin-install-path>/scripts/

Error Handling

• If resume-detect fails: show error, suggest checking .agenteam/state/
• If resume-plan fails (run not found): show error with run_id
• If verify command fails to execute (not just fails the check): show

error and fall back to choice

• If transition fails (invalid state): show error with current status

and valid transitions