@shumkov/orchestra 0.2.0

package/lib/process/factory.js

@@ -0,0 +1,236 @@
+// provenance: polygram@0.17.11 lib/process/factory.js (git 746bca6) — adapt: env prefix WATER_, bridge name water-bridge, vendor path (SHARED-LIB.md).
+/**
+ * Process factory — chooses + constructs the right Process subclass
+ * per session, based on chat / topic / bot config.
+ *
+ * Backends (post-0.12):
+ *   - 'sdk' → SdkProcess (long-lived SDK Query, per-token API billing)
+ *   - 'cli' → CliProcess (claude TUI in tmux + Channels MCP bridge + hooks ndjson,
+ *                          subscription billing; default production path)
+ *
+ * Config aliases (back-compat for existing chat configs):
+ *   - 'channels' → 'cli' (0.11.0-channels driver folded into CliProcess)
+ *   - 'tmux'     → 'cli' (0.10.0 tmux backend deleted in 0.12 Phase 4;
+ *                          existing configs keep working via this alias)
+ *
+ * Backend selection precedence:
+ *   topicConfig.pm > chatConfig.pm > config.bot.pm > 'sdk'
+ *
+ * Per-backend wiring requirements:
+ *   cli — tmuxRunner + botName + toolDispatcher + claudeBin
+ *
+ * If a backend is configured but its wiring is missing, we log a loud
+ * warning and fall back to SDK so the daemon stays up (R2-F7 — never
+ * silent-fail config).
+ *
+ * @see docs/0.10.0-process-manager-abstraction-plan.md §6.4
+ * @see docs/0.11.0-channels-driver-plan.md
+ * @see docs/0.12.0-cli-driver-plan.md
+ */
+
+'use strict';
+
+// orchestra ships BOTH Claude-session backends. The SDK backend lives in
+// ./sdk-process; @anthropic-ai/claude-agent-sdk is an OPTIONAL dependency that
+// sdk-process lazy-requires only when a pm:'sdk' session actually starts — so
+// requiring this factory (or the whole package) never loads the SDK, and cli-only
+// consumers (water) can install with --omit=optional. A consumer may still inject a
+// custom SdkProcess via createProcessFactory({ SdkProcess }); the default is ours.
+const { SdkProcess: DefaultSdkProcess } = require('./sdk-process');
+const { CliProcess } = require('./cli-process');
+
+// Aliases — config values that map to a different canonical backend.
+// Each alias emits ONE deprecation warn per-bot-process lifetime
+// (tracked in `_warnedAliases` below). Avoids per-spawn log flooding
+// on multi-chat deploys.
+const ALIASES = new Map([
+  ['channels', 'cli'],
+  ['tmux',     'cli'],   // 0.12 Phase 4: tmux backend deleted; existing configs alias to cli
+]);
+
+const _warnedAliases = new Set();
+function _maybeWarnAlias(alias, canonical, logger) {
+  if (_warnedAliases.has(alias)) return;
+  _warnedAliases.add(alias);
+  logger.warn?.(
+    `[factory] pm:'${alias}' is deprecated and now aliases to pm:'${canonical}'. ` +
+    `Update chat config to silence this warning. ` +
+    `See docs/0.12.0-cli-driver-plan.md §"Open questions resolved here" / Q5.`,
+  );
+}
+
+// 0.12 Phase 4.5.3 (R12 mitigation): chats migrating from pm:'tmux' (the
+// 0.10 backend with implicit pane-scrape approval gating) to pm:'cli'
+// silently lose approvals unless the operator explicitly sets
+// permissionMode. Warn ONCE per (botName, chatId, threadId) tuple so
+// the migration trade-off is deliberate, not a surprise regression.
+// Fires at pickBackend time (factory.js is the choke point for backend
+// resolution).
+const _warnedR12Chats = new Set();
+function _maybeWarnR12Migration({ rawPm, canonical, chatId, threadId, chatCfg, topicCfg, logger }) {
+  if (rawPm !== 'tmux' || canonical !== 'cli') return;
+  // Resolved permissionMode honors the same precedence cli-process.js
+  // uses: topic > chat > opt-default. Check both topic and chat config
+  // here; we don't know opt-default (set inside CliProcess.start), but
+  // its default is 'bypassPermissions' so absence = bypass.
+  const explicitMode = topicCfg?.permissionMode || chatCfg?.permissionMode;
+  if (explicitMode && explicitMode !== 'bypassPermissions') return;
+  const key = `${chatId}:${threadId ?? ''}`;
+  if (_warnedR12Chats.has(key)) return;
+  _warnedR12Chats.add(key);
+  logger.warn?.(
+    `[factory] R12 migration warning: chat=${chatId}${threadId ? ` thread=${threadId}` : ''} ` +
+    `was configured as pm:'tmux' and now aliases to pm:'cli'. The 0.10 tmux backend gated ` +
+    `Bash/Edit/etc tool calls via pane-scrape approval cards; the 0.12 CliProcess defaults to ` +
+    `permissionMode:'bypassPermissions' (no approvals). To preserve approval gating on this ` +
+    `chat, set permissionMode: 'default' (or 'acceptEdits' / 'plan') in chat or topic config. ` +
+    `See docs/0.12.0-cli-driver-plan.md §"Security posture" + R12.`,
+  );
+}
+
+/**
+ * @param {object} opts
+ * @param {object} opts.config            — runtime config object
+ * @param {Function} opts.spawnFn          — buildSdkOptions (SDK backend only)
+ * @param {object} [opts.db]               — for SdkProcess._logEvent + clearSessionId
+ * @param {object} [opts.logger]
+ * @param {number} [opts.queueCap]
+ * @param {number} [opts.queryCloseTimeoutMs]
+ * @param {object} [opts.tmuxRunner]       — required when ANY chat routes to 'cli'
+ * @param {string} [opts.botName]          — required when ANY chat routes to 'cli'
+ * @param {Function} [opts.toolDispatcher] — required when ANY chat routes to 'cli'.
+ *   async ({sessionKey, chatId, threadId, toolName, text, files}) => {ok, error?}.
+ *   Called when Claude's reply (or react/edit_message) tool fires inside a
+ *   CliProcess. Polygram supplies the actual Telegram-send wiring.
+ * @param {string} [opts.channelsClaudeBin] — absolute path to pinned claude binary;
+ *   required when ANY chat routes to 'cli'. (Name kept for back-compat with
+ *   existing wiring; can be renamed to `claudeBin` in a future refactor.)
+ * @returns {Function} processFactory(sessionKey, ctx) → Process
+ */
+function createProcessFactory({
+  config,
+  spawnFn,
+  db = null,
+  logger = console,
+  queueCap,
+  queryCloseTimeoutMs,
+  tmuxRunner = null,
+  botName = null,
+  toolDispatcher = null,
+  channelsClaudeBin = null,
+  displayHint = '',                             // orchestra: consumer surface-rendering hint
+  maxOutboundFileBytes = 100 * 1024 * 1024,     // orchestra: consumer outbound file cap
+  // orchestra identity — forwarded to every CliProcess so the engine is neutral.
+  sessionPrefix = 'orchestra',
+  bridgeServerName = 'orchestra-bridge',
+  appDataDir,
+  attachmentBase,
+  productName = 'orchestra',
+  surfaceName = 'the chat',
+  pmDefault = 'cli',                            // default backend when a chat has no pm
+  SdkProcess = DefaultSdkProcess,               // orchestra ships this; consumer may override
+} = {}) {
+  // spawnFn (buildSdkOptions) is only used by the deferred SDK backend; water v1 is
+  // cli-only, so it is optional here (a missing SDK wiring surfaces as the SdkProcess
+  // constructor's clear "not available" error, not a factory-construction failure).
+
+  return function processFactory(sessionKey, ctx) {
+    const chatId = ctx?.chatId ?? null;
+    const threadId = ctx?.threadId ?? null;
+    const label = ctx?.label || sessionKey;
+
+    const choice = pickBackend({ config, chatId, threadId, logger, pmDefault });
+
+    if (choice === 'cli') {
+      const missing = [];
+      if (!tmuxRunner) missing.push('tmuxRunner');
+      if (!botName) missing.push('botName');
+      if (typeof toolDispatcher !== 'function') missing.push('toolDispatcher');
+      if (!channelsClaudeBin) missing.push('channelsClaudeBin');
+      if (missing.length) {
+        logger.warn?.(
+          `[${label}] config requests pm:'cli' but ${missing.join(', ')} not wired; ` +
+          `falling back to SdkProcess. Pass these to createProcessFactory.`,
+        );
+      } else {
+        return new CliProcess({
+          sessionKey, chatId, threadId, label,
+          tmuxRunner,
+          botName,
+          claudeBin: channelsClaudeBin,
+          toolDispatcher,
+          displayHint,
+          maxOutboundFileBytes,
+          sessionPrefix, bridgeServerName, appDataDir, attachmentBase, productName, surfaceName,
+          logger,
+          db,                  // Parity P1: telemetry parity with sdk/tmux
+        });
+      }
+    }
+
+    return new SdkProcess({
+      sessionKey, chatId, threadId, label,
+      spawnFn,
+      db,
+      logger,
+      queueCap,
+      queryCloseTimeoutMs,
+    });
+  };
+}
+
+/**
+ * Per-chat / per-topic backend choice.
+ *
+ * Honors topicConfig.pm / chatConfig.pm / config.bot.pm. Resolves aliases
+ * (e.g., 'channels' → 'cli') and emits a once-per-process deprecation warn.
+ *
+ * Review AC3: unknown `pm` values (typos like `'channel'` singular) used to
+ * silently fall through to 'sdk' with no warning — violates R2-F7 "never
+ * silent-fail config". Now logs a warn and falls back to the default.
+ */
+const CANONICAL_BACKENDS = new Set(['sdk', 'cli']);
+
+function pickBackend({ config, chatId, threadId, logger = console, pmDefault = 'cli' } = {}) {
+  if (!chatId) return pmDefault;
+  const chatCfg = config?.chats?.[chatId];
+  const topicCfg = threadId && chatCfg?.topics?.[threadId];
+  const raw = topicCfg?.pm || chatCfg?.pm || config?.bot?.pm || pmDefault;
+
+  // Resolve alias (e.g., 'channels' → 'cli'). Warns once per process per
+  // alias kind, NOT per spawn — multi-chat deploys shouldn't flood logs.
+  let picked = raw;
+  if (ALIASES.has(raw)) {
+    picked = ALIASES.get(raw);
+    _maybeWarnAlias(raw, picked, logger);
+    // R12 — per-chat migration warning when pm:'tmux' aliases to 'cli'
+    // without an explicit non-bypass permissionMode override.
+    _maybeWarnR12Migration({
+      rawPm: raw,
+      canonical: picked,
+      chatId, threadId,
+      chatCfg, topicCfg,
+      logger,
+    });
+  }
+
+  if (!CANONICAL_BACKENDS.has(picked)) {
+    logger.warn?.(
+      `[factory] unknown pm value '${raw}' for chat=${chatId} thread=${threadId ?? ''}; ` +
+      `falling back to 'sdk'. Valid: ${[...CANONICAL_BACKENDS].join(', ')} ` +
+      `(aliases: ${[...ALIASES.keys()].join(', ')}).`,
+    );
+    return 'sdk';
+  }
+  return picked;
+}
+
+// _resetAliasWarnings — test-only helper. Resets the once-per-process warn
+// tracking so unit tests can verify alias-warn + R12-migration-warn behavior
+// across multiple pickBackend() invocations within a single test run.
+function _resetAliasWarnings() {
+  _warnedAliases.clear();
+  _warnedR12Chats.clear();
+}
+
+module.exports = { createProcessFactory, pickBackend, _resetAliasWarnings, ALIASES, CANONICAL_BACKENDS };

