@rubytech/create-maxy-code 0.1.210 → 0.1.214

package/payload/platform/plugins/admin/hooks/pre-tool-use.sh

@@ -8,72 +8,93 @@ set -uo pipefail
 
 AGENT_TYPE="${1:-public}"
 
+# Source the propagation emitter (Task 560). The library is fail-open;
+# any error path inside it logs to server.log and returns 0, so sourcing
+# never blocks the hook's primary allow/block contract.
+HOOKS_LIB_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)/lib"
+# shellcheck disable=SC1091
+[ -f "$HOOKS_LIB_DIR/hook-emit.sh" ] && source "$HOOKS_LIB_DIR/hook-emit.sh"
+
 # Read stdin — fail closed if unavailable
 if [ -t 0 ]; then
+  # No INPUT yet; propagate with agentId=unknown so the regression is visible.
+  if declare -F hook_emit_decision >/dev/null 2>&1; then
+    hook_emit_decision "unknown" "admin-tool-gate" "?" "block" \
+      "stdin-missing" "Blocked: Cannot determine tool call (no stdin). Failing closed." 2 0
+  fi
   echo "Blocked: Cannot determine tool call (no stdin). Failing closed." >&2
   exit 2
 fi
 INPUT=$(cat)
 TOOL_NAME=$(echo "$INPUT" | grep -o '"tool_name":"[^"]*"' | head -1 | cut -d'"' -f4)
 
+# Session id for propagation. Empty / parse-failure routes to "unknown" —
+# the propagator emits the record under agentId=unknown rather than dropping.
+SESSION_ID=$(printf '%s' "$INPUT" | python3 -c '
+import sys, json
+try:
+    print(json.load(sys.stdin).get("session_id", "") or "unknown")
+except Exception:
+    print("unknown")
+' 2>/dev/null || echo "unknown")
+
 # ---------------------------------------------------------------------------
 # Admin agent — code directory protection + approval gating
 # ---------------------------------------------------------------------------
 if [ "$AGENT_TYPE" = "admin" ]; then
 
-  # ── Orchestration-only authoring + research block (Task 529) ─────────────
+  # ── Orchestration-only authoring + research block (Task 529, 559) ────────
   # The admin seat is orchestration + clarification + delivery only.
   # Write/Edit/MultiEdit/Bash/WebFetch/WebSearch are specialist-owned —
   # content-producer for authoring, research-assistant for research, the
   # shell tools for whichever specialist owns the workflow that needs them.
   # In-window Task subagents must keep these tools (Task 222 regression
-  # class) — the discriminator is the transcript_path: Claude Code stores
-  # subagent turns in separate `*/subagents/agent-*.jsonl` files.
+  # class).
+  #
+  # Discriminator (Task 559): Claude Code passes `parent_tool_use_id` in
+  # the hook input JSON when the call originates from a subagent (the id
+  # of the parent's Task tool_use). Admin-direct calls have it absent or
+  # empty. Earlier versions used the `transcript_path` glob, but Claude
+  # Code 2.1.x passes the parent session's transcript_path to subagent
+  # hooks, so the glob never matched and every specialist subagent Bash
+  # was blocked with the admin orchestration-only wording.
   #
-  # Admin direct → exit 2 with dispatch hint.
-  # Subagent → exit 0 (passthrough).
-  # Missing/malformed transcript_path → fail-closed block (matches Task 222).
+  # Admin direct (no parent_tool_use_id) → exit 2 with dispatch hint.
+  # Subagent (parent_tool_use_id non-empty) → exit 0 (passthrough).
   case "$TOOL_NAME" in
     Write|Edit|MultiEdit|Bash|WebFetch|WebSearch)
-      TRANSCRIPT_PATH=$(echo "$INPUT" | python3 -c '
+      PARENT_TOOL_USE_ID=$(echo "$INPUT" | python3 -c '
 import sys, json
 try:
-    print(json.load(sys.stdin).get("transcript_path", "") or "")
+    v = json.load(sys.stdin).get("parent_tool_use_id", "")
+    print(v if isinstance(v, str) else "")
 except Exception:
     print("")
 ' 2>/dev/null)
-      case "$TRANSCRIPT_PATH" in
-        */subagents/agent-*.jsonl)
-          # In-window subagent — passthrough. Tool name resolves on the
-          # subagent's own frontmatter `tools:` allowlist downstream.
-          echo "[admin-tool-gate] role=subagent tool=${TOOL_NAME} decision=allow source=hook-passthrough" >&2
-          ;;
-        "")
-          # Missing transcript_path on a denied native tool — fail closed
-          # rather than guess (Task 222 fail-closed contract).
-          echo "[admin-tool-gate] role=unknown tool=${TOOL_NAME} decision=block reason=missing-transcript-path" >&2
-          echo "Blocked: ${TOOL_NAME} is unavailable from the admin seat and the caller cannot be classified (no transcript_path). Failing closed." >&2
-          exit 2
-          ;;
-        *)
-          # Admin direct invocation — refuse with dispatch hint.
-          case "$TOOL_NAME" in
-            Write|Edit|MultiEdit)
-              OWNER="content-producer"
-              ;;
-            Bash)
-              OWNER="the specialist that owns the workflow needing shell access"
-              ;;
-            WebFetch|WebSearch)
-              OWNER="research-assistant"
-              ;;
-          esac
-          echo "[admin-tool-gate] role=admin tool=${TOOL_NAME} decision=block reason=orchestration-only owner=${OWNER}" >&2
-          echo "Blocked: \`${TOOL_NAME}\` is not callable from the admin seat. The admin seat is orchestration + clarification + delivery only — authoring, shell work, and web research are owned by specialists." >&2
-          echo "Dispatch the work to ${OWNER} via the Agent tool." >&2
-          exit 2
-          ;;
-      esac
+      SPECIALIST="${MAXY_SPECIALIST:-}"
+      if [ -n "$PARENT_TOOL_USE_ID" ]; then
+        # In-window subagent — passthrough. Tool name resolves on the
+        # subagent's own frontmatter `tools:` allowlist downstream.
+        echo "[admin-tool-gate] role=subagent parent_tool_use_id=${PARENT_TOOL_USE_ID} specialist=${SPECIALIST:--} tool=${TOOL_NAME} decision=allow source=hook-passthrough" >&2
+      else
+        # Admin direct invocation — refuse with dispatch hint.
+        case "$TOOL_NAME" in
+          Write|Edit|MultiEdit)
+            OWNER="content-producer"
+            ;;
+          Bash)
+            OWNER="the specialist that owns the workflow needing shell access"
+            ;;
+          WebFetch|WebSearch)
+            OWNER="research-assistant"
+            ;;
+        esac
+        echo "[admin-tool-gate] role=admin parent_tool_use_id=- specialist=${SPECIALIST:--} tool=${TOOL_NAME} decision=block reason=orchestration-only owner=${OWNER}" >&2
+        hook_block_with_emit "$SESSION_ID" "admin-tool-gate" "${TOOL_NAME}" \
+          "orchestration-only" \
+          "Blocked: \`${TOOL_NAME}\` is not callable from the admin seat. The admin seat is orchestration + clarification + delivery only — authoring, shell work, and web research are owned by specialists.
+Dispatch the work to ${OWNER} via the Agent tool."
+      fi
       ;;
   esac
 
