@rubytech/create-maxy-code 0.1.208 → 0.1.212

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-code",
-  "version": "0.1.208",
+  "version": "0.1.212",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy-code": "./dist/index.js"

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:f568588275bcfd572f9acb4052bd482a13b82a15fa74e405726dc5e907a941fb
+content-hash: sha256:f26ae06dff1c5b82b674893120da0454280946709391d6f9f79051f48e6f40e0
 ---
 
 # Platform architecture (reference)
@@ -206,7 +206,44 @@ Each session row also carries a small muted timestamp crumb under the name showi
 
 **Download JSONL (Task 197).** `GET /<id>/log?download=1` is a one-shot byte-stream of the session's JSONL transcript with attachment-disposition headers, designed for the pane's **Download JSONL** button. Headers: `Content-Type: application/x-ndjson`, `Content-Disposition: attachment; filename="<sessionId>.jsonl"` (the basename is sanitised so any non-`[A-Za-z0-9._-]` character is replaced with underscore), `Cache-Control: no-store`. Four status branches: **200** with the byte-identical file body; **404** `{error: 'session-not-found'}` when the store has no row for the id; **202** `{pending: true, jsonlPath: null}` when the row exists but claude has not flushed the first turn yet; **404** `{error: 'jsonl-missing-on-disk'}` when the row carries a `jsonlPath` but the file has been removed under the manager (post-Purge race). The download branch is declared **before** the follow check, so `?download=1` always wins over `?follow=1` if both are set. The proxy at `app.get('/:sessionId/log')` rebuilds the upstream query from a fixed `follow|download` allowlist; inbound query keys outside that allowlist are dropped. Observability: `[claude-session-manager] log-download sessionId=<sid> bytes=<n> ms=<n>` lands per successful stream completion; the browser console emits `[admin-ui] pane-download-jsonl sessionId=<8> outcome=initiated` on click. `outcome=initiated` rather than `outcome=ok` is intentional — the handler resolves before the browser writes the bytes, so the log line names "the request was kicked off", not "the file landed". If the file does not appear in the operator's downloads folder, check the manager line for the bytes count and the browser's downloads UI for the suppression record. Auth is unchanged from the rest of the `/api/admin/claude-sessions` surface (cookie session via `requireAdminSession`); there is no new key surface.
 
-**Non-PTY scope spawn — activation gate (Tasks 552 + 554 + 555 + 556).** `/rc-spawn` and rc-daemon spawns 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:
+**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 **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 (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 |
+|------|-----------|
+| 1 | `[rc-spawn] op=request unitToken=<t> sessionId=<8|new> name=<…|none> mode=<resume|fresh> jsonl=<path|none>` |
+| 2 | `[rc-spawn] op=argv unitToken=<t> cwd=<dir> argv=<json>` (inner claude argv; the `systemd-run --scope` wrap is composed by the spawnPty adapter) |
+| 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=<…>` — **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=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). |
+
+**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:
 
 - **`boot-crash`** — `cgroup.procs` was observed non-empty at some point and is now empty: claude reached init and crashed. The observed pid is included.
 - **`child-exited-during-activation`** — `cgroup.procs` was never observed populated and systemd reports `Result=success`: the child exited normally faster than the poll interval (50 ms). Task 555 added this branch to distinguish a clean fast-exit from a genuine systemd-side start failure. Pre-Task-556 the canonical trigger was a `--remote-control … --resume <sid>` spawn that received `/dev/null` on stdin and exited at the no-input branch in ~50 ms; with the script(1) TTY wrap in place, this branch now fires only for genuine fast-exits (a missing transcript, a bad `--resume` id, etc.).

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

@@ -98,7 +98,44 @@ Each session row also carries a small muted timestamp crumb under the name showi
 
 **Download JSONL (Task 197).** `GET /<id>/log?download=1` is a one-shot byte-stream of the session's JSONL transcript with attachment-disposition headers, designed for the pane's **Download JSONL** button. Headers: `Content-Type: application/x-ndjson`, `Content-Disposition: attachment; filename="<sessionId>.jsonl"` (the basename is sanitised so any non-`[A-Za-z0-9._-]` character is replaced with underscore), `Cache-Control: no-store`. Four status branches: **200** with the byte-identical file body; **404** `{error: 'session-not-found'}` when the store has no row for the id; **202** `{pending: true, jsonlPath: null}` when the row exists but claude has not flushed the first turn yet; **404** `{error: 'jsonl-missing-on-disk'}` when the row carries a `jsonlPath` but the file has been removed under the manager (post-Purge race). The download branch is declared **before** the follow check, so `?download=1` always wins over `?follow=1` if both are set. The proxy at `app.get('/:sessionId/log')` rebuilds the upstream query from a fixed `follow|download` allowlist; inbound query keys outside that allowlist are dropped. Observability: `[claude-session-manager] log-download sessionId=<sid> bytes=<n> ms=<n>` lands per successful stream completion; the browser console emits `[admin-ui] pane-download-jsonl sessionId=<8> outcome=initiated` on click. `outcome=initiated` rather than `outcome=ok` is intentional — the handler resolves before the browser writes the bytes, so the log line names "the request was kicked off", not "the file landed". If the file does not appear in the operator's downloads folder, check the manager line for the bytes count and the browser's downloads UI for the suppression record. Auth is unchanged from the rest of the `/api/admin/claude-sessions` surface (cookie session via `requireAdminSession`); there is no new key surface.
 
-**Non-PTY scope spawn — activation gate (Tasks 552 + 554 + 555 + 556).** `/rc-spawn` and rc-daemon spawns 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:
+**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 **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 (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 |
+|------|-----------|
+| 1 | `[rc-spawn] op=request unitToken=<t> sessionId=<8|new> name=<…|none> mode=<resume|fresh> jsonl=<path|none>` |
+| 2 | `[rc-spawn] op=argv unitToken=<t> cwd=<dir> argv=<json>` (inner claude argv; the `systemd-run --scope` wrap is composed by the spawnPty adapter) |
+| 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=<…>` — **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=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). |
+
+**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:
 
 - **`boot-crash`** — `cgroup.procs` was observed non-empty at some point and is now empty: claude reached init and crashed. The observed pid is included.
 - **`child-exited-during-activation`** — `cgroup.procs` was never observed populated and systemd reports `Result=success`: the child exited normally faster than the poll interval (50 ms). Task 555 added this branch to distinguish a clean fast-exit from a genuine systemd-side start failure. Pre-Task-556 the canonical trigger was a `--remote-control … --resume <sid>` spawn that received `/dev/null` on stdin and exited at the no-input branch in ~50 ms; with the script(1) TTY wrap in place, this branch now fires only for genuine fast-exits (a missing transcript, a bad `--resume` id, etc.).

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/services/claude-session-manager/dist/http-server.d.ts

