@rubytech/create-maxy-code 0.1.299 → 0.1.301

package/payload/platform/scripts/__tests__/check-no-task-id-leaks.test.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+# Standing guard for the markdown task-id leak scan. If a fixture citation under
+# a shipped plugin/template .md stops failing the gate, the markdown coverage
+# regressed back to code-only and internal task numbers can ship to clients
+# again. The gate reads its scan root from TASK_ID_LEAK_ROOT so this test points
+# it at a mktemp fixture tree, never the real corpus.
+set -u
+GATE="$(cd "$(dirname "$0")/.." && pwd)/check-no-task-id-leaks.mjs"
+[[ -f "$GATE" ]] || { echo "FAIL: $GATE missing" >&2; exit 1; }
+PASS=0; FAIL=0
+
+ROOT=$(mktemp -d)
+trap 'rm -rf "$ROOT"' EXIT
+mkdir -p "$ROOT/platform/plugins/demo/skills/demo" \
+         "$ROOT/platform/templates/specialists" \
+         "$ROOT/.docs"
+
+clean_skill() { printf '# Demo skill\n\nDoes a thing.\n' > "$ROOT/platform/plugins/demo/skills/demo/SKILL.md"; }
+clean_skill
+
+# 1. Clean corpus -> gate passes.
+out=$(TASK_ID_LEAK_ROOT="$ROOT" node "$GATE" 2>&1); rc=$?
+if [[ "$rc" -eq 0 ]]; then
+  echo "PASS: clean markdown corpus -> exit 0"; PASS=$((PASS+1))
+else
+  echo "FAIL: clean corpus tripped gate (rc=$rc): $out" >&2; FAIL=$((FAIL+1))
+fi
+
+# 2. `(Task 999)` parenthetical under a shipped skill -> gate fails + names it.
+printf '# Demo skill\n\nDoes a thing (Task 999).\n' > "$ROOT/platform/plugins/demo/skills/demo/SKILL.md"
+out=$(TASK_ID_LEAK_ROOT="$ROOT" node "$GATE" 2>&1); rc=$?
+if [[ "$rc" -ne 0 ]] \
+   && printf '%s' "$out" | grep -q '\[task-id-leak\] file=platform/plugins/demo/skills/demo/SKILL.md'; then
+  echo "PASS: (Task 999) in shipped skill fails the gate"; PASS=$((PASS+1))
+else
+  echo "FAIL: parenthetical citation not caught (rc=$rc): $out" >&2; FAIL=$((FAIL+1))
+fi
+clean_skill
+
+# 3. Bare `Task 999` (prose form) under a shipped template -> gate fails + names it.
+printf 'Task 999 changed the routing.\n' > "$ROOT/platform/templates/specialists/AGENT.md"
+out=$(TASK_ID_LEAK_ROOT="$ROOT" node "$GATE" 2>&1); rc=$?
+if [[ "$rc" -ne 0 ]] \
+   && printf '%s' "$out" | grep -q '\[task-id-leak\] file=platform/templates/specialists/AGENT.md'; then
+  echo "PASS: bare Task 999 in shipped template fails the gate"; PASS=$((PASS+1))
+else
+  echo "FAIL: bare prose citation not caught (rc=$rc): $out" >&2; FAIL=$((FAIL+1))
+fi
+rm -f "$ROOT/platform/templates/specialists/AGENT.md"
+
+# 4. `Tasks 12 and 34` plural form under a shipped skill -> gate fails.
+printf '# Demo skill\n\nMerged behaviour (Tasks 12 and 34).\n' > "$ROOT/platform/plugins/demo/skills/demo/SKILL.md"
+out=$(TASK_ID_LEAK_ROOT="$ROOT" node "$GATE" 2>&1); rc=$?
+if [[ "$rc" -ne 0 ]] \
+   && printf '%s' "$out" | grep -q '\[task-id-leak\] .*match=Tasks 12'; then
+  echo "PASS: plural Tasks NNN form fails the gate"; PASS=$((PASS+1))
+else
+  echo "FAIL: plural citation not caught (rc=$rc): $out" >&2; FAIL=$((FAIL+1))
+fi
+clean_skill
+
+# 4b. Hyphenated `Pre-Task-748` form under a shipped skill -> gate fails.
+printf '# Demo skill\n\nPre-Task-748 the index was small.\n' > "$ROOT/platform/plugins/demo/skills/demo/SKILL.md"
+out=$(TASK_ID_LEAK_ROOT="$ROOT" node "$GATE" 2>&1); rc=$?
+if [[ "$rc" -ne 0 ]] \
+   && printf '%s' "$out" | grep -q '\[task-id-leak\] .*match=Task-748'; then
+  echo "PASS: hyphenated Pre-Task-748 form fails the gate"; PASS=$((PASS+1))
+else
+  echo "FAIL: hyphenated citation not caught (rc=$rc): $out" >&2; FAIL=$((FAIL+1))
+fi
+clean_skill
+
+# 4c. A lowercase `task-836-foo` slug (branch/file name) -> gate does NOT trip.
+printf '# Demo skill\n\nWork landed on branch task-836-foo.\n' > "$ROOT/platform/plugins/demo/skills/demo/SKILL.md"
+out=$(TASK_ID_LEAK_ROOT="$ROOT" node "$GATE" 2>&1); rc=$?
+if [[ "$rc" -eq 0 ]]; then
+  echo "PASS: lowercase task-836 slug is not flagged"; PASS=$((PASS+1))
+else
+  echo "FAIL: lowercase slug wrongly tripped gate (rc=$rc): $out" >&2; FAIL=$((FAIL+1))
+fi
+clean_skill
+
+# 4d. Lowercase prose `before task 127` under a shipped skill -> gate fails.
+printf '# Demo skill\n\nResults from before task 127 remain in the graph.\n' > "$ROOT/platform/plugins/demo/skills/demo/SKILL.md"
+out=$(TASK_ID_LEAK_ROOT="$ROOT" node "$GATE" 2>&1); rc=$?
+if [[ "$rc" -ne 0 ]] \
+   && printf '%s' "$out" | grep -q '\[task-id-leak\] .*match=task 127'; then
+  echo "PASS: lowercase prose 'task 127' fails the gate"; PASS=$((PASS+1))
+else
+  echo "FAIL: lowercase prose citation not caught (rc=$rc): $out" >&2; FAIL=$((FAIL+1))
+fi
+clean_skill
+
+# 4e. A `.tasks/<n>-…-task-NNN.md` file-path reference -> gate does NOT trip
+#     (file paths are out of scope; the hyphenated-lowercase shape is exempt).
+printf '# Demo skill\n\nTracked in `.tasks/339-installer-smoke-task-297.md` for now.\n' > "$ROOT/platform/plugins/demo/skills/demo/SKILL.md"
+out=$(TASK_ID_LEAK_ROOT="$ROOT" node "$GATE" 2>&1); rc=$?
+if [[ "$rc" -eq 0 ]]; then
+  echo "PASS: .tasks/ file-path reference is not flagged"; PASS=$((PASS+1))
+else
+  echo "FAIL: .tasks/ path wrongly tripped gate (rc=$rc): $out" >&2; FAIL=$((FAIL+1))
+fi
+clean_skill
+
+# 5. A hex colour `#999` in a shipped .md -> gate does NOT trip (not a citation).
+printf '# Demo skill\n\nUse colour `#999` for labels.\n' > "$ROOT/platform/plugins/demo/skills/demo/SKILL.md"
+out=$(TASK_ID_LEAK_ROOT="$ROOT" node "$GATE" 2>&1); rc=$?
+if [[ "$rc" -eq 0 ]]; then
+  echo "PASS: hex colour #999 is not flagged as a citation"; PASS=$((PASS+1))
+else
+  echo "FAIL: hex colour wrongly tripped gate (rc=$rc): $out" >&2; FAIL=$((FAIL+1))
+fi
+clean_skill
+
+# 6. Citation in a dev-only .docs doc -> gate does NOT trip (not a shipped root).
+printf 'Internal note about Task 999.\n' > "$ROOT/.docs/note.md"
+out=$(TASK_ID_LEAK_ROOT="$ROOT" node "$GATE" 2>&1); rc=$?
+if [[ "$rc" -eq 0 ]]; then
+  echo "PASS: .docs citation is exempt (dev-only, unscanned)"; PASS=$((PASS+1))
+else
+  echo "FAIL: .docs citation wrongly tripped gate (rc=$rc): $out" >&2; FAIL=$((FAIL+1))
+fi
+
+echo "----"; echo "PASS=$PASS FAIL=$FAIL"
+[[ "$FAIL" -eq 0 ]]

