polygram 0.10.0-rc.5 → 0.10.0-rc.50

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.5",
+  "version": "0.10.0-rc.50",
   "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/config.example.json

@@ -98,7 +98,8 @@
       "cwd": "/Users/you/admin-agent",
       "requireMention": true,
       "isolateTopics": true,
-      "_comment_topics": "rc.48: each topic entry is EITHER a string (legacy: just a label) OR an object with optional fields {name, agent, cwd, model, effort, permissionMode}. Object form lets a topic override chat-level config. Per-topic permissionMode overrides chat-level — typical use: scope one topic to permissionMode:'default' (so settings.json gates apply) while the rest of the chat stays on bypassPermissions. Object form requires isolateTopics: true (each topic gets its own SDK Query); polygram emits a startup warning otherwise.",
+      "_comment_topics": "rc.48: each topic entry is EITHER a string (legacy: just a label) OR an object with optional fields {name, agent, cwd, model, effort, permissionMode, isolateUserConfig}. Object form lets a topic override chat-level config. Per-topic permissionMode overrides chat-level — typical use: scope one topic to permissionMode:'default' (so settings.json gates apply) while the rest of the chat stays on bypassPermissions. Object form requires isolateTopics: true (each topic gets its own SDK Query); polygram emits a startup warning otherwise.",
+      "_comment_isolateUserConfig": "0.10.0, tmux backend only: isolateUserConfig:true spawns the topic's claude TUI cut off from the user-level ~/.claude config — passes --strict-mcp-config (zero MCP servers load) and --setting-sources project,local (drops ~/.claude/settings.json; the spawn cwd's own .claude/settings.json still loads). Use it when a topic's agent would otherwise inherit slow user-global MCP servers whose cold-start (tens of seconds) wedges the TUI before it can accept a prompt. Settable at chat OR topic level (topic wins). Default false.",
       "topics": {
         "100": "Customer A",
         "200": {
@@ -107,7 +108,8 @@
           "cwd": "/Users/you/customer-b-projects",
           "model": "opus",
           "effort": "high",
-          "permissionMode": "default"
+          "permissionMode": "default",
+          "isolateUserConfig": true
         }
       }
     },

package/lib/autosteered-refs.js

@@ -46,12 +46,22 @@
  *   logged to opts.logger?.error — they never block clearing of
  *   subsequent refs.
  * @param {{ error?: (msg: string) => void }} [opts.logger]
+ * @param {number} [opts.minIntervalMs=250]
+ *   minimum gap (ms) between successive applyClear calls inside a
+ *   single clear() loop. Telegram's setMessageReaction rate limit
+ *   is ~5/sec/chat; 250ms (4/sec) stays under that. Pass 0 to
+ *   disable pacing in tests / contexts where the underlying applyClear
+ *   doesn't talk to a rate-limited API. Only the GAP between calls
+ *   is paced — the first call fires immediately, single-ref clears
+ *   incur no delay. L7 fix 2026-05-16: was unpaced, exceeded the
+ *   Telegram cap under N≥6 autosteers per turn.
  * @returns {AutosteeredRefs}
  */
