Appendix A - 7. Sentinel first-commit early-abort

The Structure of Sentinel first-commit early-abort — its shape at a glance:

The first commit is the trip-wire: assert the substrate is healthy, and abort the whole run early if any assertion fails, converting an hour of waste into a one-minute abort.

flowchart LR
  First[/First commit/] --> Assert{Substrate healthy?}
  Assert -->|all predicates pass| Continue([Run proceeds])
  Assert -->|any fails| Abort([Abort at t≈0])

Accessible description: on the agent's first commit a sentinel asserts a set of substrate-health predicates; if all pass the run proceeds, and if any fails the run aborts at minute zero rather than at minute sixty.

Projected from the catalogue entry gates-and-merge-train / Sentinel first-commit early-abort.

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

Intent

Intent — A health check on an agent's first commit that surfaces orphaned-worktree and broken-substrate failures at minute zero, before the agent burns its whole budget producing work that can never land.

Motivation

An agent dispatched into a subtly broken worktree (a missing marker file, stale substrate, an empty submodule, a wrong branch) will work happily for 30–60 minutes and then fail at commit, or produce work that cannot be rebased or cherry-picked. The failure is invisible until the end, so its cost is the entire dispatch: the whole agent budget spent on unlandable work. It recurs whenever the substrate drifts between dispatch and consumption, and compounds because each occurrence wastes a full run, not a small step.

Applicability

• A detectable "first commit" moment to hang the check on.
• Substrate-health predicates that are cheap and total (marker present, branch correct, CWD under worktree); the lifecycle substrate must expose checkable facts.
• An abort path that stops the run cleanly rather than letting it limp on.

Structure

The Structure diagram appears at the top of this page.

Sample Code

The check hangs on the first-commit event and asserts a set of cheap, total substrate-health predicates — correct worktree root, live marker present, expected branch, CWD inside the worktree. Any failure aborts the run before the budget is spent.

import os, sys

def substrate_healthy(agent_id: str, cwd: str, branch: str, marker_exists) -> list[str]:
    """Cheap, total predicates. Each failure is a reason to abort at t≈0."""
    problems = []
    root = os.environ.get("AGENT_WORKTREE_ROOT", "")
    if not root or not cwd.startswith(root):
        problems.append("CWD is not under the agent's worktree root")
    if not marker_exists(agent_id):
        problems.append("live marker file is missing")
    if branch != f"worktree-agent-{agent_id}":
        problems.append(f"on branch '{branch}', expected worktree-agent-{agent_id}")
    return problems

def on_first_commit(agent_id, cwd, branch, marker_exists) -> int:
    problems = substrate_healthy(agent_id, cwd, branch, marker_exists)
    for p in problems:
        print(f"SENTINEL ABORT: {p}")
    return 1 if problems else 0   # non-zero aborts the run at its first commit

Consequences

• It only catches what it asserts. The health predicates are a hand-maintained set; a new failure mode not in the predicate list still slips to t=60. The check is as good as its assertions.
• A false abort kills a healthy agent. An over-strict or drifted predicate blocks good work; the AUDIT-ONLY → BLOCKING migration exists precisely to buy confidence before it can do that.
• First-commit latency. Small, but it is on the critical path of every agent's first commit.

Example use within DocAble

• The sentinel check: the first-commit substrate assertion + early abort.
• The dispatch-self-check: the boot-time sibling.
• The sentinel-check discipline: land a substrate check at the first commit that runs end-to-end against the real brief (AUDIT-ONLY → BLOCKING).

Related Patterns

• Layer — runs at the same commit-time stair as pre-commit-hook: this guards substrate health, the hook guards content correctness.
• Counterpart — the boot-time dispatch-self-check: boot-check at t=0-start, sentinel at first-commit; together they bracket the window a substrate can break in.
• Enabler — the agent-registry markers (Lifecycle & observability family) are the facts this check reads. Without that substrate there is nothing to assert against.