@oneie/claude 0.7.0 → 0.8.0

package/scripts/do-reconcile.sh

@@ -47,6 +47,36 @@ _sanitize() {
     | _strip_allow
 }
 
+# Read stdin with a wall clock. macOS ships no `timeout(1)` (the same absence the
+# gate governor had to work around), so the bound is built from `read -t`.
+#
+# NOT with a backgrounded `cat`: the first attempt did that and read NOTHING,
+# because a job backgrounded by a non-interactive shell gets /dev/null for stdin.
+# The checker then reported OK on input containing a dead name -- a green gate
+# over a red input, which is worse than the hang it was fixing. Caught by the red
+# proof (`echo 'colony trail' | do-reconcile.sh dictionary` must FAIL); the
+# original caught 'trail', the rewrite did not.
+#
+# `read -t` distinguishes the two endings that matter: exit >128 is the timeout,
+# exit 1 is a clean EOF. Real pipes hit EOF in milliseconds.
+_read_stdin_bounded() {
+  local secs="${RECONCILE_STDIN_TIMEOUT:-10}" line out="" st rc=0
+  while true; do
+    if IFS= read -r -t "$secs" line; then
+      out="$out$line
+"
+    else
+      st=$?
+      # a final unterminated line still carries content
+      [ -n "$line" ] && out="$out$line"
+      [ "$st" -gt 128 ] && rc=1
+      break
+    fi
+  done
+  printf '%s' "$out"
+  return "$rc"
+}
+
 _load_text() {
   local text=""
   if [ "$#" -gt 0 ]; then
@@ -56,7 +86,32 @@ _load_text() {
       if [ -f "$a" ]; then text="$text $(_sanitize < "$a")"; else text="$text $(printf '%s' "$a" | _sanitize)"; fi
     done
   else
-    text="$(_sanitize)"  # stdin fallback (matches original do-reconcile.sh behaviour)
+    # STDIN FALLBACK -- bounded, because an unbounded one hangs the loop.
+    #
+    # Measured 2026-09-01: `do-reconcile.sh dictionary` with no file argument and
+    # an inherited-but-idle stdin blocked for over NINE MINUTES before it was
+    # killed. It is not slow; it is waiting for an EOF that never comes. And
+    # do.md's own toolbox documents exactly that argument-less form
+    # ("do-reconcile.sh dictionary  # no dead name, no new synonym"), so an agent
+    # copying the documented invocation stalls its whole cycle until do-auto's
+    # hard cap reaps it -- which reads as a mysteriously slow wave, not as a hang.
+    #
+    # Two guards. A terminal stdin can never deliver piped input, so that is a
+    # usage error, immediately. Anything else is read under a wall clock: real
+    # pipes (`git diff --name-only | do-reconcile.sh types`) close in
+    # milliseconds, so the bound only ever fires on the pathological case.
+    if [ -t 0 ]; then
+      printf 'do-reconcile: %s needs a file argument, or input on stdin.\n' "$CANON" >&2
+      printf '  do-reconcile.sh %s <file>...\n  git diff --name-only | do-reconcile.sh %s\n' "$CANON" "$CANON" >&2
+      exit 2
+    fi
+    local _raw=""
+    if ! _raw="$(_read_stdin_bounded)"; then
+      printf 'do-reconcile: %s timed out waiting on stdin after %ss — no file argument was given.\n' \
+        "$CANON" "${RECONCILE_STDIN_TIMEOUT:-10}" >&2
+      exit 2
+    fi
+    text="$(printf '%s' "$_raw" | _sanitize)"
   fi
   printf '%s' "$text"
 }
@@ -247,9 +302,60 @@ case "$CANON" in
 
     current=0
     if [ -d "$folder" ] && [ -f "$folder/tsconfig.json" ]; then
-      _tsc_tmp=$(mktemp)
-      ( cd "$folder" && bunx tsc --noEmit 2>&1 | grep -c 'error TS' > "$_tsc_tmp" ) 2>/dev/null || true
-      current=$(cat "$_tsc_tmp" 2>/dev/null | tr -d '[:space:]'); rm -f "$_tsc_tmp"
+      # ── Governed tsc (2026-08-18) ──────────────────────────────────────
+      # Six concurrent Claude sessions ran this canon at once, each spawning
+      # its own `tsc --noEmit` over the SAME tree for the SAME answer: load 57
+      # on 10 cores, swap exhausted, ~26 MB/s swapins. Starved, each tsc took
+      # 18 min instead of 2, sessions timed out, and retries piled on more.
+      # Fix: one tsc per (folder, tree-fingerprint); everyone else reuses its
+      # result. Identical work collapses instead of multiplying.
+      . "$(dirname "${BASH_SOURCE[0]}")/lib/govern.sh"
+
+      # Fingerprint the tree: same fingerprint => same tsc answer.
+      #
+      # ONE derivation, shared with tsc-cached.sh: tsc_tree_fingerprint in
+      # lib/govern.sh hashes the CONTENT of everything tsc reads (the folder's
+      # .ts/.tsx/.json + lockfile, tracked or not, plus packages/sdk/src for the
+      # folders that resolve @oneie/sdk types). It used to be an mtime stat
+      # here AND a second copy in tsc-cached.sh — two derivations of one key is
+      # how the memo split, and mtime is why it never shared across worktrees.
+      _fp_extra=""
+      case "$folder" in one.ie/web|channels) _fp_extra="packages/sdk/src" ;; esac
+      _fp=$(tsc_tree_fingerprint "$folder" $_fp_extra)
+      _cache="$GOVERN_DIR/tsc-$(printf '%s' "$folder" | tr '/' '_').$_fp"
+
+      if [ -s "$_cache" ]; then
+        current=$(cat "$_cache" | tr -d '[:space:]')          # someone already computed it
+      elif gate_lock "tsc-$(printf '%s' "$folder" | tr '/' '_')" "${RECONCILE_TSC_WAIT:-900}"; then
+        trap 'gate_release_all' EXIT INT TERM
+        if [ -s "$_cache" ]; then
+          current=$(cat "$_cache" | tr -d '[:space:]')        # computed while we queued
+        else
+          _tsc_tmp=$(mktemp)
+          run_bounded "${RECONCILE_TSC_TIMEOUT:-600}" \
+            bash -c "cd '$folder' && bunx tsc --noEmit 2>&1 | grep -c 'error TS' > '$_tsc_tmp'" \
+            2>/dev/null || true
+          current=$(cat "$_tsc_tmp" 2>/dev/null | tr -d '[:space:]'); rm -f "$_tsc_tmp"
+          current=${current:-0}
+          printf '%s' "$current" > "$_cache"
+        fi
+        gate_release_all; trap - EXIT INT TERM
+      else
+        # Lock held for the full wait. Re-check the cache once — the holder may
+        # have finished and released between our last poll and now.
+        if [ -s "$_cache" ]; then
+          current=$(cat "$_cache" | tr -d '[:space:]')
+        else
+          # Never exit 0 without an answer: a gate that passes because it was
+          # busy is a fail-open, which is worse than the load it avoids.
+          echo "RECONCILE[types]: lock held ${RECONCILE_TSC_WAIT:-900}s — checking anyway" >&2
+          _tsc_tmp=$(mktemp)
+          run_bounded "${RECONCILE_TSC_TIMEOUT:-600}" \
+            bash -c "cd '$folder' && bunx tsc --noEmit 2>&1 | grep -c 'error TS' > '$_tsc_tmp'" \
+            2>/dev/null || true
+          current=$(cat "$_tsc_tmp" 2>/dev/null | tr -d '[:space:]'); rm -f "$_tsc_tmp"
+        fi
+      fi
       current=${current:-0}
     fi
 