package/payload/platform/scripts/__tests__/resume-tunnel.test.sh

@@ -276,12 +276,265 @@ case_supervision_contract() {
   return 0
 }
 
+# ---------------------------------------------------------------------------
+# Task 833 — stray-connector reap.
+#
+# install_reap_stubs adds a `ps` stub and a `kill` recorder on top of setup().
+# The ps stub reads a table file ($root/ps_table) of "<pid> <argv...>" lines and
+# answers both query shapes the script uses: `-eo pid=,args=` (full table) and
+# `-p <pid> -o args=` (single argv). The recorder ($root/bin/killrec, wired via
+# RESUME_TUNNEL_KILL_CMD) appends -TERM/-KILL calls to $root/reap_log; on a `-0`
+# liveness query it reports "gone" (exit 1) unless $root/reap_alive exists.
+install_reap_stubs() {
+  local root="$1"
+  local bin_dir="$root/bin"
+
+  cat > "$bin_dir/ps" <<SH
+#!/bin/bash
+table="$root/ps_table"
+if [[ "\$*" == *"-p"* ]]; then
+  pid=""; prev=""
+  for a in "\$@"; do
+    [[ "\$prev" == "-p" ]] && pid="\$a"
+    prev="\$a"
+  done
+  awk -v want="\$pid" '{ if (\$1==want){ \$1=""; sub(/^ /,""); print } }' "\$table" 2>/dev/null
+  exit 0
+fi
+cat "\$table" 2>/dev/null
+exit 0
+SH
+  chmod +x "$bin_dir/ps"
+
+  cat > "$bin_dir/killrec" <<SH
+#!/bin/bash
+if [[ "\$1" == "-0" ]]; then
+  [[ -f "$root/reap_alive" ]] && exit 0 || exit 1
+fi
+echo "\$*" >> "$root/reap_log"
+exit 0
+SH
+  chmod +x "$bin_dir/killrec"
+}
+
+# Write a config.yml carrying the brand tunnel id so the audit line can resolve it.
+write_branded_config() {
+  local cfg="$1"
+  cat > "$cfg" <<'YML'
+tunnel: test-tunnel-id
+credentials-file: /dev/null
+ingress:
+  - service: http_status:404
+YML
+}
+
+# Run resume-tunnel with the reap stubs + recorder active.
+# Args: root config_dir [extra env assignments...]
+run_with_reap() {
+  local root="$1" config_dir="$2"; shift 2
+  # Use env so any extra "NAME=VALUE" args (e.g. RESUME_TUNNEL_REAP_GRACE=0)
+  # are applied as assignments — a variable-expanded NAME=VALUE word is NOT
+  # treated as an assignment by bash's own simple-command parsing.
+  env \
+    HOME="$root/home" \
+    PATH="$root/bin:$PATH" \
+    MAXY_PLATFORM_ROOT="$root/platform_root" \
+    RESUME_TUNNEL_KILL_CMD="$root/bin/killrec" \
+    RESUME_TUNNEL_VERIFY_DEADLINE=2 \
+    "$@" \
+    bash "$RESUME"
+}
+
+# CASE A: stray present, service inactive → reap kills stray, leaves none, then spawns.
+case_reap_stray_then_spawn() {
+  local root; root=$(mktemp -d /tmp/resume-tunnel-test-XXXXXX)
+  setup "$root" ".maxy-code" "inactive" "yes"
+  install_reap_stubs "$root"
+  local home="$root/home"
+  local cert="$home/.maxy-code/cloudflared/cert.pem"
+  local cfg="$home/.maxy-code/cloudflared/config.yml"
+  write_branded_config "$cfg"
+  cat > "$root/ps_table" <<TBL
+210086 cloudflared --origincert $cert --config $cfg tunnel run
+777 cloudflared --origincert /home/other/.realagent/cloudflared/cert.pem --config /home/other/.realagent/cloudflared/config.yml tunnel run
+TBL
+
+  run_with_reap "$root" ".maxy-code"
+  local log; log=$(cat "$home/.maxy-code/logs/cloudflared.log" 2>/dev/null || echo "")
+  local rec; rec=$(cat "$root/reap_log" 2>/dev/null || echo "")
+  cleanup "$root"
+
+  echo "$log" | grep -q "op=reap brand=maxy-code found=1 killed=1 survivor=none" || { echo "  census wrong"; echo "$log"; return 1; }
+  echo "$rec" | grep -q -- "-TERM 210086" || { echo "  stray not SIGTERMed"; echo "$rec"; return 1; }
+  echo "$rec" | grep -q "777" && { echo "  co-resident 777 was signalled"; echo "$rec"; return 1; }
+  echo "$log" | grep -q "spawned service=cloudflared-maxy-code.service" || { echo "  did not spawn after reap"; echo "$log"; return 1; }
+  return 0
+}
+
+# CASE B: supervised survivor + stray, service active → reap kills only stray, no spawn.
+case_reap_keeps_survivor() {
+  local root; root=$(mktemp -d /tmp/resume-tunnel-test-XXXXXX)
+  setup "$root" ".maxy-code" "active" "yes"
+  install_reap_stubs "$root"
+  local home="$root/home"
+  local cert="$home/.maxy-code/cloudflared/cert.pem"
+  local cfg="$home/.maxy-code/cloudflared/config.yml"
+  write_branded_config "$cfg"
+  # 12345 is the MainPID the systemctl stub reports.
+  cat > "$root/ps_table" <<TBL
+12345 cloudflared --no-autoupdate --origincert $cert --config $cfg tunnel run
+210086 cloudflared --origincert $cert --config $cfg tunnel run
+TBL
+
+  run_with_reap "$root" ".maxy-code"
+  local log; log=$(cat "$home/.maxy-code/logs/cloudflared.log" 2>/dev/null || echo "")
+  local rec; rec=$(cat "$root/reap_log" 2>/dev/null || echo "")
+  cleanup "$root"
+
+  echo "$log" | grep -q "op=reap brand=maxy-code found=2 killed=1 survivor=12345" || { echo "  census wrong"; echo "$log"; return 1; }
+  echo "$rec" | grep -q -- "-TERM 210086" || { echo "  stray not SIGTERMed"; echo "$rec"; return 1; }
+  echo "$rec" | grep -q "12345" && { echo "  survivor 12345 was signalled"; echo "$rec"; return 1; }
+  echo "$log" | grep -q "spawned service=" && { echo "  spawned while already active"; echo "$log"; return 1; }
+  echo "$log" | grep -q "already running" || { echo "  missing already-running log"; echo "$log"; return 1; }
+  return 0
+}
+
+# CASE C: no stray, service active → idempotent, no kill, no spawn.
+case_reap_idempotent() {
+  local root; root=$(mktemp -d /tmp/resume-tunnel-test-XXXXXX)
+  setup "$root" ".maxy-code" "active" "yes"
+  install_reap_stubs "$root"
+  local home="$root/home"
+  local cert="$home/.maxy-code/cloudflared/cert.pem"
+  local cfg="$home/.maxy-code/cloudflared/config.yml"
+  write_branded_config "$cfg"
+  cat > "$root/ps_table" <<TBL
+12345 cloudflared --no-autoupdate --origincert $cert --config $cfg tunnel run
+TBL
+
+  run_with_reap "$root" ".maxy-code"
+  local log; log=$(cat "$home/.maxy-code/logs/cloudflared.log" 2>/dev/null || echo "")
+  local rec; rec=$(cat "$root/reap_log" 2>/dev/null || echo "")
+  cleanup "$root"
+
+  echo "$log" | grep -q "op=reap brand=maxy-code found=1 killed=0 survivor=12345" || { echo "  census wrong"; echo "$log"; return 1; }
+  [ -z "$rec" ] || { echo "  recorder not empty"; echo "$rec"; return 1; }
+  echo "$log" | grep -q "spawned service=" && { echo "  spawned while single+active"; echo "$log"; return 1; }
+  return 0
+}
+
+# CASE D: audit line resolves the brand tunnel id from the victim's --config.
+case_reap_audit_tunnel_id() {
+  local root; root=$(mktemp -d /tmp/resume-tunnel-test-XXXXXX)
+  setup "$root" ".maxy-code" "inactive" "yes"
+  install_reap_stubs "$root"
+  local home="$root/home"
+  local cert="$home/.maxy-code/cloudflared/cert.pem"
+  local cfg="$home/.maxy-code/cloudflared/config.yml"
+  write_branded_config "$cfg"
+  cat > "$root/ps_table" <<TBL
+210086 cloudflared --origincert $cert --config $cfg tunnel run
+TBL
+
+  run_with_reap "$root" ".maxy-code"
+  local log; log=$(cat "$home/.maxy-code/logs/cloudflared.log" 2>/dev/null || echo "")
+  cleanup "$root"
+
+  echo "$log" | grep -q "op=reap brand=maxy-code target=210086 tunnel=test-tunnel-id" || { echo "  audit line missing brand tunnel id"; echo "$log"; return 1; }
+  return 0
+}
+
+# CASE E: only a foreign (co-resident) connector present → untouched, brand still spawns.
+case_reap_foreign_untouched() {
+  local root; root=$(mktemp -d /tmp/resume-tunnel-test-XXXXXX)
+  setup "$root" ".maxy-code" "inactive" "yes"
+  install_reap_stubs "$root"
+  local home="$root/home"
+  write_branded_config "$home/.maxy-code/cloudflared/config.yml"
+  cat > "$root/ps_table" <<TBL
+777 cloudflared --origincert /home/other/.realagent/cloudflared/cert.pem --config /home/other/.realagent/cloudflared/config.yml tunnel run
+TBL
+
+  run_with_reap "$root" ".maxy-code"
+  local log; log=$(cat "$home/.maxy-code/logs/cloudflared.log" 2>/dev/null || echo "")
+  local rec; rec=$(cat "$root/reap_log" 2>/dev/null || echo "")
+  cleanup "$root"
+
+  echo "$log" | grep -q "op=reap brand=maxy-code found=0 killed=0 survivor=none" || { echo "  census wrong"; echo "$log"; return 1; }
+  [ -z "$rec" ] || { echo "  foreign connector signalled"; echo "$rec"; return 1; }
+  echo "$log" | grep -q "spawned service=cloudflared-maxy-code.service" || { echo "  did not spawn own connector"; echo "$log"; return 1; }
+  return 0
+}
+
+# CASE G: service active but MainPID unresolved → must NOT reap (can't tell the
+# live supervised connector from a stray), must skip without spawning.
+case_reap_skip_when_mainpid_unresolved() {
+  local root; root=$(mktemp -d /tmp/resume-tunnel-test-XXXXXX)
+  setup "$root" ".maxy-code" "active" "yes"
+  install_reap_stubs "$root"
+  local home="$root/home"
+  local cert="$home/.maxy-code/cloudflared/cert.pem"
+  local cfg="$home/.maxy-code/cloudflared/config.yml"
+  write_branded_config "$cfg"
+  # Override systemctl so MainPID resolves empty while is-active stays active
+  # (the RestartSec transition window).
+  cat > "$root/bin/systemctl" <<'SH'
+#!/bin/bash
+if [[ "$*" == *"is-active"* ]]; then echo "active"; exit 0; fi
+if [[ "$*" == *"--property=MainPID"* ]]; then echo ""; fi
+exit 0
+SH
+  chmod +x "$root/bin/systemctl"
+  cat > "$root/ps_table" <<TBL
+210086 cloudflared --no-autoupdate --origincert $cert --config $cfg tunnel run
+TBL
+
+  run_with_reap "$root" ".maxy-code"
+  local log; log=$(cat "$home/.maxy-code/logs/cloudflared.log" 2>/dev/null || echo "")
+  local rec; rec=$(cat "$root/reap_log" 2>/dev/null || echo "")
+  cleanup "$root"
+
+  [ -z "$rec" ] || { echo "  reaped while survivor unknown — would kill the live connector"; echo "$rec"; return 1; }
+  echo "$log" | grep -q "skipped reason=mainpid-unresolved" || { echo "  missing mainpid-unresolved skip log"; echo "$log"; return 1; }
+  echo "$log" | grep -q "spawned service=" && { echo "  spawned while active"; echo "$log"; return 1; }
+  return 0
+}
+
+# CASE F: stray survives SIGTERM → escalates to SIGKILL.
+case_reap_sigkill_escalation() {
+  local root; root=$(mktemp -d /tmp/resume-tunnel-test-XXXXXX)
+  setup "$root" ".maxy-code" "inactive" "yes"
+  install_reap_stubs "$root"
+  local home="$root/home"
+  local cert="$home/.maxy-code/cloudflared/cert.pem"
+  local cfg="$home/.maxy-code/cloudflared/config.yml"
+  write_branded_config "$cfg"
+  touch "$root/reap_alive"   # recorder reports the proc still alive on -0
+  cat > "$root/ps_table" <<TBL
+210086 cloudflared --origincert $cert --config $cfg tunnel run
+TBL
+
+  run_with_reap "$root" ".maxy-code" RESUME_TUNNEL_REAP_GRACE=0
+  local rec; rec=$(cat "$root/reap_log" 2>/dev/null || echo "")
+  cleanup "$root"
+
+  echo "$rec" | grep -q -- "-KILL 210086" || { echo "  no SIGKILL escalation"; echo "$rec"; return 1; }
+  return 0
+}
+
 run_case "skip when service active" case_skip_when_scope_active
 run_case "spawn succeeds and logs verified" case_spawn_succeeds
 run_case "spawn with no connection logs ERROR exits 0" case_spawn_no_connection
 run_case "service unit name derived from configDir" case_scope_unit_name_from_config_dir
 run_case "slice flag passed to systemd-run" case_slice_flag_present
 run_case "supervision contract: restart-always + no-autoupdate + .service" case_supervision_contract
