session-orchestrator 3.16.0 → 3.19.0

package/scripts/run-quality-gate.mjs

@@ -38,7 +38,9 @@ import { spawnSync } from 'node:child_process';
 
 import { die, warn } from './lib/common.mjs';
 import { loadQualityGatesPolicy, resolveCommand } from './lib/quality-gates-policy.mjs';
-import { emitEvent } from './lib/events.mjs';
+import { emitEvent, sessionAttribution } from './lib/events.mjs';
+import { admitSuiteCounts } from './lib/gates/gate-helpers.mjs';
+import { findScopeFile } from './lib/scope-gate.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -49,6 +51,14 @@ const GATES_DIR = join(__dirname, 'lib', 'gates');
 
 const VALID_VARIANTS = ['baseline', 'incremental', 'full-gate', 'per-file'];
 
+/**
+ * Ceiling on the gate sub-script's captured stdout. A gate writes one JSON line
+ * (5-line command tails + ≤50 debug artifacts), so this is effectively
+ * unreachable — it exists only so a pathological gate cannot be killed
+ * mid-write by the default 1 MiB spawnSync cap.
+ */
+const GATE_STDOUT_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
+
 const DEFAULT_TEST_CMD = 'npm test';
 const DEFAULT_TYPECHECK_CMD = 'npm run typecheck';
 const DEFAULT_LINT_CMD = 'npm run lint';
@@ -148,6 +158,89 @@ function extractCommand(policy, policyKey, configKey, configJson, defaultCmd) {
   return defaultCmd;
 }
 
+/**
+ * Lift the suite counts out of a gate sub-script's JSON stdout envelope (#954).
+ *
+ * This function is the ENVELOPE ADAPTER only. The numeric admission policy —
+ * which triples count as a measurement and which are refused — lives once in
+ * {@link admitSuiteCounts} (`scripts/lib/gates/gate-helpers.mjs`, #967 item 2),
+ * shared with `suiteCountsFromOutput` in `scripts/lib/quality-gate.mjs`. Before
+ * that split, the same `counts` field was written under two different policies
+ * and a consumer had to know both to read one number.
+ *
+ * The four rejections that stay here are envelope-shaped, not numeric:
+ *
+ *   1. stdout is absent or not parseable JSON;
+ *   2. `test` is not the object form — only `gate-full.mjs` reports numbers;
+ *      `gate-{baseline,incremental,per-file}.mjs` emit a bare status STRING, so
+ *      a non-full-gate variant structurally cannot carry counts;
+ *   3. the test gate was skipped (`status` neither `pass` nor `fail`);
+ *   4. the test COMMAND was detected as a stub (`echo …` / no-op) — a stub's
+ *      output parses to 0/0, which would be a fabricated zero.
+ *
+ * `failed` is NO LONGER derived here. Since #967 item 1 `gate-full.mjs`
+ * publishes it explicitly, so the whole `test` object is handed through and
+ * `admitSuiteCounts`'s `passed + failed === total` check becomes a real guard
+ * against producer/consumer envelope drift instead of an identity that a local
+ * `total - passed` derivation could never fail.
+ *
+ * Never throws — a malformed envelope yields `null`.
+ *
+ * @param {string} stdout — the gate sub-script's captured stdout.
+ * @returns {{ passed: number, failed: number, total: number }|null}
+ */
+function suiteCountsFromGateStdout(stdout) {
+  if (typeof stdout !== 'string' || !stdout.trim()) return null;
+
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+
+  const test = parsed.test;
+  if (test === null || typeof test !== 'object' || Array.isArray(test)) return null;
+  if (test.status !== 'pass' && test.status !== 'fail') return null;
+  if (parsed.stubbed && typeof parsed.stubbed === 'object' && parsed.stubbed.test) return null;
+
+  return admitSuiteCounts(test);
+}
+
+/**
+ * Resolve the active wave number from the wave-scope sidecar (#966 step 1).
+ *
+ * Mirrors `resolveWave()` in `hooks/pre-bash-memory-propose-audit.mjs` — the
+ * same `.{pi,cursor,codex,claude}/wave-scope.json` precedence via
+ * {@link findScopeFile} — with ONE deliberate difference: the hook returns `0`
+ * for "no wave-scope file", this returns `null`.
+ *
+ * Absent is not zero. A human running `npm run quality-gate` from a `git push`
+ * has no wave at all, and that is the common case; publishing `wave_number: 0`
+ * would invent a wave 0 that every consumer then has to special-case. The
+ * caller spreads the result so the KEY is omitted, exactly as `counts` is.
+ *
+ * A non-positive or non-numeric `wave` field is treated the same way — waves
+ * are 1-indexed, so `0` on disk carries no more information than an absent file.
+ *
+ * Never throws.
+ *
+ * @param {string} projectDir — directory whose wave-scope sidecar to read.
+ * @returns {number|null} positive wave number, or `null` when there is no wave.
+ */
+function resolveWaveNumber(projectDir) {
+  try {
+    const waveFile = findScopeFile(projectDir);
+    if (!waveFile || !existsSync(waveFile)) return null;
+    const wave = JSON.parse(readFileSync(waveFile, 'utf8'))?.wave;
+    if (typeof wave !== 'number' || !Number.isFinite(wave) || wave <= 0) return null;
+    return Math.trunc(wave);
+  } catch {
+    return null;
+  }
+}
+
 // Load policy file (never throws)
 const repoRoot = process.cwd();
 const policy = loadQualityGatesPolicy(repoRoot);
