@oneie/claude 0.7.0 → 0.9.0

package/scripts/pr-body.sh

@@ -0,0 +1,335 @@
+#!/usr/bin/env bash
+# pr-body.sh — the pull request a finished branch deserves, derived, never written.
+#
+#   bash .claude/scripts/pr-body.sh feat/editor-panel-tabs
+#   bash .claude/scripts/pr-body.sh do/my-plan --base main --gate "fast lane (green)"
+#   bash .claude/scripts/pr-body.sh feat/x --dev "https://dev.one.ie — 2 routes proven"
+#   bash .claude/scripts/pr-body.sh feat/x --title      # just the title line
+#   bash .claude/scripts/pr-body.sh --self-test         # the red proofs
+#
+# WHY THIS EXISTS: a /do branch arrives at the merge door carrying no explanation.
+# Context isolation throws away each cycle's reasoning to save 90-150k tokens, so
+# the prose that would have justified the diff is gone by the time a human reads
+# it. `do-auto.sh`'s `_merge_digest` solved that for the LOCAL reader by writing
+# `.do-digest.md` at trunk root. A pull request is the same document with an
+# audience: same facts, same sources, addressed to a reviewer instead of to the
+# operator standing in the tree.
+#
+# EVERY FIELD IS DERIVED FROM GIT AT CALL TIME. It deliberately does NOT read
+# `.do-digest.md`, even when one is sitting there: that file lives at trunk root,
+# is uncommitted, is written per-slug and is overwritten by the next cycle, so a
+# body that were "the digest when present, git otherwise" would be right
+# sometimes and stale sometimes with nothing on its face to say which. Deriving
+# every time is slower by milliseconds and always true.
+#
+# THE DIFF IS `merge-base..BR`, NEVER `BASE..BR`. Two-dot from the base conflates
+# what this branch added with what trunk advanced while it was building — the
+# latter reads as spurious reversions and inflates every count in the body. Same
+# rule `_merge_digest` follows, and the same reason.
+#
+# A MEASUREMENT THAT IS NOT THERE IS NOT RENDERED. The trust score, the open
+# improvements and the cycle count come from gitignored artifacts that exist only
+# beside a live worktree; the plan title comes from a file that only a /do branch
+# has. When one is absent its line is omitted — never printed as 0, "?" or
+# "unknown", which read as measured facts.
+#
+# Exit codes: 0 emitted · 2 bad usage · 3 no such branch · 4 self-test failed.
+set -uo pipefail
+# The repo this reads. Overridable ONLY through a dedicated name so the
+# self-test can point it at a scratch repo; a generic `ROOT` would inherit
+# whatever a calling script happened to export and read the wrong tree.
+ROOT="${PR_BODY_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+
+BR="" BASE="main" GATE="" DEV="" TITLE_ONLY=0 SELF_TEST=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --base) BASE="${2:-main}"; shift 2 ;;
+    --gate) GATE="${2:-}"; shift 2 ;;
+    --dev) DEV="${2:-}"; shift 2 ;;
+    --title) TITLE_ONLY=1; shift ;;
+    --self-test) SELF_TEST=1; shift ;;
+    -h|--help) sed -n '2,10p' "${BASH_SOURCE[0]}"; exit 0 ;;
+    -*) echo "pr-body.sh: unknown flag '$1'" >&2; exit 2 ;;
+    *) BR="$1"; shift ;;
+  esac
+done
+
+# --- the plan behind a branch ------------------------------------------------
+# `feat/editor-panel-tabs` and `do/editor-panel-tabs` are both the slug
+# `editor-panel-tabs`; a bare branch name is its own slug.
+slug_of() { printf '%s' "${1#*/}"; }
+
+# The worktree holding a branch, if any. The gitignored build artifacts
+# (.do-trust.json, .w4-improvements.json) live there and nowhere else, so a
+# branch with no worktree simply reports fewer facts.
+worktree_of() {
+  git worktree list --porcelain \
+    | awk -v b="refs/heads/$1" '/^worktree /{w=$2} /^branch /{if ($2==b) print w}' \
+    | head -1
+}
+
+# THE PLAN IS READ FROM THE BRANCH, NOT FROM THE TREE THIS RUNS IN.
+#
+# A /do branch commits its own `text/<slug>-todo.md`, and that copy is the one
+# whose cycles this branch actually closed. The checked-out tree may not have the
+# file at all (a plan authored entirely on the branch) or may have a STALE copy —
+# `do-auto.sh` blind-syncs `<slug>-plan.md` from main every iteration, so a tree
+# copy is not evidence about a branch. Caught by the throwaway proof: reading
+# $ROOT silently dropped the title, the cycle counts and the kill-switch, and the
+# body still looked complete because every one of those lines is optional.
+#
+# Falls back to the working tree so a branch with no committed plan (a hand-made
+# `feat/*`) can still pick up a plan that exists only locally.
+todo_for() {
+  local br="$1" slug="$2" out
+  out="$(mktemp)"
+  if git -C "$ROOT" show "${br}:text/${slug}-todo.md" > "$out" 2>/dev/null && [ -s "$out" ]; then
+    printf '%s' "$out"; return 0
+  fi
+  rm -f "$out"
+  [ -f "$ROOT/text/${slug}-todo.md" ] && { printf '%s' "$ROOT/text/${slug}-todo.md"; return 0; }
+  return 1
+}
+
+# `title: Some Words` out of a todo's frontmatter. Frontmatter only — a `title:`
+# in the body of a 900-line plan is somebody's YAML example, not the plan's name.
+plan_title() {
+  local f="$1"
+  [ -f "$f" ] || return 1
+  awk '
+    NR==1 && $0=="---" { inside=1; next }
+    inside && $0=="---" { exit }
+    inside && /^title:[[:space:]]/ { sub(/^title:[[:space:]]*/, ""); print; exit }
+  ' "$f"
+}
+
+emit() {
+  local br="$1" base="$2"
+  local mb behind shortstat slug todo wt title
+  slug="$(slug_of "$br")"
+  todo="$(todo_for "$br" "$slug" || true)"
+  wt="$(worktree_of "$br")"
+
+  mb="$(git -C "$ROOT" merge-base "$base" "$br" 2>/dev/null || printf '%s' "$base")"
+  behind="$(git -C "$ROOT" rev-list --count "$mb..$base" 2>/dev/null || echo 0)"
+  shortstat="$(git -C "$ROOT" diff --shortstat "$mb..$br" 2>/dev/null || true)"
+
+  title="$(plan_title "$todo" 2>/dev/null || true)"
+  # No plan, or a plan with no title: the branch's own first commit says what it
+  # set out to do, which is the next most honest sentence available.
+  [ -n "$title" ] || title="$(git -C "$ROOT" log --format=%s "$mb..$br" 2>/dev/null | tail -1)"
+  [ -n "$title" ] || title="$br"
+
+  if [ "$TITLE_ONLY" = "1" ]; then printf '%s\n' "$title"; return 0; fi
+
+  echo "## What this is"
+  echo
+  echo "Branch \`${br}\` → \`${base}\`. Generated by \`.claude/scripts/pr-body.sh\` from git —"
+  echo "every number below is derived at PR time, not written by hand or by a model."
+  echo
+  [ -n "$todo" ] && [ -f "$todo" ] && echo "Plan: \`text/${slug}-todo.md\`"
+  [ -n "$todo" ] && [ -f "$todo" ] && echo
+
+  # --- the counts ------------------------------------------------------------
+  echo "## Receipts"
+  echo
+  if [ -n "$todo" ] && [ -f "$todo" ]; then
+    local closed total
+    closed="$(grep -cE '\[[xX]\] \*{0,2}C[0-9]+' "$todo" 2>/dev/null || true)"
+    total="$(grep -cE '\[[ xX]\] \*{0,2}C[0-9]+' "$todo" 2>/dev/null || true)"
+    [ "${closed:-0}" != "0" ] || [ "${total:-0}" != "0" ] \
+      && echo "- **Cycles closed:** ${closed:-0} of ${total:-0}"
+  fi
+  echo "- **This branch's changes (merge-base..${br}):** ${shortstat:-none}"
+  [ "${behind:-0}" -gt 0 ] \
+    && echo "- **Trunk advanced during build:** ${behind} commit(s) — the diff above excludes them"
+
+  # Mergeability WITHOUT mutating anything. `--write-tree` computes the merge in
+  # the object store and says whether it conflicts; it does not touch a worktree,
+  # an index or a ref, which is why this is safe to run against a shared trunk.
+  if git -C "$ROOT" merge-tree --write-tree "$base" "$br" >/dev/null 2>&1; then
+    echo "- **Merges cleanly into \`${base}\`:** yes"
+  else
+    echo "- **Merges cleanly into \`${base}\`:** NO — conflicts, resolve before merging"
+  fi
+
+  # Gate result is PASSED IN by the caller that actually ran one. This script
+  # runs no gate, so it must never imply it did: no --gate, no line.
+  [ -n "$GATE" ] && echo "- **Gate:** ${GATE}"
+
+  # Same rule, one door further along: whether this branch was ever RUN, and
+  # where. `--dev` is passed only by a caller that actually shipped the branch
+  # to dev.one.ie and probed it. No flag, no line — a PR that says nothing
+  # about dev is a PR whose branch was never run, and that is the honest read.
+  [ -n "$DEV" ] && echo "- **Ran on dev:** ${DEV}"
+
+  if [ -n "$wt" ] && [ -f "$wt/.do-trust.json" ]; then
+    local trust composite
+    trust="$(jq -r '.level // empty' "$wt/.do-trust.json" 2>/dev/null || true)"
+    composite="$(jq -r '.composite // empty' "$wt/.do-trust.json" 2>/dev/null || true)"
+    [ -n "$trust$composite" ] \
+      && echo "- **Rubric:** trust=${trust:-—} · composite=${composite:-—}"
+  fi
+  if [ -n "$wt" ] && [ -f "$wt/.w4-improvements.json" ]; then
+    local open
+    open="$(jq -r 'if type=="array" then length elif type=="object" then ([.[]?]|length) else 0 end' \
+      "$wt/.w4-improvements.json" 2>/dev/null || true)"
+    [ -n "$open" ] && echo "- **Open improvements carried:** ${open}"
+  fi
+
+  # The kill-switch, quoted so a reviewer can run the same command the plan
+  # gates on rather than taking "it works" on trust.
+  if [ -n "$todo" ] && [ -f "$todo" ]; then
+    local outcome
+    outcome="$(awk '
+      NR==1 && $0=="---" { inside=1; next }
+      inside && $0=="---" { exit }
+      inside && /^outcome:[[:space:]]/ { sub(/^outcome:[[:space:]]*/, ""); print; exit }
+    ' "$todo" 2>/dev/null | sed 's/^"//; s/"$//')"
+    if [ -n "$outcome" ]; then
+      echo
+      echo "**Outcome check** — the plan's own kill-switch, exits 0 when the goal is met:"
+      echo
+      echo '```bash'
+      echo "$outcome"
+      echo '```'
+    fi
+  fi
+
+  echo
+  echo "## Files changed (this branch only)"
+  echo
+  echo '```'
+  git -C "$ROOT" diff --stat "$mb..$br" 2>/dev/null || true
+  echo '```'
+  echo
+  echo "## Commits"
+  echo
+  echo '```'
+  git -C "$ROOT" log --oneline "$mb..$br" 2>/dev/null || true
+  echo '```'
+}
+
+# --- self-test ---------------------------------------------------------------
+# The point is that each check can go RED. A body generator that emits a
+# plausible paragraph no matter what it was handed proves nothing, and every
+# claim below is one this script got wrong at least once while being written.
+self_test() {
+  local tmp fails=0
+  tmp="$(mktemp -d)"
+  trap 'rm -rf "$tmp"' RETURN
+  t_ok()  { printf '  ✓ %s\n' "$1"; }
+  t_bad() { printf '  ✗ %s\n' "$1"; fails=$((fails+1)); }
+
+  # A scratch repo, so the checks assert on a history they built themselves
+  # rather than on whatever this repo happens to look like today.
+  git init -q "$tmp/r" 2>/dev/null
+  (
+    cd "$tmp/r" || exit 1
+    git config user.email t@t; git config user.name t; git config commit.gpgsign false
+    echo base > a.txt; git add a.txt; git commit -qm "base commit"
+    git checkout -q -b feat/scratch
+    echo branch > b.txt; git add b.txt; git commit -qm "the branch's own first commit"
+    git checkout -q master 2>/dev/null || git checkout -q main
+    echo trunk >> a.txt; git add a.txt; git commit -qm "trunk moved on"
+  )
+  local basebr; basebr="$(cd "$tmp/r" && git rev-parse --abbrev-ref HEAD)"
+  local out
+  out="$(PR_BODY_ROOT="$tmp/r" bash "${BASH_SOURCE[0]}" feat/scratch --base "$basebr" 2>/dev/null)"
+
+  # 1. The diff is merge-base scoped: the branch added b.txt and NOTHING else.
+  #    A two-dot BASE..BR diff would also show a.txt as reverted.
+  grep -q 'b.txt' <<<"$out" && ! grep -q 'a.txt' <<<"$out" \
+    && t_ok "diff is merge-base scoped (trunk's own commit excluded)" \
+    || t_bad "diff leaked trunk's changes — merge-base scoping is broken"
+
+  # 2. Trunk drift is reported, not silently folded into the diff.
+  grep -q 'Trunk advanced during build:\*\* 1 commit' <<<"$out" \
+    && t_ok "trunk drift counted" || t_bad "trunk drift not reported"
+
+  # 3. With no plan file and no worktree, the absent measurements are ABSENT —
+  #    not rendered as 0 or "?". This is the claim that stops a body from
+  #    reporting "Cycles closed: 0" about a branch that never had cycles.
+  ! grep -qE 'Cycles closed|Rubric:|Open improvements' <<<"$out" \
+    && t_ok "absent measurements are omitted, not zeroed" \
+    || t_bad "rendered a measurement it never took"
+
+  # 4. No --gate ⇒ no gate line. This script runs no gate and must not imply it.
+  ! grep -q 'Gate:' <<<"$out" && t_ok "claims no gate it did not run" || t_bad "invented a gate result"
+
+  # Same for --dev. A body that implies the branch was run on dev when nobody
+  # shipped it is the same dishonesty as an invented gate, one door later.
+  ! grep -q 'Ran on dev:' <<<"$out" \
+    && t_ok "claims no dev run it did not do" || t_bad "invented a dev run"
+  outd="$(PR_BODY_ROOT="$tmp/r" bash "${BASH_SOURCE[0]}" feat/scratch --base "$basebr" --dev "https://dev.one.ie — 1 route proven" 2>/dev/null)"
+  grep -q 'Ran on dev:\*\* https://dev.one.ie' <<<"$outd" \
+    && t_ok "reports the dev run it was handed" || t_bad "dropped the caller's dev result"
+  local outg
+  outg="$(PR_BODY_ROOT="$tmp/r" bash "${BASH_SOURCE[0]}" feat/scratch --base "$basebr" --gate "fast lane (green)" 2>/dev/null)"
+  grep -q 'Gate:\*\* fast lane (green)' <<<"$outg" \
+    && t_ok "reports the gate it was handed" || t_bad "dropped the caller's gate result"
+
+  # 5. Title falls back to the branch's FIRST commit, not its last.
+  local tl
+  tl="$(PR_BODY_ROOT="$tmp/r" bash "${BASH_SOURCE[0]}" feat/scratch --base "$basebr" --title 2>/dev/null)"
+  [ "$tl" = "the branch's own first commit" ] \
+    && t_ok "title falls back to the branch's first commit" \
+    || t_bad "title fallback wrong: got '$tl'"
+
+  # 6. A conflicting branch is reported as conflicting. Without this the
+  #    mergeability line is a constant that always says yes.
+  (
+    cd "$tmp/r" || exit 1
+    git checkout -q -b feat/conflict "$basebr"
+    printf 'totally different\n' > a.txt; git add a.txt; git commit -qm "rewrite a.txt"
+    git checkout -q "$basebr"
+    printf 'trunk rewrote it too\n' > a.txt; git add a.txt; git commit -qm "trunk rewrote a.txt"
+  )
+  local outc
+  outc="$(PR_BODY_ROOT="$tmp/r" bash "${BASH_SOURCE[0]}" feat/conflict --base "$basebr" 2>/dev/null)"
+  grep -q 'Merges cleanly into .*:\*\* NO' <<<"$outc" \
+    && t_ok "a conflicting branch reads NO" || t_bad "conflict not detected — the line is a constant"
+  grep -q 'Merges cleanly into .*:\*\* yes' <<<"$out" \
+    && t_ok "a clean branch reads yes" || t_bad "clean branch misreported as conflicting"
+
+  # 7. The plan is read from the BRANCH, not from the checked-out tree. This is
+  #    the bug the throwaway PR proof caught: reading $ROOT silently dropped the
+  #    title, the cycle counts and the kill-switch, and the body still looked
+  #    complete, because every one of those lines is optional. Non-vacuous by
+  #    construction — the plan exists ONLY on the branch, never in the tree.
+  (
+    cd "$tmp/r" || exit 1
+    git switch -q -c do/planned "$basebr"
+    mkdir -p text
+    printf -- '---\ntitle: The Plan Name\nslug: planned\noutcome: "true"\n---\n\n- [x] C1 one\n- [ ] C2 two\n' > text/planned-todo.md
+    git add text/planned-todo.md; git commit -qm "add the plan"
+    git switch -q "$basebr"
+  )
+  local outp tlp
+  [ ! -f "$tmp/r/text/planned-todo.md" ] \
+    && t_ok "the plan is absent from the working tree (check is non-vacuous)" \
+    || t_bad "self-test setup wrong — plan is in the tree, so this proves nothing"
+  outp="$(PR_BODY_ROOT="$tmp/r" bash "${BASH_SOURCE[0]}" do/planned --base "$basebr" 2>/dev/null)"
+  grep -q 'Cycles closed:\*\* 1 of 2' <<<"$outp" \
+    && t_ok "cycle counts read from the branch's own plan" \
+    || t_bad "cycle counts not read from the branch"
+  grep -q 'kill-switch' <<<"$outp" \
+    && t_ok "kill-switch read from the branch's own plan" \
+    || t_bad "kill-switch not read from the branch"
+  tlp="$(PR_BODY_ROOT="$tmp/r" bash "${BASH_SOURCE[0]}" do/planned --base "$basebr" --title 2>/dev/null)"
+  [ "$tlp" = "The Plan Name" ] \
+    && t_ok "title read from the branch's own plan" \
+    || t_bad "title not read from the branch: got '$tlp'"
+
+  printf '\n'
+  [ "$fails" -eq 0 ] && { echo "pr-body.sh: all checks pass"; return 0; }
+  echo "pr-body.sh: ${fails} check(s) FAILED"; return 1
+}
+
+if [ "$SELF_TEST" = "1" ]; then self_test || exit 4; exit 0; fi
+
+[ -n "$BR" ] || { echo "pr-body.sh: name a branch" >&2; exit 2; }
+git -C "$ROOT" show-ref --verify --quiet "refs/heads/$BR" \
+  || { echo "pr-body.sh: no such branch '$BR'" >&2; exit 3; }
+
+emit "$BR" "$BASE"