+run_case "reap: stray reaped then spawn (inactive)" case_reap_stray_then_spawn
+run_case "reap: keeps supervised survivor, no spawn (active)" case_reap_keeps_survivor
+run_case "reap: idempotent when single+active" case_reap_idempotent
+run_case "reap: audit line names brand tunnel id" case_reap_audit_tunnel_id
+run_case "reap: foreign co-resident connector untouched" case_reap_foreign_untouched
+run_case "reap: SIGTERM survivor escalates to SIGKILL" case_reap_sigkill_escalation
+run_case "reap: skip when active unit's MainPID is unresolved" case_reap_skip_when_mainpid_unresolved
 
 echo ""
 echo "Results: $PASS passed, $FAIL failed"

package/payload/platform/scripts/check-no-esm-require.mjs

@@ -51,6 +51,10 @@ const ALLOWLIST = new Set([
   // (server-init-line-stamper.cjs); the test loads it via the sanctioned
   // createRequire(import.meta.url) ESM→CJS bridge, not a raw require.
   'platform/ui/app/lib/__tests__/server-init-line-stamper.test.ts',
+  // Same vi.hoisted pattern: Task 829's operator-domains test builds a tmpdir
+  // before the module's `../paths` mock fires, to redirect MAXY_DIR off the
+  // operator's real home config.
+  'platform/ui/app/lib/__tests__/operator-domains.test.ts',
 ])
 
 const REQUIRE_CALL_RE = /\brequire\s*\(/

package/payload/platform/scripts/check-no-task-id-leaks.mjs

@@ -21,7 +21,11 @@ import { dirname, join, relative, sep, basename } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url))
-const REPO_ROOT = join(SCRIPT_DIR, '..', '..')
+// REPO_ROOT is overridable so the `.test.sh` self-test can point the gate at a
+// fixture tree without dropping citation-bearing files into the real corpus.
+const REPO_ROOT = process.env.TASK_ID_LEAK_ROOT
+  ? process.env.TASK_ID_LEAK_ROOT
+  : join(SCRIPT_DIR, '..', '..')
 
 const SCAN_ROOTS = [
   join(REPO_ROOT, 'platform', 'scripts'),
@@ -37,6 +41,26 @@ const SKIP_DIR_NAMES = new Set([
 ])
 const TASK_ID_RE = /\(Task \d+\)/
 
+// Markdown mode. Unlike code files — where a citation is legal in a comment and
+// only the parenthetical operator-visible form is rejected — a shipped `.md`
+// loads into a client-facing agent's context wholesale, so ANY citation form
+// leaks. Catches `Task NNN`, `(Task NNN)`, `Tasks NNN`, `since Task NNN`. It
+// deliberately does NOT match bare `#NNN`: every `#NNN` in the corpus is a hex
+// colour and there is no signal to separate `#732`-issue from `#732`-hex.
+// Two alternatives:
+//   `\bTasks?[\s-]+\d{2,4}` — capital-T, any separator: `Task 732`, `(Task 732)`,
+//     `Tasks 12`, the hyphenated `Pre-Task-748` / `post-Task-904` forms.
+//   `\btasks?\s+\d{2,4}` — lowercase but SPACE-separated only: catches prose
+//     citations like "before task 127", while a lowercase HYPHENATED `task-537`
+//     stays exempt because that shape is a branch slug or a `.tasks/<n>-…-task-NNN.md`
+//     file-path reference (file paths are out of this gate's scope). The 2-digit
+//     floor keeps single-digit domain counts ("task 1 of 3") out.
+const MD_TASK_ID_RE = /\bTasks?[\s-]+\d{2,4}|\btasks?\s+\d{2,4}/
+const MD_SCAN_ROOTS = [
+  join(REPO_ROOT, 'platform', 'plugins'),
+  join(REPO_ROOT, 'platform', 'templates'),
+]
+
 function isCommentLine(line) {
   const trimmed = line.replace(/^\s+/, '')
   if (trimmed.startsWith('#')) return true
@@ -97,14 +121,38 @@ for (const root of SCAN_ROOTS) {
   }
 }
 
+// Markdown scan — shipped operator-loadable docs. Reuses `walk` (which already
+// skips node_modules/dist/build/.next/payload/__tests__) and matches every line
+// against MD_TASK_ID_RE with no comment skip: the whole doc is agent content.
+// .docs/ and .tasks/ are not under MD_SCAN_ROOTS, so they stay citation-rich.
+for (const root of MD_SCAN_ROOTS) {
+  for (const file of walk(root)) {
+    if (!file.endsWith('.md')) continue
+    let content
+    try {
+      content = readFileSync(file, 'utf-8')
+    } catch {
+      continue
+    }
+    const lines = content.split('\n')
+    for (let i = 0; i < lines.length; i++) {
+      const m = lines[i].match(MD_TASK_ID_RE)
+      if (!m) continue
+      leaks.push({ file: relative(REPO_ROOT, file), line: i + 1, content: m[0] })
+    }
+  }
+}
+
 if (leaks.length > 0) {
-  console.error(`check-no-task-id-leaks: ${leaks.length} operator-visible (Task NNN) citation(s) found:`)
+  console.error(`check-no-task-id-leaks: ${leaks.length} task-id citation(s) found:`)
   for (const leak of leaks) {
-    console.error(`  ${leak.file}:${leak.line}: ${leak.content}`)
+    console.error(`[task-id-leak] file=${leak.file} line=${leak.line} match=${leak.content}`)
   }
   console.error('')
-  console.error('Citations belong in inline comments only, never in operator-visible strings')
-  console.error('(stderr/stdout, log files surfaced via logs-read.sh, systemd unit')
-  console.error('--description=, error messages, console.log/warn/error, throw new Error).')
+  console.error('Code files: citations belong in inline comments only, never in operator-visible')
+  console.error('strings (stderr/stdout, logs, systemd --description=, error messages, console.*).')
+  console.error('Shipped markdown (platform/plugins, platform/templates): no task citation in any')
+  console.error('form — the whole doc loads into a client-facing agent. Dev docs (.docs/, .tasks/)')
+  console.error('are exempt and keep their citations.')
   process.exit(1)
 }

package/payload/platform/scripts/resume-tunnel.sh

@@ -60,15 +60,99 @@ fi
 BRAND="${CONFIG_DIR#.}"
 SERVICE_UNIT="cloudflared-${BRAND}.service"
 
-# Liveness check: query the service unit state, not a recorded PID.
-# The service is owned by user-systemd, fully outside the brand service's cgroup.
+CERT_PATH="$HOME/$CONFIG_DIR/cloudflared/cert.pem"
+
+# Task 833 — single-instance enforcement. cloudflared does not hot-reload
+# config.yml; a config change needs a connector restart. resume-tunnel is the
+# single spawner but historically managed only its OWN connector, so a connector
+# started any other way (an unsupervised process from before Task 757, a manual
+# `tunnel run`, a provisioning step that raw-spawned) survived — two connectors
+# on one tunnel, one on stale config, and Cloudflare routes some requests to the
+# stale one → intermittent 404 for any host added after it started. reap_strays
+# guarantees exactly one connector for THIS brand before the spawn/skip decision.
+#
+# Brand isolation: a candidate is reaped only if its argv carries a brand-scoped
+# token — the cert path, config path, or tunnel id, each unique to ~/.<brand>/.
+# A co-resident brand's connector matches none and is never touched. If no brand
+# token is known we skip the reap entirely rather than risk a match-everything.
+KILL_CMD="${RESUME_TUNNEL_KILL_CMD:-kill}"
+
+reap_strays() {
+  local survivor_pid="$1"
+  local match_args=()
+  [ -n "$CERT_PATH" ]   && match_args+=( -e "$CERT_PATH" )
+  [ -n "$CONFIG_PATH" ] && match_args+=( -e "$CONFIG_PATH" )
+  [ -n "$TUNNEL_ID" ]   && match_args+=( -e "$TUNNEL_ID" )
+  if [ "${#match_args[@]}" -eq 0 ]; then
+    log "[tunnel-supervise] op=reap brand=$BRAND found=0 killed=0 survivor=${survivor_pid:-none} (no brand token; skipped)"
+    return 0
+  fi
+
+  local pids
+  pids=$(ps -eo pid=,args= 2>/dev/null \
+    | grep 'cloudflared' \
+    | grep 'tunnel run' \
+    | grep -F "${match_args[@]}" \
+    | awk '{print $1}')
+
+  local found=0 killed=0 pid
+  for pid in $pids; do
+    found=$((found + 1))
+    if [ -n "$survivor_pid" ] && [ "$pid" = "$survivor_pid" ]; then
+      continue
+    fi
+    local victim_cfg victim_tid
+    victim_cfg=$(ps -p "$pid" -o args= 2>/dev/null | sed -n 's/.*--config[ =]\([^ ]*\).*/\1/p')
+    victim_tid=$(grep -E '^tunnel:' "$victim_cfg" 2>/dev/null | head -1 | awk '{print $2}')
+    [ -n "$victim_tid" ] || victim_tid="unknown"
+    log "[tunnel-supervise] op=reap brand=$BRAND target=$pid tunnel=$victim_tid"
+    "$KILL_CMD" -TERM "$pid" 2>/dev/null
+    local waited=0
+    while "$KILL_CMD" -0 "$pid" 2>/dev/null; do
+      if [ "$waited" -ge "${RESUME_TUNNEL_REAP_GRACE:-5}" ]; then
+        "$KILL_CMD" -KILL "$pid" 2>/dev/null
+        break
+      fi
+      sleep 1
+      waited=$((waited + 1))
+    done
+    killed=$((killed + 1))
+  done
+
+  log "[tunnel-supervise] op=reap brand=$BRAND found=$found killed=$killed survivor=${survivor_pid:-none}"
+}
+
+# Determine the supervised survivor before reaping. If the unit is active its
+# MainPID is the connector we keep; every other brand-matched connector is a
+# stray. The service is owned by user-systemd, fully outside the brand service's
+# cgroup. Unlike before, an active unit no longer short-circuits the whole
+# script: the reap runs first so strays die even when the supervised one is up.
+SURVIVOR_PID=""
+SERVICE_ACTIVE=0
 if systemctl --user is-active "$SERVICE_UNIT" >/dev/null 2>&1; then
-  SERVICE_PID=$(systemctl --user show "$SERVICE_UNIT" --property=MainPID --value 2>/dev/null || echo "unknown")
-  log "Tunnel already running (service $SERVICE_UNIT active, MainPID $SERVICE_PID) — skipping resume"
+  SERVICE_ACTIVE=1
+  SURVIVOR_PID=$(systemctl --user show "$SERVICE_UNIT" --property=MainPID --value 2>/dev/null || echo "")
+  [ "$SURVIVOR_PID" = "0" ] && SURVIVOR_PID=""
+fi
+
+# If the unit is active but its MainPID is unresolved (a RestartSec transition:
+# is-active already true while the new MainPID is not yet published), we cannot
+# tell the live supervised connector from a stray — reaping now could SIGKILL the
+# survivor. Skip the reap this cycle; the next brand-service start reaps once
+# MainPID resolves. The connector is up, so there is nothing to spawn either.
+if [ "$SERVICE_ACTIVE" -eq 1 ] && [ -z "$SURVIVOR_PID" ]; then
+  log "[tunnel-supervise] op=reap brand=$BRAND skipped reason=mainpid-unresolved survivor=unknown"
+  log "Tunnel already running (service $SERVICE_UNIT active, MainPID unresolved) — reap skipped, skipping resume"
+  exit 0
+fi
+
+reap_strays "$SURVIVOR_PID"
+
+if [ "$SERVICE_ACTIVE" -eq 1 ]; then
+  log "Tunnel already running (service $SERVICE_UNIT active, MainPID ${SURVIVOR_PID:-unknown}) — strays reaped, skipping resume"
   exit 0
 fi
 
-CERT_PATH="$HOME/$CONFIG_DIR/cloudflared/cert.pem"
 CLOUDFLARED_BIN=$(command -v cloudflared 2>/dev/null || true)
 
 if [ -z "$CLOUDFLARED_BIN" ]; then

package/payload/platform/services/whatsapp-channel/dist/notification.d.ts

@@ -137,6 +137,20 @@ export declare function postWithRetry(attempt: () => Promise<boolean>, opts: {
     delayMs: number;
     sleep: (ms: number) => Promise<void>;
 }): Promise<boolean>;
+/**
+ * Build the body for POST /wa-channel/turn-end — the turn-end decision the
+ * channel server posts once per turn (Task 832). senderId + sessionId are the
+ * server's fixed values (spawn env), never model-supplied; `replied` is whether
+ * a reply/reply-document tool_use occurred in the turn; `finalText` is the
+ * end_turn message's text (the conclusion the gateway delivers only when nothing
+ * was delivered).
+ */
+export declare function buildTurnEndPostBody(mySenderId: string, sessionId: string, replied: boolean, finalText: string): {
+    senderId: string;
+    sessionId: string;
+    replied: boolean;
+    finalText: string;
+};
 /** Map a non-OK /wa-channel/reply response into an actionable MCP error string.
  *  Terminal (logged out / device removed) tells the agent re-pairing is needed
  *  and it must NOT promise an automatic recovery; transient keeps the

package/payload/platform/services/whatsapp-channel/dist/notification.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"notification.d.ts","sourceRoot":"","sources":["../src/notification.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,CAAA;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAA;IAChB,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAA;IACZ,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAA;IACnB;;;kFAG8E;IAC9E,KAAK,EAAE,YAAY,EAAE,CAAA;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,mBAAmB,QAYI,CAAA;AAEpC;;;YAGY;AACZ,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,cAAc;;;;;EAOzD;AA0BD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,cAAc,GAAG,eAAe,CAMtE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAElF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAEvG;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,CAAC,EAAE,MAAM,GACf;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAIzD;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAE3C;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,EAC/B,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,GAChF,OAAO,CAAC,OAAO,CAAC,CAMlB;AAED;;;;gCAIgC;AAChC,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CAMrE"}
+{"version":3,"file":"notification.d.ts","sourceRoot":"","sources":["../src/notification.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,CAAA;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAA;IAChB,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAA;IACZ,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAA;IACnB;;;kFAG8E;IAC9E,KAAK,EAAE,YAAY,EAAE,CAAA;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,mBAAmB,QAYI,CAAA;AAEpC;;;YAGY;AACZ,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,cAAc;;;;;EAOzD;AA0BD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,cAAc,GAAG,eAAe,CAMtE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAElF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAEvG;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,CAAC,EAAE,MAAM,GACf;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAIzD;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAE3C;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,EAC/B,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,GAChF,OAAO,CAAC,OAAO,CAAC,CAMlB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,GAChB;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAE9E;AAED;;;;gCAIgC;AAChC,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CAMrE"}

package/payload/platform/services/whatsapp-channel/dist/notification.js

@@ -156,6 +156,17 @@ export async function postWithRetry(attempt, opts) {
     }
     return false;
 }
+/**
+ * Build the body for POST /wa-channel/turn-end — the turn-end decision the
+ * channel server posts once per turn (Task 832). senderId + sessionId are the
+ * server's fixed values (spawn env), never model-supplied; `replied` is whether
+ * a reply/reply-document tool_use occurred in the turn; `finalText` is the
+ * end_turn message's text (the conclusion the gateway delivers only when nothing
+ * was delivered).
+ */
+export function buildTurnEndPostBody(mySenderId, sessionId, replied, finalText) {
+    return { senderId: mySenderId, sessionId, replied, finalText };
+}
 /** Map a non-OK /wa-channel/reply response into an actionable MCP error string.
  *  Terminal (logged out / device removed) tells the agent re-pairing is needed
  *  and it must NOT promise an automatic recovery; transient keeps the