@rubytech/create-maxy-code 0.1.65 → 0.1.67

package/payload/platform/plugins/admin/hooks/turn-completed-graph-write.sh

@@ -1,21 +1,32 @@
 #!/usr/bin/env bash
 # Stop hook — fires on every completed admin-agent turn and dispatches one
-# headless database-operator session against the operator's most recent turn
-# text. The recorder is the only writer to the Neo4j graph; the admin agent
-# stays focused on the operator's request.
+# headless database-operator session against the operator's full
+# conversation transcript. The recorder is the only writer to the Neo4j
+# graph; the admin agent stays focused on the operator's request.
 #
 # Task 147 — the recorder spawn is byte-for-byte equivalent to a Sidebar
 # "New session" body, with three overrides:
 #   - specialist:     "database-operator"
 #   - model:          "haiku"
-#   - initialMessage: "update the graph with any new or missing information
-#                     or intent\n\n<last-turn-text>"
+#   - initialMessage: JSON-stringified envelope (Task 177)
+#
 # It POSTs to the SAME route the Sidebar uses
 # (`POST /api/admin/claude-sessions`). The wrapper accepts the loopback
 # request without a cookie, resolves the operator's `senderId` from the
 # manager's `/<adminSessionId>/meta`, and forwards a Sidebar-shape spawn
 # body. No recorder-only carving on the manager side.
 #
+# Task 177 — `initialMessage` is a JSON object stringified to a string.
+# Top-level keys EXACTLY: turns, conversationId, accountId, occurredAt.
+# `turns` is the chronologically-ordered conversation window — every
+# user / assistant message in the operator's JSONL, oldest first, no
+# windowing or truncation. Each entry:
+#     { role: "user"|"assistant", text: string, ts: string, toolCalls?: [...] }
+# `toolCalls` (assistant-only, omitted when empty) carries
+# `[{ tool, input, output }]` for tool_use/tool_result pairs in that turn.
+# Replaces the Task 175 `(operatorMessage, assistantReply)` pair contract,
+# which asserted a temporal pairing the walker never enforced.
+#
 # Gating (emits a `trigger-skipped` line via `/api/admin/log-ingest`;
 # stderr stays silent on the success path):
 #   - MAXY_SESSION_ROLE must equal "admin"        → reason=role-not-admin
@@ -23,8 +34,7 @@
 #     "database-operator"   (recursion guard)
 #   - Stop-hook stdin must be non-empty           → reason=empty-stdin
 #   - transcript_path must exist on disk          → reason=missing-transcript
-#   - at least one user or assistant record with   → reason=conversation-empty
-#     non-empty text must exist in the JSONL (Task 165)
+#   - turns array is empty after walker runs      → reason=conversation-empty
 #
 # Input: Claude Code's Stop hook stdin shape
 #   { "session_id": "<intrinsic>", "transcript_path": "<jsonl path>", ... }
