@rubytech/create-maxy-code 0.1.300 → 0.1.301

package/payload/platform/plugins/whatsapp/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "whatsapp",
-  "description": "WhatsApp messaging channel — Baileys QR pairing, DM policy enforcement, inbound routing, business hours gating, conversation browsing. Reply-only in DMs (no agent-initiated send, Task 723); observation-only in groups (the agent never responds in a group, Task 726).",
+  "description": "WhatsApp messaging channel — Baileys QR pairing, DM policy enforcement, inbound routing, business hours gating, conversation browsing. Reply-only in DMs (no agent-initiated send); observation-only in groups (the agent never responds in a group).",
   "version": "0.1.0",
   "author": {
     "name": "Rubytech LLC"

package/payload/platform/plugins/whatsapp/PLUGIN.md

@@ -1,6 +1,6 @@
 ---
 name: whatsapp
-description: WhatsApp messaging channel — Baileys QR pairing, DM policy enforcement, inbound routing, business hours gating, conversation browsing. Reply-only in DMs (no agent-initiated send, Task 723); observation-only in groups (the agent never responds in a group, Task 726).
+description: WhatsApp messaging channel — Baileys QR pairing, DM policy enforcement, inbound routing, business hours gating, conversation browsing. Reply-only in DMs (no agent-initiated send); observation-only in groups (the agent never responds in a group).
 tools:
   - name: whatsapp-login-start
     publicAllowlist: false
@@ -57,7 +57,7 @@ Activate when the user asks about WhatsApp — connecting, linking, checking sta
 - QR-code-based WhatsApp pairing via Baileys (linked device) — `whatsapp-login-start` returns the QR as a scannable Unicode block printed on the PTY surface (the only operator surface); the operator scans it directly from the terminal output
 - Multi-account support (optional, multiple linked numbers)
 - Inbound message routing — sender-keyed `claude` PTY sessions via the loopback claude-session-manager (admin phone → admin agent, public → resolved public agent); a "typing…" presence is sent on receipt as an ack while the agent turn runs
-- Group observation — group messages are stored, persisted, and browsable, but the agent never responds in a group (observation-only, Task 726)
+- Group observation — group messages are stored, persisted, and browsable, but the agent never responds in a group (observation-only)
 - DM policy enforcement (open, allowlist, disabled)
 - Conversation browsing — list active conversations, read message history, inspect group metadata
 - Inbound voice note transcription (OGG Opus → text via local whisper.cpp)
@@ -76,17 +76,17 @@ Four tools for reading WhatsApp conversation context. The first two read from th
 | `whatsapp-conversation-graph-state` | Persisted `:Message:WhatsAppMessage` rows attached to the `:Conversation` (sessionKey-keyed) plus the resolved `sessionId`, the cypher string, and a divergence header reporting graph-row count vs in-memory count. Use when the question is "what got persisted" — never compose the cypher manually |
 | `whatsapp-group-info` | Group metadata from WhatsApp servers — subject, description, participants with admin flags, creation date. Requires active connection |
 
-## Group access — observation-only (Task 726)
+## Group access — observation-only
 
 The agent never responds in a group. `checkGroupAccess` ([`inbound/access-control.ts`](../../ui/app/lib/whatsapp/inbound/access-control.ts)) is a structural observe-only deny — it always returns `allowed:false reason:group-observe-only`, so every group inbound ends at the manager's `!accessResult.allowed` return before dispatch. There is no group policy, allowlist, per-group activation, or @mention setting; setting any of those keys is a `.strict()` schema rejection, not a silently-dead key. A belt invariant in the manager's `reply` closure refuses any `@g.us` recipient and logs `op=group-reply-blocked` — that line is the leak signature if a dispatch path ever leaks.
 
 Observation is fully preserved: group messages are stored in the ring buffer, recorded as activity, and persisted to the graph at the access-independent capture site, and remain visible via `whatsapp-conversations`, `whatsapp-group-info`, `list-groups`, and the `/whatsapp` reader. This is a Meta-policy constraint (automated messaging from an unofficial linked device is penalised, the same class as the reply-only DM posture); for agent-driven group messaging, Telegram is the recommended channel.
 
-## Native channel reply surface (Task 751)
+## Native channel reply surface
 
 A native admin channel session runs a per-sender `whatsapp-channel` MCP server (`platform/services/whatsapp-channel/`) exposing two reply-only tools: `reply` (text) and `reply-document` (one or more files delivered as WhatsApp documents). `reply-document` POSTs to the gateway's `POST /wa-channel/reply-document`, which funnels through `sendWhatsAppDocument` — the single send core that owns account-dir path validation, the 100 MB ceiling, the canonical `[whatsapp:outbound] sent document …` log, and per-file reconciliation (`op=reply-document-reconciled` on delivery, `file-delivery-unreconciled` on a miss — no silent failure). A bare `SendUserFile` is also caught and delivered through the same core by a read-only JSONL follower on the session, so an attachment reaches the sender even when the agent skips the explicit tool. Both surfaces are reply-only: a file reply to a sender with no live conversation is refused. See [channels-whatsapp.md](references/channels-whatsapp.md) and `.docs/whatsapp-inbound-lifeline.md`.
 
-## Self-chat command lane (Task 774)
+## Self-chat command lane
 
 The agent links as a companion device on the operator's own WhatsApp account, so the operator cannot DM the agent from the paired handset — those messages arrive as `fromMe=true` / upsert type `append`. The operator's **self-chat** (message-yourself thread) is the command lane from that handset: the `append` branch in `manager.ts` evaluates a six-clause discriminator (`inbound/self-chat.ts`) — fromMe, self-surface jid (selfJid/selfLid/`selfPhone@s.whatsapp.net`, device-suffix normalised), not an agent-sent echo, timestamp strictly after `lastConnectedAt` (excludes reconnect history backfill; restart-safe backstop for the 2-min echo cache), not a duplicate, non-empty text — and dispatches a match to the **admin** agent with raw text; the reply lands back in the self-chat. Every self-chat `fromMe` message emits one `[whatsapp:self-chat] op=seen` line followed by `op=dispatch` or `op=skip reason=echo|backfill|duplicate|no-text`, so a dropped command is never silent. `fromMe` in any other thread is unchanged (`[Owner reply]` mirror). See [channels-whatsapp.md](references/channels-whatsapp.md) §Self-chat command lane.
 

package/payload/platform/plugins/whatsapp/references/channels-whatsapp.md

@@ -6,13 +6,13 @@ WhatsApp connects via Baileys multi-account:
 |----------|----------|------------|
 | **baileys** | All WhatsApp accounts | WebSocket via QR code (linked device) |
 
-## Reply-only posture (Task 723)
+## Reply-only posture
 
 The agent has **no tool to initiate a WhatsApp message to an arbitrary number.** The `whatsapp-send` and `whatsapp-send-document` MCP tools were removed after an agent-initiated cold first-contact send (to a number with no prior conversation) tripped WhatsApp's anti-automation guard and restricted the operator's account. Initiating is intentionally unavailable, not merely gated — a soft approval gate already existed and did not prevent the incident.
 
-What the agent **can** still do: reply within an existing chat. On a native admin channel session the whatsapp-channel server (`platform/services/whatsapp-channel/`) exposes two reply tools, both reply-only: `reply` (text) and `reply-document` (one or more files delivered as WhatsApp documents). `reply-document` POSTs to `POST /wa-channel/reply-document` → `sendWhatsAppDocument`, the one send core that owns path validation, the 100 MB ceiling, the canonical log, and per-file reconciliation (Task 751). A bare `SendUserFile` is also caught and delivered through the same core by a read-only JSONL follower on the session, so an attachment reaches the sender even if the agent skips the explicit tool. File delivery is refused for a sender with no live conversation — same reply-only posture as text. (The removed `whatsapp-send-document` route tool and the bridge path `SendUserFile` → `file-delivery-bridge.ts` → `POST /api/whatsapp/send-document` are the legacy webchat/email bridge surface, not the native WhatsApp channel.) Replying within your chats is what WhatsApp permits; starting new chats from a linked device is what it penalises.
+What the agent **can** still do: reply within an existing chat. On a native admin channel session the whatsapp-channel server (`platform/services/whatsapp-channel/`) exposes two reply tools, both reply-only: `reply` (text) and `reply-document` (one or more files delivered as WhatsApp documents). `reply-document` POSTs to `POST /wa-channel/reply-document` → `sendWhatsAppDocument`, the one send core that owns path validation, the 100 MB ceiling, the canonical log, and per-file reconciliation. A bare `SendUserFile` is also caught and delivered through the same core by a read-only JSONL follower on the session, so an attachment reaches the sender even if the agent skips the explicit tool. File delivery is refused for a sender with no live conversation — same reply-only posture as text. (The removed `whatsapp-send-document` route tool and the bridge path `SendUserFile` → `file-delivery-bridge.ts` → `POST /api/whatsapp/send-document` are the legacy webchat/email bridge surface, not the native WhatsApp channel.) Replying within your chats is what WhatsApp permits; starting new chats from a linked device is what it penalises.
 
-## Observation-only in groups (Task 726)
+## Observation-only in groups
 
 The agent **never responds in a group chat.** Every inbound group message is stored, recorded, and persisted to the graph (observation is fully preserved — `list-groups`, `whatsapp-group-info`, conversations, and the `/whatsapp` reader all still work), but it is never dispatched to a responding session and never produces an outbound message into the group. `checkGroupAccess` is a structural observe-only deny — there is no group policy, allowlist, per-group activation, or @mention setting to turn responses on. A belt invariant in the manager's `reply` closure refuses any `@g.us` recipient (`op=group-reply-blocked`).
 
@@ -118,7 +118,7 @@ Admin phones always bypass DM policy — the `isAdminPhone()` check runs before
 
 **Schema constraint:** `dmPolicy: "open"` requires `allowFrom` to include `"*"` (enforced by Zod validation).
 
-**Key file:** `access-control.ts` — `checkDmAccess()` gates DMs by the policy above; `checkGroupAccess()` is a structural observe-only deny (always `allowed:false reason:group-observe-only`, Task 726) — no group policy is consulted.
+**Key file:** `access-control.ts` — `checkDmAccess()` gates DMs by the policy above; `checkGroupAccess()` is a structural observe-only deny (always `allowed:false reason:group-observe-only`) — no group policy is consulted.
 
 **Config path:** Per-account at `whatsapp.accounts.{accountId}.dmPolicy` in `account.json`. Falls back to `whatsapp.dmPolicy`. Changes are conversational — the admin agent writes to config via `whatsapp-config action: "update-config"`.
 
@@ -150,7 +150,7 @@ The dedupe cache (`agentSentMessages`) has a 2-minute TTL and 500-entry cap, whi
 | `src/web/inbound/dedupe.ts` | `trackAgentSentMessage` / `isAgentSentMessage` — echo suppression cache |
 | `src/infra/outbound/cross-agent-echo.ts` | Adapter: agent tool → `mirrorOwnerReplyToSession` |
 
-## Self-chat command lane (Task 774)
+## Self-chat command lane
 
 The companion-device link means the operator's paired phone cannot DM the agent — a message typed from the paired number arrives as `fromMe=true` with upsert type `append`, which the manager's append branch historically dropped before dispatch. The operator's **self-chat** (the message-yourself thread, `remoteJid` == the account's own jid/lid) is the exception: the agent never writes there first, so it is an unambiguous admin command surface.
 

