Appendix A - 13. Agent registry (append-only log + marker cache)

The Structure of Agent registry (append-only log + marker cache) — its shape at a glance:

Every lifecycle tool dual-writes the append-only log and a fast marker cache; the log is authoritative, and a cleanup gate queries a chain of it before reclaiming anything.

flowchart LR
  Tools[Lifecycle tools] -->|dual-write| Log[(Append-only registry)]
  Tools -->|dual-write| Cache[(Marker cache)]
  Log -->|authoritative| Gate{cleanup / tombstone gate}
  Cache -->|fast index| Gate
  Gate -->|marker present = live| Refuse([Refuse to reclaim])

Accessible description: every lifecycle tool dual-writes an append-only registry and a fast marker cache; the registry is authoritative and the cache a fast index; a cleanup or tombstone gate reads them and refuses to reclaim any agent whose live marker is present.

Projected from the catalogue entry lifecycle-and-observability / Agent registry (append-only log + marker cache).

On this page: Intent · Motivation · Applicability · Structure · Sample Code · Consequences · Example use within DocAble · Related Patterns

Intent

Intent — An append-only registry, dual-written by every lifecycle tool, that is the authoritative record of which agents are in flight, so cleanup, tombstone, and merge decisions read a fact instead of guessing from filesystem timestamps.

Motivation

With a fleet of concurrent agents living in worktrees, "which agents are live right now?" is the central question for every reclaim decision: cleanup, tombstoning, merge readiness. Answer it by scanning worktree directories and comparing mtimes and you get a heuristic that races with live agents: an agent mid-work can look identical to a stale one and have its worktree destroyed under it (the worktree-destruction-mid-flight incident). The failure is unsafe reclaim of live work, and it recurs on every cleanup pass.

Applicability

• Universal dual-write. Every lifecycle tool writes the registry; a side-door mutation that skips it reintroduces the exact race the registry removes.
• An append-only log plus a fast cache, and a rule for which wins on divergence (registry).
• Destructive-op gates that query it before acting; the record is only protective if consulted.

Structure

The Structure diagram appears at the top of this page.

Sample Code

Liveness becomes a lookup against a recorded fact, not an inference from a timestamp. Every lifecycle tool appends to the log; a reclaim gate reads it and refuses to touch an agent still marked live — the recorded fact cannot race the way an mtime can.

import json, os

REGISTRY = "agent-registry.jsonl"

def record(agent_id: str, event: str) -> None:
    with open(REGISTRY, "a") as f:                    # append-only: every tool dual-writes here + a marker
        f.write(json.dumps({"agent": agent_id, "event": event}) + "\n")
    open(f".markers/{agent_id}", "w").close() if event == "dispatched" else None

def is_live(agent_id: str) -> bool:
    state = None
    for line in open(REGISTRY):                        # registry wins over the cache on any divergence
        row = json.loads(line)
        if row["agent"] == agent_id:
            state = row["event"]
    return state == "dispatched"

def may_reclaim(agent_id: str) -> bool:
    return not is_live(agent_id)                       # gate consults the fact before any destructive op

Consequences

• The whole registry rests on dual-write discipline, and it's fragile. One tool that mutates lifecycle without writing the registry silently brings the mtime-race back; the guarantee is only as strong as the weakest writer.
• Append-only growth. The JSONL grows unboundedly and needs rotation.
• Registry/marker divergence is possible if one write fails; resolved by "registry authoritative," but the cache can briefly mislead a tool that trusts it alone.

Example use within DocAble

• An append-only registry log + per-agent marker cache, dual-written by the dispatch wrapper's prepare step.
• The 3-gate cleanup-stale chain (registry → marker → git-lock).
• The live-worktree guard (never operate on an agent whose marker exists); the dedup-via-registry pattern.

Related Patterns

• Enabler — merge-train-mis-batching reads it for worktree readiness; sentinel-first-commit reads its markers for substrate health.
• Consumer — tombstone-commits checks live markers before writing a close record; cleanup-stale consults it before removing a dir.
• Counterpart — it replaced the mtime heuristic (now retired): the authoritative record is the hard fact that the racy signal could never be.