package/scripts/do-signal.sh

@@ -9,7 +9,10 @@
 #   do-signal.sh [--print] <type> <slug> <tier> <cycle> [key=value ...]
 #   do-signal.sh [--print] --task-create <slug> <title> [tags=a,b,c] [notes=...]
 #   do-signal.sh [--print] --task-claim  <slug>
+#   do-signal.sh [--print] --task-plan   <slug>   # one task per cycle
+#   do-signal.sh [--print] --task-reap
 #   do-signal.sh [--print] --task-link   <slug> [docs=a,b,c]
+#   do-signal.sh [--print] --task-heartbeat <slug> <body>
 #
 # --print: write JSON to stdout without POSTing (tests + dry runs).
 # Extra key=value pairs are merged into the world:do-event payload.
@@ -23,7 +26,9 @@
 #   ONE_ENV_FILE   default: one.ie/web/.env  (read SERVER_SECRET for auth)
 #   DO_ENV_FILE    accepted as an alias for ONE_ENV_FILE (kept for callers)
 #
-# Signal failure never blocks the build loop — callers wrap with `|| true`.
+# world:do-event failure never blocks the build loop — callers wrap with `|| true`.
+# tasks:* (create/claim/link/heartbeat) propagate failure so callers can log it;
+# they must still not abort the build (capture the exit, continue).
 set -euo pipefail
 
 PRINT=false