package/payload/platform/plugins/whatsapp/skills/manage-whatsapp-config/SKILL.md

@@ -70,7 +70,7 @@ The form's `submitMessage` must map the field values back to `update-config` fie
 
 The agent is **observation-only in groups**: it sees and records every group message but never replies in a group. There is no per-group setting to turn responses on — the restriction is structural, not a toggle. `whatsapp-config action: list-groups` still lists the groups the connected phone is in, for reference.
 
-This is a **Meta-policy constraint, not a Maxy limitation.** WhatsApp penalises automated and business-style messaging sent from an unofficial linked device. Replying in groups and sending cold first-contact messages are both anti-automation triggers — they restricted a live operator account, which is why the agent is observe-only in groups and reply-only in DMs (Task 723).
+This is a **Meta-policy constraint, not a Maxy limitation.** WhatsApp penalises automated and business-style messaging sent from an unofficial linked device. Replying in groups and sending cold first-contact messages are both anti-automation triggers — they restricted a live operator account, which is why the agent is observe-only in groups and reply-only in DMs.
 
 If the user wants an agent that actively messages in groups or initiates conversations, recommend **Telegram** instead. Telegram has no equivalent linked-device automation penalty, so the agent can send and respond freely there. Point them to the Telegram setup path at `platform/plugins/telegram/references/setup-guide.md`.
 