@@ -91,62 +101,188 @@ if [ -z "$ADMIN_SESSION_ID" ] || [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIP
   exit 0
 fi
 
-# Task 165 — walk every user/assistant record in transcript order; emit
-# "<type>: <text>" per record; join with "\n". The recorder needs the
-# whole exchange to infer operator-asserted facts that span multiple
-# turns (e.g. "hello / what's your business? / Smalleys"). The earlier
-# "last-turn-only" extractor stripped the framing the recorder needed.
-CONVERSATION_TEXT=$(python3 - "$TRANSCRIPT_PATH" <<'PY'
+# Task 177 — build the envelope the database-operator agent file declares
+# as its stdin contract. One Python pass walks the transcript and emits:
+#   {
+#     "turns": [
+#       { "role": "user"|"assistant", "text": "...", "ts": "...",
+#         "toolCalls"?: [{ "tool": "...", "input": {...}, "output": ... }] },
+#       ...
+#     ],
+#     "conversationId": "<session_id>",
+#     "accountId":      "<ACCOUNT_ID env>",
+#     "occurredAt":     "<hook fire time, ISO-8601 UTC, .000Z>"
+#   }
+# `python3 json.dumps` handles every escape so the hook never has to
+# concatenate strings into JSON by hand.
+OCCURRED_AT=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)
+ACCOUNT_ID_ENV="${ACCOUNT_ID:-}"
+
+ENVELOPE=$(python3 - "$TRANSCRIPT_PATH" "$ADMIN_SESSION_ID" "$ACCOUNT_ID_ENV" "$OCCURRED_AT" <<'PY'
 import sys, json
 
-def block_text(block):
-    if not isinstance(block, dict): return ""
-    if block.get("type") != "text": return ""
-    t = block.get("text")
-    return t if isinstance(t, str) else ""
-
-def record_text(rec):
-    if not isinstance(rec, dict): return ""
-    msg = rec.get("message")
-    if not isinstance(msg, dict): return ""
-    content = msg.get("content")
-    if isinstance(content, str): return content
-    if isinstance(content, list):
-        parts = [block_text(b) for b in content]
-        return "\n".join(p for p in parts if p)
-    return ""
-
-path = sys.argv[1]
-turns = []
+def concat_text(content):
+    """Concatenate every `text` block in a content list (or return the
+    string content as-is). `thinking` blocks contribute nothing."""
+    if isinstance(content, str):
+        return content
+    if not isinstance(content, list):
+        return ""
+    out = []
+    for b in content:
+        if isinstance(b, dict) and b.get("type") == "text":
+            t = b.get("text")
+            if isinstance(t, str):
+                out.append(t)
+    return "".join(out)
+
+path, conversation_id, account_id, occurred_at = sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4]
+
+turns = []                  # ordered output: { role, text, ts, toolCalls? }
+msg_id_to_turn_index = {}   # collapse rule for assistant message.id
+pending_tool_calls = {}     # tool_use_id -> (turn_index, toolCalls_index)
+
 try:
     with open(path, "r", encoding="utf-8") as f:
         for line in f:
             line = line.strip()
-            if not line: continue
-            try: rec = json.loads(line)
-            except Exception: continue
-            t = rec.get("type") if isinstance(rec, dict) else None
-            if t not in ("user", "assistant"): continue
-            tx = record_text(rec).strip()
-            if not tx: continue
-            turns.append(f"{t}: {tx}")
+            if not line:
+                continue
+            try:
+                rec = json.loads(line)
+            except Exception:
+                continue
+            if not isinstance(rec, dict):
+                continue
+            t = rec.get("type")
+            msg = rec.get("message")
+            if not isinstance(msg, dict):
+                continue
+            content = msg.get("content")
+            ts = rec.get("timestamp", "") or ""
+
+            if t == "user":
+                # tool_result blocks attach to the assistant turn that
+                # owned the corresponding tool_use; they never create a
+                # separate user turn entry.
+                if isinstance(content, list):
+                    for b in content:
+                        if isinstance(b, dict) and b.get("type") == "tool_result":
+                            tu_id = b.get("tool_use_id")
+                            if not isinstance(tu_id, str):
+                                continue
+                            slot = pending_tool_calls.pop(tu_id, None)
+                            if slot is None:
+                                continue
+                            turn_idx, call_idx = slot
+                            turns[turn_idx]["toolCalls"][call_idx]["output"] = b.get("content")
+
+                text = concat_text(content)
+                if text:
+                    turns.append({
+                        "role": "user",
+                        "text": text,
+                        "ts": ts,
+                    })
+                # No user turn emitted when content is empty or only
+                # carries tool_result blocks — those landed on the
+                # owning assistant turn above.
+
+            elif t == "assistant":
+                msg_id = msg.get("id") if isinstance(msg.get("id"), str) else None
+                text = concat_text(content)
+                tool_use_blocks = []
+                if isinstance(content, list):
+                    for b in content:
+                        if isinstance(b, dict) and b.get("type") == "tool_use":
+                            tool_use_blocks.append(b)
+
+                # Thinking-only assistant records contribute nothing and
+                # do NOT create a turn entry on their own.
+                if not text and not tool_use_blocks:
+                    continue
+
+                # Multi-block collapse: if a prior record with the same
+                # message.id created a turn, extend that one. Otherwise
+                # open a new assistant turn.
+                if msg_id is not None and msg_id in msg_id_to_turn_index:
+                    idx = msg_id_to_turn_index[msg_id]
+                    entry = turns[idx]
+                    if text:
+                        entry["text"] = (entry["text"] or "") + text
+                else:
+                    entry = {
+                        "role": "assistant",
+                        "text": text,
+                        "ts": ts,
+                    }
+                    turns.append(entry)
+                    idx = len(turns) - 1
+                    if msg_id is not None:
+                        msg_id_to_turn_index[msg_id] = idx
+
+                for b in tool_use_blocks:
+                    tc_list = entry.setdefault("toolCalls", [])
+                    tc_list.append({
+                        "tool":   b.get("name"),
+                        "input":  b.get("input"),
+                        "output": None,
+                    })
+                    tu_id = b.get("id")
+                    if isinstance(tu_id, str):
+                        pending_tool_calls[tu_id] = (idx, len(tc_list) - 1)
 except Exception:
     pass
 
-print("\n".join(turns), end="")
+envelope = {
+    "turns":          turns,
+    "conversationId": conversation_id,
+    "accountId":      account_id,
+    "occurredAt":     occurred_at,
+}
+print(json.dumps(envelope, ensure_ascii=False), end="")
 PY
 )
 