@@ -45,6 +50,10 @@ _server_secret() {
   local _f _v
   for _f in "$ONE_ENV_FILE" "$_ROOT/.env" $_MONOREPO_ENV_CANDIDATES; do
     [ -f "$_f" ] || continue
+    # DO_SIGNAL_SKIP_FALLBACKS=1 → ONE_ENV_FILE is the WHOLE ladder. Without it the
+    # no-secret state is unreachable from inside the monorepo (_ROOT resolves to a
+    # tree that carries a real .env), so the dark-cycle guard could not be proven.
+    if [ "${DO_SIGNAL_SKIP_FALLBACKS:-0}" = "1" ] && [ "$_f" != "$ONE_ENV_FILE" ]; then continue; fi
     _v=$(grep -E '^SERVER_SECRET=' "$_f" 2>/dev/null | head -1 | sed 's/^[^=]*=//;s/^"//;s/"$//' || true)
     [ -n "$_v" ] && { printf '%s' "$_v"; return 0; }
   done
@@ -66,24 +75,39 @@ _gateway_key() {
   printf ''
 }
 
-# POST a JSON payload to /api/ask/<receiver> with bearer auth. Fire-and-forget:
-# a failure is silent so the build loop is never blocked (same stance as the
-# world:do-event POST below). Prints the response body (empty on failure).
+# POST a JSON payload to /api/ask/<receiver> with bearer auth. Board writes
+# (tasks:*) must not disguise failure as ok: curl errors and a body without
+# `"ok":true` (HTTP 200 wrapping {error:...} is the TypeDB-down case) exit
+# non-zero. Prints the response body. Callers log and continue.
 _post_ask() {
-  local _receiver="$1" _payload="$2" _secret _authcfg _url _resp
+  local _receiver="$1" _payload="$2" _secret _authcfg _url _resp _rc=0
   _secret="$(_gateway_key)"
   _url="${DO_SIGNAL_URL}/api/ask/${_receiver}"
   if [ -n "$_secret" ]; then
     _authcfg="$(mktemp)"; chmod 600 "$_authcfg"
     printf 'header = "Authorization: Bearer %s"\n' "$_secret" > "$_authcfg"
-    _resp=$(curl -sf -X POST "$_url" -H "Content-Type: application/json" --config "$_authcfg" -d "$_payload" 2>/dev/null || true)
+    _resp=$(curl -sf -X POST "$_url" -H "Content-Type: application/json" --config "$_authcfg" -d "$_payload" 2>/dev/null) || _rc=$?
     rm -f "$_authcfg"
   else
-    _resp=$(curl -sf -X POST "$_url" -H "Content-Type: application/json" -d "$_payload" 2>/dev/null || true)
+    _resp=$(curl -sf -X POST "$_url" -H "Content-Type: application/json" -d "$_payload" 2>/dev/null) || _rc=$?
   fi
   printf '%s' "$_resp"
+  if [ "$_rc" -eq 0 ]; then
+    case "$_resp" in
+      *'"ok":true'*) ;;
+      *) _rc=1 ;;
+    esac
+  fi
+  return "$_rc"
 }
 