package/payload/platform/plugins/workflows/PLUGIN.md

@@ -124,7 +124,7 @@ Each step declares an `onFailure` policy:
 | `skipped` | Step failed but `onFailure: "skip"` kept execution going |
 | `failed` | Step failed and `onFailure: "abort"` stopped execution |
 
-(Historic `degraded` step results from before task 127 remain in the graph; the runner no longer produces them.)
+(Historic `degraded` step results from an earlier runner version remain in the graph; the runner no longer produces them.)
 
 ## Execution History
 

package/payload/platform/plugins/x-import/PLUGIN.md

@@ -21,7 +21,7 @@ The admin agent delegates to `specialists:database-operator` when the operator d
 
 ## What this plugin is not
 
-- **Not a new graph writer.** Every write routes through the existing `memory-ingest` surface — the document path keyed on `attachmentId` (tweet stream) writes `:KnowledgeDocument`, or the conversation-archive path keyed on `conversationIdentity` (DMs) writes `:ConversationArchive` (Task 397). Both attach `:Section` children. No bespoke `:Post`, `:DirectMessage`, `:DMThread`, `:Attachment`, or `:Thread` label is introduced; per-thread KD granularity is explicitly rejected.
+- **Not a new graph writer.** Every write routes through the existing `memory-ingest` surface — the document path keyed on `attachmentId` (tweet stream) writes `:KnowledgeDocument`, or the conversation-archive path keyed on `conversationIdentity` (DMs) writes `:ConversationArchive`. Both attach `:Section` children. No bespoke `:Post`, `:DirectMessage`, `:DMThread`, `:Attachment`, or `:Thread` label is introduced; per-thread KD granularity is explicitly rejected.
 - **Not a live X API client.** Archive-only — the X API is rate-limited and paid.
 - **Not a retweet importer.** Retweets-without-comment are not persisted reliably in X archives; the skill drops them.
 