package/scripts/preview-fd-check.sh

@@ -0,0 +1,289 @@
+#!/usr/bin/env bash
+# preview-fd-check.sh — is the preview tax a PIPE that outlives the script?
+#
+# manifest: needs-env
+#   Mode A (default) is self-contained: a scratch sandbox, one node mimic, no
+#   ports, no worktree, no astro, no credential. Mode B (--real) drives
+#   worktree-preview.sh against one.ie/web and costs a worktree and a port.
+#
+# NOT A FIX. A MEASUREMENT THAT IS ALLOWED TO COME BACK NEGATIVE.
+#
+# THE OBSERVATION. The chairman measured ~7 min of Opus per UI task blocked in
+#   worktree-preview.sh up <slug> --route / | tail -30
+# with the server green in under a minute and the shell parked in __wait4 at
+# 8m42s. Two mechanisms fit that sample and only one of them is fixable at the
+# launch line:
+#
+#   H1  THE PIPE OUTLIVES THE SCRIPT. cmd_up prints GREEN and returns, but the
+#       reader never sees EOF because a descendant of the launch still holds the
+#       script's stdout. The tool call is waiting on `tail`, not on the server.
+#   H2  THE SCRIPT REALLY IS STILL RUNNING. BOOT_LOCK_WAIT 240 + BOOT_TIMEOUT 60
+#       + WARM_TIMEOUT 180 = 480s against an observed 522s. A `sleep 1` poll loop
+#       samples as __wait4 exactly like waiting on a pipe.
+#
+# Mode A can only support or refute H1. It CANNOT exclude H2 — only --real can,
+# by asking whether the driver process is already gone at the moment the server
+# answers 200. So a green Mode A is not licence to touch worktree-preview.sh.
+#
+# THE LAUNCH THIS REPRODUCES, quoted from worktree-preview.sh (the perl branch;
+# the nohup branch is its twin):
+#   ( cd "$app" && perl -e 'setsid; exec @ARGV' -- sh -c "exec $astro dev ..." >>"$log" 2>&1 & echo $! > "$state/pid" )
+#
+# VARIANTS, each timed from the DRIVER'S OWN EXIT to the reader's EOF:
+#   V1 driver | cat                      the shape the operator runs
+#   V2 driver > file                     no pipe at all
+#   V3 driver | cat, launch gets </dev/null    is stdin the holder?
+#   V4 driver | cat, subshell does `exec >>log 2>&1 </dev/null` BEFORE the fork
+#
+# VERDICT DISCIPLINE. REPRODUCED requires ALL THREE:
+#   V1 hold >= 60% of the mimic's lifetime  AND  V2 hold <= 2s  AND  a NAMED
+#   process holding the same pipe as the reader's fd 0.
+# A timing alone is a correlation. Anything short of all three prints
+# NOT REPRODUCED with every number and exits 3, and no line of
+# worktree-preview.sh is touched.
+#
+# WHAT MODE A FOUND, 2026-09-06 (hold 12s):
+#   V1(pipe)=12.2s  V2(file)=0.0s  V3(stdin</dev/null)=12.2s  V4(exec-before-fork)=0.0s
+#   holder = <pid> bash / fd 1 / the exact peer of the reader's fd 0.
+# The holder is a BASH SUBSHELL, not node. `cmd >>log 2>&1 &` backgrounds the
+# whole `cd "$app" && perl …` AND-LIST: bash forks a subshell to run it, and the
+# `>>"$log" 2>&1` binds to the `perl` simple command INSIDE it. So the subshell
+# keeps the caller's stdout on its own fd 1 for as long as the server lives, and
+# `$!` — the pid worktree-preview.sh stores and polls — IS that subshell.
+# V3 shows stdin is not the holder; V4 shows giving the subshell its own stdio
+# before the fork closes it. That is H1, named.
+#
+# H2 IS STILL LIVE for the 522s the chairman observed (BOOT_LOCK_WAIT 240 +
+# BOOT_TIMEOUT 60 + WARM_TIMEOUT 180 = 480s), and Mode A cannot separate them.
+# NOTHING IN worktree-preview.sh HAS BEEN CHANGED on the strength of this run.
+#
+# USAGE  preview-fd-check.sh [--sandbox] [--hold N]     Mode A, default
+#        preview-fd-check.sh --real <slug>              Mode B, opt-in
+#        preview-fd-check.sh --self-test                the harness's own guards
+# EXITS  0 REPRODUCED · 3 NOT REPRODUCED · 4 bad arguments / missing tool /
+#        UNMEASURED (a variant produced no timing — never reported as a verdict)
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+HOLD="${PREVIEW_FD_HOLD:-12}"
+MODE=sandbox
+SLUG=""
+
+now() { perl -MTime::HiRes=time -e 'printf "%.3f\n", time'; }
+el()  { perl -e 'printf "%.1f\n", $ARGV[1] - $ARGV[0]' "$1" "$2"; }
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --sandbox) MODE=sandbox; shift ;;
+    --real)    MODE=real; SLUG="${2:-}"; shift 2 ;;
+    --hold)    HOLD="${2:-12}"; shift 2 ;;
+    --self-test) MODE=selftest; shift ;;
+    -h|--help) sed -n '2,50p' "${BASH_SOURCE[0]}"; exit 0 ;;
+    *) echo "preview-fd-check: unknown argument: $1" >&2; exit 4 ;;
+  esac
+done
+
+command -v perl >/dev/null 2>&1 || { echo "preview-fd-check: perl not found — it is both the timer and the launch shape" >&2; exit 4; }
+command -v node >/dev/null 2>&1 || { echo "preview-fd-check: node not found — the mimic is a node process on purpose" >&2; exit 4; }
+
+SB="${TMPDIR:-/tmp}/preview-fd-$$"
+mkdir -p "$SB"
+cleanup() {
+  local p
+  for p in "$SB"/*/pid; do [ -f "$p" ] || continue; kill -- -"$(cat "$p")" 2>/dev/null || kill "$(cat "$p")" 2>/dev/null; done
+  rm -rf "$SB"
+}
+trap cleanup EXIT INT TERM
+
+# The astro-mimic: a node process that (a) runs a worker thread, (b) spawns a
+# grandchild with inherited stdio, (c) holds the event loop. Those are the three
+# things astro dev's process tree does that a bare `sleep` child does not — and
+# a bare `sleep` child is exactly the harness that already failed to reproduce.
+cat > "$SB/mimic.js" <<'MIMIC'
+const { Worker } = require('worker_threads')
+const { spawn } = require('child_process')
+const secs = Number(process.argv[2] || 12)
+const ms = secs * 1000
+new Worker(`setTimeout(() => {}, ${ms})`, { eval: true })
+spawn('sh', ['-c', `sleep ${secs}`], { stdio: 'inherit' })
+console.log('mimic up')
+setTimeout(() => process.exit(0), ms)
+MIMIC
+
+# The driver: worktree-preview.sh's cmd_up, reduced to its launch and its GREEN
+# line. $1 = variant, $2 = state dir, $3 = hold seconds.
+cat > "$SB/driver.sh" <<'DRIVER'
+#!/usr/bin/env bash
+set -uo pipefail
+variant="$1"; state="$2"; hold="$3"
+log="$state/mimic.log"; : > "$log"
+mimic="$state/../mimic.js"
+case "$variant" in
+  plain)
+    ( cd "$state" && perl -e 'setsid; exec @ARGV' -- sh -c "exec node $mimic $hold" >>"$log" 2>&1 & echo $! > "$state/pid" ) ;;
+  stdin)
+    ( cd "$state" && perl -e 'setsid; exec @ARGV' -- sh -c "exec node $mimic $hold" >>"$log" 2>&1 </dev/null & echo $! > "$state/pid" ) ;;
+  execfd)
+    ( cd "$state" && exec >>"$log" 2>&1 </dev/null; perl -e 'setsid; exec @ARGV' -- sh -c "exec node $mimic $hold" & echo $! > "$state/pid" ) ;;
+  *) echo "driver: unknown variant $variant" >&2; exit 4 ;;
+esac
+perl -MTime::HiRes=time -e 'printf "%.3f\n", time' > "$state/driver_exit"
+echo "GREEN mimic up (driver returning, exactly as cmd_up does)"
+DRIVER
+chmod +x "$SB/driver.sh"
+
+# One variant, measured. $1 = name, $2 = driver variant, $3 = pipe|file
+run_variant() {
+  # NOT one `local` line: bash expands every word of the builtin BEFORE any of
+  # the assignments take effect, so `st="$SB/$name"` reads an unset `name` and
+  # dies under `set -u`. Measured here 2026-09-06 — it produced four empty
+  # timings that the verdict then reported as a confident NOT REPRODUCED.
+  local name="$1" variant="$2" sink="$3" t0 t_eof t_drv
+  local st="$SB/$name"
+  mkdir -p "$st"
+  t0="$(now)"
+  if [ "$sink" = pipe ]; then
+    ( bash "$SB/driver.sh" "$variant" "$st" "$HOLD" | cat > "$st/out.txt"
+      perl -MTime::HiRes=time -e 'printf "%.3f\n", time' > "$st/eof" ) &
+  else
+    ( bash "$SB/driver.sh" "$variant" "$st" "$HOLD" > "$st/out.txt"
+      perl -MTime::HiRes=time -e 'printf "%.3f\n", time' > "$st/eof" ) &
+  fi
+  local job=$!
+  # While the reader may still be blocked, name the holder. A timing without a
+  # named process is a correlation, and the verdict refuses it.
+  if [ "$sink" = pipe ] && [ "$name" = V1 ]; then sleep 3; name_holder "$st"; fi
+  wait "$job" 2>/dev/null
+  t_eof="$(cat "$st/eof" 2>/dev/null)"; t_drv="$(cat "$st/driver_exit" 2>/dev/null)"
+  if [ -z "$t_eof" ] || [ -z "$t_drv" ]; then echo "unmeasured"; return; fi
+  el "$t_drv" "$t_eof"
+}
+
+# Does any process in the launched tree hold the SAME pipe the reader is blocked
+# on? macOS lsof prints a pipe as `PIPE 0x<dev> ... ->0x<peer>`; the reader's fd
+# 0 and a writer's fd share those addresses.
+HOLDER="none"
+name_holder() {
+  local st="$1" mpid rp toks t
+  mpid="$(cat "$st/pid" 2>/dev/null)"
+  command -v lsof >/dev/null 2>&1 || { HOLDER="lsof-missing"; return; }
+  # The reader is the `cat` whose fd 1 is out.txt; find its pipe tokens on fd 0.
+  rp="$(lsof -n -t -- "$st/out.txt" 2>/dev/null | head -1)"
+  [ -n "$rp" ] || { HOLDER="reader-not-found"; return; }
+  toks="$(lsof -n -p "$rp" 2>/dev/null | awk '$5 == "PIPE" {print $6; if ($NF ~ /^->0x/) print substr($NF,3)}' | sort -u)"
+  [ -n "$toks" ] || { HOLDER="reader-holds-no-pipe"; return; }
+  local cand="" line
+  # Every descendant of the launched pid, plus the pid itself.
+  local pids; pids="$(ps -A -o pid=,ppid=,comm= 2>/dev/null)"
+  local tree; tree="$(printf '%s\n' "$mpid"; printf '%s\n' "$pids" | awk -v m="$mpid" '$2 == m {print $1}')"
+  for t in $tree; do
+    [ -n "$t" ] || continue
+    line="$(lsof -n -p "$t" 2>/dev/null | awk '$5 == "PIPE" {print $6; if ($NF ~ /^->0x/) print substr($NF,3)}' | sort -u)"
+    [ -n "$line" ] || continue
+    local shared; shared="$(comm -12 <(printf '%s\n' "$toks") <(printf '%s\n' "$line") 2>/dev/null | head -1)"
+    if [ -n "$shared" ]; then
+      # Name the process AND the pipe, with the fd it holds it on. A pid alone
+      # is a coincidence; a pid whose fd 1 is the peer of the reader's fd 0 is
+      # the mechanism.
+      local fd; fd="$(lsof -n -p "$t" 2>/dev/null | awk -v s="$shared" '$5 == "PIPE" && ($6 == s || substr($NF,3) == s) {print $4; exit}')"
+      cand="$(ps -o pid=,comm= -p "$t" 2>/dev/null | tr -s ' ' | sed 's/^ *//;s/ *$//')/fd${fd:-?}/pipe${shared}"
+      break
+    fi
+  done
+  HOLDER="${cand:-no-shared-pipe-in-launch-tree}"
+  # run_variant is called in a command substitution, so this assignment lives in
+  # a subshell and would evaporate. The answer travels by file, or the verdict
+  # would silently read `none` and refuse a real reproduction.
+  printf '%s' "$HOLDER" > "$SB/holder"
+}
+
+self_test() {
+  local fails=0 rc
+  printf '== preview-fd-check --self-test\n'
+  # The harness must refuse to call a hang a reproduction without a named holder.
+  if ( HOLDER="no-shared-pipe-in-launch-tree"; verdict 30 0 30 0 >/dev/null 2>&1 ); then
+    printf '  FAIL %-52s\n' 'a hang with NO named holder read as REPRODUCED' >&2; fails=$((fails+1))
+  else
+    printf '  ok   %-52s\n' 'no named holder => NOT REPRODUCED, whatever the timings'
+  fi
+  if ( HOLDER="1234 node"; verdict 0 0 0 0 >/dev/null 2>&1 ); then
+    printf '  FAIL %-52s\n' 'zero hold everywhere read as REPRODUCED' >&2; fails=$((fails+1))
+  else
+    printf '  ok   %-52s\n' 'no hold => NOT REPRODUCED even with a holder'
+  fi
+  if ( HOLDER="1234 node"; verdict "$HOLD" 0 "$HOLD" 0 >/dev/null 2>&1 ); then
+    printf '  ok   %-52s\n' 'all three conditions => REPRODUCED'
+  else
+    printf '  FAIL %-52s\n' 'the green half is unreachable' >&2; fails=$((fails+1))
+  fi
+  if ( HOLDER="1234 node"; verdict "$HOLD" "$HOLD" "$HOLD" "$HOLD" >/dev/null 2>&1 ); then
+    printf '  FAIL %-52s\n' 'V2 hanging too (so: not the pipe) read as REPRODUCED' >&2; fails=$((fails+1))
+  else
+    printf '  ok   %-52s\n' 'V2 hanging too => NOT REPRODUCED (not a pipe effect)'
+  fi
+  # THE HOUSE BUG, in this harness's own shape: an empty timing must not read as
+  # a benign "not reproduced". Driven for real — this exact defect shipped in the
+  # first draft and was caught by running it.
+  ( HOLDER="1234 node"; verdict "" 0 0 0 >/dev/null 2>&1 ); rc=$?
+  if [ "$rc" = 4 ]; then printf '  ok   %-52s exit 4\n' 'an unmeasured variant is UNMEASURED, not a verdict'
+  else printf '  FAIL %-52s exit %s\n' 'an empty timing produced a verdict' "$rc" >&2; fails=$((fails+1)); fi
+  ( HOLDER="1234 node"; verdict "$HOLD" unmeasured 0 0 >/dev/null 2>&1 ); rc=$?
+  if [ "$rc" = 4 ]; then printf '  ok   %-52s exit 4\n' 'a word where a number belongs is UNMEASURED'
+  else printf '  FAIL %-52s exit %s\n' 'a non-numeric timing produced a verdict' "$rc" >&2; fails=$((fails+1)); fi
+
+  [ "$fails" -eq 0 ] && { printf 'preview-fd-check --self-test: PASS (6 checks)\n'; return 0; }
+  printf 'preview-fd-check --self-test: RED — %s failed\n' "$fails" >&2; return 1
+}
+
+# verdict <v1> <v2> <v3> <v4> — the three conditions, judged together.
+verdict() {
+  local v1="$1" v2="$2" v3="$3" v4="$4" floor
+  floor="$(perl -e 'printf "%.1f", $ARGV[0] * 0.6' "$HOLD")"
+  printf 'PREVIEW-FD hold=%ss floor=%ss  V1(pipe)=%ss  V2(file)=%ss  V3(stdin</dev/null)=%ss  V4(exec-before-fork)=%ss  holder=%s\n' \
+    "$HOLD" "$floor" "$v1" "$v2" "$v3" "$v4" "$HOLDER"
+  local n
+  for n in "$v1" "$v2" "$v3" "$v4"; do
+    case "$n" in
+      ''|*[!0-9.]*)
+        printf 'PREVIEW-FD: UNMEASURED — a variant produced no timing (%s). This is NOT "not reproduced";\n' "$n"
+        printf '  the harness failed to measure and says so. worktree-preview.sh unchanged.\n'
+        return 4 ;;
+    esac
+  done
+  local ok1 ok2 ok3
+  ok1="$(perl -e 'print(($ARGV[0] =~ /^[0-9.]+$/ && $ARGV[0] >= $ARGV[1]) ? 1 : 0)' "$v1" "$floor")"
+  ok2="$(perl -e 'print(($ARGV[0] =~ /^[0-9.]+$/ && $ARGV[0] <= 2.0) ? 1 : 0)' "$v2")"
+  case "$HOLDER" in none|lsof-missing|reader-not-found|reader-holds-no-pipe|no-shared-pipe-in-launch-tree|'') ok3=0 ;; *) ok3=1 ;; esac
+  if [ "$ok1" = 1 ] && [ "$ok2" = 1 ] && [ "$ok3" = 1 ]; then
+    printf 'PREVIEW-FD: REPRODUCED (H1 candidate) — a named process in the launch tree holds the reader'"'"'s pipe.\n'
+    printf 'PREVIEW-FD: H2 IS NOT EXCLUDED — Mode A cannot separate them. --real is unrun.\n'
+    return 0
+  fi
+  printf 'PREVIEW-FD: NOT REPRODUCED — '
+  [ "$ok1" = 1 ] || printf 'V1 did not hold past the floor. '
+  [ "$ok2" = 1 ] || printf 'V2 held too (so the pipe is not the discriminator). '
+  [ "$ok3" = 1 ] || printf 'no named fd holder (%s). ' "$HOLDER"
+  printf 'worktree-preview.sh unchanged.\n'
+  return 3
+}
+
+case "$MODE" in
+  selftest) self_test; exit $? ;;
+  real)
+    [ -n "$SLUG" ] || { echo "preview-fd-check: --real needs a slug" >&2; exit 4; }
+    echo "preview-fd-check: --real is opt-in and UNRUN here — it costs a worktree, a port and ~2.3GB," >&2
+    echo "  it takes no boot lock, and this box is memory-bound. Run it alone, never in a fleet:" >&2
+    echo "  PREVIEW_FD_REAL_YES=1 bash .claude/scripts/preview-fd-check.sh --real $SLUG" >&2
+    [ "${PREVIEW_FD_REAL_YES:-0}" = 1 ] || exit 4
+    echo "preview-fd-check: --real not implemented in this cycle; Mode A is the deliverable." >&2
+    exit 4 ;;
+esac
+
+printf '== preview-fd-check --sandbox (mimic lifetime %ss)\n' "$HOLD"
+V1="$(run_variant V1 plain  pipe)"
+HOLDER="$(cat "$SB/holder" 2>/dev/null)"; HOLDER="${HOLDER:-none}"
+V2="$(run_variant V2 plain  file)"
+V3="$(run_variant V3 stdin  pipe)"
+V4="$(run_variant V4 execfd pipe)"
+verdict "$V1" "$V2" "$V3" "$V4"
+exit $?