@@ -1,6 +1,6 @@
 import { Hono } from 'hono';
 import { type SpawnDeps } from './pty-spawner.js';
-import { type SystemdScopeHandle } from './systemd-spawn.js';
+import type { SystemdScopeHandle } from './systemd-spawn.js';
 import type { FsWatcher } from './fs-watcher.js';
 import type { RateLimiter } from './spawn-rate-limiter.js';
 import type { AuditRegistry } from './public-tool-audit.js';

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,EAcL,KAAK,SAAS,EAEf,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAgB,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAY1E,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,CAswCpD"}
+{"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,11 +24,11 @@ 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, } 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';
-import { basename, dirname, join } from 'node:path';
+import { basename, join } from 'node:path';
 import { validateUserTitle } from './user-title-store.js';
 const ROLES = ['admin', 'public'];
 const CHANNELS = ['browser', 'whatsapp', 'telegram', 'webchat', 'email'];
@@ -1406,11 +1406,25 @@ export function buildHttpApp(deps) {
     // Task 543 — fire-and-forget `claude --remote-control [name] [--session-id <sid>]`
     // spawn for the admin sessions pane. The new PTY registers itself in
     // claude.ai/code as its own Remote Control entry; reconciliation with the
-    // rc-daemon is out of scope. The handle is intentionally discarded — the
-    // manager does NOT track or supervise this PTY (it is not a managed session
-    // row). The PID lands in `<CLAUDE_CONFIG_DIR>/sessions/<pid>.json` via
-    // claude's own bootstrap, which is how the sidebar list keeps `live`
-    // accurate and how the delete route later finds the PID to SIGTERM.
+    // rc-daemon is out of scope. The PID lands in
+    // `<CLAUDE_CONFIG_DIR>/sessions/<pid>.json` via claude's own bootstrap,
+    // which is how the sidebar list keeps `live` accurate and how the delete
+    // route later finds the PID to SIGTERM.
+    //
+    // Task 557 — restored the node-pty spawn path (Task 552 had swapped it
+    // for `systemdSpawn` with `stdio:'ignore'`, which inherited /dev/null on
+    // all three streams; `claude --remote-control --resume` early-exited at
+    // the no-input branch in ~50 ms). The manager now owns a real PTY for
+    // the rc-spawn child — `xterm-256color` inside `systemd-run --scope` —
+    // and registers it via `registerRcSpawnPty` so the master fd has a
+    // defined owner and release path. Lifecycle observability is the bulk
+    // of the change: every spawn writes `[rc-spawn]` lines tagged with the
+    // `unitToken` for request, argv, pty-spawned, child-output (first
+    // ≤1 KB), alive / early-exit, session-ready, fd-release,
+    // survives-fd-release, and exit, plus an `[fd-census]` snapshot of
+    // `openFdCount()` vs `livePtyCount()` after fd-release. This ends the
+    // 5-occasion blindness — the next failure on this surface is
+    // diagnosable from `server.log` alone.
     app.post('/rc-spawn', async (c) => {
         const start = Date.now();
         let body;
@@ -1429,10 +1443,7 @@ export function buildHttpApp(deps) {
         // Task 547 — when a JSONL already exists for the requested sessionId,
         // resume the existing conversation instead of forking a fresh one
         // under the same id. `--session-id` is claude's fresh-spawn flag;
-        // `--resume` is the continue-this-conversation flag. The sidebar's
-        // Resume button posts an existing sessionId; without this branch it
-        // would mint a new conversation under that id and abandon the prior
-        // transcript.
+        // `--resume` is the continue-this-conversation flag.
         const existingJsonlPath = sessionId ? findExistingJsonlForSessionId(deps.claudeConfigDir, sessionId) : null;
         const mode = existingJsonlPath ? 'resume' : 'fresh';
         const argv = ['--remote-control'];
@@ -1449,49 +1460,111 @@ export function buildHttpApp(deps) {
             brandedNeo4jPassword: process.env.NEO4J_PASSWORD ?? '',
         });
         const unitToken = `rc-resume-${randomUUID()}`;
-        // Task 552 — non-PTY spawn. systemd-run runs detached with stdio:'ignore'
-        // so the manager holds zero file descriptors for this child. The route
-        // is fire-and-forget; the handle is dropped on return (user systemd
-        // owns the scope cgroup's lifetime).
-        let handle;
+        const sessionIdForLog = sessionId ? sessionId.slice(0, 8) : 'new';
+        // Step 1 — request received, before any spawn work. The argv-resolved
+        // line (step 2) emits next, so a 500 between them isolates resolution
+        // failures from spawn failures.
+        deps.logger(`[rc-spawn] op=request unitToken=${unitToken} sessionId=${sessionIdForLog} name=${name ?? 'none'} mode=${mode} jsonl=${existingJsonlPath ?? 'none'}`);
+        // Step 2 — the exact claude argv (the inner command). The systemd-run
+        // wrap is composed by the spawnPty adapter; logging the inner argv
+        // here is enough for an operator to reproduce by hand. The wrapped
+        // argv is fully reconstructible from this line + the spawn adapter
+        // source (Task 250 / 556).
+        deps.logger(`[rc-spawn] op=argv unitToken=${unitToken} cwd=${deps.spawnCwd} argv=${JSON.stringify([deps.claudeBin, ...argv])}`);
+        let pty;
         try {
-            // Filter the env down to strings — the systemdSpawn contract is
-            // Record<string,string>, and buildRcChildEnv may carry undefined
-            // values through from process.env spreading.
-            const cleanEnv = {};
-            for (const [k, v] of Object.entries(env)) {
-                if (typeof v === 'string')
-                    cleanEnv[k] = v;
-            }
-            handle = await deps.systemdSpawn({
-                claudeBin: deps.claudeBin,
-                claudeArgs: argv,
-                env: cleanEnv,
-                cwd: deps.spawnCwd,
-                unitToken,
-                // Task 556 — per-spawn script(1) typescript file; sibling to
-                // ~/.<brand>/logs/server.log so post-mortem greps land in one tree.
-                captureFilePath: join(dirname(deps.claudeConfigDir), 'logs', `spawn-${unitToken}.log`),
-            });
+            pty = deps.spawnPty(deps.claudeBin, argv, env, unitToken);
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
             deps.logger(`[sessions-rc-resume] spawn-failed sessionId=${sessionId ?? 'new'} name=${name ?? 'none'} err=${msg}`);
+            deps.logger(`[rc-spawn] op=spawn-failed unitToken=${unitToken} err=${JSON.stringify(msg)}`);
             timed(deps.logger, 'POST', '/rc-spawn', 500, Date.now() - start);
             return c.json({ error: msg }, 500);
         }
-        // Per spec: log a single deterministic line so a future investigation can
-        // correlate these spawns with claude.ai/code Remote Control entries without
-        // re-reading the codepath.
-        // Task 550 — bridgeId=pending: the composer's ULID is learned later
-        // via the pid-file watcher subscription above; the bind is logged
-        // separately as `[sessions-bridge-bind] sessionId=… bridgeId=…`.
-        // Task 552 — spawnMethod=systemd-scope marker stays constant after
-        // this task lands; an investigation can confirm the path without
-        // re-reading the source.
-        deps.logger(`[sessions-rc-resume] mode=${mode} sessionId=${sessionId ?? 'none'} jsonlPath=${existingJsonlPath ?? 'none'} name=${name ?? 'none'} spawnedPid=${handle.pid} bridgeId=pending spawnMethod=systemd-scope env.CLAUDE_CONFIG_DIR=${deps.claudeConfigDir}`);
+        // Step 3 — PTY spawned. fd baseline at this instant; the fd-release
+        // line later in the lifecycle is read relative to this value.
+        deps.logger(`[rc-spawn] op=pty-spawned unitToken=${unitToken} pid=${pty.pid} openFds=${openFdCount()}`);
+        // Tracker registration — closes the leak gap the Task 552 path opened.
+        // For fresh spawns without a caller-supplied sessionId we register the
+        // tracker under the unitToken so the entry has a stable key; the
+        // operator-visible sessionId only becomes known when claude writes its
+        // pid file. Both keys are equally good for fd-ownership purposes.
+        const trackerKey = sessionId ?? `rc-${unitToken}`;
+        const tracker = registerRcSpawnPty({ logger: deps.logger }, trackerKey, pty, unitToken);
+        // Step 4 — first child output. Accumulate up to 1 KB or until 500 ms
+        // after the first byte arrives, then emit one line. The single log
+        // that ends the 5-occasion blindness: claude's own words land here
+        // — `Remote Control` on success, `No deferred tool marker` /
+        // `Unknown assignment` on failure.
+        let outputBuf = '';
+        let outputEmitted = false;
+        let outputTimer = null;
+        const emitChildOutput = () => {
+            if (outputEmitted)
+                return;
+            outputEmitted = true;
+            if (outputTimer) {
+                clearTimeout(outputTimer);
+                outputTimer = null;
+            }
+            deps.logger(`[rc-spawn] op=child-output unitToken=${unitToken} pid=${pty.pid} head=${JSON.stringify(outputBuf)}`);
+        };
+        pty.onData((data) => {
+            if (outputEmitted)
+                return;
+            const remaining = 1024 - outputBuf.length;
+            outputBuf += remaining >= data.length ? data : data.slice(0, remaining);
+            if (outputBuf.length >= 1024)
+                emitChildOutput();
+            else if (!outputTimer)
+                outputTimer = setTimeout(emitChildOutput, 500);
+        });
+        // Step 5/10 — exit observation. `pidFileSeen` discriminates `early-exit`
+        // (no pid file ever appeared — the no-TTY death signature) from `exit`
+        // (clean termination after a normal run). `handlePtyNaturalExit` (wired
+        // by `registerRcSpawnPty`) handles the tracker side — fd release +
+        // tracker delete + the `kill … reason=process-exited` log.
+        let pidFileSeen = false;
+        pty.onExit((e) => {
+            const ranMs = Date.now() - start;
+            if (!pidFileSeen) {
+                deps.logger(`[rc-spawn] op=early-exit unitToken=${unitToken} pid=${pty.pid} ranMs=${ranMs} exitCode=${e.exitCode} signal=${e.signal ?? 'none'}`);
+            }
+            deps.logger(`[rc-spawn] op=exit unitToken=${unitToken} pid=${pty.pid} ranMs=${ranMs}`);
+            // Flush any buffered child output that never reached 1 KB nor the
+            // 500 ms idle deadline before the child exited.
+            if (!outputEmitted)
+                emitChildOutput();
+        });
+        // 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) => {
+            pidFileSeen = true;
+            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'}`);
+        })
+            .catch((err) => {
+            deps.logger(`[rc-spawn] op=wait-pid-failed unitToken=${unitToken} pid=${pty.pid} err=${err instanceof Error ? err.message : String(err)}`);
+        });
+        // Task 552 marker preserved for grep continuity; the spawn method is
+        // now node-pty + systemd-scope (Task 557), but the operator-visible
+        // log key stays `spawnMethod=systemd-scope` because every rc-spawn
+        // child still runs inside a `systemd-run --user --scope` unit.
+        deps.logger(`[sessions-rc-resume] mode=${mode} sessionId=${sessionId ?? 'none'} jsonlPath=${existingJsonlPath ?? 'none'} name=${name ?? 'none'} spawnedPid=${pty.pid} bridgeId=pending spawnMethod=systemd-scope env.CLAUDE_CONFIG_DIR=${deps.claudeConfigDir}`);
         timed(deps.logger, 'POST', '/rc-spawn', 200, Date.now() - start);
-        return c.json({ spawnedPid: handle.pid, sessionId: sessionId ?? null });
+        return c.json({ spawnedPid: pty.pid, sessionId: sessionId ?? null });
     });
     return app;
 }