@@ -84,13 +105,15 @@ except Exception:
       case "$FILE_PATH" in
         # Platform UI source (platform/ui/) — source lives here, not on device
         */platform/ui/app/*|*/platform/ui/lib/*|*/platform/ui/*.ts|*/platform/ui/*.tsx|*/platform/ui/*.mjs)
-          echo "Blocked: Admin agent cannot modify platform UI source at $FILE_PATH" >&2
-          exit 2
+          hook_block_with_emit "$SESSION_ID" "admin-tool-gate" "${TOOL_NAME}" \
+            "code-dir-protection-ui" \
+            "Blocked: Admin agent cannot modify platform UI source at $FILE_PATH"
           ;;
         # Compiled MCP servers, hooks, and scripts — what actually ships to device
         */platform/plugins/*/mcp/dist/*|*/platform/plugins/*/hooks/*|*/platform/scripts/*)
-          echo "Blocked: Admin agent cannot modify platform code at $FILE_PATH" >&2
-          exit 2
+          hook_block_with_emit "$SESSION_ID" "admin-tool-gate" "${TOOL_NAME}" \
+            "code-dir-protection-platform" \
+            "Blocked: Admin agent cannot modify platform code at $FILE_PATH"
           ;;
         # Entitlement library — verifier source, compiled output, vendored
         # pubkey, hash file, and any signed entitlement.json. Tampering here is the
@@ -99,9 +122,10 @@ except Exception:
         # Patterns intentionally cover both absolute (*/...) and relative
         # (no leading slash) paths so an agent can't bypass via cwd-relative writes.
         */platform/lib/entitlement/*|platform/lib/entitlement/*|*/entitlement.json|entitlement.json)
-          echo "Blocked: Admin agent cannot modify entitlement files at $FILE_PATH. Effective tier and purchasedPlugins derive from a Rubytech-signed payload." >&2
           echo "[entitlement] tool-deny: tool=${TOOL_NAME} path=${FILE_PATH} field=entitlement-file" >&2
-          exit 2
+          hook_block_with_emit "$SESSION_ID" "admin-tool-gate" "${TOOL_NAME}" \
+            "entitlement-file" \
+            "Blocked: Admin agent cannot modify entitlement files at $FILE_PATH. Effective tier and purchasedPlugins derive from a Rubytech-signed payload."
           ;;
         # account.json — agent must use the account-update
         # MCP tool (or plugin-toggle-enabled for enabledPlugins changes), which
@@ -112,14 +136,16 @@ except Exception:
         # incident showed a tier upgrade via raw Edit on account.json reach
         # the disk, exactly the failure mode this hook exists to prevent.
         */data/accounts/*/account.json|*/config/accounts/*/account.json|data/accounts/*/account.json|config/accounts/*/account.json|*/account.json|*account.json|account.json)
-          echo "Blocked: Admin agent cannot edit account.json directly. Use the account-update or plugin-toggle-enabled MCP tools — they whitelist editable fields server-side and exclude tier and purchasedPlugins by design." >&2
           echo "[entitlement] tool-deny: tool=${TOOL_NAME} path=${FILE_PATH} field=account-json" >&2