@@ -29,5 +29,5 @@ The admin agent delegates to `specialists:database-operator` when the operator d
 
 - **memory** — the underlying graph-write surface used by the skill (`mcp__plugin_memory_memory__memory-write` etc.). The skill passes `source='x'` / `source='x-dm'` and `createdByAgent='x-import'` for provenance on every write.
 - **document-ingest** (memory skill) — owns the tweet-stream KnowledgeDocument writes. `:Section` classification is its responsibility, not this plugin's.
-- **conversation-archive** (memory skill) — owns the DM transcript writes (`:ConversationArchive` keyed on `conversationIdentity` — Task 397). The `x-dm` enum entry on `CONVERSATION_SOURCES` and the sibling normaliser in `platform/plugins/memory/mcp/src/lib/conversation-normalisers/x-dm.ts` are the only new code outside this plugin.
+- **conversation-archive** (memory skill) — owns the DM transcript writes (`:ConversationArchive` keyed on `conversationIdentity`). The `x-dm` enum entry on `CONVERSATION_SOURCES` and the sibling normaliser in `platform/plugins/memory/mcp/src/lib/conversation-normalisers/x-dm.ts` are the only new code outside this plugin.
 - **database-operator specialist** — owns execution. See [platform/templates/specialists/agents/database-operator.md](../../templates/specialists/agents/database-operator.md) external-archive ingestion clause.

package/payload/platform/plugins/x-import/skills/x-import/SKILL.md

@@ -118,6 +118,6 @@ Every `.js` shim read by this skill is gated through the wrapper regex documente
 
 - **Per-thread KDs.** One archive = one tweet-stream KD. Thread boundaries are section boundaries the classifier owns, not graph objects.
 - **Bespoke labels.** No `:Post`, `:Tweet`, `:DirectMessage`, `:DMThread`, `:Attachment`. Everything maps to the existing `:KnowledgeDocument` + `:ConversationArchive` + `:ImageObject` shapes.
-- **Tweet-level typed edges.** `:REPLIES_TO` / `:QUOTES` as graph edges off individual tweets are rejected; document-level `REPLIED_TO` / `QUOTED` from the KD to each `:Person` covers the same traversals at the right granularity. The Task 305 typed-edge pass enumerates the new KD and writes any further `COMMITTED_TO` / `MENTIONS` / `REFERENCES` edges from in-body references.
+- **Tweet-level typed edges.** `:REPLIES_TO` / `:QUOTES` as graph edges off individual tweets are rejected; document-level `REPLIED_TO` / `QUOTED` from the KD to each `:Person` covers the same traversals at the right granularity. The typed-edge pass enumerates the new KD and writes any further `COMMITTED_TO` / `MENTIONS` / `REFERENCES` edges from in-body references.
 - **Retweets-without-comment.** Not persisted reliably in X archives; dropped at parse.
 - **Live X API.** Archive-only.

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-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)
 }