@@ -193,23 +286,48 @@ const env = {
   SESSION_START_REF: sessionStartRef,
 };
 
+// stdout is PIPED (not inherited) so the suite counts the gate already computed
+// can be lifted straight off its JSON envelope into telemetry (#954) instead of
+// travelling as prose through the STATE.md header. The envelope is re-emitted
+// verbatim below, so the stdout contract is unchanged — a gate sub-script writes
+// exactly one JSON line at the very end (its own child commands are captured by
+// `runCheck`), so nothing streamed before and nothing streams now. stderr stays
+// inherited, keeping warnings live.
 const result = spawnSync('node', [gatePath], {
   env,
-  stdio: 'inherit',
+  stdio: ['inherit', 'pipe', 'inherit'],
+  encoding: 'utf8',
+  maxBuffer: GATE_STDOUT_MAX_BUFFER_BYTES,
 });
 
-if (result.error) {
+const gateStdout = typeof result.stdout === 'string' ? result.stdout : '';
+if (gateStdout) process.stdout.write(gateStdout);
+
+if (result.error && typeof result.status !== 'number') {
   die(`Failed to run gate script: ${result.error.message}`);
 }
 
 // Quality-gate telemetry — one canonical event per gate run via emitEvent
-// (single emission path). Best-effort: a telemetry failure must NEVER alter the
-// gate's authoritative exit code.
+// (single emission path). `sessionAttribution` is the shared helper in
+// events.mjs (#941); this CLI wrapper runs against the CWD `repoRoot`, so the
+// bare emitEvent destination (SO_PROJECT_DIR default) is correct here.
+// Best-effort: a telemetry failure must NEVER alter the gate's authoritative
+// exit code — which is why the counts parse also lives inside this try.
 const exitCode = result.status ?? 1;
 try {
+  const counts = suiteCountsFromGateStdout(gateStdout);
+  // Wave-scope sidecar is read from the SAME project dir the event lands in
+  // (emitEvent's own destination precedence), so a tmp-scoped run cannot pick
+  // up the host repo's live wave. Mirrors the hook's projectDir resolution.
+  const waveNumber = resolveWaveNumber(
+    process.env.CLAUDE_PROJECT_DIR ?? process.env.CODEX_PROJECT_DIR ?? repoRoot,
+  );
   await emitEvent(`orchestrator.quality_gate.${exitCode === 0 ? 'passed' : 'failed'}`, {
     variant,
     exit_code: exitCode,
+    ...(counts ? { counts } : {}),
+    ...(waveNumber !== null ? { wave_number: waveNumber } : {}),
+    ...sessionAttribution(repoRoot),
   });
 } catch { /* best-effort telemetry — gate result is authoritative */ }
 

package/scripts/telemetry.mjs

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+/**
+ * telemetry.mjs — operator CLI for anonymous usage telemetry (Epic #841, S3 /
+ * GitLab #844; PRD docs/prd/2026-07-20-anonymous-usage-telemetry.md §3-FA3).
+ *
+ * Subcommands:
+ *   status    show the resolved consent posture + queue occupancy
+ *   enable    grant consent (persist to telemetry.json)
+ *   disable   deny consent (persist to telemetry.json)
+ *   show      preview the usage-ping payload WITHOUT minting/persisting an anon-ID
+ *
+ * (`_flush` is an internal, hidden subcommand used by the daily-fallback hook to
+ * run a detached flush; it is intentionally omitted from --help.)
+ *
+ * Follows .claude/rules/cli-design.md:
+ *   - `--json` for machine output; human-readable by default.
+ *   - Data → stdout, diagnostics → stderr.
+ *   - Exit codes: 0 success · 1 user error (unknown subcommand) · 2 system error.
+ *
+ * All host-local state (telemetry.json, telemetry-queue.ndjson) is homedir-based;
+ * tests isolate via an injected HOME.
+ */
+
+import { parseArgs } from 'node:util';
+
+import {
+  resolveConsent,
+  readTelemetryState,
+  grantConsent,
+  denyConsent,
+} from './lib/telemetry/consent.mjs';
+import { queueStats } from './lib/telemetry/queue.mjs';
+import { flush, buildBatch } from './lib/telemetry/sync.mjs';
+import { loadOwnerConfig } from './lib/owner-yaml.mjs';
+import { readPluginVersionFromPackageJson } from './lib/bootstrap-lock-freshness.mjs';
+import { SO_PLUGIN_ROOT } from './lib/platform.mjs';
+
+const EXIT_OK = 0;
+const EXIT_USER = 1;
+const EXIT_SYSTEM = 2;
+
+const HELP = `telemetry — anonymous usage-telemetry consent + inspection CLI
+
+USAGE
+  telemetry <status|enable|disable|show> [--json]
+  telemetry --help | --version
+
+SUBCOMMANDS
+  status     show the resolved consent posture, anon-ID presence, and queue stats
+  enable     grant consent (persisted to ~/.config/session-orchestrator/telemetry.json)
+  disable    deny consent (persisted; subsequent sessions send nothing)
+  show       preview the exact usage-ping payload — never mints an ID, never sends
+
+OPTIONS
+  --json     emit machine-readable JSON on stdout
+  --help     show this help
+  --version  print the plugin version
+
+EXIT CODES
+  0  success
+  1  user error (unknown subcommand)
+  2  system error
+
+ENV KILL-SWITCHES
+  DO_NOT_TRACK=1 / SO_TELEMETRY_DISABLED=1   disable telemetry for this shell
+  SO_TELEMETRY=1                             force-enable (fleet) without a prompt
+  SO_TELEMETRY_DEBUG=1                       print the payload instead of sending
+`;
+
+/** Plugin version for `--version` — single-sourced via readPluginVersionFromPackageJson (null → 'unknown'). */
+function readPkgVersion() {
+  return readPluginVersionFromPackageJson(SO_PLUGIN_ROOT) ?? 'unknown';
+}
+
+// ---------------------------------------------------------------------------
+// Subcommand handlers
+// ---------------------------------------------------------------------------
+
+/** Resolve the current consent posture from env + owner.yaml + telemetry.json. */
+function currentPosture() {
+  const ownerConfig = loadOwnerConfig().config;
+  const { record } = readTelemetryState();
+  const consent = resolveConsent({ env: process.env, ownerConfig, state: record, interactive: false });
+  const queue = queueStats();
+  return { record, consent, queue };
+}
+
+function runStatus(json) {
+  const { record, consent, queue } = currentPosture();
+  const out = {
+    state: consent.state,
+    send: consent.send,
+    prompt: consent.prompt,
+    consent: record.consent,
+    anon_id_present: typeof record.anon_id === 'string' && record.anon_id.trim() !== '',
+    last_flush_at: record.last_flush_at,
+    queue: { count: queue.count, bytes: queue.bytes },
+  };
+
+  if (json) {
+    process.stdout.write(`${JSON.stringify(out)}\n`);
+  } else {
+    process.stdout.write(
+      [
+        `state:          ${out.state}`,
+        `send:           ${out.send}`,
+        `consent:        ${out.consent ?? '(none)'}`,
+        `anon_id:        ${out.anon_id_present ? 'present' : 'not yet minted'}`,
+        `last_flush_at:  ${out.last_flush_at ?? '(never)'}`,
+        `queue:          ${out.queue.count} batch(es), ${out.queue.bytes} byte(s)`,
+      ].join('\n') + '\n',
+    );
+  }
+  return EXIT_OK;
+}
+
+/**
+ * Persist a consent decision, then warn on stdout/stderr if an env kill-switch
+ * still overrides the file (so the operator is never misled that enabling took
+ * effect when DO_NOT_TRACK / SO_TELEMETRY_DISABLED wins for this shell).
+ */
+function runSetConsent(decision, json) {
+  const res = decision === 'granted' ? grantConsent() : denyConsent();
+  if (!res.ok) {
+    process.stderr.write('telemetry: failed to persist consent to telemetry.json\n');
+    return EXIT_SYSTEM;
+  }
+
+  // Re-resolve to detect an env override that still forces disabled.
+  const ownerConfig = loadOwnerConfig().config;
+  const consent = resolveConsent({ env: process.env, ownerConfig, state: res.record, interactive: false });
+  const envOverrides = decision === 'granted' && consent.state === 'disabled-env';
+  if (envOverrides) {
+    process.stderr.write(
+      'telemetry: WARN — DO_NOT_TRACK / SO_TELEMETRY_DISABLED overrides the file setting; ' +
+        'nothing will be sent from this shell.\n',
+    );
+  }
+
+  if (json) {
+    process.stdout.write(`${JSON.stringify({ consent: decision, effective_state: consent.state, send: consent.send })}\n`);
+  } else {
+    process.stdout.write(
+      decision === 'granted'
+        ? `Telemetry enabled (consent granted). Effective state: ${consent.state}.\n`
+        : 'Telemetry disabled (consent denied). Nothing will be sent.\n',
+    );
+  }
+  return EXIT_OK;
+}
+
+/**
+ * Preview the usage-ping payload WITHOUT minting or persisting an anon-ID
+ * (persist:false in buildBatch). Never sends. When no ID exists yet, a
+ * placeholder is shown in the anon_id slot.
+ */
+function runShow(json) {
+  const { record, reason } = buildBatch({ persist: false });
+  if (!record) {
+    process.stderr.write(`telemetry: cannot build preview (${reason ?? 'unknown'})\n`);
+    return EXIT_SYSTEM;
+  }
+
+  if (json) {
+    process.stdout.write(`${JSON.stringify(record)}\n`);
+  } else {
+    process.stdout.write(
+      'Usage-ping preview (NOT sent; anon-ID is not minted by `show`):\n' +
+        `${JSON.stringify(record, null, 2)}\n`,
+    );
+  }
+  return EXIT_OK;
+}
+
+/** Internal detached-child entry: run one flush, swallow everything, exit 0. */
+async function runFlush() {
+  try {
+    await flush();
+  } catch {
+    // never-throw contract; the detached child produces no user-facing output.
+  }
+  return EXIT_OK;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  let values;
+  let positionals;
+  try {
+    ({ values, positionals } = parseArgs({
+      options: {
+        json: { type: 'boolean', default: false },
+        help: { type: 'boolean', default: false },
+        version: { type: 'boolean', default: false },
+      },
+      allowPositionals: true,
+    }));
+  } catch (err) {
+    process.stderr.write(`telemetry: argument error: ${err?.message ?? String(err)}\n`);
+    process.exit(EXIT_USER);
+    return;
+  }
+
+  if (values.help) {
+    process.stdout.write(HELP);
+    process.exit(EXIT_OK);
+  }
+  if (values.version) {
+    process.stdout.write(`${readPkgVersion()}\n`);
+    process.exit(EXIT_OK);
+  }
+
+  const sub = positionals[0];
+  let code;
+  switch (sub) {
+    case 'status':
+      code = runStatus(values.json);
+      break;
+    case 'enable':
+      code = runSetConsent('granted', values.json);
+      break;
+    case 'disable':
+      code = runSetConsent('denied', values.json);
+      break;
+    case 'show':
+      code = runShow(values.json);
+      break;
+    case '_flush':
+      code = await runFlush();
+      break;
+    default:
+      process.stderr.write(
+        sub
+          ? `telemetry: unknown subcommand "${sub}". Try: status | enable | disable | show (--help).\n`
+          : 'telemetry: missing subcommand. Try: status | enable | disable | show (--help).\n',
+      );
+      process.exit(EXIT_USER);
+      return;
+  }
+
+  process.exit(code);
+}
+
+main().catch((err) => {
+  process.stderr.write(`telemetry: system error: ${err?.message ?? String(err)}\n`);
+  process.exit(EXIT_SYSTEM);
+});