+# _jsonesc — JSON-escape a value before it is interpolated into a payload
+# string. EVERY free-text field must go through this. Measured 2026-08-26: a
+# task filed with `notes=accept: ! grep -q "x" f.ts` produced
+#   "notes":"accept: ! grep -q "x" f.ts"
+# — malformed JSON, and the create failed. Titles carry quotes just as often.
+_jsonesc() { printf '%s' "$1" | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g' -e 's/\t/\\t/g' | tr -d '\n\r'; }
+
 # Every task this harness files lands in one workspace — /u/one/tasks — so a
 # human never has to hunt across slugs for Claude Code's own work. Overridable
 # for a differently-branded harness fork; unset means "one" (same convention
@@ -105,23 +129,122 @@ signal_tasks_create() {  # signal_tasks_create <slug> <title> [tags=a,b,c] [note
     esac
   done
   local tags_json; tags_json=$(printf '%s' "$tags" | awk -F',' '{for(i=1;i<=NF;i++){printf "%s\"%s\"", (i>1?",":""), $i}}')
-  local payload="{\"data\":{\"title\":\"${title}\",\"workspace\":\"${CC_TASKS_WORKSPACE}\",\"tags\":[${tags_json}]${notes:+,\"notes\":\"${notes}\"}}}"
+  local title_esc notes_esc
+  title_esc="$(_jsonesc "$title")"; notes_esc="$(_jsonesc "$notes")"
+  local payload="{\"data\":{\"title\":\"${title_esc}\",\"workspace\":\"${CC_TASKS_WORKSPACE}\",\"tags\":[${tags_json}]${notes:+,\"notes\":\"${notes_esc}\"}}}"
   if $PRINT; then printf '%s\n' "$payload"; return 0; fi
   _post_ask "tasks:create" "$payload"
 }
 
+# signal_tasks_plan — file EVERY cycle of a plan as its own task, once.
+#
+# WHY. The loop filed exactly ONE task per plan (do-auto.sh's `.task-created`
+# sentinel) and nothing else. Measured 2026-09-01: text/lifecycle-todo.md carries
+# 10 cycles and its promise 13 deliverables -- 1 task reached the substrate.
+# `signal_tasks_cycle` (the per-cycle status writer, and its --task-cycle flag)
+# was already written and had ZERO callers, because the tasks it sets status on
+# were never created: _tid_for_slug found nothing and it returned 1 every time.
+#
+# So the substrate could not answer "which cycles are ready" -- and that is
+# exactly why do-next.sh re-derives readiness by PARSING MARKDOWN CHECKBOXES, a
+# second source of truth whose divergences are most of this repo's scars.
+#
+# The cycle list is read from do-plan-json.sh, which is a parser, not a model.
+# tasks:create dedupes on the slug tag, so re-running a plan is idempotent.
+signal_tasks_plan() {  # signal_tasks_plan <slug>
+  local slug="$1" plan cid title n=0
+  plan="$(bash "$(dirname "${BASH_SOURCE[0]}")/do-plan-json.sh" "$slug" 2>/dev/null)" || {
+    printf 'do-signal: cannot parse plan %s — no cycle tasks filed\n' "$slug" >&2; return 1; }
+  # one task per cycle, tagged so the router can fan on any of them
+  while IFS=$'\t' read -r cid title; do
+    [ -n "$cid" ] && [ "$cid" != "null" ] || continue
+    if $PRINT; then
+      signal_tasks_create "${slug}-${cid}" "${title:-$slug $cid}" "tags=do:cycle,cycle:${cid#C},slug:${slug}"
+    else
+      signal_tasks_create "${slug}-${cid}" "${title:-$slug $cid}" "tags=do:cycle,cycle:${cid#C},slug:${slug}" >/dev/null || true
+    fi
+    n=$((n+1))
+    # `.cycles` is an OBJECT KEYED BY CYCLE ID, not an array. The first draft
+    # used `.cycles[]? | .id` and got null for every id -- it still reported
+    # "filed 2 cycle task(s)", so the count looked right while every task was
+    # named `<slug>-` and tagged `cycle:`. A count is not a check.
+  done < <(printf '%s' "$plan" | jq -r '.cycles | to_entries[] | "\(.key)\t\(.value.title // .key)"' 2>/dev/null)
+  [ "$n" -gt 0 ] || { printf 'do-signal: %s parsed but yielded ZERO cycles — refusing to report success\n' "$slug" >&2; return 1; }
+  printf 'do-signal: filed %d cycle task(s) for %s\n' "$n" "$slug"
+}
+
 # signal_tasks_claim — cycle open: leases the plan's substrate task so a fleet
 # run (or a human) never double-builds the same slug (do-fleet.sh mirrors this).
+# _tid_for_slug <slug> [title] — resolve a plan slug to its task tid, and cache it.
+#
+# The SERVER's slug→tid resolver is broken in prod: measured 2026-08-31, every
+# tasks:claim/link/heartbeat addressed by `slug` returns not_found, while the
+# same task claimed by `tid` succeeds. That cost a whole campaign's board
+# visibility — the /do engine's claim, six heartbeats and link all failed exit 1
+# on every run, silently, because nothing treats a board write as load-bearing.
+#
+# `tasks:create` is idempotent — it dedupes on the `slug:` tag and returns the
+# EXISTING tid — so create IS a working slug→tid resolver. One call adds the task
+# if missing and resolves it if present, which is also the simplest thing for a
+# human: there is no separate "add" step to forget.
+#
+# Cached under .claude/.task-tids/<slug> so the steady state is zero round-trips.
+_tid_for_slug() {
+  local slug="$1" title="${2:-}" dir="$_ROOT/.claude/.task-tids" f tid resp
+  f="$dir/$slug"
+  if [ -f "$f" ]; then tid=$(cat "$f" 2>/dev/null); [ -n "$tid" ] && { printf '%s' "$tid"; return 0; }; fi
+  [ -n "$title" ] || title="$slug — /do plan"
+  resp=$(signal_tasks_create "$slug" "$title" 2>/dev/null) || true
+  tid=$(printf '%s' "$resp" | sed -n 's/.*"tid":"\([^"]*\)".*/\1/p')
+  [ -n "$tid" ] || { printf ''; return 1; }
+  mkdir -p "$dir" && printf '%s' "$tid" > "$f"
+  printf '%s' "$tid"
+}
+
+# signal_tasks_cycle <slug> <cid> <status> — the per-CYCLE board row.
+#
+# The plan-level task says "lifecycle is being worked on". It cannot show the
+# thing an operator actually wants to watch: which cycle is in flight and which
+# ones are finished. This files one row per cycle (slug `<plan>-<cid>`, tagged
+# with the plan) and moves it open -> picked -> done as the engine runs.
+#
+# create is idempotent (dedupes on the slug: tag), so calling this on every cycle
+# open is safe and needs no separate "add" step. Status is addressed by tid,
+# because prod's slug resolver returns not_found (see _tid_for_slug).
+signal_tasks_cycle() {  # signal_tasks_cycle <slug> <cid> <status>
+  local slug="$1" cid="$2" st="${3:-picked}" cslug tid
+  cslug="$(printf '%s-%s' "$slug" "$cid" | tr '[:upper:]' '[:lower:]')"
+  tid=$(_tid_for_slug "$cslug" "${slug} ${cid}") || true
+  [ -n "$tid" ] || return 1
+  _post_ask "tasks:status" "{\"data\":{\"tid\":\"${tid}\",\"workspace\":\"${CC_TASKS_WORKSPACE}\",\"status\":\"${st}\"}}"
+}
+
 signal_tasks_claim() {  # signal_tasks_claim <slug>
   # Address the lease by the plan SLUG, not a guessed tid: create returns a random
   # task:<traceId>, so "task:<slug>" never matched — claim silently 404'd for every /do
   # run until this. The server resolves slug → tid (resolvers/tasks.ts resolveTaskBySlug).
-  local slug="$1"
-  local payload="{\"data\":{\"slug\":\"${slug}\",\"workspace\":\"${CC_TASKS_WORKSPACE}\"}}"
+  local slug="$1" tid
+  tid=$(_tid_for_slug "$slug") || true
+  local payload
+  if [ -n "$tid" ]; then
+    payload="{\"data\":{\"tid\":\"${tid}\",\"workspace\":\"${CC_TASKS_WORKSPACE}\"}}"
+  else
+    payload="{\"data\":{\"slug\":\"${slug}\",\"workspace\":\"${CC_TASKS_WORKSPACE}\"}}"
+  fi
   if $PRINT; then printf '%s\n' "$payload"; return 0; fi
   _post_ask "tasks:claim" "$payload"
 }
 
+# signal_tasks_reap — the stranded-lease sweep. `tasks:claim` is atomic, so no
+# two workers double-lease; this is the OTHER half — a lease whose owner died is
+# `picked` forever, invisible to the claimable view and blocking every dependent
+# via ready-tasks. Nothing else in the system goes looking for those rows.
+signal_tasks_reap() {  # signal_tasks_reap
+  local payload="{\"data\":{\"workspace\":\"${CC_TASKS_WORKSPACE}\"}}"
+  if $PRINT; then printf '%s\n' "$payload"; return 0; fi
+  _post_ask "tasks:reap" "$payload"
+}
+
 # signal_tasks_link — cycle close: records the handoff-completion back on the
 # origin task (provenance line + task-status:done), same shape lifecycle.ts's
 # tasks_link MCP tool posts.
@@ -136,9 +259,38 @@ signal_tasks_link() {  # signal_tasks_link <slug> [docs=a,b,c]
   done
   local docs_json=""
   [ -n "$docs" ] && docs_json=$(printf '%s' "$docs" | awk -F',' '{for(i=1;i<=NF;i++){printf "%s\"%s\"", (i>1?",":""), $i}}')
-  local payload="{\"data\":{\"slug\":\"${slug}\",\"workspace\":\"${CC_TASKS_WORKSPACE}\"${docs_json:+,\"docs\":[${docs_json}]}}}"
+  local tid; tid=$(_tid_for_slug "$slug") || true
+  local payload="{\"data\":{\"slug\":\"${slug}\"${tid:+,\"tid\":\"${tid}\"},\"workspace\":\"${CC_TASKS_WORKSPACE}\"${docs_json:+,\"docs\":[${docs_json}]}}}"
+  if $PRINT; then printf '%s\n' "$payload"; return 0; fi
+  # Prod's tasks:link still resolves by slug and ignores an explicit tid, so it
+  # returns not_found for every /do close (measured 2026-08-31). Fall back to the
+  # two tid-addressed verbs that DO work, so a close is never silently lost:
+  # status:done is the state the board renders, the comment is the provenance line.
+  if _post_ask "tasks:link" "$payload"; then return 0; fi
+  [ -n "$tid" ] || return 1
+  _post_ask "tasks:status" "{\"data\":{\"tid\":\"${tid}\",\"workspace\":\"${CC_TASKS_WORKSPACE}\",\"status\":\"done\"}}" >/dev/null || return 1
+  _post_ask "tasks:comment" "{\"data\":{\"tid\":\"${tid}\",\"workspace\":\"${CC_TASKS_WORKSPACE}\",\"body\":\"/do close — ${slug}${docs:+ (docs: ${docs})}\"}}"
+}
+
+# signal_tasks_heartbeat — batch/wave close: posts tasks:comment so the lease
+# stays live (the comment resolver bumps updated-at-ms). Slug-addressed like
+# claim/link; body is the wave-close note (e.g. "wave 2 close").
+signal_tasks_heartbeat() {  # signal_tasks_heartbeat <slug> <body>
+  local slug="$1"; shift
+  local body="$*" body_esc
+  body_esc="${body//\\/\\\\}"
+  body_esc="${body_esc//\"/\\\"}"
+  local tid; tid=$(_tid_for_slug "$slug") || true
+  # tasks:comment lets `slug` OVERRIDE `tid`, so the slug must be omitted, not merely
+  # accompanied, when the tid is known — otherwise the broken resolver runs anyway.
+  local payload
+  if [ -n "$tid" ]; then
+    payload="{\"data\":{\"tid\":\"${tid}\",\"workspace\":\"${CC_TASKS_WORKSPACE}\",\"body\":\"${body_esc}\"}}"
+  else
+    payload="{\"data\":{\"slug\":\"${slug}\",\"workspace\":\"${CC_TASKS_WORKSPACE}\",\"body\":\"${body_esc}\"}}"
+  fi
   if $PRINT; then printf '%s\n' "$payload"; return 0; fi
-  _post_ask "tasks:link" "$payload"
+  _post_ask "tasks:comment" "$payload"
 }
 
 while [ "$#" -gt 0 ]; do
@@ -156,16 +308,20 @@ while [ "$#" -gt 0 ]; do
       done
       printf 'resolved-from: %s\n' "${_which:-<none>}"
       exit 0 ;;
-    --task-create) shift; signal_tasks_create "$@"; exit 0 ;;
-    --task-claim)  shift; signal_tasks_claim "$@"; exit 0 ;;
-    --task-link)   shift; signal_tasks_link "$@"; exit 0 ;;
+    --task-create)     shift; signal_tasks_create "$@"; exit $? ;;
+    --task-claim)      shift; signal_tasks_claim "$@"; exit $? ;;
+    --task-cycle)      shift; signal_tasks_cycle "$@"; exit $? ;;
+    --task-plan)       shift; signal_tasks_plan  "$@"; exit $? ;;
+    --task-reap)       shift; signal_tasks_reap "$@"; exit $? ;;
+    --task-link)       shift; signal_tasks_link "$@"; exit $? ;;
+    --task-heartbeat)  shift; signal_tasks_heartbeat "$@"; exit $? ;;
     *) break ;;
   esac
 done
 
 if [ "$#" -lt 4 ]; then
   echo "usage: do-signal.sh [--print] <type> <slug> <tier> <cycle> [key=value ...]" >&2