package/lib/process/hook-append.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// provenance: polygram@0.17.11 lib/process/polygram-hook-append.js (git 746bca6) — verbatim*: env prefix WATER_, bridge name water-bridge, vendor path (SHARED-LIB.md).
+/**
+ * water-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>/water-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('water-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(`water-hook-append: write failed: ${err.message}\n`);
+    process.exitCode = 3;
+  } finally {
+    if (fd != null) {
+      try { fs.closeSync(fd); } catch { /* swallow */ }
+    }
+  }
+});

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

@@ -0,0 +1,163 @@
+// provenance: polygram@0.17.11 lib/process/hook-event-tail.js (git 746bca6) — verbatim: env prefix WATER_, bridge name water-bridge, vendor path (SHARED-LIB.md).
+/**
+ * hook-event-tail — typed-event parser around the per-session hook
+ * ndjson that `water-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',
+  // 0.12.0-rc.13: compaction lifecycle (carry `trigger` + custom_instructions).
+  'PreCompact',
+  'PostCompact',
+]);
+
+/**
+ * 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,
+    // PreCompact/PostCompact payload: trigger distinguishes auto vs manual
+    // compaction; custom_instructions is the `/compact <hint>` text (manual).
+    trigger:             raw?.trigger ?? null,
+    customInstructions:  raw?.custom_instructions ?? 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 claude-session-jsonl.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,
+};

package/lib/process/hook-settings.js

@@ -0,0 +1,182 @@
+// provenance: polygram@0.17.11 lib/process/hook-settings.js (git 746bca6) — verbatim*: env prefix WATER_, bridge name water-bridge, vendor path (SHARED-LIB.md).
+/**
+ * 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 `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:
+ *   ~/.water/<bot>/hooks/<sid>.settings.json   (this file's output)
+ *   ~/.water/<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, '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',
+  // 0.12.0-rc.13: compaction lifecycle. PreCompact fires when claude is about
+  // to (auto-)compact — the moment that detaches the channels MCP bridge.
+  // PostCompact fires after, when context has dropped (used to re-arm the
+  // per-chat compaction warning). Both confirmed supported by the pinned CLI
+  // (2.1.142) and carry a `trigger: auto|manual` field.
+  'PreCompact',
+  'PostCompact',
+];
+
+/**
+ * Per-bot hooks dir (parent of both settings + ndjson files).
+ * Mirrors `lib/tmux/tmux-runner.js#debugLogPath`'s `~/.water/<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, '.orchestra', 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 hook-append.js
+ *                                    (defaults to the one shipped with polygram)
+ */
+// 0.12 SEC-03: shell-quote helper + ndjson paths in the command string.
+// claude's hook runner shells out via execvp on a parsed argv. If either
+// path contains characters the shell tokenizer would split on (most
+// commonly: spaces in HOME like `/Users/Ivan Shumkov/...`), the helper
+// receives the wrong argv and exits with code 2 ("missing ndjson path").
+// Silent-drop of all hook events on bots whose HOME has a space.
+//
+// Single-quote escaping rule: replace any literal `'` with `'\''` (close
+// quote, escaped quote, re-open quote), then wrap the whole thing in
+// single quotes. POSIX-shell safe; no special chars inside single quotes
+// except `'` itself.
+function _shqSingle(s) {
+  return `'${String(s).replace(/'/g, `'\\''`)}'`;
+}
+
+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 ${_shqSingle(helperPath)} ${_shqSingle(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 });
+
+  // 0.12 SEC-04: write both files with mode 0o600. The ndjson stream
+  // carries every tool_input (file paths, Bash commands, write content,
+  // partial outputs) — load-bearing observability in CliProcess, NOT the
+  // tmux-backend observe-only surface this code was originally built for.
+  // umask 022 default leaves the files world-readable; mirror the existing
+  // 0o600 pattern from cli-process.js mcp-config writes.
+  fsImpl.writeFileSync(settingsPath, JSON.stringify(settings), { mode: 0o600 });
+  // Touch the ndjson so fs.watch attaches before the first hook fires.
+  // Use openSync with mode 0o600 so a brand-new file is created restricted
+  // from birth; if the file already exists (re-spawn case) the mode flag
+  // is silently ignored, which is fine because writeHookFiles' caller
+  // (CliProcess._spawnTmuxClaude) controls the parent dir's lifecycle.
+  const fd = fsImpl.openSync(ndjsonPath, 'a', 0o600);
+  fsImpl.closeSync(fd);
+  // Defensive re-chmod on both — in case umask interfered with the mode
+  // arg above. Same belt-and-suspenders pattern as cli-process.js:404-406.
+  try { fsImpl.chmodSync(settingsPath, 0o600); } catch {}
+  try { fsImpl.chmodSync(ndjsonPath, 0o600); } catch {}
+  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,
+};