polygram 0.10.0-rc.34 → 0.10.0-rc.35

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "polygram",
-  "version": "0.10.0-rc.34",
+  "version": "0.10.0-rc.35",
   "description": "Telegram integration for Claude Code that preserves the OpenClaw per-chat session model. Migration target for OpenClaw users. Multi-bot, multi-chat, per-topic isolation; SQLite transcripts; inline-keyboard approvals. Bundles /polygram:status|logs|pair-code|approvals admin commands plus history (transcript queries) and polygram-send (out-of-turn IPC sends with file-upload validation) skills.",
   "keywords": [
     "telegram",

package/lib/process/hook-event-tail.js

@@ -0,0 +1,144 @@
+/**
+ * hook-event-tail — typed-event parser around the per-session hook
+ * ndjson that `polygram-hook-append.js` writes for the H1 hook-based
+ * turn observability (docs/0.10.0-tmux-hook-observability.md).
+ *
+ * Mirrors the JSONL stream's `pipeToParser(tail)` shape so TmuxProcess
+ * wires it the same way `_armSessionLogTail` wires the JSONL tail.
+ *
+ * Per-line behaviour:
+ *  - Parse JSON. If the line is missing, malformed, or the helper
+ *    wrapped it with `polygram_parse_error`, emit a `parse-error`
+ *    event (observability — H1 soak measures how often this fires).
+ *  - Discriminate on `hook_event_name`. Known events become typed
+ *    HookEvent records with normalized fields; unknown event names
+ *    pass through as `unknown` with the raw object attached so we
+ *    can investigate without re-deploying.
+ *  - Empty lines are ignored (atomic-append interleave between two
+ *    helper invocations can produce them in theory — H1 measures
+ *    whether it happens in practice on macOS).
+ *
+ * Normalized HookEvent shape (the fields downstream code may rely on
+ * once H1's observer-only soak proves the stream — H2+ phases consume
+ * these):
+ *
+ *   {
+ *     type: 'PreToolUse' | 'PostToolUse' | 'UserPromptSubmit'
+ *         | 'Stop' | 'SubagentStop' | 'Notification' | 'unknown'
+ *         | 'parse-error',
+ *     sessionId, transcriptPath, cwd, permissionMode,           // common
+ *     toolName, toolUseId, toolInput, toolResponse, durationMs, // tool events
+ *     agentId, agentType,                                       // subagent-inner
+ *     agentTranscriptPath,                                      // SubagentStop
+ *     prompt,                                                   // UserPromptSubmit
+ *     stopHookActive, lastAssistantMessage,                     // Stop
+ *     receivedAtMs, raw,                                        // always
+ *   }
+ *
+ * Per the 2.1.142 spike, `parent_tool_use_id` is NOT a field, and
+ * `SubagentStart` does not fire (for general-purpose subagents) —
+ * neither is in the typed shape.
+ */
+
+'use strict';
+
+const { LogTail } = require('../tmux/log-tail');
+
+const KNOWN_EVENT_NAMES = new Set([
+  'UserPromptSubmit',
+  'PreToolUse',
+  'PostToolUse',
+  'SubagentStop',
+  'Stop',
+  'Notification',
+]);
+
+/**
+ * Normalize one raw hook payload (already JSON.parsed) into the
+ * shape downstream code consumes. Unknown shapes pass through as
+ * `unknown` so a 2.1.143-style schema drift doesn't silently lose
+ * events.
+ */
+function normalizeHookEvent(raw) {
+  if (raw && typeof raw === 'object' && raw.polygram_parse_error) {
+    return {
+      type: 'parse-error',
+      error: raw.polygram_parse_error,
+      receivedAtMs: raw.polygram_received_at_ms ?? null,
+      raw,
+    };
+  }
+  const name = raw && typeof raw === 'object' ? raw.hook_event_name : null;
+  const type = KNOWN_EVENT_NAMES.has(name) ? name : 'unknown';
+  return {
+    type,
+    sessionId:           raw?.session_id ?? null,
+    transcriptPath:      raw?.transcript_path ?? null,
+    cwd:                 raw?.cwd ?? null,
+    permissionMode:      raw?.permission_mode ?? null,
+    toolName:            raw?.tool_name ?? null,
+    toolUseId:           raw?.tool_use_id ?? null,
+    toolInput:           raw?.tool_input ?? null,
+    toolResponse:        raw?.tool_response ?? null,
+    durationMs:          raw?.duration_ms ?? null,
+    agentId:             raw?.agent_id ?? null,
+    agentType:           raw?.agent_type ?? null,
+    agentTranscriptPath: raw?.agent_transcript_path ?? null,
+    prompt:              raw?.prompt ?? null,
+    stopHookActive:      raw?.stop_hook_active ?? null,
+    lastAssistantMessage: raw?.last_assistant_message ?? null,
+    receivedAtMs:        raw?.polygram_received_at_ms ?? null,
+    raw,
+  };
+}
+
+/**
+ * Wrap a LogTail with line-by-line hook parsing. Forwards parsed
+ * events via `'event'` (same shape as session-log-parser.pipeToParser).
+ *
+ * @returns the same emitter (chainable).
+ */
+function pipeHookParser(tail) {
+  tail.on('line', (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return; // blank-line guard (interleave-paranoid)
+    let raw;
+    try {
+      raw = JSON.parse(trimmed);
+    } catch (err) {
+      tail.emit('event', {
+        type: 'parse-error',
+        error: err.message,
+        receivedAtMs: Date.now(),
+        raw: trimmed.length > 1024 ? trimmed.slice(0, 1024) + '…' : trimmed,
+      });
+      return;
+    }
+    tail.emit('event', normalizeHookEvent(raw));
+  });
+  return tail;
+}
+
+/**
+ * One-shot helper: build a LogTail at the given path with the
+ * H1-typical config (watch mode, no skipExisting because a fresh
+ * spawn's ndjson is empty), wire the hook parser, and return it.
+ * Caller calls `.start()` and `.on('event', ...)`.
+ */
+function createHookTail({ path: filePath, logger = console } = {}) {
+  const tail = new LogTail({
+    path: filePath,
+    intervalMs: 50,
+    skipExisting: false,
+    useWatch: 'auto',
+    logger,
+  });
+  return pipeHookParser(tail);
+}
+
+module.exports = {
+  KNOWN_EVENT_NAMES,
+  normalizeHookEvent,
+  pipeHookParser,
+  createHookTail,
+};

package/lib/process/hook-settings.js

@@ -0,0 +1,144 @@
+/**
+ * hook-settings — build the per-session `--settings <file>` JSON
+ * polygram injects at claude-spawn time for the H1 hook-based
+ * observability stream.
+ *
+ * See docs/0.10.0-tmux-hook-observability.md. The settings file
+ * registers a single command-type hook on every event we want to
+ * observe; the command is `polygram-hook-append.js` (a Node helper at
+ * a fixed absolute path) which appends each event as a compacted JSON
+ * line to the per-session ndjson.
+ *
+ * Path layout:
+ *   ~/.polygram/<bot>/hooks/<sid>.settings.json   (this file's output)
+ *   ~/.polygram/<bot>/hooks/<sid>.ndjson          (hook stream sink)
+ *
+ * 2.1.142 spike findings (2026-05-21) baked into the schema:
+ *  - hooks DO fire alongside `--strict-mcp-config
+ *    --setting-sources project,local --settings <file>` (so the file
+ *    is the right transport for the Music topic).
+ *  - hooks are non-blocking by default → no `async`/`timeout` needed,
+ *    but `timeout: 30` is included as a belt-and-braces backstop in
+ *    case a future CLI release flips the default to sync. 30 s is a
+ *    safe ceiling (the helper is single-syscall fast in practice).
+ *  - registered events: the five confirmed in the spike +
+ *    `Notification` (not yet observed; harmless to register).
+ *    `SubagentStart` is intentionally omitted — it did not fire for
+ *    general-purpose subagents on 2.1.142 and the design does not
+ *    depend on it.
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+const HOOK_HELPER_ABS_PATH = path.resolve(__dirname, 'polygram-hook-append.js');
+
+// Events we register hooks for. Order is informational only — claude
+// merges by event name.
+const HOOK_EVENTS = [
+  'UserPromptSubmit',
+  'PreToolUse',
+  'PostToolUse',
+  'SubagentStop',
+  'Stop',
+  'Notification',
+];
+
+/**
+ * Per-bot hooks dir (parent of both settings + ndjson files).
+ * Mirrors `lib/tmux/tmux-runner.js#debugLogPath`'s `~/.polygram/<bot>/logs`
+ * convention. No /tmp fallback when HOME is unset — fail loud (audit
+ * M4 style — symlink races on world-writable dirs).
+ *
+ * @param {string} botName
+ * @param {string} [hooksDir]  override (for tests)
+ */
+function hooksBaseDir(botName, hooksDir) {
+  if (!hooksDir && !process.env.HOME) {
+    throw Object.assign(
+      new Error('HOME env var unset; refusing /tmp fallback for hooks dir'),
+      { code: 'HOME_UNSET' },
+    );
+  }
+  const safeBot = String(botName).replace(/[^\w-]/g, '_');
+  return hooksDir || path.join(process.env.HOME, '.polygram', safeBot, 'hooks');
+}
+
+function hookNdjsonPath(botName, sessionId, hooksDir) {
+  return path.join(hooksBaseDir(botName, hooksDir), `${sessionId}.ndjson`);
+}
+
+function hookSettingsPath(botName, sessionId, hooksDir) {
+  return path.join(hooksBaseDir(botName, hooksDir), `${sessionId}.settings.json`);
+}
+
+/**
+ * Build the settings-JSON object that claude reads via `--settings`.
+ *
+ * @param {object} opts
+ * @param {string} opts.ndjsonPath    absolute path the helper appends to
+ * @param {string} [opts.helperPath]  absolute path to polygram-hook-append.js
+ *                                    (defaults to the one shipped with polygram)
+ */
+function buildHookSettings({ ndjsonPath, helperPath = HOOK_HELPER_ABS_PATH } = {}) {
+  if (!ndjsonPath || !path.isAbsolute(ndjsonPath)) {
+    throw new TypeError('buildHookSettings: ndjsonPath must be an absolute path');
+  }
+  if (!path.isAbsolute(helperPath)) {
+    throw new TypeError('buildHookSettings: helperPath must be an absolute path');
+  }
+  const command = `node ${helperPath} ${ndjsonPath}`;
+  // Per-event entry: PreToolUse/PostToolUse take a matcher (".*" =
+  // every tool); the lifecycle events don't.
+  const matched = (matcher) => [{ matcher, hooks: [{ type: 'command', command, timeout: 30 }] }];
+  const unmatched = () => [{ hooks: [{ type: 'command', command, timeout: 30 }] }];
+  const hooks = {};
+  for (const evt of HOOK_EVENTS) {
+    hooks[evt] = (evt === 'PreToolUse' || evt === 'PostToolUse') ? matched('.*') : unmatched();
+  }
+  return { hooks };
+}
+
+/**
+ * Write the settings JSON to disk (creates parent dirs). Returns the
+ * absolute path. Caller pushes `--settings <path>` to the spawn args.
+ *
+ * The empty ndjson sink is also touched here so the LogTail's
+ * fs.watch can attach immediately (LogTail handles ENOENT, but touching
+ * eliminates a small race window on the first hook event).
+ */
+function writeHookFiles({ botName, sessionId, hooksDir, helperPath, fsImpl = fs } = {}) {
+  const settingsPath = hookSettingsPath(botName, sessionId, hooksDir);
+  const ndjsonPath = hookNdjsonPath(botName, sessionId, hooksDir);
+  fsImpl.mkdirSync(path.dirname(settingsPath), { recursive: true });
+  const settings = buildHookSettings({ ndjsonPath, helperPath });
+  fsImpl.writeFileSync(settingsPath, JSON.stringify(settings));
+  // Touch the ndjson so fs.watch attaches before the first hook fires.
+  const fd = fsImpl.openSync(ndjsonPath, 'a');
+  fsImpl.closeSync(fd);
+  return { settingsPath, ndjsonPath };
+}
+
+/**
+ * Best-effort unlink of both files. Called on kill + orphan-sweep.
+ * Errors are swallowed (ENOENT is the common case after a clean kill).
+ */
+function removeHookFiles({ botName, sessionId, hooksDir, fsImpl = fs } = {}) {
+  for (const p of [hookSettingsPath(botName, sessionId, hooksDir),
+                   hookNdjsonPath(botName, sessionId, hooksDir)]) {
+    try { fsImpl.unlinkSync(p); } catch { /* swallow */ }
+  }
+}
+
+module.exports = {
+  HOOK_HELPER_ABS_PATH,
+  HOOK_EVENTS,
+  hooksBaseDir,
+  hookNdjsonPath,
+  hookSettingsPath,
+  buildHookSettings,
+  writeHookFiles,
+  removeHookFiles,
+};

package/lib/process/polygram-hook-append.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * polygram-hook-append — claude-CLI hook subprocess that appends one
+ * compacted JSON line to a per-session ndjson file.
+ *
+ * Invoked by claude as: `node <abs path>/polygram-hook-append.js <ndjson abs path>`
+ * Stdin: one JSON document (the hook payload). Stdout: nothing.
+ *
+ * Used by the tmux backend H1 (hook-based turn observability). See
+ * docs/0.10.0-tmux-hook-observability.md.
+ *
+ * Behaviour:
+ *  - Reads stdin to EOF, parses as JSON.
+ *  - Stamps `polygram_received_at_ms` (Date.now) so we can measure
+ *    Pre↔Post latency from polygram's wall clock independent of the
+ *    hook's own `duration_ms`.
+ *  - Writes ONE line (JSON.stringify + '\n') with a single fs.writeSync
+ *    on a fd opened O_APPEND. On macOS, O_APPEND atomicity is NOT
+ *    guaranteed above PIPE_BUF (~4 KB); H1 is observe-only and records
+ *    parse failures so we can measure interleave during the soak.
+ *  - Bad JSON → emits a wrapped record with the raw body and a marker
+ *    so the tail's parser can surface it (never silent-drop).
+ *  - Failures (missing argv, open/write error) exit non-zero but never
+ *    throw out of `claude` (claude already runs us with stdout/stderr
+ *    captured and a timeout); the worst case is a single missing line.
+ *
+ * Determinism: no shell, no external deps. Resolved at fixed absolute
+ * path so the `command:` string in the settings JSON is free of
+ * metachars and `~`-expansion.
+ */
+
+'use strict';
+
+const fs = require('fs');
+
+const outPath = process.argv[2];
+if (!outPath) {
+  process.stderr.write('polygram-hook-append: missing ndjson path (argv[2])\n');
+  process.exit(2);
+}
+
+let buf = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { buf += chunk; });
+process.stdin.on('end', () => {
+  let line;
+  try {
+    const obj = JSON.parse(buf);
+    obj.polygram_received_at_ms = Date.now();
+    line = JSON.stringify(obj);
+  } catch (err) {
+    // Preserve the raw body so the tail can flag it; never silent-drop.
+    line = JSON.stringify({
+      polygram_parse_error: err.message,
+      polygram_received_at_ms: Date.now(),
+      raw: buf.length > 64 * 1024 ? buf.slice(0, 64 * 1024) + '…[truncated]' : buf,
+    });
+  }
+  let fd;
+  try {
+    fd = fs.openSync(outPath, 'a');
+    fs.writeSync(fd, line + '\n');
+  } catch (err) {
+    process.stderr.write(`polygram-hook-append: write failed: ${err.message}\n`);
+    process.exitCode = 3;
+  } finally {
+    if (fd != null) {
+      try { fs.closeSync(fd); } catch { /* swallow */ }
+    }
+  }
+});