-  echo "       do-signal.sh [--print] --task-create|--task-claim|--task-link <slug> ..." >&2
+  echo "       do-signal.sh [--print] --task-create|--task-claim|--task-link|--task-heartbeat <slug> ..." >&2
   exit 1
 fi
 
@@ -218,20 +374,42 @@ for kv in "$@"; do
   esac
 done
 
+# is_test discriminator. An emission aimed anywhere but production is a test run by
+# construction, so it defaults to dev; a real prod cycle is a real run and stays
+# is_test=0. There is no automatic way to tell a developer's experimental prod cycle
+# from a genuine one, so that case is the operator's explicit DO_SIGNAL_ENV=dev —
+# which this respects rather than overrides.
+case "$DO_SIGNAL_URL" in
+  https://one.ie|https://one.ie/) : ;;
+  *) DO_SIGNAL_ENV="${DO_SIGNAL_ENV:-dev}" ;;
+esac
+# DO_SIGNAL_ENV rides in the payload so the receiver can flag the projected run
+# is_test — those cycles are then filterable instead of polluting the operator's list.
+[ -n "${DO_SIGNAL_ENV:-}" ] && EXTRA_JSON="${EXTRA_JSON},\"env\":\"${DO_SIGNAL_ENV}\""
+
 PAYLOAD="{\"type\":\"${TYPE}\",\"slug\":\"${SLUG}\",\"tier\":\"${TIER}\",\"cycle\":${CYCLE},\"tags\":[${TAGS}]${EXTRA_JSON}}"
 