-function createAutosteeredRefs({ applyClear, logger = console } = {}) {
+function createAutosteeredRefs({ applyClear, logger = console, minIntervalMs = 250 } = {}) {
   if (typeof applyClear !== 'function') {
     throw new TypeError('applyClear function required');
   }
+  const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
   /** @type {Map<string, MsgRef[]>} */
   const refs = new Map();
 
@@ -79,7 +89,15 @@ function createAutosteeredRefs({ applyClear, logger = console } = {}) {
     if (!list || list.length === 0) return 0;
     refs.delete(sessionKey);
     let cleared = 0;
-    for (const ref of list) {
+    // L7: pace inter-call gaps to stay under Telegram's
+    // setMessageReaction rate limit (~5/sec/chat). The first call
+    // fires immediately — pacing applies only to the gap BEFORE the
+    // 2nd+ call. minIntervalMs=0 disables pacing entirely.
+    for (let i = 0; i < list.length; i += 1) {
+      const ref = list[i];
+      if (i > 0 && minIntervalMs > 0) {
+        await sleep(minIntervalMs);
+      }
       try {
         await applyClear(ref);
         cleared += 1;

package/lib/claude-bin.js

@@ -0,0 +1,78 @@
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * Resolve + verify the pinned claude CLI binary for the tmux backend.
+ *
+ * Why this exists: the tmux backend reads claude CLI INTERNAL
+ * artefacts (JSONL events, queue-operation semantics, TUI banner
+ * ASCII, READY hint strings, stop_reason values) — none a stable
+ * public contract. polygram pins ONE version
+ * (CLAUDE_CLI_PINNED_VERSION in lib/process/tmux-process.js) and
+ * must spawn THAT binary, never whatever `claude` on $PATH happens
+ * to resolve to.
+ *
+ * Before this module the tmux runner spawned the bare string
+ * `claude`, resolved through $PATH. The claude CLI installs each
+ * version as a standalone binary at
+ *   ~/.local/share/claude/versions/<version>
+ * and points ~/.local/bin/claude (a symlink) at the active one.
+ * Its auto-updater re-points that symlink whenever a new version
+ * lands — so a $PATH spawn silently drifts (shumorobot 2026-05-16:
+ * CLI auto-updated 2.1.142 → 2.1.143 between deploys).
+ *
+ * Spawning the ABSOLUTE versioned path is immune to that: the
+ * updater only ADDS new version files, it never overwrites an
+ * existing one. `versions/2.1.142` stays byte-identical forever.
+ */
+
+/**
+ * Absolute path to the pinned claude binary.
+ *
+ * Resolution order:
+ *   1. POLYGRAM_CLAUDE_BIN env — explicit override (non-standard
+ *      installs, CI, hosts where the layout differs).
+ *   2. ~/.local/share/claude/versions/<version> — the standard
+ *      claude-CLI install location.
+ *
+ * The returned path is NOT guaranteed to exist — callers verify
+ * via verifyPinnedClaudeBin().
+ *
+ * @param {string} version — pinned version, e.g. '2.1.142'
+ * @returns {string} absolute path
+ */
+function resolvePinnedClaudeBin(version) {
+  const override = process.env.POLYGRAM_CLAUDE_BIN;
+  if (override) return override;
+  return path.join(os.homedir(), '.local', 'share', 'claude', 'versions', version);
+}
+
+/**
+ * Verify the pinned binary exists and is executable.
+ *
+ * @param {string} version — pinned version, e.g. '2.1.142'
+ * @returns {{ ok: boolean, path: string, reason?: string }}
+ *   ok=true → path is a spawnable binary.
+ *   ok=false → reason carries an operator-actionable message.
+ */
+function verifyPinnedClaudeBin(version) {
+  const binPath = resolvePinnedClaudeBin(version);
+  try {
+    fs.accessSync(binPath, fs.constants.X_OK);
+    return { ok: true, path: binPath };
+  } catch (err) {
+    const code = err && err.code ? err.code : (err && err.message) || 'unknown';
+    return {
+      ok: false,
+      path: binPath,
+      reason: `pinned claude CLI v${version} not found or not executable at `
+        + `${binPath} (${code}). Install it with \`claude install ${version}\` `
+        + 'or set POLYGRAM_CLAUDE_BIN to the correct binary path.',
+    };
+  }
+}
+
+module.exports = { resolvePinnedClaudeBin, verifyPinnedClaudeBin };

package/lib/db/sessions.js

@@ -95,4 +95,117 @@ function getClaudeSessionId(db, sessionKey) {
   return row?.claude_session_id || null;
 }
 
-module.exports = { migrateJsonToDb, getClaudeSessionId, countSessions };
+// ─── S2: session-config drift ────────────────────────────────────────
+//
+// A stored `sessions` row records the config the claude session was
+// SPAWNED under. Two of the recorded fields are spawn-identity:
+//   - agent — `--agent <name>` is baked into the spawned process;
+//     resuming a session spawned under agent X under agent Y forces
+//     claude to use Y's system prompt + tool whitelist against
+//     conversation history built under X's. Incoherent.
+//   - cwd — `--cwd <path>` (SDK) / tmux session cwd; claude resolves
+//     project-local config (.claude/settings.json, agent files,
+//     plugins) relative to it. Mid-conversation cwd drift means
+//     half the messages are answered with one project's allowlist
+//     and the other half with another's.
+//
+// pm_backend was REMOVED from spawn-identity (rc.32, 2026-05-21).
+// Both backends spawn the same pinned claude binary and write the
+// same on-disk JSONL (~/.claude/projects/<cwd-enc>/<sid>.jsonl) —
+// claude itself doesn't know or care which Node-side wrapper invoked
+// it. Treating a backend flip as drift was destructively dropping
+// context across the SDK→tmux migration window, costing every chat
+// its conversation history on its first turn under the new backend.
+// shumorobot 2026-05-20 18:51 incident: the Music topic flipped
+// tmux→sdk→tmux during runtime and lost its agent's prior context
+// at each flip. The orphan-tmux problem that the flip ALSO triggered
+// is solved by rc.31's spawn-time reconcile (TmuxProcess.start) —
+// independently, so a backend flip is now a no-op for session-state.
+//
+// shumorobot 2026-05-17 22:03, topic :3 (the original drift incident)
+// remains correctly handled: that row had agent+cwd drift in
+// addition to backend, so the agent+cwd drift alone still drops it.
+//
+// model + effort are deliberately EXCLUDED from the invalidating set.
+// They are NOT spawn-identity: a live `/model` or `/effort` change is
+// pushed into the running session by `pm.setModel` /
+// `pm.applyFlagSettings` with no respawn (lib/handlers/slash-commands.js,
+// lib/handlers/config-callback.js). Including them here would
+// destructively drop the whole session — discarding all context — on
+// every model switch, double-handling what the live-apply path
+// already covers cleanly. The stored model/effort columns are
+// informational, not identity.
+const SPAWN_IDENTITY_FIELDS = ['agent', 'cwd'];
+
+/**
+ * Decide whether a stored session can be resumed for the next spawn,
+ * or whether config drift means it must be dropped and re-spawned
+ * fresh.
+ *
+ * On drift the stale row is DELETED here — so the very next spawn
+ * mints a fresh claude_session_id under the correct config and the
+ * `onInit` callback re-upserts the row. This self-heals every
+ * pre-migration stale row across all chats with no manual SQL.
+ *
+ * @param {object|null} db          — DB handle (null → fresh spawn)
+ * @param {string} sessionKey
+ * @param {object} resolved         — freshly-resolved spawn config
+ * @param {string} [resolved.agent]
+ * @param {string} [resolved.cwd]
+ * @param {string} [resolved.backend] — 'sdk' | 'tmux' (resolved by
+ *   process/factory.js pickBackend); compared to the row's pm_backend
+ * @returns {{ existingSessionId: string|null, drift: object|null }}
+ *   existingSessionId — pass to start() for --resume, or null for a
+ *     fresh spawn (no stored row, or drift dropped it)
+ *   drift — null when no drift; otherwise { fields, before, after }
+ *     for the `session-config-drift` telemetry event
+ */
+function resolveSessionForSpawn(db, sessionKey, resolved = {}) {
+  if (!db) return { existingSessionId: null, drift: null };
+  const row = db.getSession(sessionKey);
+  if (!row || !row.claude_session_id) {
+    return { existingSessionId: null, drift: null };
+  }
+
+  // Normalise: a missing field on either side is treated as equal to
+  // a missing field on the other (both null/undefined → no drift).
+  const after = {
+    agent: resolved.agent || null,
+    cwd: resolved.cwd || null,
+    pm_backend: resolved.backend || null,
+  };
+  const before = {
+    agent: row.agent || null,
+    cwd: row.cwd || null,
+    pm_backend: row.pm_backend || null,
+  };
+  const drifted = SPAWN_IDENTITY_FIELDS.filter((f) => {
+    // If the resolved config does not specify a field, do not treat
+    // it as drift — we have nothing to compare against.
+    if (after[f] == null) return false;
+    return before[f] !== after[f];
+  });
+
+  if (drifted.length === 0) {
+    return { existingSessionId: row.claude_session_id, drift: null };
+  }
+
+  // Drift: drop the stale row so the next spawn is fresh + correct.
+  db.clearSessionId(sessionKey);
+  return {
+    existingSessionId: null,
+    drift: {
+      fields: drifted,
+      before: { ...before, claude_session_id: row.claude_session_id },
+      after,
+    },
+  };
+}
+
+module.exports = {
+  migrateJsonToDb,
+  getClaudeSessionId,
+  resolveSessionForSpawn,
+  countSessions,
+  SPAWN_IDENTITY_FIELDS,
+};

package/lib/error/classify.js

@@ -74,6 +74,31 @@ const PATTERNS = {
   // image-failure verb co-located with "image" or "photo".
   imageProcess:     /(could not process|cannot process|failed to (process|load|decode)|unsupported|invalid|corrupt(?:ed)?)[^\n]{0,80}\b(image|photo)\b|\b(image|photo)\b[^\n]{0,80}(could not process|failed to (process|load|decode)|is (invalid|corrupted|unsupported))/i,
 
+  // rc.50: lib/process-manager.js `_awaitLruSlot` rejects when no
+  // backend slot is available within `lruWaitMs` (default 5 min).
+  // Symptom of an upstream wedge (an inFlight tmux process can't be
+  // LRU-evicted; if its turn is wedged the slot stays held for the
+  // whole idle-ceiling). Production 2026-05-24 (shumorobot Music):
+  // hit twice during the wedged-"yes" turn that took 30 min to
+  // surface. Pre-rc.50 the user got `Hit a snag: lru wait timed
+  // out after 300000ms` which is opaque; now they get a hint that
+  // it's a busy/queued condition and a retry will probably work.
+  // Placed BEFORE the generic `timeout` pattern so the LRU phrasing
+  // wins over the broader timeout match.
+  lruWaitTimeout:   /lru wait timed out/i,
+
+  // rc.47: tmux backend's TMUX_TURN_TIMEOUT after H3 idle-ceiling fired.
+  // Production wedge 2026-05-24 msg 1020: a Bash tool's `PreToolUse`
+  // fired but `PostToolUse` never came — claude waited forever for the
+  // tool result, polygram waited 30 min then killed the turn, and the
+  // user got the generic `Hit a snag: turn did not complete in time`
+  // (the fall-through "unknown" path). This kind matches the enriched
+  // error message that `_runTurn` now throws (with the wedged-tool
+  // name + outstanding count in parens) AND the bare pre-rc.47 form
+  // for backwards compatibility. Placed BEFORE the generic `timeout`
+  // pattern so the more-specific TmuxProcess message wins.
+  tmuxToolWedge:    /TmuxProcess: turn did not complete in time/i,
+
   // Idle/wall-clock timeout from polygram's pm timers, OR
   // model-side timeout. Mapped to a single class; user message is
   // identical either way.
@@ -102,6 +127,8 @@ const USER_MESSAGES = {
   roleOrdering:     '⚠️ Conversation got into a tangled state. Try /new.',
   missingToolInput: '⚠️ Session history looks corrupted. Try /new.',
   imageProcess:     '🖼 One of the images in this conversation can\'t be re-processed by Claude — likely an older one in the history. Starting a fresh session for this chat.',
+  tmuxToolWedge:    '🔧 A tool didn\'t return in time — I cut it off. Most often this is a Bash command waiting on something external (a server, a file lock, an interactive prompt). Try resending; if it happens again, break the task into smaller steps.',
+  lruWaitTimeout:   '⏳ Other chats are busy — couldn\'t free up a backend slot in time. Try resending in a moment; if it keeps happening, an operator may need to raise the warm-process cap.',
   timeout:          '⏳ I went quiet too long without finishing. Try resending or simplifying.',
   format:           '⚠️ Invalid request format. Try rephrasing or /new.',
   // Used both for in-flight retry attempts AND for the post-retry-failed

package/lib/handlers/abort.js

@@ -41,13 +41,37 @@ function createHandleAbort({
 
     const threadId = msg.message_thread_id?.toString();
     const sessionKey = getSessionKey(chatId, threadId, chatConfig);
-    const hadActive = pm.has(sessionKey) && !!pm.get(sessionKey)?.inFlight;
+    const proc = pm.has(sessionKey) ? pm.get(sessionKey) : null;
+    const hadActive = !!proc?.inFlight;
 
     // Mark BEFORE killing: the 'close' event fires almost immediately
     // after interrupt, and the surrounding handleMessage's catch
     // needs to see the flag to skip the generic error-reply.
     if (hadActive) markSessionAborted(sessionKey);
 
+    // Bug 1 (incident 2026-05-18): "Stop" was turn-scoped — it only
+    // looked at an in-flight TURN. But the agent can leave a DETACHED
+    // background shell running (a `run_in_background:true` Bash) that
+    // outlives the turn; the tmux TUI shows an `N shell` indicator.
+    // When there is no live turn, check for such a shell and stop it
+    // so "Stop" acts truthfully instead of replying "Nothing to stop"
+    // while work is still churning. tmux-only — the SDK Process has no
+    // hasBackgroundShell()/killBackgroundShells(); the typeof guards
+    // make this a no-op there.
+    let killedBackgroundShell = false;
+    if (!hadActive && proc
+      && typeof proc.hasBackgroundShell === 'function'
+      && typeof proc.killBackgroundShells === 'function') {
+      try {
+        if (await proc.hasBackgroundShell()) {
+          markSessionAborted(sessionKey);
+          killedBackgroundShell = await proc.killBackgroundShells();
+        }
+      } catch (err) {
+        logger.error?.(`[${botName}] background-shell stop failed: ${err.message}`);
+      }
+    }
+
     // SDK abort: interrupt() + drainQueue(). interrupt() cancels
     // the in-flight turn at SDK level WITHOUT tearing down the
     // Query (cheap to reuse for the user's next message);
@@ -62,6 +86,7 @@ function createHandleAbort({
     logEvent('abort-requested', {
       chat_id: chatId, user_id: msg.from?.id || null,
       had_active: hadActive,
+      killed_background_shell: killedBackgroundShell,
       trigger: cleanText.slice(0, 40),
     });
 
@@ -69,10 +94,23 @@ function createHandleAbort({
     // detection is crude but reliable for ru/en.
     const lang = /[а-яё]/i.test(cleanText) ? 'ru' : 'en';
     const strs = {
-      en: { stopped: 'Stopped.',     nothing: 'Nothing to stop.' },
-      ru: { stopped: 'Остановлено.', nothing: 'Нечего останавливать.' },
+      en: {
+        stopped: 'Stopped.',
+        bgStopped: 'Stopped the background task.',
+        nothing: 'Nothing to stop.',
+      },
+      ru: {
+        stopped: 'Остановлено.',
+        bgStopped: 'Фоновая задача остановлена.',
+        nothing: 'Нечего останавливать.',
+      },
     }[lang];
-    const reply = hadActive ? strs.stopped : strs.nothing;
+    // Truthful ack: a stopped in-flight turn → "Stopped"; a stopped
+    // background shell → "Stopped the background task"; neither →
+    // "Nothing to stop".
+    const reply = hadActive ? strs.stopped
+      : killedBackgroundShell ? strs.bgStopped
+      : strs.nothing;
     try {
       await tg(bot, 'sendMessage', {
         chat_id: chatId, text: reply,

package/lib/handlers/autosteer.js

@@ -69,9 +69,15 @@ function createAutosteerHandlers({
     if (!entry?.inFlight) return { autosteered: false };
 
     const priority = priorityFor(chatConfig, config);
+    // rc.7: pass the autosteered msg_id through to the backend so the
+    // tmux backend can route an extra-turn reply back to Telegram if
+    // the TUI dequeues the paste as a fresh user turn (NEW-TURN path).
+    // SDK backend ignores msgId — its PostToolBatch fold path
+    // guarantees one combined reply via the primary pm.send.
     const ok = pm.injectUserMessage(sessionKey, {
       content: prompt,
       priority,
+      msgId: msg.message_id,
     });
     if (!ok) return { autosteered: false };
 

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

@@ -0,0 +1,155 @@
+/**
+ * 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), wire the hook parser, and return
+ * it. Caller calls `.start()` and `.on('event', ...)`.
+ *
+ * `skipExisting`:
+ *   - false (default) for a FRESH spawn — the ndjson was just
+ *     touched at start time and is empty, so any future write IS a
+ *     new event.
+ *   - true for a `--resume` spawn — `writeHookFiles` uses 'a' mode
+ *     (append) and never truncates, so the prior session's hook
+ *     events are still on disk. Without skipExisting they replay
+ *     into the fresh process, arming a Stop synth against the
+ *     fresh turn (H4) and heartbeating it (H3) from stale events.
+ *     rc.42 #5 (review-driven): mirror what `_armSessionLogTail`
+ *     already does for the JSONL tail.
+ */
+function createHookTail({ path: filePath, skipExisting = false, logger = console } = {}) {
+  const tail = new LogTail({
+    path: filePath,
+    intervalMs: 50,
+    skipExisting,
+    useWatch: 'auto',
+    logger,
+  });
+  return pipeHookParser(tail);
+}
+
+module.exports = {
+  KNOWN_EVENT_NAMES,
+  normalizeHookEvent,
+  pipeHookParser,
+  createHookTail,
+};