entropy-machines 0.1.1

package/hooks/post-checkout

@@ -0,0 +1,354 @@
+#!/usr/bin/env bash
+# Repo post-checkout hook — VERSION-CONTROLLED, like its commit-msg and
+# pre-commit siblings, and installed by the same `npm run hooks:install`.
+# install-hooks.sh iterates every file in hooks/, so this one was
+# picked up the moment it landed; the installer needed no change to find it.
+# (It did gain a check that the resolved hook dir is one `git worktree add`
+# actually consults — see the note at the bottom of install-hooks.sh.)
+#
+# WHAT IT DOES. When `git worktree add` creates a NEW worktree, symlink every
+# path in `worktree.linkPaths` (config.json) into it from the main checkout,
+# and give it a PRIVATE SCRATCHPAD reachable as `.scratch`.
+#
+# WHY. A worktree gets the TRACKED tree and nothing else. A dependency
+# directory is untracked; a gitignored or nested-repo directory is absent
+# outright. So a fresh agent worktree has neither, and the gap used to be
+# closed by a sentence pasted into every dispatch brief — a mechanism measured
+# at 96% adherence when pasted and 7-8% when not, i.e. it works, but the
+# missing few percent is silent.
+# The dependency half is the more dangerous one: many runtimes resolve modules
+# by walking UP the directory tree, so a worktree with no local dependency
+# directory can resolve a test runner out of a SIBLING agent's worktree. That
+# is how one agent ran someone else's code and reported it green
+#. lib/preflight-tree.mjs now refuses
+# instead of guessing, and a symlink is exactly what it asks for.
+#
+# HOW IT KNOWS IT IS A NEW WORKTREE, and not the ordinary checkout this hook
+# also fires on. All three must hold. Verified by probing a real repo on
+# 2026-08-27 rather than taken from the docs:
+#
+#   $3 = 1                  a branch checkout, not `git checkout -- <path>`
+#                           (a file checkout passes 0)
+#   $1 = the null sha       only a brand-new worktree — and `git clone` — has
+#                           no previous HEAD. A checkout inside an ALREADY
+#                           EXISTING worktree passes a real sha here, which is
+#                           the case this test alone excludes.
+#   git-dir != common-dir   we are in a LINKED worktree. This is what excludes
+#                           `git clone`, which also passes the null sha, and
+#                           the main checkout, where the two are equal.
+#
+# THE MAIN CHECKOUT IS RESOLVED, NEVER HARDCODED. `git rev-parse
+# --git-common-dir` is the main .git even when called from a worktree, so its
+# parent is the tree holding the real node_modules. A literal path would be
+# wrong on every other machine, and wrong on any machine holding a second
+# checkout of the same project.
+#
+# WRITE ACCESS THROUGH A LINKED PATH IS DELIBERATE, NOT AN OVERSIGHT.
+# A symlink is read-write, so an agent can mutate a linked tracker store — and
+# the main session writes it constantly, since dispatch and handoff both append
+# to the note log on every dispatch and every landing. We link anyway, because
+# the lost-update race that argues against it is CLOSED one layer down, in the
+# tracker backend: it wraps every load-modify-save in an exclusive lock, writes
+# through a per-pid temp file and an atomic replace, and appends the note log
+# as whole JSONL lines under that same lock. File locks key on the INODE, and a
+# symlinked path resolves to the same inode as the main checkout's, so a
+# worktree writer and a main-session writer serialize against each other
+# exactly as two main-checkout writers already do.
+#
+# A BACKEND THAT DOES NOT LOCK MAKES THIS UNSAFE. That is the contract's
+# requirement, not a nicety — see docs/TRACKER-ADAPTER.md on `remember`.
+#
+# SO, WHEN TWO WRITERS RACE: they serialize. The second blocks in flock until
+# the first releases, then re-reads and applies on top of the first's result.
+# os.replace is atomic, so no reader ever sees a torn file, and the per-pid tmp
+# name means two writers cannot collide on the temp path. Nothing is lost. That
+# lock exists precisely because the race was measured live before it landed —
+# 8/10 concurrent claims either crashed on a shared ".tmp" name or vanished.
+#
+# WHAT THAT DOES NOT COVER, said out loud rather than left implied:
+#   1. The lock only binds processes that go through the tracker backend. An
+#      editor, a shell redirect or a one-liner writing the store directly
+#      bypasses it. A read-only wrapper would not have closed that hole
+#      either, which is why there is not one — it would be a second mechanism
+#      for a job the lock already does, and "two mechanisms for one job is how
+#      a stale one survives" is the reason this hook exists at all.
+#   2. A file lock serializes WRITES, not INTENT. Two agents that each legitimately
+#      `set status=` on one issue both succeed and the later one wins. That is
+#      a dispatcher coordination question, not a data race, and no file lock
+#      can adjudicate it.
+#   3. A backend may have internal helpers that save without taking the lock
+#      themselves, safe only because every caller already holds it. That
+#      coupling belongs to the backend, not to this hook.
+#
+# THE THIRD LINK IS A SCRATCHPAD, AND IT IS THE SAME BUG ONE LAYER DOWN.
+# N agents get N worktrees so they cannot clobber each other's edits — and then
+# every one of them writes its throwaway files into ONE shared scratchpad,
+# because that is the only scratch path any of them is handed. A worker once
+# reported a sibling overwriting its mutator script mid-run. Nothing was
+# corrupted that time because the results were already captured; that is luck,
+# not isolation.
+#
+# The scratchpad is where the files whose correctness is hardest to re-check
+# from the repo afterwards live: mutation scripts, probe harnesses, captured
+# suite output. A mutation harness whose mutator is silently replaced mid-run
+# prints a full, confident, WRONG table — every row a real number, none of them
+# about the code the agent thinks it mutated.
+#
+# So: <main_tree>/.entropy-machines/scratch/<worktree-name>/, linked in as `.scratch`.
+# The key is the worktree's own directory name, which for a dispatched agent IS
+# `agent-<id>` — the same id that names the worktree — so the mapping is
+# greppable rather than derived.
+#
+# WHY THE REAL DIRECTORY LIVES OUTSIDE THE WORKTREE. A scratchpad inside the
+# worktree would be private and cleaned up for free, which is most of what is
+# wanted — but the worktree is REMOVED once its work is landed, and the scratch
+# evidence dies with it. That is an argument about where the evidence goes, not
+# where the working files go, and one directory serves both: it is private
+# while the agent runs and it is still there when the lander wants to see what
+# the agent actually ran. Nothing prunes it; it is small, and a directory that
+# deletes evidence on a schedule is worse than one that grows.
+#
+# WHAT THIS DOES NOT ENFORCE, said plainly. Nothing makes an agent WRITE there.
+# The path exists and is announced; an agent that keeps using the shared
+# session scratchpad is not stopped by anything here. The mechanical half of
+# this concern belongs to a mutator script, which fingerprints itself and
+# REFUSES when it changes mid-run — that one does not depend on any agent
+# honouring a convention.
+#
+# IT MUST NEVER BLOCK THE WORKTREE. Deliberately no `set -e`: every failure
+# warns on stderr and the hook still exits 0. A worktree with no node_modules
+# is a bad day; a `git worktree add` that fails outright is a worse one.
+
+set -u
+
+warn() {
+  echo "post-checkout: $*" >&2
+}
+
+# Always succeed, whatever happened above this line.
+trap 'exit 0' EXIT
+
+# ENTROPY_MACHINES_HOME (the harness DIRECTORY — where lib/config.py actually lives,
+# which may be the repo root or a subdirectory of it) is baked in and exported
+# by the installed shim (lib/install-hooks.sh). The fallback here only matters
+# when this hook is run directly, bypassing the shim — by hand, or from a
+# test. Best-effort and silent on failure, matching this whole hook's fail-open
+# philosophy: config_link_paths() below already no-ops with nothing linked if
+# ENTROPY_MACHINES_HOME cannot be resolved.
+#
+# This hook does not call entropy_machines_require_root — it resolves the repo's main
+# tree itself, below, via `--git-common-dir`, because it needs that value for
+# the new-worktree test too, not only for config lookup.
+if [ -z "${ENTROPY_MACHINES_HOME:-}" ]; then
+  . "$(dirname "$0")/../lib/roots.sh" 2>/dev/null && ENTROPY_MACHINES_HOME="$(entropy_machines_home "$0" 2>/dev/null)"
+fi
+
+prev="${1:-}"
+flag="${3:-0}"
+
+# --- is this a brand-new worktree? -----------------------------------------
+
+# A file checkout (`git checkout -- path`) passes 0 here.
+[ "$flag" = "1" ] || exit 0
+
+# The null sha, and only the null sha: 40 (or 64) zeros. Anything containing a
+# non-zero character is a real previous HEAD, i.e. a checkout inside a worktree
+# that already exists and already has its links.
+[ -n "$prev" ] || exit 0
+case "$prev" in
+  *[!0]*) exit 0 ;;
+esac
+
+abspath_dir() {
+  # Absolute path of a directory, without --path-format=absolute (git 2.31+)
+  # so this works on older git too.
+  case "$1" in
+    /*) printf '%s\n' "$1" ;;
+    *)  ( cd "$1" 2>/dev/null && pwd ) ;;
+  esac
+}
+
+git_dir="$(git rev-parse --git-dir 2>/dev/null)" || exit 0
+common_dir="$(git rev-parse --git-common-dir 2>/dev/null)" || exit 0
+git_dir="$(abspath_dir "$git_dir")"
+common_dir="$(abspath_dir "$common_dir")"
+[ -n "$git_dir" ] && [ -n "$common_dir" ] || exit 0
+
+# Equal in the main checkout and in a fresh `git clone`; different only in a
+# linked worktree. This is the test that keeps a clone from linking onto itself.
+[ "$git_dir" != "$common_dir" ] || exit 0
+
+here="$(git rev-parse --show-toplevel 2>/dev/null)" || exit 0
+main_tree="$(dirname "$common_dir")"
+[ -n "$here" ] && [ -n "$main_tree" ] || exit 0
+# Never link a tree to itself. STRICTLY REDUNDANT given the git-dir test above
+# — the only way here == main_tree is a plain main checkout, which that test has
+# already excluded — and deliberately kept anyway as a one-line failsafe against
+# a future edit loosening it. Said plainly because NO TEST ISOLATES THIS LINE:
+# delete it and every test still passes. It is not load-bearing; do not add
+# behaviour behind it.
+[ "$here" != "$main_tree" ] || exit 0
+
+# --- link, but never clobber -----------------------------------------------
+
+# link_one <name-in-this-worktree> [target-path]
+# The target defaults to the SAME name in the main checkout, which is what
+# the configured link paths want. The scratchpad passes its own target
+# because the two names differ on purpose: `.scratch` here, a per-worktree
+# directory under the main checkout's .entropy-machines/scratch/ there.
+link_one() {
+  name="$1"
+  target="${2:-$main_tree/$name}"
+  dest="$here/$name"
+
+  if [ ! -e "$target" ]; then
+    warn "$name does not exist in the main checkout ($main_tree) — not linked."
+    return 0
+  fi
+
+  # -L before -e: a symlink pointing at nothing is still a symlink, and -e is
+  # false for it.
+  if [ -L "$dest" ]; then
+    current="$(readlink "$dest" 2>/dev/null || true)"
+    if [ "$current" = "$target" ]; then
+      return 0
+    fi
+    warn "$name is already a symlink to '$current', not '$target' — left alone."
+    return 0
+  fi
+
+  if [ -e "$dest" ]; then
+    warn "$name already exists here and is not a symlink — left alone. This"
+    warn "  worktree will use its own copy, not the main checkout's."
+    return 0
+  fi
+
+  if ln -s "$target" "$dest" 2>/dev/null; then
+    linked="${linked:+$linked, }$name"
+  else
+    warn "could not link $name -> $target. Link it by hand if a suite refuses."
+  fi
+  return 0
+}
+
+# Read worktree.linkPaths from the MAIN checkout's config.json — the worktree
+# may not have one yet, and even if it does, the main checkout's copy is the
+# one whose dependency directories we are linking to.
+#
+# Deliberately fail-open and silent: a hook that aborts a `git worktree add`
+# because a config key is missing would make this repo's own installation the
+# thing that breaks other people's git. No config, no Python, malformed JSON —
+# all mean "link nothing", and the warning at the end still names what was and
+# was not linked.
+config_link_paths() {
+  [ -f "${ENTROPY_MACHINES_HOME:-$main_tree}/config.json" ] || return 0
+  command -v python3 >/dev/null 2>&1 || return 0
+  [ -n "${ENTROPY_MACHINES_HOME:-}" ] || return 0
+
+  # TWO PATHS, ONE ROOT. lib/config.py's own root resolution (find_repo_root)
+  # walks up from `os.getcwd()` looking for config.json — it does not care
+  # where its own file lives on disk. So cwd must be the MAIN tree for the
+  # lookup to resolve against a tree that certainly exists (a post-checkout
+  # hook's cwd is the NEW worktree, which may still be mid-creation). But
+  # lib/config.py the SCRIPT FILE lives in the harness DIRECTORY, which may be
+  # a subdirectory: "$main_tree/lib/config.py" does not exist there, only
+  # "$ENTROPY_MACHINES_HOME/lib/config.py" does. So: cd into the main tree, but exec the
+  # harness's copy of the loader. The subshell keeps the cd off the caller.
+  ( cd "$main_tree" 2>/dev/null || exit 0
+    python3 "$ENTROPY_MACHINES_HOME/lib/config.py" get worktree.linkPaths 2>/dev/null ) \
+    | tr -d '[]",' | tr ' ' '\n' | sed '/^$/d'
+}
+
+linked=""
+
+# CONFIG.JSON IS UNTRACKED AND ONLY EXISTS IN THE MAIN CHECKOUT'S HARNESS DIR.
+# Without this link every tool that reads $ENTROPY_MACHINES_HOME/config.json
+# refuses inside a worktree. Hardcoded because config.json is what tells us
+# what ELSE to link — it cannot come from its own content.
+if [ -n "${ENTROPY_MACHINES_HOME:-}" ]; then
+  case "$ENTROPY_MACHINES_HOME" in
+    "$main_tree")   link_one "config.json" ;;
+    "$main_tree"/*) link_one "${ENTROPY_MACHINES_HOME#"$main_tree"/}/config.json" ;;
+  esac
+fi
+
+# WHICH PATHS GET LINKED IS CONFIG, NOT CODE. A hardcoded list here was wrong
+# for every project but the one this hook was written in. Each entry is a path
+# relative to the main checkout; one that does not exist there is skipped in
+# silence, because a project that simply has no dependency directory is not an
+# error.
+for _p in $(config_link_paths); do
+  [ -n "$_p" ] || continue
+  link_one "$_p"
+done
+
+# --- the private scratchpad -------------------------------------------------
+# Created, not just linked: unlike the other two there is nothing in the main
+# checkout to point at until this hook makes it. Everything below is
+# best-effort and silent on the happy path, so a re-run of the hook over an
+# already-linked worktree prints nothing.
+
+scratch_name="$(basename "$here")"
+# Rooted at $main_tree (the repo's main checkout), not ENTROPY_MACHINES_HOME — the
+# scratchpad belongs to the project being worked on, not to wherever inside it
+# the harness happens to be vendored.
+scratch_root="$main_tree/${ENTROPY_MACHINES_SCRATCH_ROOT:-.entropy-machines/scratch}"
+scratch_target="$scratch_root/$scratch_name"
+
+if [ ! -d "$scratch_target" ] && ! mkdir -p "$scratch_target" 2>/dev/null; then
+  warn "could not create $scratch_target — this worktree has no private scratchpad."
+fi
+
+if [ -d "$scratch_target" ]; then
+  scratch_readme="$scratch_target/README"
+  if [ ! -e "$scratch_readme" ]; then
+    {
+      echo "Private scratchpad for one git worktree."
+      echo
+      echo "worktree: $here"
+      echo "created:  $(date -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null || echo unknown)"
+      echo
+      echo "Reachable from that worktree as .scratch — put mutators, probe"
+      echo "harnesses and captured suite output here, NOT in the session"
+      echo "scratchpad, which every concurrent agent shares. A sibling agent"
+      echo "overwrote a worker's mutator there mid-run, which is why this"
+      echo "directory exists."
+      echo
+      echo "This directory OUTLIVES the worktree: it is under the main"
+      echo "checkout, so it is still readable after the work is landed and the"
+      echo "worktree removed. Nothing prunes it."
+    } >"$scratch_readme" 2>/dev/null || warn "could not write $scratch_readme"
+  else
+    # Two worktrees resolving to one scratchpad name is the very thing this
+    # directory exists to prevent, so it is said out loud rather than merged.
+    scratch_owner="$(sed -n 's/^worktree: //p' "$scratch_readme" 2>/dev/null | head -1)"
+    if [ -n "$scratch_owner" ] && [ "$scratch_owner" != "$here" ]; then
+      warn ".scratch target $scratch_target was created for $scratch_owner,"
+      warn "  not $here — two worktrees share one scratchpad name. Files written"
+      warn "  through either link land in the same directory."
+    fi
+  fi
+  link_one .scratch "$scratch_target"
+fi
+
+if [ -n "$linked" ]; then
+  warn "linked $linked from $main_tree"
+  case "$linked" in
+    *tracker*|*issues*|*plan*|*docs*)
+      warn "  A linked path is SHARED AND WRITABLE, not a copy. If it holds"
+      warn "  tracker state, a mutating command here changes the REAL tracker."
+      warn "  Writes serialize (the backend takes a lock), so nothing is lost"
+      warn "  — but there is no sandbox to undo them in."
+      ;;
+  esac
+  case "$linked" in
+    *.scratch*)
+      warn "  .scratch is PRIVATE TO THIS WORKTREE and outlives it:"
+      warn "  $scratch_target"
+      warn "  Write mutators and captured output there, not in the session"
+      warn "  scratchpad every concurrent agent shares."
+      ;;
+  esac
+fi
+
+exit 0

package/hooks/pre-commit

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# Repo pre-commit hook — VERSION-CONTROLLED, unlike the copy in .git/hooks.
+#
+# The installed shim (lib/install-hooks.sh) execs THIS working-tree file
+# directly, by an ABSOLUTE path baked in at install time, so the installed
+# artefact never goes stale and reviewing the hook means reviewing this file.
+# The baked path is the harness in the MAIN checkout, so every worktree runs
+# THIS copy, not its own checked-in one — deliberate: a gate that a worker
+# could weaken by editing its own worktree would not be a gate.
+#
+# ONE ROOT. lib/changelog-guard.sh is a harness file living one directory up
+# from this one, inside the same repository as the commit being made. The shim
+# exports ENTROPY_MACHINES_HOME (it lives in .git/hooks and cannot find lib/ relatively);
+# the fallback below only matters when this file is run directly — by hand, or
+# from a test — bypassing the shim.
+#
+# `git diff --cached`, which changelog-guard.sh reads, operates on the working
+# tree git already put us in: git runs pre-commit with cwd at the working-tree
+# root, and nothing here changes that. In a linked worktree that is the
+# worktree, which is correct — the staged files being committed are there.
+#
+# Keep it fast. It runs on every commit; anything slower than a `git diff`
+# belongs in CI.
+
+set -euo pipefail
+
+. "$(dirname "$0")/../lib/roots.sh"
+
+: "${ENTROPY_MACHINES_HOME:=$(entropy_machines_home "$0")}"
+export ENTROPY_MACHINES_HOME
+entropy_machines_require_root pre-commit
+
+exec "$ENTROPY_MACHINES_HOME/lib/changelog-guard.sh" --staged