package/lib/process/tmux-process.js

@@ -44,6 +44,8 @@ const { POLYGRAM_DISPLAY_HINT } = require('../telegram/display-hint');
 const { verifyPinnedClaudeBin } = require('../claude-bin');
 const { createAsyncLock } = require('../async-lock');
 const { TurnPhase, isLegalTransition } = require('./turn-phase');
+const { writeHookFiles, removeHookFiles } = require('./hook-settings');
+const { createHookTail } = require('./hook-event-tail');
 
 // ─── Pinned claude CLI version ───────────────────────────────────────
 //
@@ -472,6 +474,40 @@ class TmuxProcess extends Process {
         args.push('--strict-mcp-config');
         args.push('--setting-sources', 'project,local');
       }
+      // 0.10.0 H1 — hook-based turn observability. Inject a per-spawn
+      // settings file that registers command-type hooks for every
+      // event we want to observe. Hooks fire INSIDE subagents and
+      // are non-blocking on 2.1.142 (spike 2026-05-21 confirmed).
+      // The hook command appends each event as a compacted JSON line
+      // to a per-session ndjson; polygram tails it via `_armHookTail`
+      // below. See docs/0.10.0-tmux-hook-observability.md.
+      //
+      // OBSERVER-ONLY in H1: events are persisted to the events DB
+      // (`hook-event` rows) but no control flow consumes them.
+      // Mirrors the patience-model Commit 1 discipline — soak proves
+      // stream reliability before H2 wires the reactor.
+      //
+      // Survives `--setting-sources project,local` (spike confirmed
+      // the `--settings <file>` layer is honored even when user-level
+      // settings are excluded).
+      try {
+        const { settingsPath, ndjsonPath } = writeHookFiles({
+          botName: this.botName,
+          sessionId: this.claudeSessionId,
+        });
+        this._hookSettingsPath = settingsPath;
+        this._hookNdjsonPath = ndjsonPath;
+        args.push('--settings', settingsPath);
+      } catch (err) {
+        // Refuse to spawn without hooks would be too aggressive in
+        // H1 (observer-only); log and continue without injection so
+        // a transient FS error never blocks a real turn.
+        this.logger.warn?.(
+          `[${this.label}] hook-settings write failed (continuing without hooks): ${err.message}`,
+        );
+        this._hookSettingsPath = null;
+        this._hookNdjsonPath = null;
+      }
       // Cross-backend parity: SDK appends polygram's Telegram display
       // hint to every agent's systemPrompt (lib/sdk/build-options.js).
       // Without this, the spawned claude session has no idea it's