+# SERVER_SECRET for the Authorization header — _server_secret() (defined above) is the
+# one lookup, shared with the tasks:* verbs. .env historically lacks it;
+# .secrets.generated.local is what push-prod-secrets.sh pushed to the worker, so it
+# matches prod. Without a matching secret the POST is silently 401/403-dropped at the
+# gateway (verified 2026-07-04 — zero do-* threads had ever landed in prod D1).
+SERVER_SECRET="$(_server_secret)"
+
+# Dark-cycle guard — resolved BEFORE the --print exit so a dry run reports the same
+# state a real emit would hit. A worktree with no secret emits nothing, and the
+# resulting gap in the run trace reads as "no cycles ran" rather than "the wire was
+# down". One loud stderr line; stdout is untouched, so every existing --print
+# consumer is unaffected.
+if [ -z "$SERVER_SECRET" ]; then
+  echo "[do-signal] dark: no secret (SERVER_SECRET unresolved from ${ONE_ENV_FILE}) — this cycle emits nothing" >&2
+fi
+
 if $PRINT; then
   printf '%s\n' "$PAYLOAD"
   exit 0
 fi
 
-# SERVER_SECRET for the Authorization header — _server_secret() (defined above)
-# is the one lookup, shared with the tasks:* verbs. .env historically lacks it;
-# .secrets.generated.local is what push-prod-secrets.sh pushed to the worker, so
-# it matches prod. Without a matching secret the POST is silently 401/403-dropped
-# at the gateway (verified 2026-07-04 — zero do-* threads had ever landed in prod D1).
-SERVER_SECRET="$(_server_secret)"
-
 # POST — fire-and-forget; failures are silent so the build loop is never blocked.
 _url="${DO_SIGNAL_URL}/api/signal/world:do-event"
 if [ -n "$SERVER_SECRET" ]; then

