entropy-machines 0.1.7 → 0.1.8

package/bin/dispatch

@@ -199,6 +199,17 @@ if [ -n "$hits" ]; then
   fi
 fi
 
+# CHECK — issue existence. A nonexistent issue is usually a typo. Checked
+# after scope/history so safety guards always fire first.
+if ! "$ENTROPY_MACHINES_HOME/bin/tracker" show "$id" >/dev/null 2>&1; then
+  if [ "$force" != "1" ]; then
+    echo "dispatch: REFUSED — issue '$id' not found in the tracker." >&2
+    echo "  Check the id for typos, or pass --force to dispatch anyway." >&2
+    exit 1
+  fi
+  echo "dispatch: WARNING — issue '$id' not found in the tracker (--force overrides)."
+fi
+
 # CHECK 4 — recently-touched files. A declared file that was touched in the
 # last 5 commits on any branch is hot: the change may still be landing, the
 # agent may be re-doing work that already shipped, or the base commit already
@@ -661,6 +672,7 @@ fi
 echo
 if [ "$dry" -eq 1 ]; then
   echo "dispatch: OK (dry run) — nothing recorded on $id."
+  exit 0
 else
   echo "dispatch: OK — brief + scope recorded on $id."
 fi

package/bin/dispatch-gate

@@ -0,0 +1,116 @@
+#!/bin/sh
+# PreToolUse hook: refuse Agent calls for tracked issues that have no
+# DISPATCH note in the tracker log. Forces all issue work through the
+# dispatch pipeline (bin/dispatch-run → worktree → auto-verify → handoff).
+#
+# Same mechanism as bin/no-fork-gate. Registered in .claude/settings.json
+# as a PreToolUse hook on "Agent".
+#
+# WHAT IT CHECKS:
+#   1. Does the Agent call's prompt mention a tracked issue id (i-<slug>)?
+#   2. If so, does the tracker's note log have a DISPATCH note for that id?
+#   3. If no DISPATCH note, REFUSE — the agent must go through dispatch.
+#
+# WHAT IT ALLOWS:
+#   - Agent calls with no issue id in the prompt (general work, not tracked)
+#   - Agent calls where the issue has been properly dispatched
+#   - Verifier agents (prompt starts with "VERIFIER for issue")
+#
+# WHY THE PROMPT, NOT THE NAME. The Agent tool's "name" field is optional
+# and often missing. The prompt always contains the issue id when work is
+# being done on a tracked issue.
+
+set -e
+
+# TOOL_INPUT is the JSON body of the Agent tool call, set by Claude Code.
+prompt=$(printf '%s' "$TOOL_INPUT" | python3 -c '
+import json, sys
+try:
+    data = json.loads(sys.stdin.read())
+    print(data.get("prompt", ""))
+except Exception:
+    pass
+')
+
+# Allow verifier agents — they are launched BY the dispatch pipeline.
+case "$prompt" in
+  "VERIFIER for issue"*) exit 0 ;;
+  "Verify"*) exit 0 ;;
+esac
+
+# Extract issue ids from the prompt.
+ids=$(printf '%s' "$prompt" | grep -oE '\bi-[a-z0-9][a-z0-9-]{4,}' | sort -u || true)
+
+# No issue ids → not tracked work → allow.
+[ -n "$ids" ] || exit 0
+
+# Resolve the project root.
+if [ -z "${ENTROPY_MACHINES_HOME:-}" ]; then
+  # Walk up from this script to find the harness.
+  ENTROPY_MACHINES_HOME="$(cd "$(dirname "$0")/.." && pwd -P)"
+fi
+. "$ENTROPY_MACHINES_HOME/lib/roots.sh"
+root=$(entropy_machines_root 2>/dev/null || true)
+
+# No project root → can't check → allow (don't block on misconfiguration).
+[ -n "$root" ] || exit 0
+
+# Read the tracker's note log.
+tracker="$ENTROPY_MACHINES_HOME/bin/tracker"
+[ -x "$tracker" ] || exit 0
+
+for id in $ids; do
+  # Check whether the issue exists in the tracker at all.
+  issue_json=$("$tracker" show "$id" 2>/dev/null || true)
+  if [ -z "$issue_json" ]; then
+    # Issue not in the tracker — not tracked work. Allow.
+    continue
+  fi
+
+  # Issue exists. Check whether it's already done — done issues don't need
+  # dispatch (verifiers, follow-ups, etc.).
+  is_done=$(printf '%s' "$issue_json" | python3 -c '
+import json, sys
+try:
+    d = json.loads(sys.stdin.read())
+    if d.get("status") == "done":
+        print("yes")
+except Exception:
+    pass
+' 2>/dev/null || true)
+  [ "$is_done" = "yes" ] && continue
+
+  # Issue exists and is not done. Check for a DISPATCH note.
+  notes=$("$tracker" notes --issue "$id" 2>/dev/null || true)
+  has_dispatch=""
+  if [ -n "$notes" ]; then
+    has_dispatch=$(printf '%s' "$notes" | python3 -c '
+import json, sys
+for line in sys.stdin:
+    line = line.strip()
+    if not line:
+        continue
+    try:
+        r = json.loads(line)
+    except Exception:
+        continue
+    verb = r.get("verb", "")
+    text = r.get("text", "")
+    if isinstance(text, str) and text.startswith("DISPATCH "):
+        print("yes")
+        break
+    if verb == "DISPATCH":
+        print("yes")
+        break
+' 2>/dev/null || true)
+  fi
+
+  if [ -z "$has_dispatch" ]; then
+    echo "DENIED: Agent call references issue $id, but no DISPATCH note exists in the tracker." >&2
+    echo "  Use the MCP dispatch_issue tool or bin/dispatch-run to dispatch through the full pipeline." >&2
+    echo "  This ensures pre-flight checks, worktree isolation, and auto-verification." >&2
+    exit 2
+  fi
+done
+
+exit 0

package/bin/dispatch-run

@@ -0,0 +1,245 @@
+#!/bin/sh
+# One-shot attended dispatch: pre-flight → worker → verify → report.
+#
+#   bin/dispatch-run <issue-id> --brief "one-line task" --files "path1 path2"
+#                    [--anyway] [--force] [--timeout <seconds>]
+#
+# Chains the full dispatch pipeline as a single blocking command:
+#   1. bin/dispatch  (pre-flight checks, context file, DISPATCH note, claim)
+#   2. Worker agent  (claude -p, isolated worktree, writes HANDOFF.md)
+#   3. bin/auto-verify inline (polls for HANDOFF.md, zero tokens)
+#   4. Verifier agent (claude -p, interrogate → lift → test → verify)
+#   5. Exits — orchestrator picks up at fold (review + commit)
+#
+# Modeled on bin/drain-run.sh, which does the same for scheduled batch work.
+# The difference: drain-run picks its own issues; this one takes an explicit
+# issue id and runs interactively (no armed flag, no branch guard).
+#
+# The MCP dispatch_issue tool shells out to this script. The orchestrator
+# (Claude Code) calls the MCP tool; this script runs the pipeline; the
+# orchestrator gets back a result when verification is complete.
+#
+# EXIT CODES:
+#   0  verified and ready for fold     3  bin/dispatch pre-flight refused
+#   1  internal error                  4  worker timed out
+#   2  usage error                     5  auto-verify timed out
+#                                      6  verifier timed out / failed
+set -e
+
+usage() {
+  echo "usage: bin/dispatch-run <issue-id> --brief \"<text>\" --files \"<paths>\" [--anyway] [--force] [--timeout <sec>]" >&2
+  exit 2
+}
+
+id=""; brief=""; files=""; anyway=""; force=""; timeout_s=5400
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --brief) brief="$2"; shift 2 ;;
+    --files) files="$2"; shift 2 ;;
+    --anyway) anyway="--anyway"; shift ;;
+    --force) force="--force"; shift ;;
+    --timeout) timeout_s="$2"; shift 2 ;;
+    -h|--help) usage ;;
+    -*) usage ;;
+    *) [ -n "$id" ] && usage; id="$1"; shift ;;
+  esac
+done
+[ -n "$id" ] && [ -n "$brief" ] && [ -n "$files" ] || usage
+
+. "$(dirname "$0")/../lib/roots.sh"
+ENTROPY_MACHINES_HOME=$(entropy_machines_home "$0")
+entropy_machines_require_root dispatch-run
+
+cd "$ENTROPY_MACHINES_ROOT"
+
+CONFIG_PY="$ENTROPY_MACHINES_HOME/lib/config.py"
+
+cfg() {
+  python3 "$CONFIG_PY" get "$1" 2>/dev/null || echo "$2"
+}
+
+stamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+slug=$(date -u +%Y%m%d-%H%M%S)
+outdir="$ENTROPY_MACHINES_ROOT/.entropy-machines/dispatch-runs/$slug"
+mkdir -p "$outdir"
+
+# ---------------------------------------------------------------------------
+# STEP 1 — bin/dispatch (pre-flight, context file, DISPATCH note)
+# ---------------------------------------------------------------------------
+echo "dispatch-run($id): step 1 — pre-flight and context file"
+dispatch_args="$id --files \"$files\" --brief \"$brief\""
+[ -n "$anyway" ] && dispatch_args="$dispatch_args $anyway"
+[ -n "$force" ] && dispatch_args="$dispatch_args $force"
+
+dispatch_out="$outdir/dispatch.out"
+dispatch_err="$outdir/dispatch.err"
+if ! eval "$ENTROPY_MACHINES_HOME/bin/dispatch $dispatch_args" >"$dispatch_out" 2>"$dispatch_err"; then
+  echo "dispatch-run($id): REFUSED — bin/dispatch pre-flight failed:" >&2
+  cat "$dispatch_err" >&2
+  exit 3
+fi
+
+echo "dispatch-run($id): pre-flight passed."
+
+# Parse the agent call JSON from bin/dispatch's structured output.
+worker_json=$(sed -n '/^--- AGENT CALL ---$/,/^--- END AGENT CALL ---$/p' "$dispatch_out" | grep -v '^---')
+if [ -z "$worker_json" ]; then
+  echo "dispatch-run($id): ERROR — could not parse agent call from bin/dispatch output" >&2
+  exit 1
+fi
+
+# Extract the worker prompt from the JSON.
+worker_prompt=$(printf '%s' "$worker_json" | python3 -c '
+import json, sys
+call = json.loads(sys.stdin.read())
+print(call["prompt"])
+')
+
+# ---------------------------------------------------------------------------
+# STEP 1.5 — Create an isolated worktree for the worker
+# ---------------------------------------------------------------------------
+# dispatch-run manages the worktree lifecycle itself. The orchestrator flow
+# uses the Agent tool's isolation: "worktree" parameter, but claude -p has
+# no such parameter — so we create and populate the worktree here.
+# git worktree add triggers the post-checkout hook, which links shared paths
+# (config.json, node_modules, etc.) automatically if hooks are installed.
+wt_branch="dispatch/$id/$slug"
+wt_dir="$ENTROPY_MACHINES_ROOT/.claude/worktrees/dispatch-$id-$slug"
+
+echo "dispatch-run($id): creating worktree at $wt_dir"
+mkdir -p "$(dirname "$wt_dir")"
+if ! git worktree add -b "$wt_branch" "$wt_dir" HEAD 2>"$outdir/worktree.err"; then
+  echo "dispatch-run($id): ERROR — could not create worktree:" >&2
+  cat "$outdir/worktree.err" >&2
+  exit 1
+fi
+
+echo "$id" > "$wt_dir/.dispatch-issue"
+echo "dispatch-run($id): worktree ready, .dispatch-issue written."
+
+# ---------------------------------------------------------------------------
+# STEP 2 — Worker agent (isolated worktree)
+# ---------------------------------------------------------------------------
+echo "dispatch-run($id): step 2 — launching worker agent in $wt_dir"
+
+# Agent CLI is pluggable, same as drain-run.
+set --
+while IFS= read -r tok; do
+  [ -n "$tok" ] && set -- "$@" "$tok"
+done <<AGENTCMD
+$(python3 - "$ENTROPY_MACHINES_ROOT/config.json" <<'PY'
+import json, sys
+try:
+    data = json.load(open(sys.argv[1]))
+    cmd = data.get("unattended", {}).get("agent", {}).get("cmd") or ["claude", "-p"]
+except Exception:
+    cmd = ["claude", "-p"]
+for tok in cmd:
+    print(tok)
+PY
+)
+AGENTCMD
+
+(cd "$wt_dir" && exec "$@" "$worker_prompt") > "$outdir/worker.json" 2> "$outdir/worker.err" &
+worker_pid=$!
+deadline=$(( $(date +%s) + timeout_s ))
+
+while kill -0 "$worker_pid" 2>/dev/null; do
+  if [ "$(date +%s)" -gt "$deadline" ]; then
+    kill -TERM "$worker_pid" 2>/dev/null || true
+    sleep 5
+    kill -KILL "$worker_pid" 2>/dev/null || true
+    echo "dispatch-run($id): TIMEOUT — worker killed after $((timeout_s / 60))m" >&2
+    exit 4
+  fi
+  sleep 10
+done
+
+wait "$worker_pid" || true
+echo "dispatch-run($id): worker finished."
+
+# ---------------------------------------------------------------------------
+# STEP 3 — Check for HANDOFF.md (worker already finished, check directly)
+# ---------------------------------------------------------------------------
+# No polling needed: dispatch-run created the worktree and waited for the
+# worker synchronously. The worktree path is known; just check it.
+worker_wt="$wt_dir"
+
+if [ -f "$worker_wt/HANDOFF.md" ]; then
+  echo "dispatch-run($id): HANDOFF.md found at $worker_wt"
+else
+  echo "dispatch-run($id): worker finished but left no HANDOFF.md at $worker_wt" >&2
+  echo "  The worker may have exited early or failed. Check:" >&2
+  echo "    $outdir/worker.err" >&2
+  echo "    $outdir/worker.json" >&2
+  exit 5
+fi
+
+# ---------------------------------------------------------------------------
+# STEP 4 — Verifier agent
+# ---------------------------------------------------------------------------
+echo "dispatch-run($id): step 4 — launching verifier agent"
+
+ctx="$ENTROPY_MACHINES_ROOT/.dispatch-context/$id.md"
+
+verifier_prompt="VERIFIER for issue $id.
+
+A worker agent completed implementation in worktree: $worker_wt
+Dispatch context: $ctx
+
+Read BOTH files before doing anything else.
+
+## STEP 1 — INTERROGATE THE WORKER
+Run: bin/handoff $id --interrogate
+Use ListAgents to find the worker agent named \"$id\". Send ALL questions via SendMessage.
+Wait for the worker to respond. Record the answers:
+  bin/handoff $id --record-interrogation --answer \"<answers>\"
+If the worker cannot be reached, answer from artifacts:
+  1. Read $worker_wt/HANDOFF.md
+  2. Read the changed files in the worktree
+
+## STEP 2 — LIFT
+Run: bin/handoff $id --from $worker_wt --lift
+If any files are rejected (main drifted), merge manually.
+
+## STEP 3 — TEST
+Run: tests/run
+All tests must pass. Fix failures caused by the lift.
+
+## STEP 4 — VERIFY (do NOT commit)
+Run: bin/handoff $id --from $worker_wt --verified \"auto-verified: tests passed\"
+If HANDOFF.md had found: none AND next: none, add --clean.
+If it had real found: or next: values, pass --found \"...\" --next \"...\"
+
+DO NOT commit or push. Report what you verified and stop.
+The orchestrator reviews your work and commits."
+
+"$@" "$verifier_prompt" > "$outdir/verifier.json" 2> "$outdir/verifier.err" &
+verifier_pid=$!
+deadline=$(( $(date +%s) + timeout_s ))
+
+while kill -0 "$verifier_pid" 2>/dev/null; do
+  if [ "$(date +%s)" -gt "$deadline" ]; then
+    kill -TERM "$verifier_pid" 2>/dev/null || true
+    sleep 5
+    kill -KILL "$verifier_pid" 2>/dev/null || true
+    echo "dispatch-run($id): TIMEOUT — verifier killed after $((timeout_s / 60))m" >&2
+    exit 6
+  fi
+  sleep 10
+done
+
+wait "$verifier_pid" || true
+echo "dispatch-run($id): verifier finished."
+
+# ---------------------------------------------------------------------------
+# REPORT — ready for fold
+# ---------------------------------------------------------------------------
+echo
+echo "dispatch-run($id): READY FOR FOLD"
+echo "  worker worktree: $worker_wt"
+echo "  dispatch context: $ctx"
+echo "  logs: $outdir/"
+echo
+echo "Review the staged changes in this checkout, then commit."
+echo "The commit-msg hook (handoff-guard) will enforce the handoff record."

package/bin/doclint

@@ -40,11 +40,9 @@ WHAT IT ENFORCES, AND WHY THOSE TWO THINGS
    this rule exists to catch is a doc that LOOKS answerable and is not.
 
 WHAT IT DELIBERATELY DOES NOT ENFORCE: the look. Colours, fonts, type scale,
-layout, whether there is a theme toggle — all of it is the author's. The house
-style in lib/REPORT-TEMPLATE.html is a good default and a starting point, not
-a conformance target. Somebody using this harness may want a report that looks
-nothing like ours, and that is fine; a report that fetches from the internet is
-not.
+layout, whether there is a theme toggle — all of it is the author's. Somebody
+using this harness may want a report that looks nothing like ours, and that is
+fine; a report that fetches from the internet is not.
 
 TARGETED REGEX, NOT AN HTML PARSER. Deliberate, and the same thing the rest of
 this harness does (bin/serve's save merge and answer counts, bin/status's
@@ -57,7 +55,7 @@ slip past. A doc built by hand or from the template does not do those things.
 
 HTML COMMENTS ARE MASKED BEFORE ANYTHING IS COUNTED. A commented-out remote
 link loads nothing, and — the expensive half — a comment that DOCUMENTS the
-answer-box markup is not a question. lib/doc-template.html once carried a
+answer-box markup is not a question. The old doc template once carried a
 literal example in its header comment; every regex reader of these docs counted
 it, so each doc reported one phantom unanswered question nobody could answer
 and "fully answered" was unreachable. Masking keeps line numbers intact.
@@ -438,8 +436,7 @@ def main(argv):
               "answer in place.")
         print("  It never fetches from an external site, and every section "
               "has a box to")
-        print("  answer in. Start from lib/REPORT-TEMPLATE.html. The look is "
-              "yours; these")
+        print("  answer in. The look is yours; these")
         print("  two rules are not.")
         return 1
 

package/bin/drain

@@ -35,7 +35,7 @@ os=$(uname)
 # refusal is this script's job for the keys that truly have none, e.g. an
 # unsupported scheduler below).
 cfg() {
-  python3 - "$ENTROPY_MACHINES_HOME/config.json" "$1" "$2" <<'PY'
+  python3 - "${ENTROPY_MACHINES_CONFIG:-$ENTROPY_MACHINES_HOME/config.json}" "$1" "$2" <<'PY'
 import json, sys
 path, key, default = sys.argv[1], sys.argv[2], sys.argv[3]
 try:

package/bin/entropy-machines-init

@@ -42,7 +42,7 @@ const PKG = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf
 // README names because the harness points at it from inside itself —
 // lib/roots.sh's refusal message cites `<harness>/docs/CONFIG.md`, and
 // docs/QUICKSTART.md is the document the next agent is told to read.
-const HARNESS_DIRS = ['bin', 'lib', 'docs', 'doctrine', 'hooks', 'agents'];
+const HARNESS_DIRS = ['bin', 'lib', 'docs', 'doctrine', 'hooks', 'agents', 'ui'];
 
 // Never copied, at any depth. `.git` is the load-bearing one.
 const NEVER_COPY = new Set(['.git', '__pycache__', 'node_modules', '.DS_Store']);

package/bin/handoff

@@ -165,7 +165,7 @@ set -e
 usage() {
   echo "usage: bin/handoff <issue-id> --changed \"...\" --verified \"...\"" >&2
   echo "         [--found \"...\"]... [--assumed \"...\"]... [--next \"...\"] [--clean]" >&2
-  echo "         [--drift-reviewed \"why the worker's version is right\"]" >&2
+  echo "         [--drift-reviewed \"why the worker's version is right\"] [--no-cleanup]" >&2
   echo "   or: bin/handoff <issue-id> --from <agent-worktree> --verified \"...\"" >&2
   echo "   or: bin/handoff <issue-id> --from <agent-worktree> --lift  (copy, record nothing)" >&2
   echo "   or: bin/handoff <issue-id> --interrogate [--ask \"...\"]  (print the questions)" >&2
@@ -176,7 +176,7 @@ usage() {
 id=""; changed=""; verified=""; next_note=""; clean=0; dry=0
 found=""; assumed=""; from=""; lift=0; drift_reviewed=""
 interrogate=0; record_interrogation=0; ask=""; answers=""; n_answers=0; blank_answer=0
-no_interrogation=""
+no_interrogation=""; no_cleanup=0
 while [ $# -gt 0 ]; do
   case "$1" in
     --changed)  changed="$2"; shift 2 ;;
@@ -216,6 +216,10 @@ while [ $# -gt 0 ]; do
     # The escape hatch, and it lands on the record as a positive claim rather
     # than an absence — the same shape as --clean and --drift-reviewed.
     --no-interrogation) no_interrogation="$2"; shift 2 ;;
+    # Suppress the automatic cleanup of the source worktree after a successful
+    # record. The rare case where the lander wants to keep the worktree around
+    # (e.g. to re-read the worker's full tree during a subsequent review pass).
+    --no-cleanup) no_cleanup=1; shift ;;
     # Print the note and write nothing. The log is shared and append-only with
     # no delete, so "let me see what this records" needs an answer that is not
     # "record it and find out".
@@ -1158,7 +1162,7 @@ echo "  The commit-msg guard for $id is now satisfied."
 #
 # ONLY DOCS THAT APPEAR IN THE CHANGED-FILES LIST ($tmp/changes) ARE OPENED.
 # No fallback to dispatch scope or dispatch context — those opened every doc
-# merely REFERENCED by a file like enhance.py, not docs that actually changed.
+# merely REFERENCED by an infrastructure file, not docs that actually changed.
 #
 # BEST-EFFORT: wrapped in a subshell whose failure is caught and discarded. A
 # doc that cannot be opened, a serve that cannot start, a port that cannot be
@@ -1228,3 +1232,61 @@ _open_changed_docs() {
   done
 }
 _open_changed_docs 2>/dev/null || true
+
+# --- auto-clean the source worktree (best-effort) ----------------------------
+#
+# After a successful record, the source worktree's work has been lifted into
+# this checkout and the handoff note is written — the worktree has no further
+# use. Leaving it around wastes disk and accumulates stale branches; over 70
+# agent-* worktrees were found in a single checkout during a sprint.
+#
+# ONLY AGENT WORKTREES ARE CLEANED. The pattern `.claude/worktrees/agent-*` is
+# what bin/dispatch creates and what bin/auto-verify polls for. A --from that
+# points at any other directory is left alone — it may be a human's worktree
+# or a worktree managed by another tool.
+#
+# BEST-EFFORT: the record already succeeded, so a cleanup failure must not
+# turn a green landing red. The git branch is also deleted — `git worktree
+# add` creates a `worktree-agent-*` branch that serves no purpose after the
+# worktree is gone.
+#
+# --no-cleanup suppresses this, for the rare case where the lander wants to
+# keep the worktree around (e.g. to re-read the worker's tree during review).
+# It is parsed at the top alongside the other flags.
+_cleanup_source_worktree() {
+  [ -n "$from" ] || return 0
+  [ "$no_cleanup" -eq 0 ] || return 0
+  [ "$dry" -eq 0 ] || return 0
+
+  # Resolve the absolute path, same as scan_worktree does.
+  _cwt=$(cd "$from" 2>/dev/null && pwd -P) || return 0
+
+  # Only agent worktrees — never a human's worktree or anything else.
+  case "$_cwt" in */.claude/worktrees/agent-*) ;; *) return 0 ;; esac
+
+  # The worktree directory must still exist.
+  [ -d "$_cwt" ] || return 0
+
+  # Derive the branch name git worktree add would have created.
+  _wt_basename=$(basename "$_cwt")
+  _wt_branch="worktree-$_wt_basename"
+
+  # `git worktree remove` is the proper cleanup — it removes the directory AND
+  # the worktree bookkeeping under .git/worktrees/. --force is needed because
+  # the worktree has uncommitted changes (the agent's edits, which have already
+  # been lifted).
+  if git -C "$ENTROPY_MACHINES_ROOT" worktree remove --force "$_cwt" 2>/dev/null; then
+    echo "  cleaned up worktree: $_cwt"
+  else
+    # Fall back to manual removal if `git worktree remove` fails (e.g. old git).
+    rm -rf "$_cwt" 2>/dev/null
+    git -C "$ENTROPY_MACHINES_ROOT" worktree prune 2>/dev/null
+    echo "  cleaned up worktree (manual): $_cwt"
+  fi
+
+  # Delete the per-worktree branch — it was created solely for the worktree and
+  # carries no commits the agent should not have made.
+  git -C "$ENTROPY_MACHINES_ROOT" branch -D "$_wt_branch" 2>/dev/null && \
+    echo "  deleted branch: $_wt_branch" || true
+}
+_cleanup_source_worktree 2>/dev/null || true

package/bin/init

@@ -65,7 +65,15 @@ if ! project=$(entropy_machines_root); then
   exit 2
 fi
 
-target="$ENTROPY_MACHINES_HOME/config.json"
+# Vendored (plain tracked files next to project code): config.json lives next
+# to bin/ and lib/. npm install (node_modules/) or external path: config.json
+# goes at the project root. node_modules is inside the project tree but is NOT
+# a vendored layout — it is a package manager install.
+case "$ENTROPY_MACHINES_HOME" in
+  */node_modules/*) target="$project/config.json" ;;
+  "$project"|"$project"/?*) target="$ENTROPY_MACHINES_HOME/config.json" ;;
+  *) target="$project/config.json" ;;
+esac
 
 if [ -f "$target" ] && [ -z "$force" ]; then
   echo "init: REFUSED — config.json already exists at $target." >&2
@@ -188,6 +196,31 @@ else
   prd_note="init: wrote $prd_dst — open it. It is the first PRD, and the"
 fi
 
+manifest="$project/$docs_dir/manifest.json"
+if [ ! -f "$manifest" ]; then
+  if [ -n "$prd_written" ]; then
+    # The PRD was just copied in, so it is a real doc the tracker/serve layer
+    # needs to know about — an empty manifest would leave PRD-001 written to
+    # disk but invisible to anything that reads manifest.json for status.
+    cat > "$manifest" <<'EOF'
+{
+  "docs": {
+    "PRD-001-orientation": {
+      "file": "PRD-001-orientation.html",
+      "title": "Orientation",
+      "status": "open",
+      "version": 0
+    }
+  }
+}
+EOF
+  else
+    # No PRD was written this run (it already existed and --force wasn't
+    # given), so there is nothing to register yet.
+    printf '{}\n' > "$manifest"
+  fi
+fi
+
 # STEP 6 — prove the tracker actually answers before claiming success.
 # A read, not a write: nothing is filed here. An init that reports success
 # while the tracker is unreachable is the exact failure this harness exists
@@ -212,6 +245,65 @@ if ! (cd "$project" && "$ENTROPY_MACHINES_HOME/bin/tracker" ready >/dev/null 2>&
   exit 2
 fi
 
+# STEP 7 — build the SQLite database so bin/serve's dashboard works on first
+# run. Non-fatal: a missing db is inconvenient (the dashboard says "API
+# unreachable") but not broken — the user can always run migrate-db by hand.
+# Must come after the manifest write (step 5) so the PRD gets migrated.
+(cd "$project" && "$ENTROPY_MACHINES_HOME/bin/migrate-db" >/dev/null 2>&1) || \
+  printf "${YELLOW}init: warning — could not build the database; run \`${CYAN}bin/migrate-db${YELLOW}\` before serving.${RESET}\n" >&2
+
+# STEP 8 — install Claude Code hooks so agents are forced through the dispatch
+# pipeline. Three gates: dispatch-gate-writes blocks Edit/Write on main,
+# mcp-gate blocks Bash calls to bin/* when MCP is connected, dispatch-gate
+# and no-fork-gate block Agent misuse. Non-fatal: missing hooks degrade to
+# convention enforcement via CLAUDE.md.
+claude_dir="$project/.claude"
+claude_settings="$claude_dir/settings.json"
+if [ ! -f "$claude_settings" ]; then
+  mkdir -p "$claude_dir"
+  # Paths are relative to the project root, adjusted for harness location.
+  case "$ENTROPY_MACHINES_HOME" in
+    "$project") hook_prefix="" ;;
+    "$project"/?*) hook_prefix="${ENTROPY_MACHINES_HOME#"$project"/}/" ;;
+    *) hook_prefix="$ENTROPY_MACHINES_HOME/" ;;
+  esac
+  cat > "$claude_settings" <<SETTINGS
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Agent",
+        "hooks": [
+          {"type": "command", "command": "${hook_prefix}bin/no-fork-gate"},
+          {"type": "command", "command": "${hook_prefix}bin/dispatch-gate"}
+        ]
+      },
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {"type": "command", "command": "${hook_prefix}hooks/dispatch-gate-writes"}
+        ]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [
+          {"type": "command", "command": "${hook_prefix}hooks/dispatch-gate-writes"}
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {"type": "command", "command": "${hook_prefix}hooks/mcp-gate"}
+        ]
+      }
+    ]
+  },
+  "enableAllProjectMcpServers": true
+}
+SETTINGS
+  add_ignore ".claude/"
+fi
+
 printf "${GREEN}init: wrote $target${RESET}\n"
 printf "${GREEN}$prd_note${RESET}\n"
 if [ -n "$prd_written" ]; then
@@ -235,5 +327,10 @@ esac
   printf "${YELLOW}init: warning — could not render TRACKER.html; run \`${CYAN}$cmd_prefix/tracker render${YELLOW}\`${RESET}\n" >&2
 
 printf "${GREEN}init: tracker is live and empty${RESET} — \`${CYAN}$cmd_prefix/tracker ready${RESET}\` answers.\n"
-printf "${BOLD}init: next — run \`${CYAN}$cmd_prefix/serve${RESET}${BOLD}\` and answer the PRD it opens.${RESET}\n"
+printf "${BOLD}init: next —${RESET}\n"
+printf "  ${BOLD}1.${RESET} \`${CYAN}$cmd_prefix/install-hooks${RESET}\`  install git hooks (per-clone, not shared)\n"
+printf "  ${BOLD}2.${RESET} \`${CYAN}$cmd_prefix/serve${RESET}\`           start the factory\n"
+if [ -n "$prd_written" ]; then
+  printf "      ${BOLD}Open the orientation PRD at ${CYAN}/prds/PRD-001-orientation${RESET}\n"
+fi
 echo "      Filing the issues it produces is step one."

package/bin/install-hooks

@@ -0,0 +1,4 @@
+#!/bin/sh
+# bin/install-hooks — install git hook shims for this clone.
+# Delegates to lib/install-hooks.sh.
+exec "$(dirname "$0")/../lib/install-hooks.sh" "$@"