-          exit 2
+          hook_block_with_emit "$SESSION_ID" "admin-tool-gate" "${TOOL_NAME}" \
+            "account-json" \
+            "Blocked: Admin agent cannot edit account.json directly. Use the account-update or plugin-toggle-enabled MCP tools — they whitelist editable fields server-side and exclude tier and purchasedPlugins by design."
           ;;
         # Pending action queue — only the hook and MCP tools may write here
         */pending-actions/*)
-          echo "Blocked: Admin agent cannot modify pending action files directly" >&2
-          exit 2
+          hook_block_with_emit "$SESSION_ID" "admin-tool-gate" "${TOOL_NAME}" \
+            "pending-actions" \
+            "Blocked: Admin agent cannot modify pending action files directly"
           ;;
       esac
       ;;
@@ -127,24 +153,28 @@ except Exception:
       # Block shell commands referencing protected code directories or pending actions
       case "$INPUT" in
         *"platform/ui/app/"*|*"platform/ui/lib/"*|*"platform/plugins/"*"hooks/"*|*"platform/scripts/"*)
-          echo "Blocked: Admin agent cannot run shell commands against code directories" >&2
-          exit 2
+          hook_block_with_emit "$SESSION_ID" "admin-tool-gate" "Bash" \
+            "code-dir-protection-bash" \
+            "Blocked: Admin agent cannot run shell commands against code directories"
           ;;
         # Entitlement files via shell — same surface, blocked symmetrically
         *"platform/lib/entitlement/"*|*"entitlement.json"*)
-          echo "Blocked: Admin agent cannot reference entitlement files via shell." >&2
           echo "[entitlement] tool-deny: tool=Bash path=entitlement-file field=entitlement-file" >&2
-          exit 2
+          hook_block_with_emit "$SESSION_ID" "admin-tool-gate" "Bash" \
+            "entitlement-shell" \
+            "Blocked: Admin agent cannot reference entitlement files via shell."
           ;;
         # account.json via shell — same rationale as Edit/Write block
         *"data/accounts/"*"account.json"*|*"config/accounts/"*"account.json"*)
-          echo "Blocked: Admin agent cannot edit account.json via shell. Use the account-update MCP tool." >&2
           echo "[entitlement] tool-deny: tool=Bash path=account-json field=account-json" >&2
-          exit 2
+          hook_block_with_emit "$SESSION_ID" "admin-tool-gate" "Bash" \
+            "account-json-shell" \
+            "Blocked: Admin agent cannot edit account.json via shell. Use the account-update MCP tool."
           ;;
         *"pending-actions/"*)
-          echo "Blocked: Admin agent cannot modify pending action files via shell" >&2
-          exit 2
+          hook_block_with_emit "$SESSION_ID" "admin-tool-gate" "Bash" \
+            "pending-actions-shell" \
+            "Blocked: Admin agent cannot modify pending action files via shell"
           ;;
       esac
       ;;
@@ -229,17 +259,19 @@ except Exception:
     REJECT:base64-write-content:*)
       BYTES="${GUARD_VERDICT##*:}"
       echo "[pre-tool-use] guard=base64-write-content bytes=${BYTES} action=reject" >&2
-      echo "Blocked: ${TOOL_NAME} content carries an inline base64 payload (>4 KB encoded). Inline binary in Write.content overloads the model context — the same path produced a main_stream_stalled at ~33 KB on 2026-05-09." >&2
-      echo "Save the bytes to \$ACCOUNT_DIR/tmp/<sha1>.<ext> via Bash (e.g. 'base64 -d > out.png'), then reference the file from the document: <img src=\"./<file>\"> or Read-by-path. Do not carry binary bytes through the assistant turn." >&2
-      exit 2
+      hook_block_with_emit "$SESSION_ID" "base64-guard" "${TOOL_NAME}" \
+        "base64-write-content" \
+        "Blocked: ${TOOL_NAME} content carries an inline base64 payload (>4 KB encoded). Inline binary in Write.content overloads the model context — the same path produced a main_stream_stalled at ~33 KB on 2026-05-09.
+Save the bytes to \$ACCOUNT_DIR/tmp/<sha1>.<ext> via Bash (e.g. 'base64 -d > out.png'), then reference the file from the document: <img src=\"./<file>\"> or Read-by-path. Do not carry binary bytes through the assistant turn."
       ;;
     REJECT:base64-encoder:*|REJECT:xxd-plain-hex:*)
       REASON="${GUARD_VERDICT#REJECT:}"; REASON="${REASON%:*}"
       BYTES="${GUARD_VERDICT##*:}"
       echo "[pre-tool-use] guard=base64-tool-result bytes=${BYTES} tool=Bash reason=${REASON} action=reject" >&2
-      echo "Blocked: Bash command would emit binary as inline base64/hex to stdout, which lands in the assistant turn and overloads the model context (the 2026-05-09 Rubytech-invoice path hit 66% context after a single ~33 KB tool_result)." >&2
-      echo "Instead: save the bytes directly to \$ACCOUNT_DIR/tmp/<sha1>.<ext> and operate on the file via path — Read for inspection, <img src=\"./<file>\"> for HTML embedding, the \`file-presentation\` skill for delivery. Decoding base64 (e.g. 'base64 -d in.b64 > out.bin') is allowed." >&2
-      exit 2
+      hook_block_with_emit "$SESSION_ID" "base64-guard" "Bash" \
+        "$REASON" \
+        "Blocked: Bash command would emit binary as inline base64/hex to stdout, which lands in the assistant turn and overloads the model context (the 2026-05-09 Rubytech-invoice path hit 66% context after a single ~33 KB tool_result).
+Instead: save the bytes directly to \$ACCOUNT_DIR/tmp/<sha1>.<ext> and operate on the file via path — Read for inspection, <img src=\"./<file>\"> for HTML embedding, the \`file-presentation\` skill for delivery. Decoding base64 (e.g. 'base64 -d in.b64 > out.bin') is allowed."
       ;;
     *)
       : # ALLOW — fall through to approval gating below
@@ -313,8 +345,9 @@ except Exception:
   # Write atomically: temp file + mv
   TEMP=$(mktemp "${PENDING_DIR}/.tmp.XXXXXX" 2>/dev/null)
   if [ -z "$TEMP" ]; then
-    echo "Blocked: Action requires approval but failed to create queue file (disk error). Failing closed." >&2
-    exit 2
+    hook_block_with_emit "$SESSION_ID" "approval-gate" "${TOOL_NAME}" \
+      "approval-queue-mktemp" \
+      "Blocked: Action requires approval but failed to create queue file (disk error). Failing closed."
   fi
 
   # The pending action file contains the full hook JSON (tool_name + tool_input)
@@ -332,10 +365,19 @@ ENDJSON
 
   if ! mv "$TEMP" "${PENDING_DIR}/${ACTION_ID}.json" 2>/dev/null; then
     rm -f "$TEMP" 2>/dev/null
-    echo "Blocked: Action requires approval but failed to queue (filesystem error). Failing closed." >&2
-    exit 2
+    hook_block_with_emit "$SESSION_ID" "approval-gate" "${TOOL_NAME}" \
+      "approval-queue-mv" \
+      "Blocked: Action requires approval but failed to queue (filesystem error). Failing closed."
   fi
 
+  # Record the queued-for-approval block in the propagation buffer; the
+  # readable summary still goes to stdout (CC attaches it as the agent's
+  # tool_result). hook_emit_decision is the no-exit variant — the
+  # subsequent echoes + exit 2 below remain the operator-facing surface.
+  hook_emit_decision "$SESSION_ID" "approval-gate" "${TOOL_NAME}" \
+    "block" "approval-queued" \
+    "Action ${ACTION_ID} queued for review" 2 0
+
   # Extract a readable summary of the action for the agent to present
   # tool_input is the second JSON value in the hook payload
   echo "Action requires approval before execution."

package/payload/platform/plugins/admin/skills/investigate/SKILL.md

@@ -135,6 +135,21 @@ If no specific artifact was provided, proceed directly to Phase 1.
    task for the observability fix. Resume after instrumentation is
    deployed and the issue is reproduced with proper evidence.
 
+   **Test for the no-event blind spot explicitly.** Transition-only
+   logging (a line per action) is structurally blind to any failure that
+   emits *no event and does not reproduce on demand* — a leak, an
+   orphan, a stuck or idle resource, a silently-failed cleanup, slow
+   drift. There is no action to hang a log on, and re-running the code
+   will not surface it. For **every failure mode you can name**, ask the
+   forcing question: *"what signal reveals it, without reproducing the
+   failure and without waiting for unrelated future activity?"* If the
+   answer is "none until something else happens," the missing
+   instrumentation is a **standing check — an independent periodic audit
+   that reconciles expected state against actual** — not another action
+   log, and that gap is itself the finding. Verify post-conditions,
+   never log intentions: "called the cleanup" is not evidence the
+   resource was freed.
+
 Output: **"Root cause hypothesis: ..."** — a specific, testable claim
 supported by cited evidence, plus the narrowest module the fix would
 touch (informational; investigation does not edit source).

package/payload/platform/plugins/admin/skills/platform-architecture/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: platform-architecture
 description: Use when grounding any claim about what Maxy is, how the platform is built, how plugins/skills/specialists work, how install/deploy runs, or any other product-architecture fact. The body of this skill is the only permissible source for such claims. Cite the `Source:` URL inline.
-content-hash: sha256:7a63e89172ec61a001e45436e346b7e89e5bae8b72436c74ea6279321e114a55
+content-hash: sha256:f26ae06dff1c5b82b674893120da0454280946709391d6f9f79051f48e6f40e0
 ---
 
 # Platform architecture (reference)
@@ -209,9 +209,9 @@ Each session row also carries a small muted timestamp crumb under the name showi
 **Two spawn methods coexist (Task 557).** The manager runs two separate on-device spawn surfaces:
 
 - **`claude rc` daemon** — spawned at platform boot by `rc-daemon.ts`, **`systemdSpawn`** path. Owns the long-lived composer session that backs claude.ai/code Remote Control. The script(1) TTY wrap (Task 556) inside the scope keeps the daemon resident even though the manager holds no fd. The activation gate below covers this path.
-- **`claude --remote-control` on-device sidebar spawn** — spawned per-click by `/rc-spawn` in `http-server.ts`, **`spawnPty` (node-pty) + `systemd-run --scope`** path. Node-pty inside the scope owns the real `xterm-256color` TTY (120×40); the manager process holds the master fd at spawn time and releases it at `op=session-ready` once claude's pid file lands. The `trap "" HUP` wrap inside the scope keeps claude resident after the release, so the manager can detach without killing the session. Task 552's `systemdSpawn`-with-`stdio:'ignore'` swap broke this surface for five occasions because `--scope` units inherit the launcher's fds, so claude got `/dev/null` on all three streams and exited at the no-input branch in ~50 ms; Task 557 restored node-pty here and left the daemon path unchanged.
+- **`claude --remote-control` on-device sidebar spawn** — spawned per-click by `/rc-spawn` in `http-server.ts`, **`spawnPty` (node-pty) + `systemd-run --scope`** path. Node-pty inside the scope owns the real `xterm-256color` TTY (120×40); the manager process holds the master fd **for the session's entire lifetime**. The pty master IS the live session — claude operates on the slave, and closing the master hangs up the slave (Task 557 evidence: claude exited ~0.8 s after `op=fd-release trigger=session-ready`). Task 558 deletes that release point. The only valid master-release points are now (1) the explicit operator teardown — `/stop` → `stopSession` → `op=archive-release` — and (2) the natural-exit path inside `pty.onExit → handlePtyNaturalExit`. Task 552's `systemdSpawn`-with-`stdio:'ignore'` swap broke this surface for five occasions because `--scope` units inherit the launcher's fds, so claude got `/dev/null` on all three streams and exited at the no-input branch in ~50 ms; Task 557 restored node-pty here and left the daemon path unchanged.
 
-**`/rc-spawn` lifecycle observability (Task 557).** Every on-device sidebar resume emits a stream of `[rc-spawn]` lines tagged with the same `unitToken=rc-resume-<uuid>` so one spawn's full lifeline can be reconstructed by `grep` alone. The lines, in order:
+**`/rc-spawn` lifecycle observability (Tasks 557 + 558).** Every on-device sidebar resume emits a stream of `[rc-spawn]` lines tagged with the same `unitToken=rc-resume-<uuid>` so one spawn's full lifeline can be reconstructed by `grep` alone. The lines, in order:
 
 | Step | Line shape |
 |------|-----------|
@@ -220,13 +220,28 @@ Each session row also carries a small muted timestamp crumb under the name showi
 | 3 | `[rc-spawn] op=pty-spawned unitToken=<t> pid=<pid> openFds=<n>` (fd baseline) |
 | 4 | `[rc-spawn] op=child-output unitToken=<t> pid=<pid> head=<json>` (first ≤1 KB or 500 ms idle — claude's own words: `Remote Control connecting…` on success, `No deferred tool marker` / `Unknown assignment` on failure) |
 | 5 | `[rc-spawn] op=alive unitToken=<t> pid=<pid> ranMs=<n>` and `op=early-exit` mirror — `early-exit` fires when `pty.onExit` lands before the pid file (the no-TTY death signature) |
-| 6 | `[rc-spawn] op=session-ready unitToken=<t> pid=<pid> pidFile=<path> bridgeId=<…>` (pid file written by claude — the candidate safe fd-release point) |
+| 6 | `[rc-spawn] op=session-ready unitToken=<t> pid=<pid> pidFile=<path> bridgeId=<…>` — **terminal for the spawn path.** No `op=fd-release trigger=session-ready` follows. The tracker remains in `livePtys` for the session's lifetime. |
 | 7 | `[pty-tracker] op=spawn sessionId=<8> pid=<pid> size=<n>` (also fires for spawnClaudeSession; same line shape on the rc-spawn path) |
-| 8 | `[rc-spawn] op=fd-release unitToken=<t> pid=<pid> trigger=session-ready master-fd=closed openFds=<n>` then `[rc-spawn] op=survives-fd-release unitToken=<t> pid=<pid> alive=<bool>` (kill -0 — the empirical evidence for whether `trap "" HUP` holds) |
-| 9 | `[fd-census] trigger=rc-spawn openFds=<n> livePtys=<n>` (the leak time-series — `openFds` rising while `livePtys` stays flat across successive spawns is the leak signature; `openFds` returning to baseline after each release is no leak) |
-| 10 | `[rc-spawn] op=exit unitToken=<t> pid=<pid> ranMs=<n>` paired with `[pty-tracker] op=exit` from `handlePtyNaturalExit` (fires only if the child exits before fd-release — once the master fd is closed `pty.onExit` no longer fires, so `op=detach` from `op=fd-release` is the terminal manager-side line for surviving children) |
+| 8 | `[rc-spawn] op=exit unitToken=<t> pid=<pid> ranMs=<n>` paired with `[pty-tracker] op=exit` from `handlePtyNaturalExit` — fires when claude exits on its own (operator typed `/quit`, SIGINT in the PTY, crash). |
 
-`openFdCount()` reads `/proc/self/fd` directly on Linux and returns `-1` on darwin (the dev-Mac path). The fd-leak audit on the laptop is one line: `~/maxy-code/platform/scripts/logs-read.sh --tail server 200 | grep -E '\[rc-spawn\]|\[fd-census\]'`, then filter by `unitToken` to isolate a single spawn or by `trigger=rc-spawn` to read the cross-spawn fd time-series.
+**Operator-archive release (Task 558).** When the operator clicks End in the UI, `/stop` → `stopSession` → `archiveReleaseTracker` emits a single verified release line:
+
+`[rc-spawn] op=archive-release sessionId=<8> pid=<pid> master-fd=<closed|close-failed err=…> fdBefore=<n> fdAfter=<n> fdDelta=<n> removedFds=<list|none> trackerRemoved=<bool> verified=<bool>`
+
+`verified=true` requires `master-fd=closed` AND `fdDelta>=1` AND `trackerRemoved=true`. `master-fd=close-failed` is logged at error level (`[rc-spawn-error]` prefix) — never swallowed; the next post-archive sweep is the catch-net.
+
+**Post-archive fd sweep (Task 558).** Independent of spawn/archive request traffic, the manager runs a 60 s sweep that walks both directions of the master-fd invariant:
+
+- `[fd-audit] op=orphan-master sessionId=<8> pid=<n> archivedAt=<ms> heldSinceArchiveMs=<n> fd=<n|unknown>` — fires per tracker whose row is archived (the leak).
+- `[fd-audit] op=orphan-master-escalate sessionId=<8> fd=<n|unknown> heldSinceArchiveMs=<n>` — fires when `heldSinceArchiveMs ≥ 300 000` ms (5 min); strongest leak signal.
+- `[fd-audit] op=post-archive-sweep archivedSessions=<n> orphanMasters=<n> openFds=<n> livePtys=<n>` — once per sweep.
+- `[fd-audit] op=master-reconcile liveTrackers=<n> liveSessions=<n> archivedWithMaster=<n> orphanLiveSessionsNoMaster=<n>` — once per sweep. `archivedWithMaster>0` = fd leak; `orphanLiveSessionsNoMaster>0` = inverse defect (a live session whose master is gone — it cannot operate). Both are alarms.
+
+The sweep is the catch-net for `master-fd=close-failed` and any future regression that orphans a tracker after archive. The steady-state `archivedWithMaster=0 orphanLiveSessionsNoMaster=0` is itself the signal the sweep ran.
+
+**Manager-shutdown master-audit (Task 558).** On SIGTERM/SIGINT the manager emits `[manager-shutdown] op=master-audit held=<n> liveSessionsClosed=<n>` after walking `livePtys`. `held` is the count of trackers at shutdown entry; `liveSessionsClosed` is the subset whose master was destroyed by this shutdown. This is the data the out-of-scope "does manager restart kill on-device live sessions?" question is decided by — a logged number, not speculation.
+
+`openFdCount()` reads `/proc/self/fd` directly on Linux and returns `-1` on darwin (the dev-Mac path). The fd-leak audit on the laptop: `~/maxy-code/platform/scripts/logs-read.sh --tail server 400 | grep -E '\[fd-audit\]|op=archive-release'`. Full per-spawn lifeline: `grep -E '\[rc-spawn\]|\[pty-tracker\]'` filtered by `unitToken`.
 
 **Non-PTY scope spawn — activation gate (Tasks 552 + 554 + 555 + 556).** `claude rc` daemon spawns (and historically `/rc-spawn`, until Task 557 restored node-pty for that path) go through `systemdSpawn` (a `child_process.spawn` around `systemd-run --user --scope ...`, no PTY). The scope's inner command is `script -q -f -c "<claude cmd>" "<captureFilePath>"` (Task 556): `script(1)` allocates a real pty master and slave so claude runs on a TTY (without one, `claude --remote-control --resume` and `claude rc --spawn` early-exit because `--scope` units inherit the launcher's `stdio: 'ignore'` fds), and writes its typescript to a per-spawn capture file at `~/.<brand>/logs/spawn-<unitToken>.log`. The capture file holds the child's stdout/stderr and survives scope reaping, so a fast-exiting child's last words are recoverable by reading the file. (The prior Task 555 attempt — `StandardOutput=journal` + `SyslogIdentifier=` scope properties — was a no-op because those are `Exec*=` *service-unit* fields that systemd silently ignores on `--scope` units.) The activation gate polls `systemctl show -p ActiveState -p ControlGroup -p Result -p SubState` every 50 ms until either the scope reaches `ActiveState=active` with a pid in `cgroup.procs` (success — a handle is returned) or it reaches a terminal state. Four terminal outcomes are distinguished:
 

package/payload/platform/plugins/admin/skills/task/SKILL.md

@@ -162,6 +162,37 @@ How the change will be monitored once deployed. This section is
 mandatory — code that cannot be observed in production is incomplete
 code.
 
+**Derive it first, adversarially — do not write this section last.**
+Observability designed after the fix inherits the fix's blind spots;
+designed first, it forces the fix to expose what would otherwise stay
+hidden. Before writing prose, name **every way the change can fail**,
+and treat the failures that emit *no event and do not reproduce on
+demand* as first-class — they are the ones routinely missed. For
+**each** failure mode, answer one forcing question and write the answer
+in:
+
+> **What signal reveals this failure — and does it fire (a) without
+> reproducing the failure and (b) without waiting for unrelated future
+> activity?**
+
+The two clauses are the part repeatedly gotten wrong:
+
+- **Presence ≠ adequacy.** A section that merely has "what to log /
+  signals / diagnostic path" passes a presence check while still being
+  blind. The test is not "is there a section" but "is every failure
+  mode answered by the forcing question."
+- **Event-driven logging is structurally blind to no-event failures.**
+  A failure that triggers no action produces no log line, and re-running
+  the code will not surface it. Any such failure REQUIRES a **standing
+  check — an independent periodic audit that reconciles expected state
+  against actual** — not a log hung on some action. A task that names a
+  no-event failure mode but specifies no standing check to detect it is
+  inadequate by construction.
+- **Verify outcomes, don't log intentions.** "Called the cleanup" is
+  not "the resource was freed." Log the *verified* post-condition (a
+  measured delta, the resource absent from the live set), and never
+  swallow the failure branch.
+
 The observability section addresses:
 
 - **What to log** — the specific events, state transitions, or error

package/payload/platform/plugins/docs/references/platform.md

@@ -101,9 +101,9 @@ Each session row also carries a small muted timestamp crumb under the name showi
 **Two spawn methods coexist (Task 557).** The manager runs two separate on-device spawn surfaces:
 
 - **`claude rc` daemon** — spawned at platform boot by `rc-daemon.ts`, **`systemdSpawn`** path. Owns the long-lived composer session that backs claude.ai/code Remote Control. The script(1) TTY wrap (Task 556) inside the scope keeps the daemon resident even though the manager holds no fd. The activation gate below covers this path.
-- **`claude --remote-control` on-device sidebar spawn** — spawned per-click by `/rc-spawn` in `http-server.ts`, **`spawnPty` (node-pty) + `systemd-run --scope`** path. Node-pty inside the scope owns the real `xterm-256color` TTY (120×40); the manager process holds the master fd at spawn time and releases it at `op=session-ready` once claude's pid file lands. The `trap "" HUP` wrap inside the scope keeps claude resident after the release, so the manager can detach without killing the session. Task 552's `systemdSpawn`-with-`stdio:'ignore'` swap broke this surface for five occasions because `--scope` units inherit the launcher's fds, so claude got `/dev/null` on all three streams and exited at the no-input branch in ~50 ms; Task 557 restored node-pty here and left the daemon path unchanged.
+- **`claude --remote-control` on-device sidebar spawn** — spawned per-click by `/rc-spawn` in `http-server.ts`, **`spawnPty` (node-pty) + `systemd-run --scope`** path. Node-pty inside the scope owns the real `xterm-256color` TTY (120×40); the manager process holds the master fd **for the session's entire lifetime**. The pty master IS the live session — claude operates on the slave, and closing the master hangs up the slave (Task 557 evidence: claude exited ~0.8 s after `op=fd-release trigger=session-ready`). Task 558 deletes that release point. The only valid master-release points are now (1) the explicit operator teardown — `/stop` → `stopSession` → `op=archive-release` — and (2) the natural-exit path inside `pty.onExit → handlePtyNaturalExit`. Task 552's `systemdSpawn`-with-`stdio:'ignore'` swap broke this surface for five occasions because `--scope` units inherit the launcher's fds, so claude got `/dev/null` on all three streams and exited at the no-input branch in ~50 ms; Task 557 restored node-pty here and left the daemon path unchanged.
 
-**`/rc-spawn` lifecycle observability (Task 557).** Every on-device sidebar resume emits a stream of `[rc-spawn]` lines tagged with the same `unitToken=rc-resume-<uuid>` so one spawn's full lifeline can be reconstructed by `grep` alone. The lines, in order:
+**`/rc-spawn` lifecycle observability (Tasks 557 + 558).** Every on-device sidebar resume emits a stream of `[rc-spawn]` lines tagged with the same `unitToken=rc-resume-<uuid>` so one spawn's full lifeline can be reconstructed by `grep` alone. The lines, in order:
 
 | Step | Line shape |
 |------|-----------|
@@ -112,13 +112,28 @@ Each session row also carries a small muted timestamp crumb under the name showi
 | 3 | `[rc-spawn] op=pty-spawned unitToken=<t> pid=<pid> openFds=<n>` (fd baseline) |
 | 4 | `[rc-spawn] op=child-output unitToken=<t> pid=<pid> head=<json>` (first ≤1 KB or 500 ms idle — claude's own words: `Remote Control connecting…` on success, `No deferred tool marker` / `Unknown assignment` on failure) |
 | 5 | `[rc-spawn] op=alive unitToken=<t> pid=<pid> ranMs=<n>` and `op=early-exit` mirror — `early-exit` fires when `pty.onExit` lands before the pid file (the no-TTY death signature) |
-| 6 | `[rc-spawn] op=session-ready unitToken=<t> pid=<pid> pidFile=<path> bridgeId=<…>` (pid file written by claude — the candidate safe fd-release point) |
+| 6 | `[rc-spawn] op=session-ready unitToken=<t> pid=<pid> pidFile=<path> bridgeId=<…>` — **terminal for the spawn path.** No `op=fd-release trigger=session-ready` follows. The tracker remains in `livePtys` for the session's lifetime. |
 | 7 | `[pty-tracker] op=spawn sessionId=<8> pid=<pid> size=<n>` (also fires for spawnClaudeSession; same line shape on the rc-spawn path) |
-| 8 | `[rc-spawn] op=fd-release unitToken=<t> pid=<pid> trigger=session-ready master-fd=closed openFds=<n>` then `[rc-spawn] op=survives-fd-release unitToken=<t> pid=<pid> alive=<bool>` (kill -0 — the empirical evidence for whether `trap "" HUP` holds) |
-| 9 | `[fd-census] trigger=rc-spawn openFds=<n> livePtys=<n>` (the leak time-series — `openFds` rising while `livePtys` stays flat across successive spawns is the leak signature; `openFds` returning to baseline after each release is no leak) |
-| 10 | `[rc-spawn] op=exit unitToken=<t> pid=<pid> ranMs=<n>` paired with `[pty-tracker] op=exit` from `handlePtyNaturalExit` (fires only if the child exits before fd-release — once the master fd is closed `pty.onExit` no longer fires, so `op=detach` from `op=fd-release` is the terminal manager-side line for surviving children) |
+| 8 | `[rc-spawn] op=exit unitToken=<t> pid=<pid> ranMs=<n>` paired with `[pty-tracker] op=exit` from `handlePtyNaturalExit` — fires when claude exits on its own (operator typed `/quit`, SIGINT in the PTY, crash). |
 
-`openFdCount()` reads `/proc/self/fd` directly on Linux and returns `-1` on darwin (the dev-Mac path). The fd-leak audit on the laptop is one line: `~/maxy-code/platform/scripts/logs-read.sh --tail server 200 | grep -E '\[rc-spawn\]|\[fd-census\]'`, then filter by `unitToken` to isolate a single spawn or by `trigger=rc-spawn` to read the cross-spawn fd time-series.
+**Operator-archive release (Task 558).** When the operator clicks End in the UI, `/stop` → `stopSession` → `archiveReleaseTracker` emits a single verified release line:
+
+`[rc-spawn] op=archive-release sessionId=<8> pid=<pid> master-fd=<closed|close-failed err=…> fdBefore=<n> fdAfter=<n> fdDelta=<n> removedFds=<list|none> trackerRemoved=<bool> verified=<bool>`
+
+`verified=true` requires `master-fd=closed` AND `fdDelta>=1` AND `trackerRemoved=true`. `master-fd=close-failed` is logged at error level (`[rc-spawn-error]` prefix) — never swallowed; the next post-archive sweep is the catch-net.
+
+**Post-archive fd sweep (Task 558).** Independent of spawn/archive request traffic, the manager runs a 60 s sweep that walks both directions of the master-fd invariant:
+
+- `[fd-audit] op=orphan-master sessionId=<8> pid=<n> archivedAt=<ms> heldSinceArchiveMs=<n> fd=<n|unknown>` — fires per tracker whose row is archived (the leak).
+- `[fd-audit] op=orphan-master-escalate sessionId=<8> fd=<n|unknown> heldSinceArchiveMs=<n>` — fires when `heldSinceArchiveMs ≥ 300 000` ms (5 min); strongest leak signal.
+- `[fd-audit] op=post-archive-sweep archivedSessions=<n> orphanMasters=<n> openFds=<n> livePtys=<n>` — once per sweep.
+- `[fd-audit] op=master-reconcile liveTrackers=<n> liveSessions=<n> archivedWithMaster=<n> orphanLiveSessionsNoMaster=<n>` — once per sweep. `archivedWithMaster>0` = fd leak; `orphanLiveSessionsNoMaster>0` = inverse defect (a live session whose master is gone — it cannot operate). Both are alarms.
+
+The sweep is the catch-net for `master-fd=close-failed` and any future regression that orphans a tracker after archive. The steady-state `archivedWithMaster=0 orphanLiveSessionsNoMaster=0` is itself the signal the sweep ran.
+
+**Manager-shutdown master-audit (Task 558).** On SIGTERM/SIGINT the manager emits `[manager-shutdown] op=master-audit held=<n> liveSessionsClosed=<n>` after walking `livePtys`. `held` is the count of trackers at shutdown entry; `liveSessionsClosed` is the subset whose master was destroyed by this shutdown. This is the data the out-of-scope "does manager restart kill on-device live sessions?" question is decided by — a logged number, not speculation.
+
+`openFdCount()` reads `/proc/self/fd` directly on Linux and returns `-1` on darwin (the dev-Mac path). The fd-leak audit on the laptop: `~/maxy-code/platform/scripts/logs-read.sh --tail server 400 | grep -E '\[fd-audit\]|op=archive-release'`. Full per-spawn lifeline: `grep -E '\[rc-spawn\]|\[pty-tracker\]'` filtered by `unitToken`.
 
 **Non-PTY scope spawn — activation gate (Tasks 552 + 554 + 555 + 556).** `claude rc` daemon spawns (and historically `/rc-spawn`, until Task 557 restored node-pty for that path) go through `systemdSpawn` (a `child_process.spawn` around `systemd-run --user --scope ...`, no PTY). The scope's inner command is `script -q -f -c "<claude cmd>" "<captureFilePath>"` (Task 556): `script(1)` allocates a real pty master and slave so claude runs on a TTY (without one, `claude --remote-control --resume` and `claude rc --spawn` early-exit because `--scope` units inherit the launcher's `stdio: 'ignore'` fds), and writes its typescript to a per-spawn capture file at `~/.<brand>/logs/spawn-<unitToken>.log`. The capture file holds the child's stdout/stderr and survives scope reaping, so a fast-exiting child's last words are recoverable by reading the file. (The prior Task 555 attempt — `StandardOutput=journal` + `SyslogIdentifier=` scope properties — was a no-op because those are `Exec*=` *service-unit* fields that systemd silently ignores on `--scope` units.) The activation gate polls `systemctl show -p ActiveState -p ControlGroup -p Result -p SubState` every 50 ms until either the scope reaches `ActiveState=active` with a pid in `cgroup.procs` (success — a handle is returned) or it reaches a terminal state. Four terminal outcomes are distinguished:
 

package/payload/platform/plugins/prompt-optimiser/skills/prompt-optimiser/SKILL.md

@@ -19,6 +19,7 @@ This skill is invoked two ways, and they want opposite outputs. Decide which one
 - Write it as plain prose or a short bulleted brief. No fenced code block. No role line, no XML tags, no length-cap ceremony unless the user asked for one.
 - Do not end with "Think before answering". Do not ask the user to paste anything — you already have the content and the context.
 - Do not invent requirements or add scope the user did not ask for. If the prompt was already clear, say so in one line and restate it tightly.
+- The restated brief is bound by the three doctrines (see `/doctrine`): precise/concise/plain, no speculation, observability-first. If the user's wording carries a speculative claim or skips an observability step the doctrines require, the restatement corrects it rather than echoing the slip.
 - End the restated brief with this exact sentence as its own final line: "Delegate this task to the appropriate specialist." Apply on every restatement, without exception. The owning specialist is identified from the AGENTS.md roster loaded alongside this seat — the closing line is the trigger, not the classifier (Task 529).
 
 Then do the work from the restated task. Everything below this section is for the other mode and does not apply — stop reading here.

package/payload/platform/scripts/setup-account.sh

@@ -121,6 +121,12 @@ cat > "$ACCOUNT_SETTINGS" << SETTINGS_EOF
       }
     ],
     "PostToolUse": [
+      {
+        "matcher": "Agent",
+        "hooks": [
+          { "type": "command", "command": "bash $HOOKS_PATH/post-tool-use-agent.sh" }
+        ]
+      },
       {
         "matcher": "mcp__.*__.*-(export|import)-parse$",
         "hooks": [

package/payload/platform/services/claude-session-manager/dist/http-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-server.d.ts","sourceRoot":"","sources":["../src/http-server.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAM3B,OAAO,EAiBL,KAAK,SAAS,EAEf,MAAM,kBAAkB,CAAA;AAEzB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAa5D,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,iBAAiB,CAAA;AAE5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAA;AA+E9E,eAAO,MAAM,kBAAkB,QAA2B,CAAA;AAI1D,MAAM,WAAW,QAAS,SAAQ,IAAI,CAAC,SAAS,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAC7E,OAAO,EAAE,SAAS,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,iBAAiB,EAAE,MAAM,CAAA;IACzB,kBAAkB,EAAE,WAAW,CAAA;IAC/B,eAAe,EAAE,aAAa,CAAA;IAC9B;kFAC8E;IAC9E,cAAc,EAAE,cAAc,CAAA;IAC9B;;;;2DAIuD;IACvD,YAAY,EAAE,CAAC,MAAM,EAAE;QACrB,SAAS,EAAE,MAAM,CAAA;QACjB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;QAC7B,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;QACrC,GAAG,EAAE,MAAM,CAAA;QACX,SAAS,EAAE,MAAM,CAAA;QACjB,eAAe,EAAE,MAAM,CAAA;KACxB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAA;CAClC;AA4LD;;;kEAGkE;AAClE,MAAM,MAAM,OAAO,GAAG,IAAI,GAAG;IAC3B,2BAA2B,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACpD;;;+CAG2C;IAC3C,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAChD,CAAA;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CA83CpD"}
+{"version":3,"file":"http-server.d.ts","sourceRoot":"","sources":["../src/http-server.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAM3B,OAAO,EAgBL,KAAK,SAAS,EAEf,MAAM,kBAAkB,CAAA;AAEzB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAa5D,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,iBAAiB,CAAA;AAE5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAA;AA+E9E,eAAO,MAAM,kBAAkB,QAA2B,CAAA;AAI1D,MAAM,WAAW,QAAS,SAAQ,IAAI,CAAC,SAAS,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAC7E,OAAO,EAAE,SAAS,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,iBAAiB,EAAE,MAAM,CAAA;IACzB,kBAAkB,EAAE,WAAW,CAAA;IAC/B,eAAe,EAAE,aAAa,CAAA;IAC9B;kFAC8E;IAC9E,cAAc,EAAE,cAAc,CAAA;IAC9B;;;;2DAIuD;IACvD,YAAY,EAAE,CAAC,MAAM,EAAE;QACrB,SAAS,EAAE,MAAM,CAAA;QACjB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;QAC7B,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;QACrC,GAAG,EAAE,MAAM,CAAA;QACX,SAAS,EAAE,MAAM,CAAA;QACjB,eAAe,EAAE,MAAM,CAAA;KACxB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAA;CAClC;AA4LD;;;kEAGkE;AAClE,MAAM,MAAM,OAAO,GAAG,IAAI,GAAG;IAC3B,2BAA2B,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACpD;;;+CAG2C;IAC3C,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAChD,CAAA;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAm2CpD"}

package/payload/platform/services/claude-session-manager/dist/http-server.js

@@ -24,7 +24,7 @@ import { stream } from 'hono/streaming';
 import { existsSync, statSync, createReadStream, watchFile, unwatchFile, rmSync, mkdirSync, renameSync, readFileSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { buildRcChildEnv } from './rc-daemon.js';
-import { spawnClaudeSession, stopSession, writeInputToPty, isLive, onPtyExit, livePtyCount, getPtyTrackerForTests, livePidForSession, priorExitedCountForSession, PERMISSION_MODES, resolveLiveMemory, openFdCount, registerRcSpawnPty, releaseAndUnregisterRcSpawnPty, } from './pty-spawner.js';
+import { spawnClaudeSession, stopSession, writeInputToPty, isLive, onPtyExit, livePtyCount, getPtyTrackerForTests, livePidForSession, priorExitedCountForSession, PERMISSION_MODES, resolveLiveMemory, openFdCount, registerRcSpawnPty, } from './pty-spawner.js';
 import { readSidecar, updateSidecar, appendBridgeId } from './session-sidecar.js';
 import { readJsonlSession } from './jsonl-enumerator.js';
 import { claudeStateRoot, projectSlugForCwd, jsonlPathForSessionId, sidecarPathForSessionId, permissionModeLogPathForSessionId, findExistingJsonlForSessionId, } from './jsonl-path.js';
@@ -1537,12 +1537,16 @@ export function buildHttpApp(deps) {
             if (!outputEmitted)
                 emitChildOutput();
         });
-        // Step 6/8/9 — session-ready (pid file landed) → fd-release →
-        // survives-fd-release → fd-census. Runs async; the route returns
-        // immediately after spawn (the sidebar UX is fire-and-forget). The
-        // `waitForPid` timeout cap is the spawner's `pidFileTimeoutMs`; on
-        // timeout we log but do not release the fd (the tracker's onExit
-        // path handles cleanup if claude exits later).
+        // Task 558 — session-ready is terminal for the spawn path. The PTY
+        // master IS the live session, not a reclaimable spawn artifact:
+        // claude operates on the slave, and closing the master hangs up the
+        // slave (Task 557 evidence: claude exits ~0.8s after `op=fd-release
+        // trigger=session-ready`). The master must stay open for the slave
+        // to function. The only valid release points are the explicit
+        // operator teardown — `/stop` → `stopSession` → `releasePtyMasterFd`
+        // — and the natural-exit path inside `pty.onExit →
+        // handlePtyNaturalExit`. The tracker remains in `livePtys` for the
+        // session's lifetime.
         void deps.watcher
             .waitForPid(pty.pid, deps.pidFileTimeoutMs)
             .then((row) => {
@@ -1550,26 +1554,6 @@ export function buildHttpApp(deps) {
             const aliveMs = Date.now() - start;
             deps.logger(`[rc-spawn] op=alive unitToken=${unitToken} pid=${pty.pid} ranMs=${aliveMs}`);
             deps.logger(`[rc-spawn] op=session-ready unitToken=${unitToken} pid=${pty.pid} pidFile=${row.pidFilePath ?? 'unknown'} bridgeId=${row.bridgeSessionId ?? 'unknown'}`);
-            // Master-fd release at the session-ready point. Whether claude
-            // survives the release is the empirical question Task 557 was
-            // filed to answer; the `op=survives-fd-release` line below is
-            // the evidence. If `alive=false` lands across the verification
-            // spawns, the release point moves later (per the brief). The
-            // tracker is unregistered here because `pty.onExit` will not
-            // fire for the surviving child after destroy() closes the
-            // master fd.
-            const release = releaseAndUnregisterRcSpawnPty({ logger: deps.logger }, tracker, 'session-ready');
-            deps.logger(`[rc-spawn] op=fd-release unitToken=${unitToken} pid=${pty.pid} trigger=session-ready ${release.suffix} openFds=${release.openFds}`);
-            let alive = false;
-            try {
-                process.kill(pty.pid, 0);
-                alive = true;
-            }
-            catch {
-                alive = false;
-            }
-            deps.logger(`[rc-spawn] op=survives-fd-release unitToken=${unitToken} pid=${pty.pid} alive=${alive}`);
-            deps.logger(`[fd-census] trigger=rc-spawn openFds=${openFdCount()} livePtys=${livePtyCount()}`);
         })
             .catch((err) => {
             deps.logger(`[rc-spawn] op=wait-pid-failed unitToken=${unitToken} pid=${pty.pid} err=${err instanceof Error ? err.message : String(err)}`);