package/scripts/do-test-gate.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# do-test-gate.sh — a vitest accept clause that cannot pass vacuously.
+#
+# WHY THIS EXISTS. A promise `accept:` of the form
+#     ( cd <workdir> && bunx vitest run tests/unit/<slug>.test.ts )
+# is not proof. Measured on vitest 4.1.7 in this repo (2026-08-18):
+#   · a test file full of `it.skip(...)`          → exit 0
+#   · `-t "name-that-does-not-exist"`             → exit 0, "10 skipped"
+#   · a file containing only `it('x', () => {})`  → exit 0
+# The only shape that DOES go red is a missing file ("No test files found",
+# exit 1). So the clause proves the file exists — the same class of claim as a
+# presence grep, and the same trap: the cycle that must pass the check is the
+# cycle that authors the file.
+#
+# This gate asserts the run actually EXERCISED something: at least <min> tests
+# passed, zero failed, and zero were pending/skipped. A skipped test is a hole,
+# not a pass — `it.skip` in a security accept is the failure mode this closes.
+#
+# Usage:  do-test-gate.sh <workdir> <min-passed> <test-file> [<test-file>...]
+# Example (inside a promise accept:):
+#   bash .claude/scripts/do-test-gate.sh <workdir> 4 tests/unit/<slug>-persona.test.ts
+#
+# Exit 0 only when: numFailedTests == 0 AND numPendingTests == 0 AND
+#                   numPassedTests >= min.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+workdir="${1:?usage: do-test-gate.sh <workdir> <min-passed> <test-file>...}"
+min="${2:?usage: do-test-gate.sh <workdir> <min-passed> <test-file>...}"
+shift 2
+[ "$#" -gt 0 ] || { echo "[test-gate] no test files given" >&2; exit 2; }
+
+case "$min" in ''|*[!0-9]*) echo "[test-gate] min-passed must be an integer, got '$min'" >&2; exit 2 ;; esac
+
+out="$(mktemp -t do-test-gate.XXXXXX)"
+trap 'rm -f "$out"' EXIT
+
+# Missing files must fail here rather than inside vitest's include-glob, whose
+# "No test files found" message is easy to mistake for a red test.
+for f in "$@"; do
+  [ -f "$ROOT/$workdir/$f" ] || { echo "[test-gate] FAIL missing test file: $workdir/$f" >&2; exit 1; }
+done
+
+# vitest's own exit code is deliberately IGNORED — it is 0 for the vacuous
+# shapes above. The json report is the verdict.
+#
+# GOVERNED. This gate is written to be called from many parallel /do cycles at
+# once, and a bare `bunx vitest` is exactly the ungoverned heavy gate that melted
+# a 10-core box (see .claude/CLAUDE.md § Machine governor): no slot, no wall
+# clock, no process-group reap. Routing through gate-run.sh means N parallel
+# cycles QUEUE on GOVERN_MAX_GATES instead of thrashing, and it also satisfies
+# hook:load-guard, which would otherwise refuse a direct `vitest run` on a
+# saturated box and fail the accept for a reason that has nothing to do with the
+# code. Degrades to a plain exec when the governor lib is absent (CI, fresh clone).
+GATE_RUN="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/gate-run.sh"
+runner=( bash "$GATE_RUN" "test-gate:$workdir" -- )
+[ -x "$GATE_RUN" ] || runner=()
+( cd "$ROOT/$workdir" && "${runner[@]}" bunx vitest run "$@" --reporter=json --outputFile="$out" ) >/dev/null 2>&1 || true
+
+python3 - "$out" "$min" "$workdir" "$@" <<'PY'
+import json, sys
+out, min_passed, workdir = sys.argv[1], int(sys.argv[2]), sys.argv[3]
+files = sys.argv[4:]
+try:
+    d = json.load(open(out))
+except Exception as e:
+    print(f"[test-gate] FAIL no json report ({e}) — the run did not start", file=sys.stderr)
+    sys.exit(1)
+passed  = int(d.get("numPassedTests", 0))
+failed  = int(d.get("numFailedTests", 0))
+pending = int(d.get("numPendingTests", 0))
+label = " ".join(files)
+if failed:
+    print(f"[test-gate] FAIL {label}: {failed} failing", file=sys.stderr); sys.exit(1)
+if pending:
+    print(f"[test-gate] FAIL {label}: {pending} skipped — a skipped assertion is a hole, not a pass", file=sys.stderr); sys.exit(1)
+if passed < min_passed:
+    print(f"[test-gate] FAIL {label}: {passed} passed, expected >= {min_passed}", file=sys.stderr); sys.exit(1)
+print(f"[test-gate] OK {workdir}/{label} — {passed} passed, 0 skipped, 0 failed (floor {min_passed})")
+PY