-CONVERSATION_BYTES=$(printf '%s' "$CONVERSATION_TEXT" | wc -c | tr -d ' ')
+# Skip when turns is empty — no user text, no assistant text, no tool_use
+# in the operator JSONL. Same skip surface as the prior `conversation-empty`
+# reason; the meaning is now binary on turns.length === 0.
+EMPTY_CHECK=$(printf '%s' "$ENVELOPE" | python3 -c '
+import sys, json
+try:
+    e = json.load(sys.stdin)
+    print("empty" if not (e.get("turns") or []) else "ok")
+except Exception:
+    print("empty")
+')
+
+CONVERSATION_BYTES=$(printf '%s' "$ENVELOPE" | wc -c | tr -d ' ')
 TRANSCRIPT_BYTES=$(wc -c <"$TRANSCRIPT_PATH" 2>/dev/null | tr -d ' ' || echo 0)
 
 emit_log "trigger sessionId=${ADMIN_SESSION_ID} turnIndex=0 transcriptBytes=${TRANSCRIPT_BYTES} conversationBytes=${CONVERSATION_BYTES}"
 
-if [ -z "$CONVERSATION_TEXT" ]; then
+if [ "$EMPTY_CHECK" = "empty" ]; then
   emit_log "trigger-skipped sessionId=${ADMIN_SESSION_ID} reason=conversation-empty"
   exit 0
 fi
 
+# Task 177 observability — one envelope summary line per recorder fire,
+# emitted BEFORE the spawn POST so a future audit reads counts from
+# server.log without re-walking the JSONL. `turnsCount` is monotone
+# across spawns in the same operator session — flat or decreasing is
+# the regression signature for "windowing crept back in".
+ENVELOPE_COUNTS=$(printf '%s' "$ENVELOPE" | python3 -c '
+import sys, json
+e = json.load(sys.stdin)
+turns = e.get("turns") or []
+u = sum(1 for t in turns if t.get("role") == "user")
+a = sum(1 for t in turns if t.get("role") == "assistant")
+tc = sum(1 for t in turns if (t.get("toolCalls") or []))
+print(f"{len(turns)} {u} {a} {tc}")
+')
+read -r TURNS_COUNT USER_TURNS ASST_TURNS TC_TURNS <<<"$ENVELOPE_COUNTS"
+emit_log "envelope sessionId=${ADMIN_SESSION_ID} turnsCount=${TURNS_COUNT} userTurns=${USER_TURNS} assistantTurns=${ASST_TURNS} toolCallTurns=${TC_TURNS}"
+
 # Compose the Sidebar-shape spawn body. Three overrides relative to a
 # plain Sidebar "New session" click: specialist, model, initialMessage.
 # `adminSessionId` is the loopback-bypass key the wrapper uses to resolve
@@ -154,20 +290,18 @@ fi
 SPAWN_BODY=$(python3 -c '
 import sys, json
 sid = sys.argv[1]
-conversation = sys.argv[2]
-instruction = "update the graph with any new or missing information or intent"
-text = instruction + "\n\n" + conversation
+envelope_str = sys.argv[2]
 body = {
   "adminSessionId": sid,
   "channel": "browser",
   "specialist": "database-operator",
   "model": "haiku",
-  "initialMessage": text,
+  "initialMessage": envelope_str,
 }
 print(json.dumps(body))
-' "$ADMIN_SESSION_ID" "$CONVERSATION_TEXT" 2>/dev/null)
+' "$ADMIN_SESSION_ID" "$ENVELOPE" 2>/dev/null)
 
-INITIAL_BYTES=$(printf '%s\n\n%s' "update the graph with any new or missing information or intent" "$CONVERSATION_TEXT" | wc -c | tr -d ' ')
+INITIAL_BYTES=$(printf '%s' "$ENVELOPE" | wc -c | tr -d ' ')
 emit_log "spawn-request sessionId=${ADMIN_SESSION_ID} specialist=database-operator initialMessageBytes=${INITIAL_BYTES}"
 
 SPAWN_RES_FILE=$(mktemp)

package/payload/platform/plugins/docs/references/admin-session.md

@@ -92,11 +92,29 @@ After every completed operator admin turn, the Stop hook `platform/plugins/admin
 Body overrides relative to a plain Sidebar click:
 - `specialist: 'database-operator'`
 - `model: 'haiku'`
-- `initialMessage: "update the graph with any new or missing information or intent\n\n<conversation-text>"`
+- `initialMessage: <json-envelope>` (string carrying a JSON-stringified object — see below)
 
 **Spawn body.** The hook POSTs `{adminSessionId, channel: 'browser', specialist: 'database-operator', model: 'haiku', initialMessage}` to `POST /api/admin/claude-sessions`. `adminSessionId` is the loopback-bypass key — the wrapper resolves the operator's real `senderId` from `GET <managerBase>/<adminSessionId>/meta` and forwards a Sidebar-shape body to the manager.
 
-**`<conversation-text>`** is the operator JSONL walked in transcript order: every `user`/`assistant` record with non-empty text emitted as `"<type>: <text>"`, joined by `\n`. The full exchange is preserved so the recorder can infer operator-asserted facts that span multiple turns (e.g. "hello / what's your business? / Smalleys"). The earlier "last-turn-only" extractor stripped the framing the recorder needed. If no qualifying record exists, the hook emits `trigger-skipped reason=conversation-empty` and no recorder is spawned.
+**`initialMessage` JSON envelope (Task 177).** A single JSON object stringified to a string. Top-level keys exactly match the database-operator agent file `## Input shape`:
+
+```
+{
+  "turns": [
+    { "role": "user",      "text": "...", "ts": "<ISO-8601>" },
+    { "role": "assistant", "text": "...", "ts": "<ISO-8601>",
+      "toolCalls": [ { "tool": "...", "input": {...}, "output": ... } ] },
+    ...
+  ],
+  "conversationId": "<operator session_id>",
+  "accountId":      "<ACCOUNT_ID env, stamped on the manager systemd unit>",
+  "occurredAt":     "<hook fire time, ISO-8601 UTC, .000Z>"
+}
+```
+
+`turns` is the operator's full conversation transcript, oldest first, newest last — every user / assistant message in the operator's JSONL from session start to the moment the recorder fired. No windowing, no truncation, no env knob. The walker collapses multi-record assistant messages on `message.id` (e.g. one `thinking` record + one `text` record from the same message become one `turns` entry with combined text). `toolCalls` is assistant-only and omitted on turns that called no tools. `toolCalls[].input` and `toolCalls[].output` are native JSON values, not re-stringified — `jq -r '.toolCalls[0].input.foo'` reaches the inner field directly. `tool_use` and `tool_result` blocks are paired by `tool_use_id` and attach to the assistant turn that owned the `tool_use`; the user record carrying only the `tool_result` does not create a separate user turn. Unanswered `tool_use` calls surface with `output: null`. No leading instruction prose — the agent file's system prompt teaches the model what to do with the payload. If `turns` is empty after the walker runs, the hook emits `trigger-skipped reason=conversation-empty` and no recorder is spawned. (Task 175's earlier `(operatorMessage, assistantReply)` pair contract was superseded — the pair asserted a temporal Q→A relationship the walker never enforced, so Task 177 replaced it with the ordered window.)
+
+The hook also emits one summary line per fire immediately before `spawn-request`: `[turn-recorder] envelope sessionId=<op> turnsCount=<n> userTurns=<n> assistantTurns=<n> toolCallTurns=<n>`. `turnsCount` is monotone across spawns in the same operator session — a flat or decreasing series is the regression signature for "windowing crept back in".
 
 **Manager-side specialist branches.** The recorder is the first specialist subagent that exercises the full specialist flag matrix:
 - The bundled `platform/templates/specialists/agents/database-operator.md` template is symlinked into `$CLAUDE_CONFIG_DIR/agents/database-operator.md` by the installer; without that link `claude --agent database-operator` silently falls back to the admin agent.
@@ -109,16 +127,17 @@ Body overrides relative to a plain Sidebar click:
 
 **Hook recursion gate.** `pty-spawner` stamps `MAXY_SPECIALIST=<specialist>` on every PTY env. The Stop hook short-circuits when `MAXY_SPECIALIST=database-operator` so the recorder's own end-of-turn does not re-fire the hook.
 
-**Observability.** The hook emits exactly two lines per operator turn via `/api/admin/log-ingest`: `[turn-recorder] trigger sessionId=<op> turnIndex=0 transcriptBytes=<n> conversationBytes=<n>` and `[turn-recorder] spawn-request sessionId=<op> specialist=database-operator initialMessageBytes=<n>`. The manager adds `pty-spawn-allowlist specialist=database-operator count=11 stripped=0 sourced-from=agent-frontmatter` and `pty-spawn-start … specialist=database-operator append-system-prompt-bytes=0` before the PTY launches. The remainder of the recorder lifecycle is covered by the Sidebar's existing lines (`pty-spawned`, JSONL events, `auto-archive`). Failure-mode names: `trigger-skipped reason=…` enumerates `role-not-admin | is-recorder | empty-stdin | missing-transcript | conversation-empty`. Hook-side spawn errors emit `[turn-recorder] spawn-failed reason=loopback-http http=<code>`.
+**Observability.** The hook emits exactly two lines per operator turn via `/api/admin/log-ingest`: `[turn-recorder] trigger sessionId=<op> turnIndex=0 transcriptBytes=<n> conversationBytes=<n>` and `[turn-recorder] spawn-request sessionId=<op> specialist=database-operator initialMessageBytes=<n>`. The manager adds `pty-spawn-allowlist specialist=database-operator count=11 stripped=0 sourced-from=agent-frontmatter`, `pty-spawn-start … specialist=database-operator append-system-prompt-bytes=0` before the PTY launches, and one `[pty-spawn-tool-inventory] sessionId=<rec> specialist=database-operator argv-tools=<n> mcp-listed-tools=<n> exposed=<csv> not-exposed=<csv>` line per spawn once the shadow probe of each MCP server returns. The remainder of the recorder lifecycle is covered by the Sidebar's existing lines (`pty-spawned`, JSONL events, `auto-archive`). Failure-mode names: `trigger-skipped reason=…` enumerates `role-not-admin | is-recorder | empty-stdin | missing-transcript | conversation-empty`. Hook-side spawn errors emit `[turn-recorder] spawn-failed reason=loopback-http http=<code>`. Probe-side failure on the inventory line emits `[pty-spawn-tool-inventory-failed] sessionId=<rec> specialist=<name> err=<json>`.
 
 ### Recorder lifecycle diagnostic
 
-When the operator reports "the recorder did nothing this turn", run these six greps in order. The first absent line names the phase that failed. `<op>` is the admin operator's session id from the original Stop hook; `<rec>` is the recorder session id returned in phase 2's response and reused across phases 3–6.
+When the operator reports "the recorder did nothing this turn", run these seven greps in order. The first absent line names the phase that failed. `<op>` is the admin operator's session id from the original Stop hook; `<rec>` is the recorder session id returned in phase 2's response and reused across phases 3–6.
 
 1. **Stop hook fired.** `grep '\[turn-recorder\] trigger sessionId=<op>' ~/.<brand>/logs/server.log` — expects one line of shape `[turn-recorder] trigger sessionId=<op> turnIndex=0 transcriptBytes=<n> conversationBytes=<n>`. Absent: the Stop hook didn't run; check that `MAXY_SESSION_ROLE=admin` was set on the operator PTY and that `MAXY_SPECIALIST!=database-operator` (recursion gate).
 2. **/spawn accepted.** `grep '\[turn-recorder\] spawn-request sessionId=<op>' ~/.<brand>/logs/server.log` — expects `[turn-recorder] spawn-request sessionId=<op> specialist=database-operator initialMessageBytes=<n>`. The response body of this POST carries `<rec>`. Absent: the hook fired but `/api/admin/claude-sessions` rejected; look for `[turn-recorder] spawn-failed reason=loopback-http http=<code>` on the next line.
 3. **PTY started.** `grep 'pty-spawn-start .* specialist=database-operator' ~/.<brand>/logs/server.log` — expects `pty-spawn-start claudeBin=<…> argv-count=<n> append-system-prompt-bytes=0 … specialist=database-operator prompt-positional=yes prompt-bytes=<n>`. Absent: the wrapper accepted but the manager rejected before exec; check the spawn-failure surfaces (`which-claude-not-found | pty-spawn-failed | pid-file-timeout | host-context-unresolved | identity-unresolved | mcp-config-write-failed`).
 4. **Agent file resolved.** `grep 'pty-spawn-allowlist specialist=database-operator count=11 stripped=0 sourced-from=agent-frontmatter' ~/.<brand>/logs/server.log` — expects exactly one line per recorder spawn. Absent (or `count` not equal to the frontmatter's tool count, or `stripped>0` meaning the brand excluded a plugin the recorder template references — Task 173): the agent file at `$CLAUDE_CONFIG_DIR/agents/database-operator.md` is missing the `tools:` line, the symlink the installer creates never landed, or the brand-aware drift filter dropped tools. Re-run the installer; cross-reference `brand.json#plugins.excluded` against the agent frontmatter.
+4b. **Tool inventory exposed to the model.** `grep '\[pty-spawn-tool-inventory\] sessionId=<rec>' ~/.<brand>/logs/server.log` — expects one line of shape `[pty-spawn-tool-inventory] sessionId=<rec> specialist=database-operator argv-tools=11 mcp-listed-tools=<n> exposed=<csv> not-exposed=<csv>`. The line lands once per spawn after the manager's shadow probe finishes a `tools/list` against each MCP server in the per-spawn `mcp.json`. The four fields decode the recorder's runtime tool surface directly: `argv-tools` is the allowlist on the `claude` argv (= phase 4's `count`); `mcp-listed-tools` is the sum across servers of names the probe captured; `exposed` is the intersection (in frontmatter order); `not-exposed` is the allowlist minus `exposed`. The regression query for "model says no tools" is `exposed=$|exposed= ` — when the line ends `exposed= not-exposed=<all 11>`, the allowlist landed on the argv but none of the names came back from any MCP server (cause space: frontmatter format, name canonicalisation, MCP handshake repair). Absent line: probe is fire-and-forget, so absence either means the spawn was not a specialist (operator chat) or the probe itself crashed — in which case `[pty-spawn-tool-inventory-failed] sessionId=<rec> specialist=… err=…` is the partner line to grep. Note: the probe captures what each MCP server offers, not what claude code's own tools/list saw — CLI-side filtering after handshake is a separate observability concern.
 5. **Graph write outcome.** `grep '\[mcp:memory\] memory-write .* session=<rec>' ~/.<brand>/logs/server.log` — expects one line ending `result=ok elementId=<id>` or `result=error reason=<slug>` (slug enumerated by the memory MCP write-path observability work). Absent: the recorder loaded but produced no tool calls — model-side decision, not infra. Read the recorder JSONL at `<accountDir>/.claude/projects/<slug>/<rec>.jsonl` to see what the LLM did.
 6. **Auto-archive.** `grep 'auto-archive .* sessionId=<rec> .* specialist=database-operator reason=end-turn' ~/.<brand>/logs/server.log` — expects one line. Absent: the recorder finished but the manager's end-turn watcher didn't fire; the fs-watcher row will get reaped on its TTL but the recorder hung longer than expected. Investigate `pty-spawn-stop` and `pid-file-removed` lines on the same `<rec>`.
 

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

@@ -504,6 +504,8 @@ This gate was Task 173. The `brand-excluded` branch closes the recurring crash-r
 
 **Recorder auto-archive (lifecycle, not user-initiated).** The session manager's `attachRecorderAutoArchive` ([`platform/services/claude-session-manager/src/http-server.ts:178`](../../../services/claude-session-manager/src/http-server.ts)) wires every spawn whose `senderId === 'turn-recorder'` to a JSONL watcher: as soon as the recorder's JSONL contains `"stop_reason":"end_turn"`, the manager calls `stopSession`, the PTY exits, the PID file is removed, and `fs-watcher.ts:275-297` demotes the row to `state: 'archived'`. This is the lifecycle archive path — the row stays in place, the JSONL stays on disk, no directory move. It is structurally distinct from the user-initiated `POST /api/admin/claude-sessions/:id/archive` route, which actually `mv`s the JSONL between `<slugDir>` and `<slugDir>/archive/`; that path is the operator pruning their visible session list, not the recorder's per-turn cleanup.
 
+**Resume idempotency and specialist propagation (Task 179).** `POST /resume` accepts an optional `idempotencyKey` on the body; two POSTs sharing the same `${senderId}:${idempotencyKey}` within 5 seconds return the cached payload without spawning a second PTY. The client (`platform/ui/app/lib/session-actions.ts`) generates a fresh `crypto.randomUUID()` per Resume click and forwards it through the proxy. A synchronous `useRef` guard inside `resume()` short-circuits a same-frame re-fire (React StrictMode, rapid double-click) before the network is touched, and `Sidebar.tsx` disables the Resume button while `inFlight === 'resume'`. The resume route also accepts a `specialist` field on the body, validated by the same regex `/^[A-Za-z0-9_-]{1,64}$/` that `/spawn` uses; when absent, the route falls back to `resolveRow(deps.watcher, sessionId).agent` so a `database-operator` resume always lands as a `database-operator` session rather than collapsing to an admin row. Forensic log lines: `resume-dedup senderId=… idempotencyKey=… cacheHit=yes age-ms=<n>` on a deduplicated POST, and `resume-specialist-propagated source=<sid> specialist=<name>` on a resume that carried a non-default specialist.
+
 ## Tool Call Audit Trail
 
 Every tool invocation by the admin agent produces a durable `ToolCall` node in the knowledge graph, linked to the `Conversation` that triggered it. This covers all admin agent tool calls — the full history of what the agent did, when, and in what context.

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

@@ -88,7 +88,7 @@ The sidebar row's displayed name is `tail.aiTitle` verbatim, parsed by `jsonl-en
 
 **Stop vs. delete.** `POST /<id>/stop` sends SIGTERM, leaves the JSONL on disk for audit, and is idempotent against an already-dead row. `DELETE /<id>` removes the JSONL + per-session subdir and returns 409 if the PTY is still alive (stop first). Any unknown id returns 404; nothing returns a silent 204 against an id the manager does not know.
 
-**stopSession fd contract (Task 170).** Before `/stop` returns, the manager explicitly releases the pty master file descriptor by calling `pty.destroy()` on node-pty's `UnixTerminal` — the only path that synchronously closes the internal tty socket. Without the explicit call, the master fd waits on V8 GC finalising the IPty object, which is non-deterministic and accumulates under heavy operator-stop traffic until the kernel pty cap (Linux 3072, macOS 511) refuses new spawns. The release is verified by the `stop-session-fd-release` integration test, and every `kill … reason=operator-request` log line now ends in `master-fd=closed` (or `master-fd=close-failed err=<msg>` on the rescued throw branch — a graceful degradation so a corner-case socket-state failure cannot turn a logically-successful stop into a 500).
+**PTY lifecycle contract (Tasks 170 + 176).** A PTY reaches its end via one of two branches: **operator-request** (operator clicks End or the auto-archive Stop hook calls `stopSession`) or **natural-exit** (the claude child exits on its own — operator typed `/quit`, SIGINT in the PTY, crash, network drop on `--remote-control`). Both branches honour a single invariant: the pty master file descriptor is released by an explicit `pty.destroy()` and the SessionStore row is removed before the next `/list` or `/events` tick. Without the explicit destroy, the master fd lingers in node-pty's internal socket until V8 GC finalises the IPty object — non-deterministic and accumulates under load until the kernel pty cap (Linux 3072, macOS 511) refuses new spawns. Without the explicit row removal, the manager shutdown loop SIGTERMs PIDs that already logged `process-exited`, masking the leak only because the manager restarts every few hours. When both branches fire on the same exit (operator clicks End and node-pty's `onExit` fans out the SIGTERM to both listeners), a per-row `fdReleased` flag short-circuits the second branch so `pty.destroy()` runs exactly once on the live socket — without the flag, the second call throws "socket already destroyed" and the operator-request line would falsely log `master-fd=close-failed`. If the first branch's destroy throws and is rescued, the flag stays unset and the second branch retries (defense in depth). Every `kill … pid=<n>` log line carries a `master-fd=closed` suffix (or `master-fd=close-failed err=<msg>` on the rescued throw branch — a graceful degradation so a corner-case socket-state failure cannot turn a logically-successful exit into a 500); the operator-request line additionally identifies `reason=operator-request`, the natural-exit line identifies `reason=process-exited`. Both branches are verified by the `stop-session-fd-release` and `endpoint-stop-delete` integration tests (operator-request live and already-exited cycles + natural-exit cycle + throw-then-retry coordination, Linux kernel-level ptmx fd accounting on each).
 
 The metadata pane subscribes to the same /list projection. When an operator clicks End on an alive row, the DELETE returns 200 and the post-mutation refetch decides what happens next: a session that wrote a JSONL surfaces as a dehydrated `status: 'ended'` row (the pane swaps `End session` for `Purge JSONL` plus `Resume`), and a session that never wrote a JSONL (`Turns: 0`) leaves the list entirely (the pane shows a `Session ended without a transcript. Close this pane.` banner with a Close button and no destructive action). The manager's `/list` and `/meta` are the only authorities on post-End state; the client does not pre-empt either response with an optimistic mutation.
 

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

@@ -4,6 +4,9 @@ import { type SpawnDeps } from './pty-spawner.js';
 import type { FsWatcher } from './fs-watcher.js';
 import type { RateLimiter } from './spawn-rate-limiter.js';
 import type { AuditRegistry } from './public-tool-audit.js';
+/** Test-only — clear the dedup cache between vitest cases so module state
+ *  does not leak across describe blocks. */
+export declare function __resetResumeDedupCacheForTests(): void;
 export interface HttpDeps extends Omit<SpawnDeps, 'store' | 'onSessionReady' | 'watcher'> {
     store: SessionStore;
     watcher: FsWatcher;

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":"AAwBA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAI3B,OAAO,KAAK,EAAE,YAAY,EAAiB,MAAM,oBAAoB,CAAA;AACrE,OAAO,EAA0E,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAIzH,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;AA6E3D,MAAM,WAAW,QAAS,SAAQ,IAAI,CAAC,SAAS,EAAE,OAAO,GAAG,gBAAgB,GAAG,SAAS,CAAC;IACvF,KAAK,EAAE,YAAY,CAAA;IACnB,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;CAC/B;AAoHD,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CA8sBjD"}
+{"version":3,"file":"http-server.d.ts","sourceRoot":"","sources":["../src/http-server.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAI3B,OAAO,KAAK,EAAE,YAAY,EAAiB,MAAM,oBAAoB,CAAA;AACrE,OAAO,EAA0E,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAIzH,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;AAoB3D;4CAC4C;AAC5C,wBAAgB,+BAA+B,IAAI,IAAI,CAEtD;AA0ED,MAAM,WAAW,QAAS,SAAQ,IAAI,CAAC,SAAS,EAAE,OAAO,GAAG,gBAAgB,GAAG,SAAS,CAAC;IACvF,KAAK,EAAE,YAAY,CAAA;IACnB,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;CAC/B;AAoHD,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAiwBjD"}

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

@@ -30,6 +30,25 @@ import { claudeStateRoot, projectSlugForCwd } from './jsonl-path.js';
 import { basename, join } from 'node:path';
 const ROLES = ['admin', 'public'];
 const CHANNELS = ['browser', 'whatsapp', 'telegram', 'webchat', 'email'];
+// Task 179 — resume idempotency. Two POSTs 9ms apart with the same
+// idempotencyKey produce one PTY and return the same ManagerSession.
+// Keyed on `${senderId}:${idempotencyKey}` so two operators' keys cannot
+// collide; TTL is 5000ms — long enough to absorb a React StrictMode
+// re-render race or a cross-surface double-click, short enough that a
+// real second resume two seconds later still spawns a new PTY.
+const RESUME_DEDUP_TTL_MS = 5_000;
+const resumeDedupCache = new Map();
+function pruneResumeDedupCache(now) {
+    for (const [key, entry] of resumeDedupCache) {
+        if (now - entry.createdAt > RESUME_DEDUP_TTL_MS)
+            resumeDedupCache.delete(key);
+    }
+}
+/** Test-only — clear the dedup cache between vitest cases so module state
+ *  does not leak across describe blocks. */
+export function __resetResumeDedupCacheForTests() {
+    resumeDedupCache.clear();
+}
 function parseAboutOwner(raw) {
     if (!raw || typeof raw !== 'object')
         return undefined;
@@ -568,6 +587,22 @@ export function buildHttpApp(deps) {
             timed(deps.logger, 'POST', '/resume', 400, Date.now() - start);
             return c.json({ error: 'invalid-arguments' }, 400);
         }
+        // Task 179 — idempotency dedup. Same key + same senderId within 5s
+        // returns the cached payload; no new spawn.
+        const idempotencyKey = typeof body.idempotencyKey === 'string' && /^[A-Za-z0-9_-]{1,64}$/.test(body.idempotencyKey)
+            ? body.idempotencyKey
+            : undefined;
+        if (idempotencyKey) {
+            const now = Date.now();
+            pruneResumeDedupCache(now);
+            const cacheKey = `${senderId}:${idempotencyKey}`;
+            const hit = resumeDedupCache.get(cacheKey);
+            if (hit && now - hit.createdAt <= RESUME_DEDUP_TTL_MS) {
+                deps.logger(`resume-dedup senderId=${senderId} idempotencyKey=${idempotencyKey} cacheHit=yes age-ms=${now - hit.createdAt}`);
+                timed(deps.logger, 'POST', '/resume', 200, Date.now() - start);
+                return c.json(hit.payload, 200);
+            }
+        }
         const channels = Array.isArray(body.channels)
             ? body.channels.filter((c) => typeof c === 'string' && c.length > 0)
             : undefined;
@@ -580,6 +615,16 @@ export function buildHttpApp(deps) {
             : body.tunnelUrl === null
                 ? null
                 : undefined;
+        // Task 179 — specialist propagation. Body field takes precedence; when
+        // absent, fall back to the source row's `agent`. Either path: the
+        // resumed PTY is spawned with `--agent <name>` so the new row inherits
+        // the same specialist as the source. A database-operator resume now
+        // produces a database-operator session, not an admin session.
+        const bodySpecialist = typeof body.specialist === 'string' && /^[A-Za-z0-9_-]{1,64}$/.test(body.specialist)
+            ? body.specialist
+            : undefined;
+        const sourceRow = resolveRow(deps.watcher, sessionId);
+        const specialist = bodySpecialist ?? sourceRow?.agent ?? undefined;
         const result = await spawnClaudeSession({ ...deps, store: deps.store, watcher: deps.watcher, onSessionReady: (s) => { attachPublicAudit(deps, s); attachSpecialistEndTurnAutoArchive(deps, s); }, tunnelUrlOverride }, {
             senderId,
             role: role,
@@ -590,6 +635,7 @@ export function buildHttpApp(deps) {
             dormantPlugins,
             activePlugins,
             specialistDomains,
+            specialist,
         });
         if (!result.ok) {
             if ('rejected' in result) {
@@ -603,9 +649,16 @@ export function buildHttpApp(deps) {
             timed(deps.logger, 'POST', '/resume', 500, Date.now() - start);
             return c.json({ error: 'resume-failed', reason: result.reason }, 500);
         }
+        if (specialist) {
+            deps.logger(`resume-specialist-propagated source=${sessionId} specialist=${specialist}`);
+        }
         deps.logger(`resume pid=${result.session.pid} sessionId=${result.session.sessionId} resumeFrom=${sessionId} latency-ms=${Date.now() - start}`);
+        const payload = toLivePayload(result.session);
+        if (idempotencyKey) {
+            resumeDedupCache.set(`${senderId}:${idempotencyKey}`, { payload, createdAt: Date.now() });
+        }
         timed(deps.logger, 'POST', '/resume', 200, Date.now() - start);
-        return c.json(toLivePayload(result.session), 200);
+        return c.json(payload, 200);
     });
     app.get('/:sessionId/meta', (c) => {
         const start = Date.now();