session-orchestrator 3.16.0 → 3.19.0

package/hooks/pre-bash-templates-first.mjs

@@ -22,8 +22,8 @@
  *   G7 transcript inspection via hooks/_lib/transcript-history.mjs.
  *      If any prior Read tool call matches one of the host-specific template
  *      paths from the policy, exit 0.
- *   G8 fall-through: emit deny via stdout JSON + structured stderr listing the
- *      template paths, and exit 2.
+ *   G8 fall-through: emit the PreToolUse deny envelope on stdout via emitDeny
+ *      (exit 0) with the template-path list + ack hint inside the reason.
  *
  * Fail-safe posture: any internal exception is swallowed in main().catch and
  * the hook exits 0 (allow). Rationale matches pre-bash-destructive-guard.mjs:
@@ -31,14 +31,17 @@
  * worst case is a missed enforcement, not a wedged session.
  *
  * Exit codes:
- *   0  — pass-through (G1-G3 short-circuits, bypass match, acknowledgement, Read found, error)
- *   2  — deny + structured JSON on stdout (PRD § 3 Gherkin Pattern 3)
+ *   0  — every path. Pass-through (G1-G3 short-circuits, bypass match,
+ *        acknowledgement, Read found, error) emits nothing; G8 emits the deny
+ *        envelope on stdout. Exit 2 is NEVER used: Claude Code discards stdout
+ *        on exit 2, which would throw away the deny envelope entirely (#906).
  */
 
-import { readStdin, emitAllow } from '../scripts/lib/io.mjs';
+import { readStdin, emitAllow, emitDeny } from '../scripts/lib/io.mjs';
 import { resolveProjectDir, resolvePluginRoot } from '../scripts/lib/platform.mjs';
 import { readJson } from '../scripts/lib/common.mjs';
 import { hasReadInSession } from './_lib/transcript-history.mjs';
+import { resolveHost, matchesBypass } from './_lib/vcs-create-matcher.mjs';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
 import { existsSync, readdirSync, lstatSync } from 'node:fs';
@@ -54,13 +57,11 @@ if (!shouldRunHook('pre-bash-templates-first')) process.exit(0);
 // ---------------------------------------------------------------------------
 
 /**
- * Matches the canonical `gh` / `glab` issue/PR/MR creation invocations.
- * Anchored at start (^) with optional leading whitespace to catch indented
- * shell snippets. Word-boundary at the end avoids false positives on tokens
- * like `created` or `news`. Edit operations (`gh pr edit`, `glab mr edit`)
- * are deliberately out of scope per PRD § 2 Out-of-Scope.
+ * The `gh`/`glab` create matcher (`CREATE_REGEX`, `resolveHost`,
+ * `matchesBypass`) now lives in `hooks/_lib/vcs-create-matcher.mjs` so the
+ * sibling issue-budget hook parses create commands with byte-identical
+ * semantics instead of a diverging copy. Behaviour here is unchanged.
  */
-const CREATE_REGEX = /^\s*(gh|glab)\s+(pr|mr|issue)\s+(create|new)\b/;
 
 /**
  * Default acknowledgement path, relative to project root. Used when the
@@ -68,14 +69,91 @@ const CREATE_REGEX = /^\s*(gh|glab)\s+(pr|mr|issue)\s+(create|new)\b/;
  */
 const DEFAULT_ACK_PATH = '.orchestrator/runtime/templates-acknowledged.json';
 
+/**
+ * Ceiling (in characters) for the raw bash command echoed into the deny reason.
+ *
+ * ## Why this file needs its own bound at all (#919, follow-up to #906)
+ *
+ * `command` is the ONE attacker/agent-controlled term in the reason — every
+ * other line is fixed text or a repo-derived path list. Echoing it unbounded
+ * made this hook the shortest path to the failure mode #906 was repaired for:
+ * a reason large enough to push the stdout envelope past the 65 536-byte kernel
+ * pipe buffer, where a truncated envelope reads as "no decision" and the tool
+ * call is ALLOWED. `emitDeny`'s {@link DENY_REASON_MAX} clamp (16 000) now
+ * stands in that path, but a consumer that respects the bound itself is the
+ * more robust shape — defence in depth, not reliance on the single downstream
+ * clamp.
+ *
+ * The clamp alone is also NOT sufficient here, which is the concrete bug this
+ * constant fixes rather than merely hardens against. `Command:` is line 2 of 6;
+ * the template-path list and the `/templates-ack` hint are lines 3-6. A
+ * 200 000-char command therefore consumed the entire 16 000-char budget and cut
+ * the remedy off the end — the deny still bit, but PRD § 3 Gherkin Pattern 3's
+ * required content never reached the reader.
+ *
+ * ## Why 512 and not the 80 used at the two stderr sites below
+ *
+ * This file already truncates `command` twice (bypass-matched and
+ * no-templates-found), both at `slice(0, 80)`. Those are one-line **stderr log**
+ * lines, where 80 is the terminal-width convention — a different consumer class.
+ * The repo's precedent for bounding a bash command inside a **structured record
+ * field** is `hooks/pre-bash-staging-fence.mjs` (`staged_paths[].command`,
+ * `slice(0, 512)`), and `permissionDecisionReason` is exactly that: a structured
+ * field, not a log line. Reusing 512 follows the matching house convention
+ * instead of inventing a third number. Reusing 80 would clip a realistic
+ * `gh pr create --title … --body …` mid-flag, defeating the recognisability the
+ * line exists to provide.
+ *
+ * Bound check: the fixed part of this reason measures 348 chars (see the
+ * call-site table in `scripts/lib/io.mjs`), so the worst case is 348 + 512 +
+ * the path list — ~19× below `DENY_REASON_MAX` and ~76× below the pipe buffer.
+ * This hook no longer contributes an unbounded term to the envelope at all.
+ */
+const COMMAND_ECHO_MAX = 512;
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
 /**
- * Block the create command: write structured deny JSON to stdout + exit 2.
- * Mirrors the exact format from pre-bash-destructive-guard.mjs blockCommand()
- * so downstream Claude Code rendering is consistent.
+ * Clip the echoed command to {@link COMMAND_ECHO_MAX}, marking the cut so the
+ * reader can tell the command was truncated rather than ending there.
+ *
+ * The marker is budgeted INSIDE the ceiling — mirroring `_clampReason` in
+ * `scripts/lib/io.mjs` — so the returned string never exceeds it and the
+ * worst-case reason length stays a fixed, auditable number.
+ *
+ * @param {string} command
+ * @returns {string}
+ */
+function clipCommand(command) {
+  if (command.length <= COMMAND_ECHO_MAX) return command;
+  const marker = `… [truncated: showing ${COMMAND_ECHO_MAX} of ${command.length} characters]`;
+  return command.slice(0, COMMAND_ECHO_MAX - marker.length) + marker;
+}
+
+/**
+ * Block the create command: emit the PreToolUse deny envelope via emitDeny
+ * (exit 0). Mirrors pre-bash-destructive-guard.mjs blockCommand() so downstream
+ * Claude Code rendering is consistent.
+ *
+ * PRD § 3 Gherkin Pattern 3 requires the template-path list plus the
+ * `/templates-ack` hint to reach the reader. That requirement is UNCHANGED —
+ * only the channel moved (#906). Until #906 this text was written to stderr AND
+ * duplicated into an `exit 2` stdout envelope, the mixed form the hook docs
+ * forbid ("choose one approach per hook, not both"). Under exit 0, stderr is
+ * only surfaced in the debug log — invisible to both operator and model — so a
+ * stderr write would look alive while being dead. The full multi-line text
+ * therefore travels as the emitDeny `reason`, landing in
+ * `permissionDecisionReason`, which is fed to **Claude** — the actor that has
+ * to read the template or run `/templates-ack`. The operator sees the first
+ * line via the derived `systemMessage` headline.
+ *
+ * The echoed `command` is bounded by {@link COMMAND_ECHO_MAX} before it enters
+ * the reason: it is the only agent-controlled term here, and left unbounded it
+ * both risked the pipe-buffer fail-open #906 repaired AND pushed the template
+ * list plus the ack hint past `emitDeny`'s clamp — i.e. truncated away exactly
+ * the content the PRD requires. See that constant for the full rationale.
  *
  * @param {{ host: string, command: string, templatePaths: string[],
  *           ackFile: string }} ctx
@@ -88,21 +166,16 @@ function blockCreate(ctx) {
     : '  (none configured)';
   const reason = [
     `pre-bash-templates-first: ${host} create call detected without prior template Read.`,
-    `Command: ${command}`,
+    `Command: ${clipCommand(command)}`,
     `Found templates:`,
     pathList,
     `Read one of these first, OR run \`/templates-ack\` (writes ${ackFile}) to bypass for this session.`,
     `See: issue #519, "gsd Pattern Adoption Quick-Wins" (archived in the private Meta-Vault) (Pattern 3)`,
   ].join('\n');
 
-  // PRD § 3 Gherkin Pattern 3 spec: stderr lists template paths + ack hint.
-  // We emit BOTH stderr (human-readable per spec) AND the structured stdout
-  // JSON envelope (machine-readable for Claude Code hook protocol).
-  process.stderr.write(reason + '\n');
-  process.stdout.write(
-    JSON.stringify({ permissionDecision: 'deny', reason }) + '\n',
-  );
-  process.exit(2);
+  // Single channel: the full multi-line reason (template paths + ack hint)
+  // rides in permissionDecisionReason. Never returns.
+  emitDeny(reason);
 }
 
 /**
@@ -142,46 +215,6 @@ function resolvePolicyPath(projectDir) {
   return null;
 }
 
-/**
- * Determine which host the command targets by inspecting the CREATE_REGEX
- * capture. `gh` → "github", `glab` → "gitlab".
- *
- * @param {string} command
- * @returns {"github"|"gitlab"|null}
- */
-function resolveHost(command) {
-  const m = command.match(CREATE_REGEX);
-  if (!m) return null;
-  return m[1] === 'gh' ? 'github' : 'gitlab';
-}
-
-/**
- * True when the command starts with any of the bypass patterns. Bypass match
- * is a prefix check with a word/EOL boundary on the trailing edge — this
- * prevents trivial bypass via prefix-inclusion (e.g. policy entry
- * "gh issue create --label bot" must not match "gh issue create --label botanical").
- *
- * @param {string} command
- * @param {string[]} bypassPatterns
- * @returns {boolean}
- */
-function matchesBypass(command, bypassPatterns) {
-  if (!Array.isArray(bypassPatterns) || bypassPatterns.length === 0) {
-    return false;
-  }
-  const stripped = command.replace(/^\s+/, '');
-  for (const pat of bypassPatterns) {
-    if (typeof pat !== 'string' || pat.length === 0) continue;
-    const patStripped = pat.replace(/^\s+/, '');
-    if (!stripped.startsWith(patStripped)) continue;
-    // Boundary check: next character must be whitespace, EOL, or absent.
-    // This prevents "gh foo --label bot" from matching policy "gh foo --label botanical".
-    const nextChar = stripped.charAt(patStripped.length);
-    if (nextChar === '' || /\s/.test(nextChar)) return true;
-  }
-  return false;
-}
-
 /**
  * Check the acknowledgement file for the current session_id. Best-effort:
  * any read or parse error means "no acknowledgement" (returns false) so the

package/hooks/skill-invocation-telemetry.mjs

@@ -6,23 +6,35 @@
  * Fires when the Skill tool is invoked (a skill is selected). Writes a
  * selection record to `.orchestrator/metrics/skill-invocations.jsonl`.
  *
- * Decision flow:
+ * Decision flow (when run as the hook, not imported):
  *   1. shouldRunHook gate — exit 0 immediately when the hook is disabled.
  *   2. Read JSON payload from stdin: { tool_name, tool_input: { skill }, session_id }.
  *   3. Belt-and-suspenders guard: if tool_name !== "Skill", exit 0 immediately.
  *   4. Build a 'selected' record and call appendSkillInvocation().
- *   5. Output: nothing on stdout. Diagnostic errors to stderr only.
+ *   5. Daily-fallback telemetry flush check (Epic #841, #844) — non-blocking:
+ *      when a bounded offline queue has aged past 24h AND consent resolves to
+ *      send, spawn a detached child that runs `telemetry _flush`. Cheap by
+ *      construction (env kill-switch pre-check → queue+state stat → consent)
+ *      and never loads the roster on the hot hook path.
+ *   6. Output: nothing on stdout. Diagnostic errors to stderr only.
  *
  * Exit codes: 0 always (informational, never blocking).
+ *
+ * The module is import-safe: the self-execution block below is guarded so that a
+ * test can `import { maybeSpawnDailyFlush }` without triggering the hook's
+ * stdin-read + exit path.
  */
 
-import { shouldRunHook } from './_lib/profile-gate.mjs';
-// Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
-if (!shouldRunHook('skill-invocation-telemetry')) process.exit(0);
-
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+
+import { shouldRunHook } from './_lib/profile-gate.mjs';
 import { appendSkillInvocation } from '../scripts/lib/skill-invocations-schema.mjs';
 import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
+import { shouldDailyFlush } from '../scripts/lib/telemetry/sync.mjs';
+import { resolveConsent, readTelemetryState } from '../scripts/lib/telemetry/consent.mjs';
+import { loadOwnerConfig } from '../scripts/lib/owner-yaml.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -30,10 +42,29 @@ import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
 
 const JSONL_PATH = path.join(SO_PROJECT_DIR, '.orchestrator', 'metrics', 'skill-invocations.jsonl');
 
+/** Absolute path to the telemetry CLI (carries the hidden `_flush` subcommand). */
+const TELEMETRY_CLI_PATH = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../scripts/telemetry.mjs',
+);
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * True when an env var carries a truthy "on" signal (present, non-empty, not
+ * '0'/'false'). Kept local so the hook does not pull anything extra from consent.mjs.
+ * @param {unknown} raw
+ * @returns {boolean}
+ */
+function isTruthyEnvFlag(raw) {
+  if (raw === undefined || raw === null) return false;
+  const t = String(raw).trim();
+  if (t === '' || t === '0') return false;
+  return t.toLowerCase() !== 'false';
+}
+
 /**
  * Read stdin to EOF (best-effort). Returns parsed JSON or null on failure.
  * Uses a 5 s timeout consistent with Claude Code hook contract.
@@ -61,6 +92,61 @@ function readStdinJson() {
   });
 }
 
+/**
+ * Non-blocking daily-fallback flush trigger. Ordered cheapest-first:
+ *   1. env kill-switches (no I/O) — DO_NOT_TRACK / SO_TELEMETRY_DISABLED.
+ *   2. shouldDailyFlush (one telemetry.json read + one queue stat) — the common
+ *      case (empty queue) returns here WITHOUT loading owner.yaml or the roster.
+ *   3. full consent resolution — spawn a detached `telemetry _flush` only when it
+ *      resolves to send.
+ *
+ * Never throws; the caller's hook must always exit 0.
+ *
+ * @param {object} [opts]
+ * @param {NodeJS.ProcessEnv} [opts.env]  Env source (default process.env).
+ * @param {typeof spawn} [opts.spawnFn]   Spawn function (test injection).
+ * @param {number} [opts.now]             Reference time epoch-ms (default Date.now()).
+ * @param {string} [opts.statePath]       telemetry.json path override (test injection).
+ * @param {string} [opts.queuePath]       queue path override (test injection).
+ * @returns {{ spawned: boolean, reason: string }}
+ */
+export function maybeSpawnDailyFlush({
+  env = process.env,
+  spawnFn = spawn,
+  now = Date.now(),
+  statePath,
+  queuePath,
+} = {}) {
+  try {
+    // 1. Cheapest gate: env kill-switches, no file I/O.
+    if (isTruthyEnvFlag(env?.DO_NOT_TRACK) || env?.SO_TELEMETRY_DISABLED === '1') {
+      return { spawned: false, reason: 'disabled-env' };
+    }
+
+    // 2. Cheap backlog check — bails out before owner.yaml load in the common case.
+    if (!shouldDailyFlush({ statePath, queuePath, now })) {
+      return { spawned: false, reason: 'not-due' };
+    }
+
+    // 3. Authoritative consent gate.
+    const ownerConfig = loadOwnerConfig().config;
+    const { record } = readTelemetryState({ path: statePath });
+    const consent = resolveConsent({ env, ownerConfig, state: record, interactive: false });
+    if (consent.send !== true) {
+      return { spawned: false, reason: 'gated' };
+    }
+
+    const child = spawnFn(process.execPath, [TELEMETRY_CLI_PATH, '_flush'], {
+      detached: true,
+      stdio: 'ignore',
+    });
+    if (child && typeof child.unref === 'function') child.unref();
+    return { spawned: true, reason: 'spawned' };
+  } catch {
+    return { spawned: false, reason: 'error' };
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -91,9 +177,22 @@ async function main() {
   };
 
   await appendSkillInvocation(JSONL_PATH, record);
+
+  // Daily-fallback telemetry flush — non-blocking, best-effort, never throws.
+  maybeSpawnDailyFlush();
 }
 
-// Exit 0 always — informational hook must never block the Skill tool.
-main().catch((err) => {
-  process.stderr.write(`[skill-invocation-telemetry] ERROR: ${err?.message ?? err}\n`);
-}).finally(() => process.exit(0));
+// ---------------------------------------------------------------------------
+// Self-execution guard — run only when invoked directly (not when imported).
+// ---------------------------------------------------------------------------
+
+const isMain = process.argv[1] === fileURLToPath(import.meta.url);
+if (isMain) {
+  // Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
+  if (!shouldRunHook('skill-invocation-telemetry')) process.exit(0);
+
+  // Exit 0 always — informational hook must never block the Skill tool.
+  main().catch((err) => {
+    process.stderr.write(`[skill-invocation-telemetry] ERROR: ${err?.message ?? err}\n`);
+  }).finally(() => process.exit(0));
+}