HALT — Reliability for Long-Running AI Agents

English | 简体中文

HALT (Hierarchical Automaton for Long-horizon Tasks)

Keep long-running agents from losing work when the session ends.

Sessions die without warning, contexts fill up, executors get replaced midway — and the half-finished work usually lives only in a chat transcript nobody can fully trust. HALT is a reliability layer for exactly this problem: it makes progress durable, verifiable, and resumable, so work survives crashes, context loss, and executor changes without relying on chat history.

It ships in three forms: a normative specification (spec/), an installable agent skill (SKILL.md), and a dependency-free Python reference runtime (spec/runtime/).

Agents can claim progress. HALT only counts committed progress.

Agent:  "DONE."
HALT:   "Show me the artifact."
        exists → registered → checksummed → committed → DONE

What goes wrong without it

Failure	Without HALT	With HALT
Session dies mid-task	Guess from the transcript	Recompute from the journal
An agent reports DONE	Trust the claim	Demand a registered, checksummed artifact on disk
Crash leaves files inconsistent	Hand-reconcile until it looks right	Deterministic recovery (R0–R7) with the journal as truth
A different executor takes over	Infer context from chat	Establish the legal starting position
Someone asks "what did it actually do?"	Search chat logs	Replay one append-only ledger

Who this is for

Your situation	The decision you face	What HALT does
Task outlives one session (multi-hour builds, batch jobs over many items)	Resume from a chat summary — or from provable disk state?	Only write→verify→commit counts as progress; a fresh session recomputes its legal starting position from the journal
Work fans out to parallel workers or subagents	Trust reported DONE — or verify against disk?	Claim ≠ commit: DONE requires registered artifacts on disk; every failure class has a declared escalation route
You're about to build persistence and recovery into an agent or skill	Reinvent crash recovery from scratch — or adopt a field-tested one?	Lifecycle FSMs, canonical workspace layout, and a recovery procedure backed by 8 regression tests
A run went wrong and you need to know what actually happened	Reconstruct from scattered chat logs — or replay one ledger?	Every state transition cites its evidence; the conformance checklist makes runs auditable after the fact

Why this specification

Long-running agent work is usually framed as a capability problem — better models, better planning. HALT treats it as a reliability problem, orthogonal to whichever framework or model you use:

1. Field-validated. Every mechanism carries an evidence class (paper / practice / design); all four amendments trace to real incidents they now prevent (spec/12-validation-report.md).
2. Falsifiable. Field incidents are replayable as automated fixtures — the runtime's 8 tests are exactly those incidents, mechanized.
3. Executor-agnostic. The same specification has been executed by human-coordinated LLM agents, by plain Python, and packaged as an agent skill. Nothing binds to a model, framework, or vendor.
4. Honest about scope. Implemented vs. specified-but-not-implemented is declared explicitly in spec/11-conformance-and-derivations.md under "Known Limitations"; the runtime refuses loudly wherever the spec says "undefined".

Verify it, then use it

cd spec/runtime
python test_halt_rt.py        # expect: 8 passed

import os
from halt_rt import HaltRuntime

with HaltRuntime(workspace, task_id="my-task") as rt:   # fresh workspace; lease held inside
    rt.add_node("N1", "do thing")
    rt.transition("N1", "READY")
    rt.transition("N1", "RUNNING")

    # content hits disk BEFORE registration (PD-J1: no disk, no DONE)
    out = os.path.join(workspace, "artifacts", "N1", "n1-out.md")
    os.makedirs(os.path.dirname(out), exist_ok=True)
    open(out, "w").write("node N1 output")
    rt.register_artifact("A-N1", "artifacts/N1/n1-out.md", kind="doc", node_id="N1")
    rt.transition("N1", "VERIFYING", evidence=["A-N1"])
    rt.transition("N1", "DONE", evidence=["A-N1 verified"])
# lease released at scope exit

# ... crash happens ...
rt = HaltRuntime.resume(workspace)               # rebuild from the journal

Reading paths:

• Just the idea: spec/00-index.md → spec/01-core-model.md
• Implement it: spec/04-persistence-layout.md → spec/runtime/README.md
• Trust it: spec/12-validation-report.md → spec/provenance.md (Evidence Matrix)
• 中文读者：spec/zh/01-core-model.md

What it deliberately does NOT do

• No magic persistence. HALT is a discipline enforced by formats and checks, not a database. If the disk dies, the journal dies with it; Tier 2 dual-write exists for hostile environments, and nothing survives total media loss.
• No multi-node runtime yet. Parallel dispatch, nesting, and cross-task memory are fully specified but remain manual disciplines (HALT-06/07/10); the reference runtime is explicitly single-node, single-writer.
• No framework lock-in. Zero dependencies, zero vendor APIs. The specification is plain Markdown designed to outlive any particular agent product.
• No prediction of task duration or cost. HALT governs how work survives; estimating how long it takes is outside its scope.

Structure

SKILL.md          installable skill: operational entry layer over the spec
spec/             HALT v1.0.2 normative text — 00–12 + glossary + provenance
spec/runtime/     stdlib-only Python reference runtime (~470 lines) + 8 fixture tests
spec/zh/          Chinese edition of the core document

License

MIT — see LICENSE.