package/scripts/do-tick.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# do-tick.sh <slug> <C1> [C2 ...] — tick a cycle's Status-kanban line after a
+# green W4. Run from the plan worktree (or pass DO_TICK_ROOT).
+#
+# manifest: portable
+#
+# WHY (2026-08-31). do-engine had no writer for the tick, so a cycle that PASSED
+# stayed `- [ ]` forever. openCyclesFromTodo/_remaining then reported it open on
+# the next launch, the batch rebuilt work that was already verified green, and
+# because a rebuilt batch never got further the run reported stoppedAt:1 every
+# time. Measured: lifecycle-money C2 was verified green at 15:43 and was being
+# rebuilt from scratch at 16:02. Two W2 agents diagnosed it independently and
+# named it ROOT CAUSE in the census.
+#
+# Deterministic on purpose: ticking is a two-character edit on a line whose exact
+# shape is already the contract. Nothing about it needs a model.
+set -euo pipefail
+SLUG="${1:-}"; shift || true
+[ -n "$SLUG" ] && [ "$#" -gt 0 ] || { echo "usage: do-tick.sh <slug> <C1> [C2 ...]" >&2; exit 2; }
+ROOT="${DO_TICK_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+TODO="$ROOT/text/${SLUG}-todo.md"
+[ -f "$TODO" ] || { echo "do-tick: no such plan: $TODO" >&2; exit 3; }
+
+# _is_open <cid> — the ONE reader in this script. Same shape do-auto.sh's
+# _remaining() and do-engine's openCyclesFromTodo use; parity across all four
+# is proven behaviourally by do-cycle-shape-check.sh, not by eyeballing them.
+_is_open() { grep -qE "^[[:space:]]*- \[[ ~]\] \*{0,2}${1}\*{0,2} —" "$TODO"; }
+
+# ── the OTHER half of closing a cycle ────────────────────────────────────────
+# This script was the single writer of the markdown tick and touched the
+# substrate ZERO times, so a cycle went `[x]` in a file while the platform task
+# stayed open forever. Two records of the same fact, one of them always stale --
+# and the stale one is what a human or an agent reads on the board.
+#
+# So the tick writes BOTH, here, in the one place a cycle is declared complete.
+#
+# It must not fail the tick. The markdown tick is the ratchet the engine reads to
+# avoid rebuilding proven work; losing it because a gateway was unreachable would
+# trade a stale board for a rebuilt cycle, which is far worse. Instead an
+# unreachable substrate PARKS the update in a machine-keyed pending file and every
+# later tick flushes it first -- so "as soon as complete" degrades to "at the next
+# tick", never to "never". Same debt-ledger shape as the deferred test pins.
+PENDING="${DO_TICK_PENDING:-${TMPDIR:-/tmp}/one-do-tick-pending}"
+_sig() { bash "$(dirname "${BASH_SOURCE[0]}")/do-signal.sh" --task-cycle "$1" "$2" done >/dev/null 2>&1; }
+
+_flush_pending() {
+  [ -f "$PENDING" ] || return 0
+  local left; left="$(mktemp)"
+  while IFS=$'\t' read -r pslug pcid; do
+    [ -n "$pcid" ] || continue
+    _sig "$pslug" "$pcid" || printf '%s\t%s\n' "$pslug" "$pcid" >> "$left"
+  done < "$PENDING"
+  if [ -s "$left" ]; then mv "$left" "$PENDING"
+    echo "do-tick: $(wc -l < "$PENDING" | tr -d ' ') substrate update(s) still pending"
+  else rm -f "$left" "$PENDING"; fi
+}
+
+_mark_done_in_substrate() {
+  local cid="$1"
+  if _sig "$SLUG" "$cid"; then
+    echo "do-tick: ${SLUG} ${cid} -> task done (substrate)"
+  else
+    printf '%s\t%s\n' "$SLUG" "$cid" >> "$PENDING"
+    echo "do-tick: substrate unreachable — ${SLUG} ${cid} PARKED in $PENDING (flushed on the next tick)" >&2
+  fi
+}
+
+_flush_pending
+
+ticked=0; failed=0
+for cid in "$@"; do
+  case "$cid" in C[0-9]|C[0-9][0-9]) ;; *) echo "do-tick: skip bad cycle id '$cid'" >&2; continue ;; esac
+  # Only ever [ ] or [~] -> [x]. Never the reverse: the ratchet cannot regress.
+  if _is_open "$cid"; then
+    # SUBSTRATE FIRST, checkbox second. The task is the record; the checkbox is a
+    # projection of it. Writing the file first made these two peers that could
+    # disagree -- a dual write, which is the same two-sources-of-truth shape that
+    # produced every engine scar here. Written in this order the box can only
+    # reach [x] downstream of a task that is already `done`.
+    _mark_done_in_substrate "$cid"
+    perl -i -pe "s/^(\s*- )\[[ ~]\](\s\*{0,2}${cid}\*{0,2}\s—)/\${1}[x]\${2}/" "$TODO"
+    # POST-CONDITION. A fire-and-forget write is how the original bug survived:
+    # the engine called a ticker, nobody checked the box actually moved, and the
+    # next launch rebuilt proven work. Asserting the write LANDED — with this
+    # script's own reader — is the guard that works even when do-engine runs from
+    # a cached snapshot, because it runs inside whatever code actually executed.
+    if _is_open "$cid"; then
+      echo "do-tick: FAILED — ${SLUG} ${cid} is STILL open after the write. The plan will rebuild proven work. Line shape in $TODO does not match the writer." >&2
+      failed=$((failed+1))
+    else
+      echo "do-tick: ${SLUG} ${cid} -> [x]"; ticked=$((ticked+1))
+    fi
+  else
+    echo "do-tick: ${SLUG} ${cid} already closed or absent — no change"
+  fi
+done
+
+# Report what the ENGINE's next launch will see. A silent success that leaves the
+# same count open is the failure mode this whole file exists to end.
+open_now=$(grep -cE '^[[:space:]]*- \[[ ~]\] \*{0,2}C[0-9]+\*{0,2} —' "$TODO" 2>/dev/null || true)
+echo "do-tick: ${SLUG} ticked=${ticked} open=${open_now:-0}"
+[ "$failed" -eq 0 ] || exit 4