@@ -579,6 +615,11 @@ class TmuxProcess extends Process {
         // LogTail tolerates ENOENT.
         this._cwd = cwd;
         this._armSessionLogTail({ resuming: Boolean(ctx.existingSessionId) });
+        // H1 — same-pattern hook tail. Only arm when the settings
+        // write succeeded above (otherwise there's nothing to tail).
+        if (this._hookNdjsonPath) {
+          this._armHookTail();
+        }
 
         // G6 — block until TUI is responsive.
         await this._waitForReady();
@@ -600,6 +641,19 @@ class TmuxProcess extends Process {
             try { this._sessionLogTail.close(); } catch { /* swallow */ }
             this._sessionLogTail = null;
           }
+          if (this._hookTail) {
+            try { this._hookTail.close(); } catch { /* swallow */ }
+            this._hookTail = null;
+          }
+          // Remove the per-spawn settings + ndjson so a retry gets a
+          // clean pair. Best-effort (ENOENT is fine).
+          if (this._hookSettingsPath || this._hookNdjsonPath) {
+            try {
+              removeHookFiles({ botName: this.botName, sessionId: this.claudeSessionId });
+            } catch { /* swallow */ }
+            this._hookSettingsPath = null;
+            this._hookNdjsonPath = null;
+          }
           try {
             await this.runner.killSession(this.tmuxName);
           } catch (killErr) {
@@ -739,134 +793,47 @@ class TmuxProcess extends Process {
       // instead of re-sending Enter / failing loud. See the method
       // doc.
       //
-      // The confirm drives TWO derived promises below:
-      //   submitConfirmP — rejects TMUX_SUBMIT_FAILED → a racer that
-      //     fails the turn fast and loud; on success it never settles.
-      //   submitOkP      — resolves ONLY once the submit is confirmed;
-      //     on failure it never settles. It GATES the capture-pane
-      //     racer: an "idle" capture-pane is meaningless until the turn
-      //     has actually started — pre-gate, a `[Pasted text #N]`
-      //     prompt sitting unsubmitted reads as an idle (=="complete")
-      //     pane, so the capture racer would win with TMUX_NO_JSONL_TEXT
-      //     and mask the real TMUX_SUBMIT_FAILED cause.
-      // (submitConfirmP / submitOkP plumbing is retired in Commit 3's
-      // _runTurn race rewrite — kept here so Commit 2 stays surgical.)
+      // 0.10.0 Commit 3: the submit-confirm watchdog. On success the
+      // turn proceeds; on TMUX_SUBMIT_FAILED `_awaitSettle` fails the
+      // turn fast. The pre-Commit-3 `submitConfirmP`/`submitOkP`
+      // never-settling-promise gymnastics are gone — `_awaitSettle`
+      // reads `turn.submitConfirmed` (a predicate field) directly to
+      // gate capture-pane quiescence, which is clearer and is the
+      // milestone where control flow starts consuming the predicate.
       const confirmP = turn.token
         ? this._scheduleSubmitRetries(turn.token, turn)
         : Promise.resolve();             // no token — nothing to confirm
-      const submitConfirmP = confirmP.then(() => new Promise(() => {}));
-      const submitOkP = confirmP.then(() => true, () => new Promise(() => {}));
-
-      // R7: an ABSOLUTE timeout wrapping the whole race. The
-      // capture-pane completion detector re-checks its deadline only
-      // BETWEEN `captureWide` subprocess calls — if a single `tmux
-      // capture-pane` wedges (its promise never resolves), the poll
-      // loop is parked on the await and neither the capture-complete
-      // promise nor the JSONL `resultPromise` ever settle, so `send()`
-      // hangs forever and starves the turn queue.
-      //
-      // One setTimeout drives two things: an `abortP` (resolves — fed
-      // to _awaitTurnComplete so its poll loop can break out of a
-      // wedged capture and release the scheduler), and a
-      // `turnDeadlineP` (rejects — the third racer below, guaranteeing
-      // _runTurn ALWAYS settles within turnTimeoutMs). `unref` so the
-      // timer never keeps the process alive on its own; cleared in the
-      // `finally` so a turn that ends early leaves no dangling timer.
-      let turnDeadlineTimer = null;
-      let signalAbort = null;
-      const abortP = new Promise((resolve) => { signalAbort = resolve; });
-      const turnDeadlineP = new Promise((_resolve, reject) => {
-        turnDeadlineTimer = setTimeout(() => {
-          signalAbort();
-          reject(Object.assign(
-            new Error('TmuxProcess: turn did not complete in time'),
-            { code: 'TMUX_TURN_TIMEOUT', tmuxName: this.tmuxName },
-          ));
-        }, turnTimeoutMs);
-        turnDeadlineTimer.unref?.();
-      });
 
-      // Race: JSONL terminal result vs capture-pane quiescence vs the
-      // hard turn timeout. 0.10.0 Phase 4 §6: JSONL is the SOLE source
-      // of reply text. capture-pane is a LIVENESS signal only — it
-      // detects "the turn is done" so we never wait forever for a
-      // `result` that never arrives, but it NEVER delivers text.
-      const captureCompleteP = this._awaitTurnComplete({
-        timeoutMs: turnTimeoutMs, abortP,
-      });
-      // The capture-pane loop may end via the absolute-deadline abort
-      // (it returns the abort sentinel) or reject (its own timeout).
-      // Both are swallowed here — the `turnDeadlineP` reject below is
-      // what actually fails the turn.
-      //
-      // B7: gate the capture racer behind `submitOkP`. A capture-pane
-      // "idle" reading only means "the turn completed" once the turn
-      // has actually STARTED. If the paste never submitted, the pane is
-      // idle because the prompt is still sitting in the input box — not
-      // because a turn finished. Without the gate the capture racer
-      // would win with TMUX_NO_JSONL_TEXT and mask the real
-      // TMUX_SUBMIT_FAILED. `captureCompleteP` is still awaited inside
-      // the racer (so its rejection is always handled — never orphaned
-      // into an unhandled rejection) and the poll loop / scheduler
-      // refcount lifecycle is unchanged; only the racer's eligibility
-      // to WIN is gated on submit confirmation.
-      const captureRaceP = (async () => {
-        let buf;
-        try {
-          buf = await captureCompleteP;
-        } catch {
-          return new Promise(() => {});   // capture's own timeout — turnDeadlineP fails the turn
-        }
-        if (buf === ABORT_SENTINEL) return new Promise(() => {});
-        await submitOkP;                  // gate: capture cannot win pre-submit-confirm
-        return { kind: 'capture' };
-      })();
-
-      let resolvedVia = 'jsonl';
-      let winner;
-      try {
-        winner = await Promise.race([
-          turn.resultPromise.then((ev) => ({ kind: 'jsonl', ev })),
-          captureRaceP,
-          turnDeadlineP,
-          turn.interruptP.then(() => ({ kind: 'interrupt' })),
-          // B7: TMUX_SUBMIT_FAILED rejection fails the turn fast.
-          submitConfirmP,
-        ]);
-
-        // If capture-pane won but the turn used a tool, the agent is
-        // still working — the "ready" hint was a transient idle between
-        // tool calls. Wait for the real terminal result from JSONL, but
-        // keep the absolute deadline armed so a JSONL `result` that
-        // never arrives still fails the turn rather than hanging it.
-        // The interrupt signal still wins here too — Bug 3: an
-        // interrupted tool turn writes no terminal JSONL `result`, so
-        // without this racer it would hang to `turnTimeoutMs`.
-        //
-        // B10: an outstanding `Agent` subagent counts as "tool in
-        // flight" exactly like a foreground `Bash` — its `tool-use`
-        // already set `toolUsedThisTurn`, so this branch catches the
-        // common case. The race where capture wins BEFORE the `Agent`
-        // tool_use line is tailed is handled by the §6 re-check below.
-        if (winner.kind === 'capture' && turn.toolUsedThisTurn) {
-          winner = await Promise.race([
-            turn.resultPromise.then((ev) => ({ kind: 'jsonl', ev })),
-            turnDeadlineP,
-            turn.interruptP.then(() => ({ kind: 'interrupt' })),
-          ]);
-        }
-      } finally {
-        if (turnDeadlineTimer) clearTimeout(turnDeadlineTimer);
-        // Ensure the capture-pane loop is released even when the JSONL
-        // race won — otherwise it would poll on until its own internal
-        // deadline (and, with a shared PollScheduler, hold a refcount).
-        signalAbort();
+      // Commit 3: ONE settle subscription replaces the 5-way
+      // `Promise.race` (+ its nested capture-then-rewait). See
+      // `_awaitSettle`. The hardened behaviours are preserved as
+      // *dispositions* rather than race branches:
+      //   - jsonl       : terminal JSONL `result` (the happy path)
+      //   - interrupt   : `/stop` (Bug 3)
+      //   - submit-fail : TMUX_SUBMIT_FAILED (B7)
+      //   - quiesced    : capture-pane idle, GATED on the predicate —
+      //                   only fires when submitConfirmed (subsumes the
+      //                   old submitOkP gate / B7) AND no tool/subagent
+      //                   outstanding (subsumes B10 — capture can no
+      //                   longer settle a turn mid-subagent, so the old
+      //                   nested re-wait is unnecessary)
+      //   - timeout     : W1 absolute deadline (one setTimeout, not a
+      //                   racer)
+      const outcome = await this._awaitSettle(turn, { turnTimeoutMs, confirmP });
+
+      if (outcome.kind === 'submit-fail') throw outcome.err;
+      if (outcome.kind === 'timeout') {
+        throw Object.assign(
+          new Error('TmuxProcess: turn did not complete in time'),
+          { code: 'TMUX_TURN_TIMEOUT', tmuxName: this.tmuxName },
+        );
       }
 
+      let resolvedVia = 'jsonl';
       let text;
       let resultSubtype = 'success';
       let stopReason = null;
-      if (winner.kind === 'interrupt') {
+      if (outcome.kind === 'interrupt') {
         // Bug 3: `interrupt()` ended the turn. C-c was sent to the
         // TUI; the turn stops here instead of hanging until the
         // absolute `turnTimeoutMs`. Deliver whatever partial text the
@@ -877,11 +844,11 @@ class TmuxProcess extends Process {
         text = turn.text || '';
         resultSubtype = 'interrupted';
         stopReason = 'interrupted';
-      } else if (winner.kind === 'jsonl') {
-        text = turn.text || winner.ev.text || '';
-        resultSubtype = winner.ev.subtype || 'success';
-        stopReason = winner.ev.stopReason || null;
-        if (winner.ev.sessionId) this.claudeSessionId = winner.ev.sessionId;
+      } else if (outcome.kind === 'jsonl') {
+        text = turn.text || outcome.ev.text || '';
+        resultSubtype = outcome.ev.subtype || 'success';
+        stopReason = outcome.ev.stopReason || null;
+        if (outcome.ev.sessionId) this.claudeSessionId = outcome.ev.sessionId;
         // R10: a genuinely-empty terminal `result` — end_turn, no
         // reply text, AND no tool ran this turn — is the agent
         // producing literally nothing (a thinking-only terminal
@@ -904,42 +871,65 @@ class TmuxProcess extends Process {
           );
         }
       } else {
-        // Capture-pane quiescence judged the turn complete. Force the
-        // JSONL aggregator to finalize any buffered message so the
-        // structured `result` settles turn.resultPromise now.
+        // outcome.kind === 'quiesced': capture-pane went idle AND the
+        // predicate confirmed it is SAFE to conclude (submitConfirmed
+        // + no outstanding tool/subagent — see `_awaitSettle`). JSONL
+        // is the SOLE source of reply text; capture-pane never delivers
+        // text.
+        //
+        // B10 is structurally gone here: `_awaitSettle` cannot emit a
+        // `quiesced` outcome while `outstandingSubagents` (or
+        // `outstandingTools`) is non-empty, so a subagent turn can NO
+        // LONGER reach this branch mid-flight — it settles via the
+        // JSONL `result` (or the W1 deadline) instead. The old nested
+        // re-wait + `subagent-wait` emit are therefore removed.
         this._sessionLogTail?.flushParser?.();
         if (turn.text) {
           resolvedVia = 'jsonl-streamed';
           text = turn.text;
         } else {
+          // No streamed text yet — the terminal JSONL `result` may be
+          // milliseconds behind the pane going idle. Wait a short grace
+          // for it (interrupt still wins, Bug 3).
           const lateGraceMs = this.lateGraceMs ?? 1500;
           let late = await Promise.race([
             turn.resultPromise.then((ev) => ({ kind: 'jsonl-late', ev })),
+            turn.interruptP.then(() => ({ kind: 'interrupt' })),
             new Promise((r) => setTimeout(() => r({ kind: 'no-jsonl' }), lateGraceMs)),
           ]);
-          // B10 (shumorobot Music topic, 2026-05-20): the main agent
-          // delegated to an `Agent` subagent within ~7 s, then the main
-          // pane went quiescent for MINUTES while the subagent ran in
-          // its own sidechain. capture-pane read that quiescence as
-          // "done"; the main agent had emitted only the `Agent` call so
-          // no JSONL reply text existed yet, and the §6 fail-loud below
-          // fired ~grace-window in — closing a turn that was genuinely
-          // in flight. A subagent is still running iff its `Agent`
-          // tool_use has no matching `tool-result` yet. While one is
-          // outstanding, capture-pane quiescence of the MAIN pane is
-          // meaningless — the turn completes only when the subagent
-          // returns and the main agent emits its real terminal reply.
-          // Wait for that JSONL `result`, bounded by the absolute turn
-          // deadline so a genuinely wedged turn still fails loud.
-          if (late.kind === 'no-jsonl' && turn.outstandingSubagents.size > 0) {
+          // B10 production race (shumorobot Music topic): the pane went
+          // idle BEFORE the `Agent` tool_use line was tailed, so the
+          // `_awaitSettle` B10 gate saw an empty outstanding set and let
+          // `quiesced` through. The `Agent` line then lands DURING this
+          // late grace, populating `outstandingSubagents`. The main
+          // pane stays quiescent for MINUTES while the subagent runs in
+          // its sidechain — that quiescence must NOT be read as "done."
+          // Wait for the real terminal JSONL `result`, bounded by the
+          // turn's remaining absolute budget (the `_awaitSettle` W1
+          // timer was cleared when `quiesced` won, so we re-arm a
+          // fresh remaining-budget timeout to the SAME wall-clock
+          // ceiling). Generalised to `outstandingTools` too — a long
+          // foreground tool (dl-batch) is the same shape.
+          if (late.kind === 'no-jsonl'
+            && (turn.outstandingSubagents.size > 0
+              || turn.outstandingTools.size > 0)) {
             this.emit('subagent-wait', {
               outstanding: turn.outstandingSubagents.size,
+              outstandingTools: turn.outstandingTools.size,
               turnId: turn.turnId,
             });
+            const remainingMs = Math.max(
+              0, (turn.startedAt + turnTimeoutMs) - this._now());
             late = await Promise.race([
               turn.resultPromise.then((ev) => ({ kind: 'jsonl-late', ev })),
-              turnDeadlineP,
               turn.interruptP.then(() => ({ kind: 'interrupt' })),
+              new Promise((_resolve, reject) => {
+                const t = setTimeout(() => reject(Object.assign(
+                  new Error('TmuxProcess: turn did not complete in time'),
+                  { code: 'TMUX_TURN_TIMEOUT', tmuxName: this.tmuxName },
+                )), remainingMs);
+                t.unref?.();
+              }),
             ]);
           }
           if (late.kind === 'interrupt') {
@@ -954,13 +944,12 @@ class TmuxProcess extends Process {
             stopReason = late.ev.stopReason || null;
             if (late.ev.sessionId) this.claudeSessionId = late.ev.sessionId;
           } else {
-            // §6: capture-pane judged the turn done, but JSONL
-            // produced NO reply text within the grace window. FAIL
-            // LOUD — never fall back to capture-pane diff text. That
-            // fallback WAS the echoed-input failure (the pane diff
-            // returned the user's own echoed prompt) and the
-            // banner-as-reply failure (L1). The error result clears
-            // the reactor explicitly instead of delivering garbage.
+            // §6: capture-pane judged the turn done, but JSONL produced
+            // NO reply text within the grace window. FAIL LOUD — never
+            // fall back to capture-pane diff text (that WAS the
+            // echoed-input failure and the banner-as-reply L1 failure).
+            // The error result clears the reactor explicitly instead of
+            // delivering garbage.
             throw Object.assign(
               new Error('turn produced no JSONL reply text within grace window'),
               { code: 'TMUX_NO_JSONL_TEXT' },
@@ -975,11 +964,10 @@ class TmuxProcess extends Process {
       const u = this._lastUsage;
       const cost = u ? computeCostUsd(u, u.model) : null;
       turn.state = 'done';
-      // Predicate (observer-only): terminal phase. The JSONL `result`
-      // event also drives this via `_evaluatePhaseFromSessionEvent`,
-      // but the capture-pane / interrupt / submit-fail branches do
-      // not; this ensures every successful exit lands the turn in
-      // `done` regardless of which racer won.
+      // Terminal phase. The JSONL `result` event also drives DONE via
+      // `_evaluatePhaseFromSessionEvent`, but the quiesced / interrupt
+      // outcomes do not; this ensures every successful exit lands the
+      // turn in `done` regardless of which settle outcome won.
       this._setPhase(
         turn,
         TurnPhase.DONE,
@@ -1020,6 +1008,103 @@ class TmuxProcess extends Process {
     }
   }
 
+  /**
+   * 0.10.0 Commit 3: settle a turn via a single subscription instead
+   * of the old 5-way `Promise.race` (+ its nested capture-then-rewait).
+   *
+   * Returns an `outcome` the caller maps to text/subtype/stopReason:
+   *   { kind: 'jsonl', ev }      — terminal JSONL `result` arrived
+   *                                (the authoritative happy path)
+   *   { kind: 'interrupt' }      — `interrupt()` fired (Bug 3)
+   *   { kind: 'submit-fail', err }—`_scheduleSubmitRetries` rejected
+   *                                TMUX_SUBMIT_FAILED (B7)
+   *   { kind: 'quiesced' }       — capture-pane idle AND the predicate
+   *                                says it is SAFE to conclude
+   *   { kind: 'timeout' }        — W1 absolute deadline
+   *
+   * The structural win over the old race:
+   *   - B7 gate: capture quiescence is ignored until
+   *     `turn.submitConfirmed` (a predicate field) — no more
+   *     `submitOkP = confirmP.then(() => new Promise(() => {}))`.
+   *   - B10 gate: capture quiescence is ignored while any tool OR
+   *     subagent is outstanding (`outstandingTools` /
+   *     `outstandingSubagents`) — a subagent turn can no longer reach
+   *     the `quiesced` outcome mid-flight, so the old nested re-wait +
+   *     `subagent-wait` emit are unnecessary. The turn settles via the
+   *     JSONL `result` (or W1) instead, which is exactly B10's intent.
+   *   - W1 is ONE `setTimeout`, not a racer.
+   *
+   * Capture-pane is still polled (heartbeat + approval-prompt
+   * detection live in `_awaitTurnComplete`); `signalAbort` releases
+   * the poll loop + PollScheduler refcount the instant the turn
+   * settles, exactly as the old `finally { signalAbort() }` did.
+   */
+  _awaitSettle(turn, { turnTimeoutMs, confirmP }) {
+    let signalAbort = null;
+    const abortP = new Promise((resolve) => { signalAbort = resolve; });
+    return new Promise((resolve) => {
+      let done = false;
+      let deadlineTimer = null;
+      const finish = (outcome) => {
+        if (done) return;
+        done = true;
+        if (deadlineTimer) clearTimeout(deadlineTimer);
+        // Release the capture-pane poll loop (and, with a shared
+        // PollScheduler, its refcount) even when a non-capture outcome
+        // won — mirrors the old `finally { signalAbort() }`.
+        signalAbort();
+        resolve(outcome);
+      };
+
+      // 1. Terminal JSONL `result` — settled by `_flushActiveGroup`
+      //    via `turn.settleResult`. The happy path.
+      turn.resultPromise.then((ev) => finish({ kind: 'jsonl', ev }));
+
+      // 2. Interrupt (`/stop` → C-c). Bug 3.
+      turn.interruptP.then(() => finish({ kind: 'interrupt' }));
+
+      // 3. Submit-confirm. On success the turn proceeds (no settle);
+      //    on TMUX_SUBMIT_FAILED fail the turn fast (B7).
+      confirmP.then(
+        () => { /* submitted ok — turn proceeds */ },
+        (err) => finish({ kind: 'submit-fail', err }),
+      );
+
+      // 4. Capture-pane quiescence, GATED by the predicate.
+      (async () => {
+        let buf;
+        try {
+          buf = await this._awaitTurnComplete({ timeoutMs: turnTimeoutMs, abortP });
+        } catch {
+          return;   // capture's own timeout — the W1 deadline (#5) settles
+        }
+        if (buf === ABORT_SENTINEL) return;   // released by another outcome
+        // B7 gate: a paste that never submitted leaves the pane idle
+        // because the prompt still sits in the input box — not because
+        // a turn finished. Ignore capture until the submit is
+        // confirmed. (A token-less turn — no confirm to wait on — is
+        // exempt: submitConfirmed stays false but there's nothing to
+        // gate.)
+        if (turn.token && !turn.submitConfirmed) return;
+        // B10 gate: a tool or subagent is in flight — the main pane is
+        // quiescent because the agent is WORKING, not done. Ignore
+        // capture; settle via JSONL `result` (or W1) when the work
+        // returns.
+        if (turn.outstandingTools.size > 0
+          || turn.outstandingSubagents.size > 0) return;
+        finish({ kind: 'quiesced' });
+      })();
+
+      // 5. W1 absolute deadline — one timer, not a racer. `unref` so
+      //    it never keeps the process alive on its own.
+      deadlineTimer = setTimeout(
+        () => finish({ kind: 'timeout' }),
+        turnTimeoutMs,
+      );
+      deadlineTimer.unref?.();
+    });
+  }
+
   /**
    * Retire a finished primary turn and drain the next queued one.
    */
@@ -1430,6 +1515,52 @@ class TmuxProcess extends Process {
     this._sessionLogPath = logPath;
   }
 
+  /**
+   * H1 hook tail — open a typed-event tail on the per-session ndjson
+   * that `polygram-hook-append.js` appends to, and forward normalized
+   * HookEvent objects to `_handleHookEvent`.
+   *
+   * Mirrors `_armSessionLogTail`: same LogTail watch/poll-fallback
+   * pattern, idempotent, swallows ENOENT (the file is touched at spawn
+   * time but a tail-before-write race is still possible). OBSERVER-
+   * ONLY — `_handleHookEvent` only persists events; no control flow
+   * consumes them in H1.
+   *
+   * See docs/0.10.0-tmux-hook-observability.md.
+   */
+  _armHookTail() {
+    if (this._hookTail) return; // idempotent
+    if (!this._hookNdjsonPath) {
+      this.logger.warn?.(`[${this.label}] _armHookTail: no ndjson path, skipping`);
+      return;
+    }
+    const tail = createHookTail({ path: this._hookNdjsonPath, logger: this.logger });
+    tail.on('event', (ev) => this._handleHookEvent(ev));
+    tail.on('error', (err) => {
+      this.logger.warn?.(`[${this.label}] hook-tail error: ${err.message}`);
+    });
+    tail.start();
+    this._hookTail = tail;
+  }
+
+  /**
+   * Observer-only hook-event handler. Persists each event for the
+   * H1 soak (so the trajectory can be inspected against real Music
+   * traffic) and emits a `hook-event` event so process-manager's
+   * `onHookEvent` callback writes it to the events DB.
+   *
+   * No `turn.*` field consumes hook signals in H1. The next phases
+   * (see hook-observability doc):
+   *   H2 — reactor wiring (kills the fear).
+   *   H3 — predicate progress + W1 retirement.
+   *   H4 — `Stop` as authoritative completion.
+   */
+  _handleHookEvent(ev) {
+    // Parse errors and unknown event shapes are intentionally
+    // forwarded — H1 measures how often they fire on real traffic.
+    this.emit('hook-event', ev);
+  }
+
   _handleSessionEvent(ev) {
     // Predicate (observer-only): snapshot the active group's turns
     // BEFORE the existing branches run. The `result` and `last-prompt`
@@ -2757,6 +2888,20 @@ class TmuxProcess extends Process {
       try { this._sessionLogTail.close(); } catch { /* swallow */ }
       this._sessionLogTail = null;
     }
+    // H1 — close hook tail + remove the per-session settings + ndjson.
+    // Files are best-effort unlinked (ENOENT fine if a sweeper or a
+    // crashed cleanup got there first).
+    if (this._hookTail) {
+      try { this._hookTail.close(); } catch { /* swallow */ }
+      this._hookTail = null;
+    }
+    if (this._hookSettingsPath || this._hookNdjsonPath) {
+      try {
+        removeHookFiles({ botName: this.botName, sessionId: this.claudeSessionId });
+      } catch { /* swallow */ }
+      this._hookSettingsPath = null;
+      this._hookNdjsonPath = null;
+    }
     await this.runner.killSession(this.tmuxName);
     // P1.3 close-event parity: emit integer code first (matches SDK
     // shape `0`/`1`). Optional second arg carries tmux-specific

package/lib/process-manager.js

@@ -88,6 +88,16 @@ const CALLBACK_TO_EVENT = {
   // consuming turn.phase for control flow. SDK backend never emits
   // this — predicate is tmux-specific.
   onPhaseChange:                'phase-change',
+  // 0.10.0 H1: tmux backend hook-based turn observability. TmuxProcess
+  // tails a per-session ndjson that claude appends to via
+  // `--settings`-injected command hooks (PreToolUse/PostToolUse/
+  // UserPromptSubmit/Stop/SubagentStop/Notification). Each event is
+  // forwarded here so polygram persists it as `hook-event` in the
+  // events DB for the H1 soak. OBSERVER-ONLY — no control flow
+  // consumes the events yet (mirrors Commit 1 of the patience-model
+  // unification). SDK backend never emits — hooks are tmux-specific.
+  // See docs/0.10.0-tmux-hook-observability.md.
+  onHookEvent:                  'hook-event',
 };
 
 class ProcessManager {

package/lib/sdk/callbacks.js

@@ -344,6 +344,54 @@ function createSdkCallbacks({
       }
     },
 
+    // 0.10.0 H1 (observer-only): tmux backend hook-based turn
+    // observability. TmuxProcess emits `hook-event` with normalized
+    // HookEvent records for every claude-CLI hook firing (PreToolUse,
+    // PostToolUse, UserPromptSubmit, Stop, SubagentStop, Notification,
+    // plus `unknown` for any schema drift). Persisted compact so the
+    // soak can characterize the stream's reliability against real
+    // Music traffic before H2/H3/H4 consume it.
+    //
+    // Fields persisted are intentionally narrow: identity + tool/
+    // subagent scoping + `duration_ms` (free per-tool latency from
+    // PostToolUse) + a `received_at_ms` so we can measure Pre→Post
+    // wall-clock independently of the CLI's own clock. Bulky payloads
+    // (`tool_input`, full `tool_response`, `last_assistant_message`)
+    // are NOT persisted to the events DB — they'd inflate row size
+    // without informing the soak.
+    onHookEvent: (sessionKey, payload /* , entry */) => {
+      try {
+        const detail = {
+          chat_id: getChatIdFromKey(sessionKey),
+          session_key: sessionKey,
+          backend: 'tmux',
+          hook_type:           payload?.type ?? null,
+          claude_session_id:   payload?.sessionId ?? null,
+          tool_name:           payload?.toolName ?? null,
+          tool_use_id:         payload?.toolUseId ?? null,
+          agent_id:            payload?.agentId ?? null,
+          agent_type:          payload?.agentType ?? null,
+          duration_ms:         payload?.durationMs ?? null,
+          stop_hook_active:    payload?.stopHookActive ?? null,
+          received_at_ms:      payload?.receivedAtMs ?? null,
+        };
+        // `parse-error` and `unknown` carry their raw body so soak
+        // analysis can decide whether they indicate transport
+        // corruption or schema drift. Truncate hard — these are
+        // expected to be rare.
+        if (payload?.type === 'parse-error' || payload?.type === 'unknown') {
+          let rawStr;
+          try { rawStr = JSON.stringify(payload.raw); }
+          catch { rawStr = String(payload.raw); }
+          detail.raw_truncated = (rawStr || '').slice(0, 512);
+          detail.parse_error = payload?.error ?? null;
+        }
+        logEvent('hook-event', detail);
+      } catch (err) {
+        logger.error?.(`[${botName}] hook-event handler: ${err.message}`);
+      }
+    },
+
     onInjectFail: (sessionKey, payload /* , entry */) => {
       try {
         const msgId = payload?.msgId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.10.0-rc.34",
+  "version": "0.10.0-rc.35",
   "description": "Telegram daemon for Claude Code that preserves the OpenClaw per-chat session model. Migration path for OpenClaw users moving to Claude Code.",
   "main": "lib/ipc/client.js",
   "bin": {