session-orchestrator 3.23.0 → 4.0.0

package/hooks/on-stop.mjs

@@ -16,23 +16,42 @@
  * JSONL format (`.orchestrator/metrics/events.jsonl`) — emitted via the canonical
  * `emitEvent()` so the JSONL record and the optional Clank webhook always carry the
  * SAME dotted event name (was: bare `stop`/`subagent_stop` in JSONL vs dotted in webhook):
- *   Stop:        {"timestamp":<ISO>,"event":"orchestrator.session.stopped","session_id":"...","semantic_session_id":"...","wave":<int>,"branch":"...","commit":"...","duration_ms":<int>}
- *                (`session_id` / `semantic_session_id` are omitted when unresolvable — #1068 AC1.)
- *   SubagentStop: {"timestamp":<ISO>,"event":"orchestrator.agent.stopped","agent":"<name>"}
+ *   Stop:        {"timestamp":<ISO>,"event":"orchestrator.turn.stopped","session_id":"...","semantic_session_id":"...","wave":<int>,"branch":"...","commit":"...","duration_ms":<int>,"duration_source":"session-lock"}
+ *                + the SAME payload under the DEPRECATED legacy name (one generation, removal 2027-03-06):
+ *                {"timestamp":<ISO>,"event":"orchestrator.session.stopped",…same fields…,"deprecated":true}
+ *                (`session_id` / `semantic_session_id` are omitted when unresolvable — #1068 AC1.
+ *                 `duration_ms` + `duration_source` are omitted TOGETHER when no OWNED
+ *                 session.lock is readable — never a fabricated 0, see K5 below.)
+ *   SubagentStop: {"timestamp":<ISO>,"event":"orchestrator.agent.stopped","agent":"<name>","agent_id":"...",
+ *                  "agent_type_meta":"...","tool_use_id":"...","transcript_found":true,
+ *                  "duration_ms":<int>,"duration_source":"meta-birthtime","status":"done"}
+ *                (#1190 — every key after `event` is OPTIONAL and OMITTED when the
+ *                 measurement could not be made; `agent` too. See docs/events-schema.md.)
  */
 
 import path from 'node:path';
-import { promises as fs, statSync, writeFileSync } from 'node:fs';
+import {
+  promises as fs,
+  closeSync,
+  existsSync,
+  fstatSync,
+  openSync,
+  readFileSync,
+  readSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
+import { AGENT_ID_RE, resolveSubagentSidecar } from './_lib/subagent-paths.mjs';
 // #211: exit 0 immediately (silent allow) when this hook is disabled via profile/env
 if (!shouldRunHook('on-stop')) process.exit(0);
 
 import { emitEvent } from '../scripts/lib/events.mjs';
-import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
+import { getProjectDir } from '../scripts/lib/platform.mjs';
 import { parseSessionId } from '../scripts/lib/session-id.mjs';
 import { heartbeat, logSweepEvent } from '../scripts/lib/session-registry.mjs';
-import { updateHeartbeat } from '../scripts/lib/session-lock.mjs';
+import { readLock, updateHeartbeat } from '../scripts/lib/session-lock.mjs';
 
 // ---------------------------------------------------------------------------
 // stdin reading (inline — no io.mjs because Stop hooks exit 0 always, never deny)
@@ -247,7 +266,8 @@ async function readWaveNumber(projectRoot) {
  */
 async function resolveSessionId(input, projectRoot) {
   const fromStdin = input?.session_id ?? input?.sessionId ?? null;
-  let sessionId = parseSessionId(fromStdin)?.format === 'uuid' ? fromStdin : null;
+  const rawStdinId = parseSessionId(fromStdin)?.format === 'uuid' ? fromStdin : null;
+  let sessionId = rawStdinId;
 
   let recordedId = null;
   let semanticSessionId = null;
@@ -265,21 +285,90 @@ async function resolveSessionId(input, projectRoot) {
     }
   } catch { /* missing or unparseable is fine */ }
 
+  // Actor-identity fallback ONLY — `sessionId` drives the registry heartbeat and
+  // the lock heartbeat, both of which need an id even when stdin carried none.
   if (sessionId === null) sessionId = recordedId;
 
-  const isRecordedSession = sessionId !== null && sessionId === recordedId;
+  // W4a review F-A, second site of the same defect (census: exactly 2, both in
+  // hooks/, `grep -rn "= recordedId;" hooks/ scripts/` 2026-09-02). Comparing
+  // the RESOLVED id against `recordedId` is self-fulfilling: the line above may
+  // have just copied one into the other, so an id-less or non-UUID turn-end
+  // always read as "I am the recorded session" and inherited a live PEER's
+  // semantic identity — the exact #863 defect (c) contamination this gate
+  // exists to refuse. Decided on the RAW stdin UUID instead.
+  const isRecordedSession = rawStdinId !== null && rawStdinId === recordedId;
   return {
     sessionId,
     semanticSessionId: isRecordedSession ? semanticSessionId : null,
   };
 }
 
+/**
+ * Resolve an elapsed span for this Stop event — and WHICH span depends on the
+ * source, which is why `duration_source` ships beside the number (W4a F-C).
+ *
+ *   `session-lock`   — SESSION-elapsed, measured at this turn's end. Stop fires
+ *                      once per TURN, and `started_at` is stamped once per
+ *                      SESSION, so this number GROWS MONOTONICALLY across the
+ *                      turns of one session: the last Stop of a 3-hour session
+ *                      reports ~3 hours, not the length of its final turn.
+ *   `stdin-start-ms` — TURN-elapsed, the only first-party measurement of the
+ *                      turn itself. Measured today: the harness never sends it,
+ *                      so this source has never appeared in the fleet stream.
+ *
+ * Consumers must therefore not aggregate the two: summing `session-lock` spans
+ * over a session double-counts, where summing `stdin-start-ms` spans would not.
+ *
+ * OWNERSHIP-GATED, on the raw stdin `session_id` only. A lock in this working
+ * copy may name a PEER session (two windows share one checkout routinely), and
+ * a working-copy artefact is not a process-local identity witness — so the
+ * lock's `session_id` must match the id the STOPPING session was handed on
+ * stdin. `resolveSessionId()`'s resolved id is deliberately NOT used here: it
+ * falls back to `current-session.json`, which is exactly the foreign-identity
+ * inheritance this guard exists to refuse.
+ *
+ * Returns an object to SPREAD into the payload: `{}` when nothing is
+ * attestable, so `duration_ms` and `duration_source` are omitted together
+ * rather than written as a fabricated 0 (K5).
+ *
+ * `start_ms` is honoured first when the harness ever starts sending it — it is
+ * the only first-party measurement of the turn itself; measured today it is
+ * never present.
+ *
+ * @param {object|null} input parsed stdin payload
+ * @param {string} projectRoot
+ * @returns {{duration_ms?: number, duration_source?: string}}
+ */
+function resolveStopDuration(input, projectRoot) {
+  if (typeof input?.start_ms === 'number' && Number.isFinite(input.start_ms)) {
+    const ms = Date.now() - input.start_ms;
+    if (Number.isFinite(ms) && ms >= 0) {
+      return { duration_ms: Math.round(ms), duration_source: 'stdin-start-ms' };
+    }
+  }
+
+  const stdinId = input?.session_id ?? input?.sessionId ?? null;
+  if (typeof stdinId !== 'string' || stdinId.length === 0) return {};
+
+  try {
+    const lock = readLock({ repoRoot: projectRoot });
+    if (lock === null || lock.session_id !== stdinId) return {};
+    const startedAt = Date.parse(lock.started_at);
+    if (Number.isNaN(startedAt)) return {};
+    const ms = Date.now() - startedAt;
+    if (!Number.isFinite(ms) || ms < 0) return {};
+    return { duration_ms: Math.round(ms), duration_source: 'session-lock' };
+  } catch {
+    return {}; // best-effort — an unreadable lock measures nothing
+  }
+}
+
 /**
  * Handle a Stop event. Reads wave from scope file + git info, appends JSONL.
  * @param {object|null} input
  */
 async function handleStop(input) {
-  const projectRoot = SO_PROJECT_DIR;
+  const projectRoot = getProjectDir();
 
   const wave = await readWaveNumber(projectRoot);
   const { commit, branch } = await gitInfo(projectRoot);
@@ -350,9 +439,15 @@ async function handleStop(input) {
     } catch { /* best-effort */ }
   }
 
-  // duration_ms: if input provides a start time we compute from it, else 0
-  const durationMs =
-    typeof input?.start_ms === 'number' ? Date.now() - input.start_ms : 0;
+  // K5 — `duration_ms` was literally 0 in 8.127 of 8.127 fleet
+  // `orchestrator.session.stopped` records (measured 2026-09-02): the old
+  // expression fell back to a hard 0 because the harness never sends
+  // `start_ms`. A fabricated 0 is the exact failure class
+  // `scripts/lib/telemetry/subagents-schema.mjs:20-35` documents — it reads as
+  // a MEASURED zero-length session and is indistinguishable from one. So the
+  // span now comes from the session.lock's `started_at`, and BOTH keys are
+  // omitted when it cannot be measured.
+  const duration = resolveStopDuration(input, projectRoot);
 
   // Single emission path: emitEvent writes the canonical {timestamp, event, ...payload}
   // JSONL record AND fires the optional Clank webhook with the SAME event name — no
@@ -361,14 +456,42 @@ async function handleStop(input) {
   // turn-end outcome is joinable by identity from events.jsonl alone. Omitted
   // (never `""`/`null`) when unattested: an unresolved identity stays visibly
   // unresolved rather than becoming a guessed id.
-  await emitEvent('orchestrator.session.stopped', {
+  // #1183 — a malformed record throws EventValidationError BEFORE any side
+  // effect (scripts/lib/events.mjs); this hook must never abort on that, so
+  // the emit is wrapped rather than left to propagate.
+  //
+  // ── THE RENAME (GitLab #1234) ──────────────────────────────────────────────
+  // `orchestrator.session.stopped` is a TURN counter with a session's name. The
+  // Stop hook fires once per ASSISTANT TURN, not once per session: measured
+  // 2026-09-06 over 90 days, 15.538 records against 2.016 distinct
+  // `session.started` ids = 7,7 per session, with 184 for a single id. Six
+  // consumers read it as a session-lifecycle signal and are wrong by that factor.
+  //
+  // So the same payload now leaves under BOTH names for one generation:
+  //   - `orchestrator.turn.stopped`    — the correct name, what new readers use.
+  //   - `orchestrator.session.stopped` — unchanged shape PLUS `deprecated: true`,
+  //     so an existing reader keeps working and a NEW reader can tell at a glance
+  //     that it picked the legacy name.
+  // Removal of the legacy name: 2027-03-06 (docs/events-schema.md).
+  //
+  // The SubagentStop branch (`orchestrator.agent.stopped`) is deliberately NOT
+  // renamed — it is a different event and its per-agent cardinality is correct.
+  const stoppedPayload = {
     ...(sessionId !== null ? { session_id: sessionId } : {}),
     ...(semanticSessionId !== null ? { semantic_session_id: semanticSessionId } : {}),
     wave,
     ...(branch !== null ? { branch } : {}),
     ...(commit !== null ? { commit } : {}),
-    duration_ms: durationMs,
-  });
+    ...duration,
+  };
+
+  try {
+    await emitEvent('orchestrator.turn.stopped', stoppedPayload);
+  } catch { /* telemetry never blocks the hook (#1183) */ }
+
+  try {
+    await emitEvent('orchestrator.session.stopped', { ...stoppedPayload, deprecated: true });
+  } catch { /* telemetry never blocks the hook (#1183) */ }
 }
 
 /**
@@ -380,11 +503,242 @@ async function handleStop(input) {
  * @returns {Promise<string|null>} additionalContext or null
  */
 async function handleSubagentStop(input) {
-  const agent = input?.agent_type ?? 'unknown';
-  await emitEvent('orchestrator.agent.stopped', { agent });
+  /** @type {Record<string, unknown>} */
+  const payload = {};
+
+  // `agent` — the #1190 headline fix. The harness sends the EMPTY STRING, which
+  // `?? 'unknown'` never caught: 89.991 of 103.763 fleet records (86,7%,
+  // measured 2026-09-02) carry `agent: ""`. Trim, and emit the key ONLY when a
+  // real value remains — an unmeasured type stays visibly unmeasured rather
+  // than becoming `""` or a guessed `'unknown'`.
+  //
+  // Clamped with the SAME regex as `agent_type_meta` below (Q1-LOW-F3): this is
+  // the identical value class from a different source, it lands in the ledger
+  // and travels the optional Clank webhook, and it was the only unclamped
+  // string in this payload. A mismatch OMITS the key — never a truncation,
+  // which would look like a measured (but wrong) agent type.
+  const rawAgent = firstNonEmptyString(input, ['agent_type', 'subagent_type']);
+  const agent = rawAgent !== null && AGENT_TYPE_META_RE.test(rawAgent) ? rawAgent : null;
+  if (agent !== null) payload.agent = agent;
+
+  // `agent_id` — reader shape copied from hooks/subagent-telemetry.mjs (both
+  // naming conventions the harness may use). Charset-guarded before it is ever
+  // interpolated into a path (same precedent, resolveSubagentTranscriptPath)
+  // AND before it is emitted: an unbounded, unvalidated id (`../../etc/passwd`,
+  // or a 10 KB blob) would otherwise land verbatim in the ledger and travel
+  // over the optional Clank webhook unredacted. A rejected id is OMITTED — the
+  // same omission contract every other field in this payload uses — never
+  // sanitised into a different id that looks measured.
+  const rawAgentId = firstNonEmptyString(input, ['agent_id', 'subagent_id']);
+  const agentId = rawAgentId !== null && AGENT_ID_RE.test(rawAgentId) ? rawAgentId : null;
+  if (agentId !== null) payload.agent_id = agentId;
+
+  // Sidecar-derived fields. Every derivation is individually wrapped: a failure
+  // omits its own field and nothing else, and this function must never throw —
+  // a throw here would skip the emit and lose the record that already works.
+  // Consolidated derivation (#1196): hooks/_lib/subagent-paths.mjs now also
+  // rejects the literal 'unknown' agentId — this file's own AGENT_ID_RE-only
+  // check (above, for the emitted `agent_id` field) never did.
+  const sidecar = resolveSubagentSidecar({ transcriptPath: input?.transcript_path, agentId });
+  if (sidecar !== null) {
+    const transcriptPath = sidecar.transcript;
+    const metaPath = sidecar.meta;
+
+    let transcriptFound = false;
+    try {
+      transcriptFound = existsSync(transcriptPath);
+      payload.transcript_found = transcriptFound;
+    } catch { /* probe failed — omit rather than assert `false` */ }
+
+    try {
+      // One small read, one parse, two fields. `description` is operator prose
+      // and is deliberately NOT carried: this payload also travels over the
+      // optional Clank webhook unredacted.
+      const meta = JSON.parse(readFileSync(metaPath, 'utf8'));
+      // Both fields are CHARSET+LENGTH CLAMPED before they enter the payload,
+      // for the same reason `agent_id` above is: this record is appended to the
+      // ledger AND travels over the optional Clank webhook UNREDACTED, and
+      // meta.json is written by the harness, not by us. An oversized or
+      // structured value would land verbatim in both. A rejected value is
+      // OMITTED, never truncated into a shorter value that still looks measured.
+      if (typeof meta?.toolUseId === 'string' && TOOL_USE_ID_RE.test(meta.toolUseId.trim())) {
+        payload.tool_use_id = meta.toolUseId.trim();
+      }
+      // A SECOND witness for the type — never merged into `agent`, so the
+      // empty-`agent_type` rate stays measurable.
+      if (typeof meta?.agentType === 'string' && AGENT_TYPE_META_RE.test(meta.agentType.trim())) {
+        payload.agent_type_meta = meta.agentType.trim();
+      }
+    } catch { /* absent or corrupt sidecar meta — omit both fields */ }
+
+    try {
+      // meta.json carries no spawn timestamp; the harness writes the file AT
+      // spawn, so its birthtime IS the spawn moment. `duration_source` puts
+      // that provenance in the record instead of implying a measured span.
+      const span = spanFromBirthtime(Date.now(), statSync(metaPath).birthtimeMs);
+      if (span !== null) {
+        payload.duration_ms = span;
+        payload.duration_source = 'meta-birthtime';
+      }
+    } catch { /* stat failed — omit both keys (never a fabricated 0) */ }
+
+    if (transcriptFound) {
+      const status = readStatusFromTranscriptTail(transcriptPath);
+      if (status !== null) payload.status = status;
+    }
+  }
+
+  // #1183 — a malformed record throws EventValidationError BEFORE any side
+  // effect (scripts/lib/events.mjs); this hook must never abort on that, so
+  // the emit is wrapped rather than left to propagate.
+  try {
+    await emitEvent('orchestrator.agent.stopped', payload);
+  } catch { /* telemetry never blocks the hook (#1183) */ }
   return null;
 }
 
+// ---------------------------------------------------------------------------
+// SubagentStop payload derivations (#1190)
+// ---------------------------------------------------------------------------
+
+/**
+ * Harness tool-use ids, measured on-disk 2026-09-02 in a real sidecar meta.json:
+ * `toolu_01Xj6qZ3ApsVfomhByNftmxj` (25 chars, alphanumeric + one underscore).
+ */
+const TOOL_USE_ID_RE = /^[A-Za-z0-9_.-]{1,64}$/;
+
+/**
+ * Agent types carry a plugin qualifier, so the COLON is part of the real shape —
+ * measured in the same file: `session-orchestrator:code-implementer` (37 chars).
+ * A `tool_use_id`-identical charset would have rejected every plugin-qualified
+ * agent type in this repo, i.e. silently removed the field it clamps.
+ */
+const AGENT_TYPE_META_RE = /^[A-Za-z0-9_.:-]{1,64}$/;
+
+/**
+ * Upper bound on a `meta-birthtime` span, in ms. NAMED CEILING (BV-004): 7 days.
+ *
+ * No subagent runs for a week — the longest recorded here is minutes — so a
+ * span above this is not a long agent, it is a birthtime the filesystem did not
+ * supply. Node documents `birthtimeMs` as unavailable on filesystems that do
+ * not record it (overlayfs and some CI images among them), where it surfaces as
+ * 0 / 1970-01-01; the old `>= 0` lower bound accepted that verbatim and would
+ * ship a ~55-YEAR span stamped `duration_source: 'meta-birthtime'` — a
+ * fabricated measurement of exactly the class K5 removed.
+ *
+ * REVISIT TRIGGER: if a legitimately long-running agent class ever appears
+ * (a background agent measured in hours-to-days), raise this — but raise it to
+ * a measured bound, never remove it.
+ */
+const META_BIRTHTIME_MAX_SPAN_MS = 7 * 24 * 60 * 60 * 1000;
+
+/**
+ * Span between a birthtime and now, or `null` when the birthtime is not a
+ * usable measurement.
+ *
+ * Rejects a non-positive `birthtimeMs` (the "filesystem records no birthtime"
+ * signal) and any span outside `(0, META_BIRTHTIME_MAX_SPAN_MS)`. `null` means
+ * "omit both keys" at the call site — never a fabricated number.
+ *
+ * Pure, and separate from the call site so the two out-of-band cases are
+ * testable without a filesystem that can forge a birthtime.
+ *
+ * @param {number} nowMs
+ * @param {number} birthtimeMs
+ * @returns {number|null} rounded span in ms, or null
+ */
+function spanFromBirthtime(nowMs, birthtimeMs) {
+  if (!Number.isFinite(birthtimeMs) || birthtimeMs <= 0) return null;
+  const span = nowMs - birthtimeMs;
+  if (!Number.isFinite(span) || span < 0 || span > META_BIRTHTIME_MAX_SPAN_MS) return null;
+  return Math.round(span);
+}
+
+/** Tail window for the STATUS scan — sidecars measured at 113–528 KB. */
+const STATUS_TAIL_BYTES = 64 * 1024;
+
+/**
+ * STATUS literals an agent reports at the START of a line (optionally bold).
+ *
+ * LINE-ANCHORED on purpose — the rationale and the measurement are at
+ * `scripts/lib/wave-transcript-tail.mjs:105-112`: a free-floating
+ * `/STATUS: partial/` fires on any agent that merely QUOTES the marker
+ * (2 of 2 live hits in that measurement were quotations, 0 were reports).
+ * NOT imported from that module because the two alternations are DIFFERENT
+ * literal sets, not two copies of one: the tailer's `STATUS_RE` matches only
+ * `partial|blocked|failed` (it classifies a single `status-partial` attention
+ * pattern), while this hook records the agent's SELF-REPORTED status and must
+ * therefore also match `done` and `no-tests-needed`. Importing its constant
+ * would silently drop the two success literals. (Import cost is NOT the reason —
+ * measured 2026-09-02 as equal.)
+ */
+const AGENT_STATUS_RE = /^[ \t*_]*STATUS:\s*(done|partial|blocked|failed|no-tests-needed)\b/im;
+
+/**
+ * Pick the first non-empty trimmed string among `keys` on `input`.
+ * @param {object|null|undefined} input
+ * @param {string[]} keys
+ * @returns {string|null}
+ */
+function firstNonEmptyString(input, keys) {
+  for (const k of keys) {
+    const v = input?.[k];
+    if (typeof v === 'string' && v.trim()) return v.trim();
+  }
+  return null;
+}
+
+/**
+ * Read the LAST `STATUS_TAIL_BYTES` of an agent transcript and return the most
+ * recent line-anchored STATUS literal, or null when none is present.
+ *
+ * Never reads the whole file: measured sidecar sizes are 113–528 KB and this
+ * hook fires on every SubagentStop. Absence means NOT FOUND, never success —
+ * measured 2026-09-02, only 1 of 4 live sidecars carried a STATUS token in its
+ * last 64 KiB, so the miss is the common path.
+ *
+ * @param {string} transcriptPath
+ * @returns {string|null}
+ */
+function readStatusFromTranscriptTail(transcriptPath) {
+  let fd = null;
+  try {
+    fd = openSync(transcriptPath, 'r');
+    const size = fstatSync(fd).size;
+    const length = Math.min(size, STATUS_TAIL_BYTES);
+    const start = size - length;
+    const buf = Buffer.alloc(length);
+    const read = readSync(fd, buf, 0, length, start);
+    let lines = buf.subarray(0, read).toString('utf8').split('\n');
+    // Drop the leading partial line when the window did not start at byte 0.
+    if (start > 0) lines = lines.slice(1);
+
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+      const line = lines[i].trim();
+      if (!line) continue;
+      let rec;
+      try {
+        rec = JSON.parse(line);
+      } catch { continue; }
+      const content = rec?.message?.content;
+      if (!Array.isArray(content)) continue;
+      for (let j = content.length - 1; j >= 0; j -= 1) {
+        const block = content[j];
+        if (typeof block?.text !== 'string') continue;
+        const m = AGENT_STATUS_RE.exec(block.text);
+        if (m) return m[1].toLowerCase();
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  } finally {
+    if (fd !== null) {
+      try { closeSync(fd); } catch { /* best-effort */ }
+    }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // main
 // ---------------------------------------------------------------------------

package/hooks/operator-steer.mjs

@@ -37,14 +37,14 @@ import { shouldRunHook } from './_lib/profile-gate.mjs';
 // Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
 if (!shouldRunHook('operator-steer')) process.exit(0);
 
-import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
+import { getProjectDir } from '../scripts/lib/platform.mjs';
 
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
 
 async function main() {
-  const steerPath = path.join(SO_PROJECT_DIR, '.orchestrator', 'STEER.md');
+  const steerPath = path.join(getProjectDir(), '.orchestrator', 'STEER.md');
 
   // File absent — nothing to do.
   if (!existsSync(steerPath)) return;