entropy-machines 0.1.1

package/bin/dispatch

@@ -0,0 +1,700 @@
+#!/bin/sh
+# Pre-flight gate for dispatching a writing agent.
+#
+#   bin/dispatch i-foo --files "src/x.ts tests/x.test.ts" --brief "one-line task"
+#
+# Exit 0 means SAFE TO DISPATCH; anything else names the hazard. It does not
+# spawn the agent — your agent runner does that — it refuses the mistakes
+# that have each burned a real run:
+#
+#   1. NON-ROOT CWD. A worktree is created in whatever repo the dispatching
+#      session's cwd belongs to. A session parked one directory off from the
+#      repo root has, more than once, handed an agent a worktree of the
+#      WRONG repository — none of the files it needed were in it. This
+#      checks the caller's cwd before anything else.
+#   2. UNCOMMITTED WORK INSIDE THE AGENT'S OWN FILE SCOPE. A worker's
+#      worktree branches from local HEAD, so unpushed commits are visible —
+#      nothing has to be pushed before dispatching. What is still invisible
+#      is uncommitted edits: hand an agent a file you are mid-edit in and it
+#      works from the committed version, and its result silently drops your
+#      changes. Only the declared scope is checked; a dirty tree elsewhere is
+#      none of this agent's business.
+#   3. ALREADY-LANDED WORK. If git log already mentions the issue id, the
+#      task may be partly or fully done. The audit comes before the dispatch.
+#   4. UNRECORDED BRIEFS. The brief + file scope are appended to the tracker
+#      notes log in the same act, so any session can see what was handed out
+#      and scopes can be checked for overlap before agents collide in a file.
+#
+# THE SCOPE LIST IS A DENYLIST, NOT AN ALLOWLIST. --files used to declare the
+# files the agent MAY write: a prediction made at the moment of least
+# information, by the one party who has not read the code, and correcting it
+# later costs a round trip. The dispatcher does not know what the agent will
+# need. It knows one thing that is true and small: which files OTHER agents
+# are holding right now, because it dispatched them. So the ENFORCED, PASTED
+# thing is the exclusion set, and --files stays an advisory prediction that
+# is still recorded for the audit trail.
+#
+# Every recorded scope failure under the old allowlist model was an
+# exclusion with nothing behind it: a shared, append-only interface file
+# left out of scope, so a change to it shipped undeclared; a wire-format
+# producer left out of scope because its directory wasn't listed, so a field
+# shipped with no writer; a worker's own brand-new changelog fragment
+# refused at landing purely because the scope line had been drawn too
+# narrow to get past a gate.
+#
+# THE CLAIM SET NEEDS NO NEW STATE. This script writes a DISPATCH note to the
+# tracker and bin/handoff writes the matching HANDOFF note that releases it,
+# so live claims are derivable from the notes log: an issue whose last event
+# is a DISPATCH holds its scope, a HANDOFF releases it, and a claim by the id
+# being dispatched now is not a claim against this agent. An unreachable
+# tracker degrades to "unavailable" and the context file tells the agent to
+# treat the advisory list as hard — an unreadable claim log is not an empty
+# one.
+#
+# COLLISION DETECTION STAYS AT THE LAND STEP. `bin/handoff --lift` compares
+# what the worker changed against the recorded denylist and refuses a
+# claimed file just as hard as an out-of-allowlist one used to be refused; a
+# file outside --files that nobody claimed is reported for the lander to
+# read, not refused.
+#
+# IT ALSO WRITES THE AGENT'S CONTEXT FILE. Everything this script already
+# knows was, for a long time, printed only to the DISPATCHER's terminal and
+# reached the agent only if a human retyped it. Measured over 224 subagent
+# transcripts / 152 worktree agents on an earlier version of this workflow: a
+# rule PASTED into the brief was followed ~96% of the time; the same rule
+# sitting only in a file the agent was told to go read was followed ~38%;
+# left unmentioned, ~8%. Compliance tracks what the brief PASTES, not what it
+# points at. So the issue text, the carry-forward notes, `git log --grep`,
+# the scope and the brief are all WRITTEN to a file, and the brief block's
+# first line is the absolute path to it.
+#
+# WHY A WORKTREE'S BASE IS LOCAL HEAD, AND WHY THAT NEEDS CHECK 1. Basing a
+# worktree on the pushed remote instead requires a push before every
+# dispatch, which serialises landing across concurrent sessions for no
+# safety benefit — agents are isolated by their worktree, not by their base
+# commit. Basing it on local HEAD instead means a worktree is created in
+# whatever repo the dispatching shell's cwd resolves to, so a session that
+# has drifted into a different directory gets a worktree of the WRONG repo
+# with no obvious symptom until the agent can't find its own files. Check 1
+# is what closes that.
+#
+# --anyway skips check 3 only (the git-log hits are still printed); checks 1
+# and 2 have no override — there is no correct dispatch from a wrong cwd or
+# over your own uncommitted edits.
+set -e
+
+usage() { echo "usage: bin/dispatch <issue-id> --files \"<paths>\" --brief \"<text>\" [--anyway] [--dry-run]" >&2; exit 2; }
+
+id=""; files=""; brief=""; anyway=0; dry=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --files) files="$2"; shift 2 ;;
+    --brief) brief="$2"; shift 2 ;;
+    --anyway) anyway=1; shift ;;
+    # Run every check and print the brief block, but write nothing to the
+    # log. Added after a smoke test of this script left a phantom DISPATCH
+    # note behind — a note that can be annotated but never removed, and that
+    # reads to any later session as an agent someone forgot to land.
+    --dry-run) dry=1; shift ;;
+    -*) usage ;;
+    *) [ -n "$id" ] && usage; id="$1"; shift ;;
+  esac
+done
+[ -n "$id" ] && [ -n "$files" ] && [ -n "$brief" ] || usage
+
+. "$(dirname "$0")/../lib/roots.sh"
+ENTROPY_MACHINES_HOME=$(entropy_machines_home "$0")
+entropy_machines_require_root dispatch
+CONFIG_PY="$ENTROPY_MACHINES_HOME/lib/config.py"
+NOTES_PY="$ENTROPY_MACHINES_HOME/lib/notes.py"
+LIBDIR="$ENTROPY_MACHINES_HOME/lib"
+: "${ENTROPY_ACTOR:=dispatch}"
+export ENTROPY_ACTOR
+
+cfg_get() { python3 "$CONFIG_PY" get "$1" 2>/dev/null; }
+
+if [ "$(pwd -P)" != "$ENTROPY_MACHINES_ROOT" ]; then
+  echo "dispatch: REFUSED — cwd is $(pwd -P), not the project root ($ENTROPY_MACHINES_ROOT)." >&2
+  echo "  Worktrees are created in the repo the dispatching session's cwd is in." >&2
+  echo "  Run:  cd $ENTROPY_MACHINES_ROOT" >&2
+  exit 1
+fi
+
+# The handoff gate is a commit-msg hook and nothing else — see
+# lib/handoff-guard.sh for why it is local-only by design. That makes an
+# uninstalled hook a silent total loss of the gate, in a checkout that looks
+# identical to one that has it. Checked HERE because dispatch is the last
+# moment before the only activity the gate protects.
+#
+# BOTH halves are checked: the installed shim, AND the checked-in hook it
+# delegates to. The hooks directory is SHARED by every worktree of this
+# repo, but the checked-in hook file it execs is per-worktree — so a
+# worktree whose checkout predates the hook has the shim, has a dead gate,
+# and checking only the shim would report OK.
+hooks=$(git rev-parse --git-path hooks)
+case "$hooks" in /*) ;; *) hooks="$ENTROPY_MACHINES_ROOT/$hooks" ;; esac
+if [ ! -x "$hooks/commit-msg" ]; then
+  echo "dispatch: REFUSED — no commit-msg shim in $hooks." >&2
+  echo "  Without it nothing requires a handoff when you land this agent, and the" >&2
+  echo "  only record of what it found and did not fix dies with its worktree." >&2
+  echo "  Run:  $ENTROPY_MACHINES_HOME/lib/install-hooks.sh" >&2
+  exit 1
+fi
+if [ ! -x "$ENTROPY_MACHINES_HOME/hooks/commit-msg" ]; then
+  echo "dispatch: REFUSED — the commit-msg shim is installed but the harness has" >&2
+  echo "  no hooks/commit-msg, so the shim exits 0 and the gate is dead." >&2
+  echo "  $ENTROPY_MACHINES_HOME is on a commit older than the hook." >&2
+  echo "  Merge or rebase the harness onto a commit that has it, or land this work" >&2
+  echo "  from a harness checkout that does." >&2
+  exit 1
+fi
+
+branch=$(git branch --show-current)
+head=$(git rev-parse --short HEAD)
+echo "dispatch: agent will branch from $branch @ $head (base: local HEAD)."
+
+# Uncommitted edits are invisible inside the worktree. Only a collision with
+# the agent's OWN declared scope is a hazard, so that is all this refuses on
+# — a dirty tree elsewhere is normal and none of this agent's business.
+#
+# Scope entries carry annotations ("path/(own)", "dir/*.md", "dir/") and the
+# matching logic that understands them lives in lib/notes.py — path_under()
+# — so this and every other scope check in this file and bin/handoff read
+# one annotation grammar the same way, instead of five independent sed
+# reimplementations of it.
+dirty=$(git status --porcelain 2>/dev/null | awk '{print $NF}')
+clash=$(python3 -c '
+import sys
+sys.path.insert(0, sys.argv[1])
+import notes as notes_mod
+scope = sys.argv[2].split()
+dirty = sys.argv[3].split()
+print(" ".join(d for d in dirty if notes_mod.path_under(d, scope)))
+' "$LIBDIR" "$files" "$dirty")
+if [ -n "$clash" ]; then
+  echo "dispatch: REFUSED — you have uncommitted edits inside the agent's own file scope:" >&2
+  for c in $clash; do echo "    $c" >&2; done
+  echo "  The agent inherits committed HEAD, so it would work from the old version" >&2
+  echo "  and its result would silently drop these edits. Commit them first." >&2
+  exit 1
+fi
+
+hits=$(git log --oneline --grep="$id" | head -5)
+if [ -n "$hits" ]; then
+  echo "dispatch: git log already mentions $id:" >&2
+  echo "$hits" >&2
+  if [ "$anyway" != "1" ]; then
+    echo "  Audit what landed before briefing (bin/tracker show $id), then rerun with --anyway." >&2
+    exit 1
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# THE DENYLIST — what OTHER agents are holding right now
+# ---------------------------------------------------------------------------
+# Derived from the shared notes log, which already carries both halves: this
+# script writes a DISPATCH note and bin/handoff writes a HANDOFF note that
+# releases it. Last event per id wins, so a re-dispatched issue reclaims its
+# files and a handed-off one releases them. No new state, no registry file.
+#
+# A CLAIM EXPIRES after DISPATCH_CLAIM_HOURS (default 24). The notes log is
+# append-only with no delete, so a dispatch that was never handed off would
+# otherwise hold its files forever, and the end state of an ever-growing
+# denylist is the allowlist this inversion exists to avoid, with worse
+# ergonomics. The changelog fragment directory, if configured, is never
+# claimable — every agent writes its own file there by design, so a claim on
+# the directory would wall every OTHER agent off its own fragment.
+#
+# THREE STATES, and they are not the same. A real list is enforced at lift.
+# An empty list ("(none)") means the log was read and nobody holds anything,
+# so every file is the agent's. "(unavailable)" means the log could not be
+# read at all, and that degrades to the OLD allowlist behaviour on both
+# ends: the context file tells the agent to treat --files as hard, and
+# bin/handoff falls back to refusing anything outside it. An unreadable
+# claim log is not an empty one.
+never_claimed=""
+if [ "$(cfg_get changelog.enabled)" = "true" ]; then
+  never_claimed=$(cfg_get changelog.fragmentDir)
+fi
+
+claims=""; deny=""; claim_lines=""; deny_ok=0
+if claims_raw=$("$ENTROPY_MACHINES_HOME/bin/tracker" notes 2>/dev/null); then
+  deny_ok=1
+  hours="${DISPATCH_CLAIM_HOURS:-24}"
+  if [ -n "$never_claimed" ]; then
+    claims=$(printf '%s\n' "$claims_raw" | python3 "$NOTES_PY" claims --self "$id" --hours "$hours" --exclude "$never_claimed" 2>/dev/null || true)
+  else
+    claims=$(printf '%s\n' "$claims_raw" | python3 "$NOTES_PY" claims --self "$id" --hours "$hours" 2>/dev/null || true)
+  fi
+  deny=$(printf '%s\n' "$claims" | awk -F'\t' '$1=="PATHS"{print $2}')
+  # One line per claiming issue, so the agent can see WHO holds a file and
+  # the lander can go ask them. A flat path list alone reads as an
+  # arbitrary wall.
+  claim_lines=$(printf '%s\n' "$claims" | awk -F'\t' '$1=="CLAIM"{printf "    %s\n        (claimed by %s)\n", $3, $2}')
+fi
+
+if [ "$deny_ok" -eq 0 ]; then deny_field="(unavailable)"
+elif [ -z "$deny" ]; then deny_field="(none)"
+else deny_field="$deny"; fi
+
+# --files overlapping a live claim is dispatch rule 3 — two issues in one
+# file serialize, they do not run concurrently. Printed, not refused:
+# re-dispatching an issue over its own predecessor's files is legitimate,
+# and the lander is the one who can tell that from a genuine collision. The
+# lift-side refusal is the mechanism; this is the early warning.
+overlap=$(python3 -c '
+import sys
+sys.path.insert(0, sys.argv[1])
+import notes as notes_mod
+files = sys.argv[2].split()
+deny = sys.argv[3].split()
+seen, out = set(), []
+for d in deny:
+    if d in seen:
+        continue
+    if any(notes_mod.paths_overlap(f, d) for f in files):
+        out.append(d); seen.add(d)
+print(" ".join(out))
+' "$LIBDIR" "$files" "$deny")
+if [ -n "$overlap" ]; then
+  echo "dispatch: WARNING — your --files overlaps a LIVE claim by another issue:" >&2
+  for o in $overlap; do echo "    $o" >&2; done
+  echo "  Two issues touching one file serialize; they do not run concurrently." >&2
+  echo "  Land or hand off the other agent first, or narrow this one." >&2
+  echo "  bin/handoff --lift will refuse these files when this agent returns." >&2
+fi
+
+# THE INTERROGATION FIELD. A note carrying it is an agent that was actually
+# told, in its own brief, that it would be questioned before its work was
+# lifted — that is what lets bin/handoff enforce a contract the agent was
+# actually given, rather than one invented at landing time. Notes without it
+# — hand-done work, or a note written before this landed — are reported and
+# never refused.
+interrogation_field="required"
+
+if [ "$dry" -eq 1 ]; then
+  echo "dispatch: --dry-run — all checks passed, nothing recorded. Would log a"
+  echo "  DISPATCH note: scope=$files brief=$brief interrogation=$interrogation_field denylist=$deny_field"
+else
+  if [ "$deny_ok" -eq 1 ]; then
+    payload=$(python3 "$NOTES_PY" encode --verb DISPATCH --actor "$ENTROPY_ACTOR" \
+      --field "brief=$brief" --field "interrogation=$interrogation_field" \
+      --field "scope=$files" --field "denylist=$deny")
+  else
+    payload=$(python3 "$NOTES_PY" encode --verb DISPATCH --actor "$ENTROPY_ACTOR" \
+      --field "brief=$brief" --field "interrogation=$interrogation_field" \
+      --field "scope=$files")
+  fi
+  if ! out=$("$ENTROPY_MACHINES_HOME/bin/tracker" remember --issue "$id" "$payload" 2>&1); then
+    echo "dispatch: REFUSED — could not record the brief on $id." >&2
+    echo "  bin/tracker said: $out" >&2
+    echo "  Nothing is dispatched blind: without this note, no other session can" >&2
+    echo "  see what was handed out, and the denylist above is unrecorded. Fix" >&2
+    echo "  the tracker (docs/TRACKER-ADAPTER.md, docs/CONFIG.md) and rerun." >&2
+    exit 1
+  fi
+
+  # CLAIM THE ISSUE IN THE SAME ACT THAT RECORDS THE BRIEF. Recording a
+  # DISPATCH note with no claim left status untouched, so a second session
+  # could see an issue with a live agent on it as free work. The adapter's
+  # `claim` op does this atomically and is never fatal here — losing the
+  # dispatch over a claim hiccup would be worse than an unclaimed issue.
+  if claim_out=$("$ENTROPY_MACHINES_HOME/bin/tracker" claim "$id" 2>&1); then
+    case "$claim_out" in
+      *'"claimed": false'*|*'"claimed":false'*)
+        echo "dispatch: NOTE — $id is not notstarted; not claiming it. Re-dispatching" >&2
+        echo "  finished or already-progressing work is a correction; set the status" >&2
+        echo "  yourself if that is what you mean." >&2 ;;
+      *) echo "dispatch: $id claimed." ;;
+    esac
+  else
+    claim_rc=$?
+    if [ "$claim_rc" -eq 4 ]; then
+      echo "dispatch: WARNING — $id is already claimed by another actor: $claim_out" >&2
+    else
+      echo "dispatch: WARNING — could not claim $id; it may still read unclaimed to other sessions ($claim_out)." >&2
+    fi
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# THE AGENT'S CONTEXT FILE
+# ---------------------------------------------------------------------------
+# WHY A FILE AND NOT MORE TERMINAL OUTPUT. Whether the tracker and any local
+# docs directory are reachable from inside a worktree depends on this
+# project's config.json worktree.linkPaths and on whether this clone's
+# hooks are installed — don't assume either way. The one channel that
+# reliably lands is what the brief PASTES (see the measured numbers in the
+# header), so everything is written here and the brief's first line is this
+# file's path.
+#
+# WHY PER-ISSUE AND NOT A SINGLE FILE AT THE ROOT. A dispatch round briefs N
+# agents back to back from one checkout; a fixed filename means agent A's
+# file is overwritten by agent B's dispatch before A ever reads it, and A
+# then reads B's issue, scope and brief as its own — worse than absent,
+# because nothing looks wrong. One file per issue cannot collide.
+#
+# WHY IT LIVES IN THE MAIN CHECKOUT. It is untracked, and `git worktree add`
+# materialises a commit — untracked files are not carried in. So the path
+# printed in the brief is ABSOLUTE and points back at this checkout, which
+# the agent can read (its worktree lives under it).
+ctxdir="$ENTROPY_MACHINES_ROOT/.dispatch-context"
+ctx="$ctxdir/$id.md"
+
+# The three carry-forward fields an incoming agent can act on, read out of
+# the LAST HANDOFF note on this issue via lib/notes.py's verb-anchored
+# lookup (not a free-text scan). verified/scope-released are the lander's
+# bookkeeping, not the next agent's context, so they are left out.
+notes_raw=$("$ENTROPY_MACHINES_HOME/bin/tracker" notes --issue "$id" 2>/dev/null || true)
+carry=$(printf '%s\n' "$notes_raw" | python3 "$NOTES_PY" record --issue "$id" --verb HANDOFF --last 2>/dev/null | python3 -c '
+import json, sys
+line = sys.stdin.readline()
+if not line.strip():
+    raise SystemExit(0)
+rec = json.loads(line)
+fields = rec.get("fields") or {}
+for key, label in (("next", "next-agent"), ("found", "found-not-fixed"), ("assumed", "assumed")):
+    v = fields.get(key)
+    if not v:
+        continue
+    items = v if isinstance(v, list) else [v]
+    for item in items:
+        item = str(item).strip()
+        if item:
+            print(f"    - [{label}] {item}")
+' 2>/dev/null || true)
+
+# Human-readable rendering of a JSONL note stream, shared by the context
+# file's notes section and the terminal's PRIOR NOTES section below. Reads
+# already-parsed records (json.loads per line) — the note-format parsing
+# itself (verb anchoring, scope grammar) stays in lib/notes.py; this only
+# formats fields for a person to read.
+render_notes() {
+  python3 -c '
+import json, sys
+any_line = False
+for line in sys.stdin:
+    line = line.strip()
+    if not line:
+        continue
+    try:
+        r = json.loads(line)
+    except json.JSONDecodeError:
+        continue
+    any_line = True
+    ts, verb, actor = r.get("ts", "?"), r.get("verb", "?"), r.get("actor", "?")
+    fields = r.get("fields") or {}
+    parts = []
+    for k in sorted(fields):
+        v = fields[k]
+        if isinstance(v, list):
+            v = ", ".join(str(x) for x in v)
+        parts.append(f"{k}: {v}")
+    print(f"  [{ts}] {verb} (by {actor}) " + " | ".join(parts))
+if not any_line:
+    print("  (none)")
+'
+}
+
+if [ "$dry" -eq 0 ]; then
+  issue_json=$("$ENTROPY_MACHINES_HOME/bin/tracker" show "$id" 2>&1) || issue_json="UNAVAILABLE — bin/tracker could not be reached. It said:
+
+$issue_json
+
+Whether the tracker is reachable from inside your worktree depends on this
+project's config.json worktree.linkPaths and on whether this clone's hooks
+are installed. Ask the dispatching session for the issue text if you need it."
+
+  notes_rendered=$(printf '%s\n' "$notes_raw" | render_notes)
+
+  # Not capped: an id with a long history is exactly the case the audit is
+  # for.
+  landed=$(git log --oneline --grep="$id" || true)
+  [ -n "$landed" ] || landed="(nothing — git log --oneline --grep=$id is empty; no commit in this checkout names this issue)"
+
+  carry_text="$carry"
+  [ -n "$carry_text" ] || carry_text="(nothing recorded — no earlier HANDOFF note on this issue)"
+
+  suites_text=$(cfg_get suites | python3 -c '
+import json, sys
+try:
+    suites = json.loads(sys.stdin.read() or "[]")
+except Exception:
+    suites = []
+if not suites:
+    print("  (none configured — see config.json suites)")
+for s in suites:
+    name = s.get("name", "?")
+    cmd = " ".join(s.get("cmd") or [])
+    tag = s.get("tag")
+    suffix = " [" + tag + "]" if tag else ""
+    print("  " + name + suffix + ": " + cmd)
+')
+
+  link_paths=$(cfg_get worktree.linkPaths)
+
+  mkdir -p "$ctxdir"
+  {
+    echo "# Dispatch context — $id"
+    echo
+    echo "Written by bin/dispatch on $(date -u '+%Y-%m-%dT%H:%M:%SZ') from $ENTROPY_MACHINES_ROOT ($branch @ $head)."
+    echo "READ THIS BEFORE YOU DO ANYTHING ELSE. Everything you cannot look up for"
+    echo "yourself was captured here at dispatch time — whether the tracker and any"
+    echo "local docs directory are reachable from your worktree depends on this"
+    echo "project's config.json worktree.linkPaths and on whether this clone's"
+    echo "hooks are installed; don't assume either way."
+    echo
+    echo "## Files you must NOT write — CLAIMED by another agent right now"
+    echo
+    if [ "$deny_ok" -eq 0 ]; then
+      echo "    UNAVAILABLE — bin/tracker could not be reached, so the live-claim"
+      echo "    log could not be read. Treat the advisory list below as a HARD"
+      echo "    boundary instead: an unreadable claim log is not an empty one."
+    elif [ -z "$deny" ]; then
+      echo "    (none — no other issue holds a live claim this round)"
+      echo
+      echo "Every file in this repo is yours to write if the fix genuinely needs it."
+    else
+      echo "$claim_lines"
+      echo
+      echo "Every OTHER file in this repo is yours to write if the fix genuinely"
+      echo "needs it. Say in HANDOFF.md's changed: line what you took beyond the"
+      echo "advisory list below, so the lander reads that diff on purpose."
+    fi
+    echo
+    echo "Derived from the shared notes log, not from a guess: an issue whose last"
+    echo "event is a DISPATCH holds its scope, a HANDOFF releases it, and a claim"
+    echo "by this issue's own id is not a claim against you."
+    echo
+    echo "### If your fix needs a CLAIMED file: STOP AND REPORT. This is a refusal,"
+    echo "### not a preference."
+    echo
+    echo "An agent that finds it needs a claimed file has three options — write it"
+    echo "anyway and risk clobbering a concurrent agent, ship the half it was"
+    echo "allowed to write, or stop. This workflow has, more than once, watched an"
+    echo "agent take the middle option and report success: two halves of one"
+    echo "change individually green, the change itself broken, because each half"
+    echo "was written by an agent that could not reach the other's file. Neither"
+    echo "agent said it was blocked. The cost lands on the lander, who is the one"
+    echo "context that can see both halves — exactly the serialisation this model"
+    echo "exists to avoid. So:"
+    echo
+    echo "  1. STOP at the boundary. Do not write the claimed file, and do not"
+    echo "     ship the half of the change that does not work without it."
+    echo "  2. Leave the in-scope work UNCOMMITTED AND COHERENT — it must build"
+    echo "     and test on its own. If it cannot, say so in changed: rather than"
+    echo "     leaving a green half that is wrong on the wire."
+    echo "  3. Put the blocked half in HANDOFF.md's found: line, naming the EXACT"
+    echo "     file and what it must contain. 'needed a file outside scope' is"
+    echo "     not enough for the lander to finish it."
+    echo "  4. Say the same in your final report, in the same words."
+    echo
+    echo "WHAT ENFORCES THIS: nothing mechanical, and pretending otherwise would be"
+    echo "worse than saying it. Nothing can detect a half-change from outside — the"
+    echo "mechanism is this wording plus the lander reading your found: line, and"
+    echo "bin/handoff refuses a record with no --found and no --next unless the"
+    echo "lander passes --clean as a positive claim."
+    echo
+    echo "## What the dispatcher expected you to touch — ADVISORY, not a boundary"
+    echo
+    echo "    $files"
+    echo
+    echo "This is a prediction made before anyone read the code, by the party that"
+    echo "has not read it. It is recorded for the audit trail and it is NOT the"
+    echo "limit of what you may write. The enforced limit is the claimed list above."
+    echo
+    echo "## Your brief"
+    echo
+    echo "    $brief"
+    echo
+    echo "## You will be QUESTIONED before your work is lifted"
+    echo
+    echo "When you stop, you are still resumable and you still hold context nobody"
+    echo "else has. The lander will put these questions to you and record your"
+    echo "answers on the issue; bin/handoff refuses to record the landing until it"
+    echo "has them. Gather them AS YOU WORK — they are much harder to reconstruct"
+    echo "afterwards, and a wrong answer is worse than a blank one."
+    echo
+    qs=$("$ENTROPY_MACHINES_HOME/bin/handoff" "$id" --questions 2>/dev/null || true)
+    if [ -n "$qs" ]; then echo "$qs"
+    else echo "  (unavailable — bin/handoff --questions could not be read here)"; fi
+    echo
+    echo "None of these can be answered with \"no\", and that is deliberate. Both"
+    echo "recorded half-changes above were reported as successes by the agent that"
+    echo "shipped them, so \"are you complete?\" is worse than asking nothing. At"
+    echo "least one of your answers must be substantive — \"nothing\" across the"
+    echo "whole set is refused, so silence has to be a claim you made rather than"
+    echo "an absence."
+    echo
+    echo "## The issue (bin/tracker show $id)"
+    echo
+    echo "$issue_json"
+    echo
+    echo "## This issue's notes (bin/tracker notes --issue $id)"
+    echo
+    echo "$notes_rendered"
+    echo
+    echo "## What already landed for this issue (git log --oneline --grep=$id)"
+    echo
+    echo "IF THIS IS NON-EMPTY, AUDIT IT BEFORE WRITING CODE. An issue whose desc has"
+    echo "gone stale reads as unstarted work — treat a non-empty match as a reason"
+    echo "to look before reimplementing something that already landed under this id."
+    echo
+    echo "$landed"
+    echo
+    echo "## What earlier work on this issue left you"
+    echo
+    echo "$carry_text"
+    echo
+    echo "## This project's suites (config.json)"
+    echo
+    echo "$suites_text"
+    echo
+    echo "Never run this project's full build/release command in your worktree —"
+    echo "some rewrite committed bookkeeping (a collated changelog, a checkpoint"
+    echo "file) as a side effect. Use the suites above."
+    echo
+    echo "## Shared paths linked into your worktree, IF this clone's hooks are"
+    echo "## installed (config.json worktree.linkPaths: ${link_paths:-[]})"
+    echo
+    echo "Don't assume either way — a resolver that can't find a dependency here"
+    echo "will sometimes walk up and resolve it out of a SIBLING agent's worktree"
+    echo "instead, which means testing someone else's code and reporting it as"
+    echo "yours. If a suite refuses to run because it can't resolve its own"
+    echo "dependencies, that is the refusal working as designed — don't work"
+    echo "around it by hand."
+    echo
+    echo "## Before you finish: write HANDOFF.md at the root of YOUR worktree"
+    echo
+    echo "Exactly these four keys, ONE LINE each, no prose, under six lines total:"
+    echo
+    echo "    changed: <what you changed>"
+    echo "    found:   <seen but not fixed, out of scope — or: none>"
+    echo "    assumed: <what you took as given — or: none>"
+    echo "    next:    <what the next agent needs to know — or: none>"
+    echo
+    echo "Do not commit it; it is gitignored. found and next are why the file exists"
+    echo "— your diff already says what changed. Do not commit, push or merge anything"
+    echo "at all: the dispatching session lifts your worktree and lands it."
+  } > "$ctx"
+  echo "dispatch: context written — $ctx"
+fi
+
+# The issue's own note thread, printed at the moment a brief is being
+# written, so a prior agent's findings on the same issue don't stay unread
+# by the next one. This was fetched BEFORE the DISPATCH note above was
+# written, so it is naturally prior — no filtering needed.
+if [ -n "$notes_raw" ]; then
+  echo
+  echo "PRIOR NOTES ON $id — read before briefing; fold anything load-bearing into the brief:"
+  printf '%s\n' "$notes_raw" | render_notes | sed 's/^/  /'
+fi
+
+echo
+if [ "$dry" -eq 1 ]; then
+  echo "dispatch: OK (dry run) — nothing recorded on $id."
+else
+  echo "dispatch: OK — brief + scope recorded on $id."
+fi
+echo "Dispatch the worker defined in agents/isolated-worker.md."
+echo "  Claude Code: Agent tool, subagent_type: isolated-worker."
+echo "  A different runner: give it its own worktree, this brief directly (not"
+echo "  just pointed at it), and a way for you to read back its HANDOFF.md —"
+echo "  see the note at the top of agents/isolated-worker.md."
+echo "  issue: $id"
+echo "  advisory --files: $files"
+echo "  ENFORCED denylist: $deny_field"
+echo "  brief: $brief"
+echo
+# Pasted verbatim into the agent's brief. Four keys, one line each, and the
+# instruction says so twice — an agent given a free-form "write up what you
+# found" returns prose the lander then has to read and compress, which is
+# the work this was meant to remove. The file is gitignored, so the agent
+# cannot accidentally add it to the tree.
+echo "PASTE INTO THE AGENT'S BRIEF:"
+echo "  BRIEF: $brief"
+echo
+# FIRST LINE after the brief, and the load-bearing one — see the measured
+# numbers in the header. This holds regardless of whether your runner
+# auto-loads a project-instructions file into subagents: proximity to the
+# prompt is what changes behaviour, not presence in context.
+echo "  FIRST, before anything else: read this file, in full, with one Read:"
+echo "    $ctx"
+echo "  It is your issue text, what already landed under this id, your scope and"
+echo "  brief, what earlier agents left you, and this project's suites. It is in"
+echo "  the MAIN checkout, NOT in your worktree; the path above is absolute, use"
+echo "  it as-is."
+if [ "$dry" -eq 1 ]; then
+  echo "  (--dry-run: that file was NOT written. Rerun without --dry-run.)"
+fi
+# The cwd check, stated to the AGENT. This script already refuses a
+# non-root cwd, but that runs when the brief is written and the dispatch
+# call happens after — a `cd` in between still misroutes the worktree, and
+# has once taken out three agents at once this way. Nothing in the tool
+# chain can catch that on the way in, so the agent checks on the way out.
+#
+# --git-common-dir answers WHICH REPO IS THIS A WORKTREE OF. From a linked
+# worktree it resolves to the MAIN repo's .git as an ABSOLUTE path, so it
+# carries the repo's own path. From a non-worktree checkout at its root it
+# prints a bare relative `.git`, which is why the wording calls that out as
+# its own reportable state rather than leaving the agent to interpret it.
+# --show-toplevel is the wrong check here: it prints the WORKTREE's own
+# path, which can never equal the main repo's path, so it can never confirm
+# which repo the worktree belongs to.
+echo "  Your scope is a DENYLIST, not an allowlist. These files are claimed by"
+echo "  another agent RIGHT NOW and you must NOT write them: $deny_field"
+echo "  Everything else is yours if the fix needs it. If your fix needs a CLAIMED"
+echo "  file: STOP — do not write it, and do NOT ship the half you were allowed"
+echo "  to write. Leave the in-scope work coherent and name the exact file and"
+echo "  what it must contain in HANDOFF.md's found: line. The context file above"
+echo "  has the full protocol and says what does and does not enforce it."
+echo "  SECOND, before you write anything: run \`git rev-parse --git-common-dir\`."
+echo "  It prints the MAIN repo's .git — which repo your worktree branched from."
+echo "  It MUST contain /$(basename "$ENTROPY_MACHINES_ROOT")/. A bare relative \`.git\` means you"
+echo "  are not in a worktree at all: report that."
+echo "  If either is wrong, STOP and report it. NEVER cd to make it pass and"
+echo "  never write to the shared checkout — a cd is the failure, not the fix."
+echo "  Do NOT use --show-toplevel here: yours is the worktree path, so it can"
+echo "  never end in /$(basename "$ENTROPY_MACHINES_ROOT") and tells you nothing about the repo."
+# THE SCRATCHPAD, IN THE PASTE BLOCK RATHER THAN ONLY IN A DOC. The same
+# measurement that shapes the rest of this block puts a pasted rule at ~96%
+# and one sitting only in a doc the agent was told to go read at far less —
+# and a scratchpad the worker never hears about is the shared one it was
+# already using.
+echo "  YOUR PRIVATE SCRATCHPAD is \`.scratch\` at the root of your worktree —"
+echo "  mutators, probe harnesses, captured suite output go THERE, not in any"
+echo "  scratchpad shared with the agents running beside you. Two concurrent"
+echo "  agents have overwritten each other's throwaway files by both reaching"
+echo "  for a shared scratch directory instead. If a tool refuses to write"
+echo "  through .scratch, say so in HANDOFF.md — do not fall back to a shared"
+echo "  scratchpad silently."
+# Earlier agents' carry-forward lines, INSIDE the paste block rather than
+# only in the context file above it, for the same measured reason.
+if [ -n "$carry" ]; then
+  echo "  WHAT EARLIER WORK ON THIS ISSUE LEFT YOU (you may not be able to look"
+  echo "  this up yourself — see the context file for how to check):"
+  echo "$carry"
+  echo
+fi
+echo "  Before you finish, write HANDOFF.md at the root of your worktree."
+echo "  Exactly these four keys, ONE LINE each, no prose:"
+echo "    changed: <what you changed>"
+echo "    found:   <seen but not fixed, out of scope — or: none>"
+echo "    assumed: <what you took as given — or: none>"
+echo "    next:    <what the next agent needs to know — or: none>"
+echo "  Keep it under six lines total. Do not commit it; it is gitignored."
+echo "  AFTER YOU STOP YOU WILL BE QUESTIONED, while you are still resumable, and"
+echo "  your work is not lifted until your answers are recorded. The questions are"
+echo "  adversarial on purpose — what you did NOT run, which of your assertions is"
+echo "  weakest, what you took on trust, what in the brief you skipped, what you"
+echo "  would check next. They are listed in the context file above; note the"
+echo "  answers as you work. \"Nothing\" to every one of them is refused."
+echo
+echo "WHEN YOU LAND IT, before committing:"
+echo "  bin/handoff $id --interrogate                     # the questions; send them to the LIVE agent"
+echo "  bin/handoff $id --record-interrogation --answer \"...\"   # what it said"
+echo "  bin/handoff $id --from <agent-worktree> --lift    # copies the files IN, refusing any that drifted"
+echo "  ...then verify in THIS tree, then:"
+echo "  bin/handoff $id --from <agent-worktree> --verified \"what YOU re-ran\""
+echo "  (or spell the fields out: --changed \"...\" [--found \"...\"] [--next \"...\"] [--clean])"
+echo "  The commit-msg hook refuses a commit naming $id until that exists."