session-orchestrator 3.22.0 → 3.23.0

package/hooks/pre-task-scope-disjoint.mjs

@@ -107,8 +107,8 @@
  *   | 2 | repo module failed to load             | ALLOW + GUARD INACTIVE on stderr | #992/#993: a broken module must never brick the session — but never SILENTLY, or a crash is indistinguishable from `emitAllow` |
  *   | 3 | stdin empty / not JSON                 | ALLOW               | not a real hook call; denying here blocks every dispatch on a harness quirk |
  *   | 4 | `tool_name` is not the dispatch tool   | ALLOW               | not our tool |
- *   | 5 | prompt carries no scope marker         | ALLOW               | 105 of 147 real prompts (71.4 %) have none. Non-extractable ≠ violation; denying these would deny 7 dispatches in 10 |
- *   | 6 | scope block present but unparseable    | ALLOW               | same reason as 5 — the parser is the fragile part, so its failures must resolve to the harmless side |
+ *   | 5 | prompt carries no scope marker         | ALLOW + COUNT       | 105 of 147 real prompts (71.4 %) have none. Non-extractable ≠ violation; denying these would deny 7 dispatches in 10. #1092: the allow now carries a counter-only record, so it is no longer byte-identical to "the guard never ran" |
+ *   | 6 | scope block present but unparseable    | ALLOW + COUNT       | same reason as 5 — the parser is the fragile part, so its failures must resolve to the harmless side. Counted under a DISTINCT class from row 5 |
  *   | 7 | ledger unreadable / corrupt            | WARN + ALLOW + SELF-HEAL | loss of state is not evidence of a violation; loud so it gets noticed. The verdict now CARRIES a fresh ledger, so the corruption is repaired on the spot — without it the guard stayed OFF for the whole remaining wave, visible only in one `systemMessage` |
  *   | 8 | `git ls-files` failed                  | ALLOW (degraded)    | glob-vs-glob expansion degrades, concrete collisions are still found. A git outage is not a scope violation |
  *   | 9 | `findScopeCollisions` → not evaluable   | WARN + ALLOW        | the library says "not evaluable". Denying on a verdict with no witness is an assertion without evidence |
@@ -119,6 +119,13 @@
  *   |13 | liveness probe throws / no evidence at all | treat as IN FLIGHT | keeps row 11 biting; the blind case is bounded by `IN_FLIGHT_TTL_MS`, never unbounded |
  *   |14 | ledger lock not acquirable in `LEDGER_LOCK_TIMEOUT_MS` | run UNLOCKED (degraded) | the lock removes the read-modify-write race (below); failing to take it must not deny, so the cycle degrades to the pre-lock behaviour |
  *
+ * Every row that reaches a verdict from `decide()` — 5–11 and 13–14 — also
+ * leaves an event record (§ Observability), so "which row fired" is answerable
+ * after the fact and not only in the moment. Rows 1–4 emit nothing (no decision
+ * was made), and neither do the two crash rows 2 and 12: a hook that fell over
+ * cannot describe itself, which is precisely why the GUARD INACTIVE banner on
+ * stderr is the signal there.
+ *
  * Rows 7 and 9 use `emitWarn`, which calls `process.exit(0)` and NEVER RETURNS.
  * That is why `decide()` below is a PURE function returning a verdict object and
  * this module emits exactly ONCE, at the end. Warning from inside the checking
@@ -137,6 +144,26 @@
  * PSA-005 STATE.md lock), with a dead-PID stale override and a short timeout;
  * on timeout it degrades to the unlocked cycle (row 14) rather than denying.
  *
+ * ## Observability — the ledger half of #1092
+ *
+ * Every dispatch DECISION also appends one `orchestrator.wave_dispatch.scope_checked`
+ * record to `<projectDir>/.orchestrator/metrics/events.jsonl`. The reason it
+ * exists is matrix rows 5/6: the no-signal ALLOW used to be byte-identical to
+ * "the guard never ran", and the in-ledger counter added first is a WAVE tally —
+ * it cannot say WHICH dispatch carried a scope. Payload: `wave` (omitted, never
+ * `0`, when unknown), `agent_id`, `declared_path_count`, `injected`, `shape`,
+ * `signal`, `ledger_result`, `collision_count`, `hook`, plus `session_id` /
+ * `semantic_session_id` when a session lock is readable.
+ *
+ * WHAT IT PROVES: this hook SAW (or did not see) a `FILE-SCOPE` declaration in
+ * the prompt the coordinator handed to the dispatch tool, and what the guard
+ * then decided. WHAT IT DOES NOT PROVE: that the block reached the agent's
+ * context, or that the agent read it. That is a RECEIVE-side question and the
+ * platform exposes no prompt-assembly boundary to answer it — the open half of
+ * #1092, with its revisit trigger in `docs/scope-collision-guard.md` § 4.2.
+ * NOTHING derived from the prompt BODY is in the payload: counts and enums
+ * only, no paths (#1092 acceptance criterion 3).
+ *
  * ## stdout discipline
  *
  * Under the exit-0 protocol (#906, ADR-0011) allow and deny share exit code 0 —
@@ -240,6 +267,34 @@ const MAX_PATH_CHARS = 120;
 /** Ledger bound: a wave dispatching more than this is pathological; drop oldest. */
 const MAX_LEDGER_AGENTS = 64;
 
+/**
+ * Scope-signal classes (#1092). Counter-only — see {@link bumpSignalCounter}.
+ */
+const SIGNAL_MARKER_ABSENT = 'marker-absent';
+const SIGNAL_UNPARSEABLE = 'unparseable';
+const SIGNAL_EXTRACTED = 'extracted';
+
+/**
+ * Which declaration SHAPE produced the extracted paths (#1092). `none` means no
+ * shape yielded a path — the `marker-absent` AND the `unparseable` case alike,
+ * which is why the event carries `signal` beside `shape`: `shape` says which
+ * parser won, `signal` says whether a declaration was there at all.
+ */
+const SHAPE_FENCED = 'fenced';
+const SHAPE_INLINE = 'inline';
+const SHAPE_NONE = 'none';
+
+/** The per-dispatch observability record (#1092) — see § Observability. */
+const SCOPE_EVENT = 'orchestrator.wave_dispatch.scope_checked';
+
+/**
+ * Clamp for the one free-form string the event carries (`agent_id`, built from
+ * the coordinator's own `description`). A dispatch description is a label, but
+ * nothing enforces that, so the ledger line is bounded like every other payload
+ * in this file (§ stdout discipline).
+ */
+const MAX_AGENT_ID_CHARS = 120;
+
 /**
  * Blind-fallback liveness bound — see § Liveness for the measurement, the named
  * ceiling and the revisit trigger. Only reached when the transcript carries NO
@@ -321,12 +376,74 @@ async function bootstrap() {
 // Scope extraction — the fragile part, so every failure resolves to ALLOW
 // ---------------------------------------------------------------------------
 
+/** The marker vocabulary, shared by both declaration shapes below. */
+const SCOPE_TERMS = 'DATEI[- ]SCOPE|FILE[- ]SCOPE|FILE SCOPE|DEIN SCOPE|SCOPE \\(|FILES? IN SCOPE';
+
 /**
- * Markers that introduce a file-scope block in a dispatch prompt. Measured
- * coverage: 42 of 147 archived prompts (28.6 %) carry one of these. The other
- * 71.4 % are matrix row 5 — allowed, not denied.
+ * SHAPE 1 (highest precedence) — a marker near the START of a line, followed by
+ * a fenced block. This is the form `skills/wave-executor/wave-loop.md` § Scope
+ * Manifest specifies. Measured coverage: 42 of 147 archived prompts (28.6 %)
+ * carry one of these; the other 71.4 % are matrix row 5 — allowed, not denied.
+ *
+ * ## The 80-char window is NOT widened, and that is a measurement (#1092)
+ *
+ * The obvious repair for "the marker sits at column 210…506 of its line" is to
+ * widen the window. Measured 2026-08-26 over 4452 real first-record subagent
+ * prompts under `~/.claude/projects/ * / * /subagents/agent-*.jsonl` (709 of them
+ * this repo's own), comparing this regex against `^.{0,600}`:
+ *
+ *   window 80  → 701 marker hits, 267 prompts yield ≥1 extracted path
+ *   window 600 → 810 marker hits, 267 prompts yield ≥1 extracted path
+ *   of the 102 prompts the wider window newly matches, 12 have any fenced block
+ *   after the marker at all, and 0 yield a single path. In THIS repo: +34 newly
+ *   matched, 0 with a fence, 0 paths.
+ *
+ * So widening recovers NOTHING and costs something real: it reclassifies 102
+ * prompts from "no marker" to "marker present but unparseable", which is
+ * precisely the distinction the signal counter below exists to record. Worse,
+ * most of what it newly matches is a CITATION, not a declaration — "quote the
+ * exact command, the file scope, the result", "outside your file scope",
+ * "File-Scope-Disjunktheit". A citation is not a declaration; reading the first
+ * hit in a region as one is the recorded failure of `parseEpicRef` (#1112).
+ *
+ * The real miss class is a different SHAPE, handled by {@link INLINE_SCOPE_DECL}.
  */
-const SCOPE_MARKER = /^.{0,80}(DATEI[- ]SCOPE|FILE[- ]SCOPE|FILE SCOPE|DEIN SCOPE|SCOPE \(|FILES? IN SCOPE)/im;
+const SCOPE_MARKER = new RegExp(`^.{0,80}(${SCOPE_TERMS})`, 'im');
+
+/**
+ * SHAPE 2 (lower precedence) — the measured miss class: a declaration written
+ * INLINE, mid-sentence, with its paths comma-separated on the same line rather
+ * than in a fenced block:
+ *
+ *   "…Max 25 turns. Edit ONLY your FILE-SCOPE: scripts/a.mjs, scripts/b.mjs"
+ *
+ * What separates this from a citation is not WHERE it sits but that it
+ * INTRODUCES something — the marker is followed by an optional short qualifier
+ * and/or parenthetical and then a declaration operator (`:` or an em/en dash).
+ * A bare hyphen is deliberately NOT an operator: it would admit
+ * "File-Scope-Planung". Anchored declaration shapes with precedence, rather than
+ * a narrower search space, is the fix #1112's learning prescribes.
+ *
+ * The tail window before the operator is 2 characters, and that is measured
+ * too: at 24 it admitted \`File-Scope-Disjunktheit: a.mjs, b.mjs\` — a compound
+ * NOUN reading as a declaration. A dash-introduced qualifier
+ * (\`FILE-SCOPE — exactly these:\`) is allowed explicitly instead of by window
+ * width, so widening the window is never the way to admit one.
+ *
+ * Measured 2026-08-26 on this repo's 709 subagent prompts: 136 yield paths
+ * today; this shape recovers 9 more, all of them genuine wave file scopes.
+ * Host-wide the same operator test admits 41 additional marker hits and its
+ * one false extraction (`[".filter"]`) is a prose fragment, which is why the
+ * fenced shape keeps precedence and this one runs only when that found nothing.
+ */
+const INLINE_SCOPE_DECL = new RegExp(`(${SCOPE_TERMS})`, 'ig');
+const INLINE_DECL_OPERATOR = /^[^\n(:—–]{0,2}(\([^)\n]{0,80}\))?\s*(?:[—–][^\n:]{0,30})?\s*(:|—|–)/;
+
+/** Separators a coordinator uses between paths in an inline declaration. */
+const INLINE_SCOPE_SEPARATOR = /[,;·]| und | and | sowie /;
+
+/** Bound the inline scan; a prompt naming the vocabulary this often is prose. */
+const MAX_INLINE_MARKER_SCANS = 8;
 
 /**
  * A plausible repo-relative path. Deliberately strict — a false ACCEPT here
@@ -427,30 +544,19 @@ export function promoteDirEntries(files, known) {
 }
 
 /**
- * Extract the declared file scope from a dispatch prompt.
+ * Accept the segments that survive `looksLikeRepoPath`, normalised and deduped
+ * with order preserved. Shared by both declaration shapes.
  *
- * Strategy: find a scope marker line, take the FIRST fenced block after it, and
- * accept only lines that survive `looksLikeRepoPath`. Returns `[]` when nothing
- * is confidently extractable — which the caller treats as ALLOW (matrix rows
- * 5 and 6), never as an empty scope that could collide.
- *
- * @param {string} prompt
- * @returns {string[]} repo-relative paths/globs, normalised, deduped, order preserved
+ * @param {string[]} segments
+ * @returns {string[]}
  */
-export function extractScopeFromPrompt(prompt) {
-  if (typeof prompt !== 'string' || prompt.length === 0) return [];
-  const markerMatch = SCOPE_MARKER.exec(prompt);
-  if (markerMatch === null) return [];
-
-  const after = prompt.slice(markerMatch.index + markerMatch[0].length);
-  // First fenced block after the marker. Non-greedy body; tolerates a language tag.
-  const fence = /```[^\n]*\n([\s\S]*?)```/.exec(after);
-  if (fence === null) return [];
-
+function collectScopePaths(segments) {
   const out = [];
   const seen = new Set();
-  for (const rawLine of fence[1].split('\n')) {
-    const cleaned = normalizeScopeEntry(cleanScopeLine(rawLine));
+  for (const raw of segments) {
+    // A trailing sentence period is punctuation, never part of a path
+    // (measured: "docs/events-schema.md." at the end of an inline declaration).
+    const cleaned = normalizeScopeEntry(cleanScopeLine(raw).replace(/\.$/, ''));
     if (!looksLikeRepoPath(cleaned)) continue;
     if (seen.has(cleaned)) continue;
     seen.add(cleaned);
@@ -459,6 +565,94 @@ export function extractScopeFromPrompt(prompt) {
   return out;
 }
 
+/**
+ * SHAPE 2 extraction — see {@link INLINE_SCOPE_DECL}. Reports whether a
+ * DECLARATION (not a citation) was seen at all, so the caller can tell matrix
+ * row 5 from row 6 even when no path survives.
+ *
+ * @param {string} prompt
+ * @returns {{seen: boolean, files: string[]}}
+ */
+function extractInlineScopeDeclaration(prompt) {
+  INLINE_SCOPE_DECL.lastIndex = 0;
+  let seen = false;
+  let match;
+  let scans = 0;
+  while ((match = INLINE_SCOPE_DECL.exec(prompt)) !== null && scans < MAX_INLINE_MARKER_SCANS) {
+    scans++;
+    const after = prompt.slice(match.index + match[0].length);
+    const operator = INLINE_DECL_OPERATOR.exec(after);
+    if (operator === null) continue;   // a citation, not a declaration
+    seen = true;
+    const line = after.slice(operator[0].length).split('\n')[0];
+    const files = collectScopePaths(line.split(INLINE_SCOPE_SEPARATOR));
+    if (files.length > 0) return { seen: true, files };
+  }
+  return { seen, files: [] };
+}
+
+/**
+ * Classify the scope signal a dispatch prompt carries, and extract it.
+ *
+ * Precedence, deliberately: SHAPE 1 (line-leading marker + fenced block, the
+ * documented form) first; SHAPE 2 (inline comma-separated declaration) only
+ * when SHAPE 1 produced nothing. The status is what makes a no-signal ALLOW
+ * distinguishable after the fact:
+ *
+ *   `marker-absent`  — no declaration of any recognised shape (matrix row 5)
+ *   `unparseable`    — a declaration is present but no path survived (row 6)
+ *   `extracted`      — `files` is non-empty
+ *
+ * `shape` names the parser that WON — `fenced` (SHAPE 1), `inline` (SHAPE 2), or
+ * `none` when neither produced a path. It is deliberately NOT a second spelling
+ * of `status`: a prompt carrying a fenced block whose lines are prose is
+ * `{status: 'unparseable', shape: 'none'}`, and collapsing the two would lose
+ * exactly the row-5/row-6 distinction the counter exists for.
+ *
+ * @param {string} prompt
+ * @returns {{status: 'marker-absent'|'unparseable'|'extracted',
+ *            shape: 'fenced'|'inline'|'none', files: string[]}}
+ */
+export function extractScopeSignal(prompt) {
+  if (typeof prompt !== 'string' || prompt.length === 0) {
+    return { status: SIGNAL_MARKER_ABSENT, shape: SHAPE_NONE, files: [] };
+  }
+
+  const markerMatch = SCOPE_MARKER.exec(prompt);
+  if (markerMatch !== null) {
+    const after = prompt.slice(markerMatch.index + markerMatch[0].length);
+    // First fenced block after the marker. Non-greedy body; tolerates a language tag.
+    const fence = /```[^\n]*\n([\s\S]*?)```/.exec(after);
+    if (fence !== null) {
+      const files = collectScopePaths(fence[1].split('\n'));
+      if (files.length > 0) return { status: SIGNAL_EXTRACTED, shape: SHAPE_FENCED, files };
+    }
+  }
+
+  const inline = extractInlineScopeDeclaration(prompt);
+  if (inline.files.length > 0) return { status: SIGNAL_EXTRACTED, shape: SHAPE_INLINE, files: inline.files };
+  return {
+    status: markerMatch !== null || inline.seen ? SIGNAL_UNPARSEABLE : SIGNAL_MARKER_ABSENT,
+    shape: SHAPE_NONE,
+    files: [],
+  };
+}
+
+/**
+ * Extract the declared file scope from a dispatch prompt. Returns `[]` when
+ * nothing is confidently extractable — which the caller treats as ALLOW (matrix
+ * rows 5 and 6), never as an empty scope that could collide.
+ *
+ * Thin wrapper over {@link extractScopeSignal}: callers that only need the paths
+ * (and the tests that pin them) keep the original signature.
+ *
+ * @param {string} prompt
+ * @returns {string[]} repo-relative paths/globs, normalised, deduped, order preserved
+ */
+export function extractScopeFromPrompt(prompt) {
+  return extractScopeSignal(prompt).files;
+}
+
 /**
  * The dispatch's human description — the field the liveness probe matches
  * against the transcript's `tool_use` blocks (present in 147/147 measured
@@ -662,6 +856,26 @@ export function waveKeyOf(projectDir, sessionId, readFn) {
   return `${sessionId}|w?|?`;
 }
 
+/**
+ * The wave NUMBER out of a `waveKeyOf()` key, for the telemetry record (#1092).
+ *
+ * Returns `null` — never `0` — when the key carries the `w?` fallback or a
+ * non-positive value, so the caller can OMIT the field. `.claude/rules/host-
+ * resources.md` § HR-105 in one line: an invented `wave: 0` would read as a real
+ * wave in every later query, exactly like the `wave_number` contract the
+ * quality-gate event already follows (`docs/events-schema.md`).
+ *
+ * @param {string} waveKey
+ * @returns {number|null}
+ */
+function waveNumberOf(waveKey) {
+  if (typeof waveKey !== 'string') return null;
+  const seg = waveKey.split('|')[1];
+  if (typeof seg !== 'string' || !seg.startsWith('w')) return null;
+  const n = Number(seg.slice(1));
+  return Number.isSafeInteger(n) && n > 0 ? n : null;
+}
+
 /**
  * Tracked files, for glob expansion inside `findScopeCollisions`. The library is
  * pure and must not spawn — supplying this is precisely the hook's job.
@@ -716,9 +930,59 @@ function clipPath(p) {
 // since #1020's lock landed, would also skip the lock's release `finally`.
 // ---------------------------------------------------------------------------
 
+/**
+ * Record that ONE dispatch carried a given scope-signal class (#1092).
+ *
+ * ## Why this exists
+ *
+ * The no-signal path returned `{action: 'allow'}` with no `ledger` field, and
+ * the caller only writes `if (verdict.ledger)` — so nothing was written
+ * anywhere. Correct operation ("this agent legitimately has no scope") and total
+ * absence ("the coordinator injected nothing, or the marker never matched")
+ * produced BYTE-IDENTICAL evidence. Measured 2026-08-26 over 709 of this repo's
+ * subagent prompts: 136 yield paths, 47 carry a line-leading marker with no
+ * fenced block, 59 carry marker + fence but no surviving path. Without a counter
+ * none of those three classes is distinguishable from "the guard never ran".
+ *
+ * ## What it is NOT
+ *
+ * This is a SEND-SIDE counter. It observes what the COORDINATOR PUT IN THE
+ * PROMPT at dispatch time — never what the agent received, parsed, or obeyed. A
+ * non-zero `extracted` proves a scope was written into the prompt; it proves
+ * nothing about delivery or about the agent honouring it. Whether the injected
+ * block actually reached the agent's context is a RECEIVE-side question that
+ * only the subagent transcript can answer, and no number here may be read as
+ * that proof.
+ *
+ * Counter ONLY: no prompt text, no paths, no agent ids. The ledger is a shared
+ * working-copy artefact, and a scope-signal tally must not become a second,
+ * unreviewed copy of prompt content.
+ *
+ * Scoped to the wave, like `agents`: a new `waveKey` starts a fresh tally
+ * rather than accumulating across waves.
+ *
+ * @param {object|null} ledger    previously recorded wave state
+ * @param {string} waveKey
+ * @param {'marker-absent'|'unparseable'|'extracted'} status
+ * @returns {{'marker-absent': number, unparseable: number, extracted: number}}
+ */
+export function bumpSignalCounter(ledger, waveKey, status) {
+  const carried = (ledger !== null && ledger?.waveKey === waveKey && ledger.scopeSignals !== null
+    && typeof ledger.scopeSignals === 'object' && !Array.isArray(ledger.scopeSignals))
+    ? ledger.scopeSignals
+    : {};
+  const next = {};
+  for (const key of [SIGNAL_MARKER_ABSENT, SIGNAL_UNPARSEABLE, SIGNAL_EXTRACTED]) {
+    const prior = carried[key];
+    next[key] = Number.isSafeInteger(prior) && prior >= 0 ? prior : 0;
+  }
+  next[status] += 1;
+  return next;
+}
+
 /**
  * @typedef {{action: 'allow'|'deny'|'warn', reason?: string, suggestion?: string,
- *            ledger?: object|null, note?: string}} Verdict
+ *            ledger?: object|null, note?: string, telemetry?: object}} Verdict
  */
 
 /**
@@ -743,14 +1007,54 @@ export function decide({ input, ledger, ledgerCorrupt, waveKey, knownFiles, coll
   const toolInput = input?.tool_input;
   if (toolInput === null || typeof toolInput !== 'object') return { action: 'allow' };
 
-  const files = extractScopeFromPrompt(toolInput.prompt);
+  const at = typeof nowIso === 'string' ? nowIso : new Date().toISOString();
+
+  const signal = extractScopeSignal(toolInput.prompt);
+  const files = signal.files;
+  const id = agentIdOf(toolInput);
+  const priorAgents = (ledger !== null && ledger?.waveKey === waveKey && Array.isArray(ledger.agents))
+    ? ledger.agents
+    : [];
+
+  // #1092 — the observability record this dispatch will leave in the ledger.
+  // BUILT here, EMITTED by the caller: `decide()` is a pure function (§ stdout
+  // discipline), and an `await` inside it would put an I/O failure on the
+  // decision path. Counter-shaped by construction — a count, three enums and the
+  // agent id, never a path, never a byte of the prompt (issue #1092 acceptance
+  // criterion 3). `wave` is omitted rather than zeroed when unknown.
+  const wave = waveNumberOf(waveKey);
+  const telemetryFor = (ledgerResult, collisionCount = 0) => ({
+    ...(wave === null ? {} : { wave }),
+    agent_id: id.slice(0, MAX_AGENT_ID_CHARS),
+    declared_path_count: files.length,
+    injected: files.length > 0,
+    shape: signal.shape,
+    signal: signal.status,
+    ledger_result: ledgerResult,
+    collision_count: collisionCount,
+  });
+
   // Rows 5 + 6: nothing confidently extractable → allow. Non-extractable is not
   // a violation, and denying here would deny ~7 dispatches in 10.
-  if (files.length === 0) return { action: 'allow' };
+  //
+  // #1092: the ALLOW now CARRIES a counter so it leaves a trace. Before this,
+  // "no scope in the prompt" and "the guard never ran" were indistinguishable
+  // after the fact. `agents` is carried through UNCHANGED — this dispatch
+  // declared no scope, so it adds no scope claim to the wave.
+  if (files.length === 0) {
+    return {
+      action: 'allow',
+      telemetry: telemetryFor('no-scope'),
+      ledger: {
+        waveKey,
+        updated: at,
+        agents: priorAgents,
+        scopeSignals: bumpSignalCounter(ledger, waveKey, signal.status),
+      },
+    };
+  }
 
-  const id = agentIdOf(toolInput);
   const desc = agentDescOf(toolInput);
-  const at = typeof nowIso === 'string' ? nowIso : new Date().toISOString();
   const self = { id, desc, files, at };
 
   // Row 7: ledger existed but was unparseable. Terminal warn — decided here and
@@ -760,7 +1064,8 @@ export function decide({ input, ledger, ledgerCorrupt, waveKey, knownFiles, coll
   if (ledgerCorrupt) {
     return {
       action: 'warn',
-      ledger: { waveKey, updated: at, agents: [self] },
+      telemetry: telemetryFor('warn-ledger-corrupt'),
+      ledger: { waveKey, updated: at, agents: [self], scopeSignals: bumpSignalCounter(null, waveKey, signal.status) },
       note:
         `${HOOK_NAME}: wave dispatch ledger was unreadable — scope-disjointness NOT checked for ` +
         `"${id}"; the ledger has been reset, so the next dispatch is checked again.`,
@@ -792,6 +1097,7 @@ export function decide({ input, ledger, ledgerCorrupt, waveKey, knownFiles, coll
     waveKey,
     updated: at,
     agents: [...others, self].slice(-MAX_LEDGER_AGENTS),
+    scopeSignals: bumpSignalCounter(ledger, waveKey, signal.status),
   };
 
   const collisions = Array.isArray(verdictLib?.collisions) ? verdictLib.collisions : [];
@@ -806,6 +1112,7 @@ export function decide({ input, ledger, ledgerCorrupt, waveKey, knownFiles, coll
   if (verdictLib?.ok !== true && collisions.length === 0 && duplicateIds.length === 0) {
     return {
       action: 'warn',
+      telemetry: telemetryFor('warn-not-evaluable'),
       ledger: nextLedger,
       note:
         `${HOOK_NAME}: scope collision check not evaluable for "${id}" — dispatch allowed, ` +
@@ -818,7 +1125,7 @@ export function decide({ input, ledger, ledgerCorrupt, waveKey, knownFiles, coll
   // this guard, and re-denying it would block an innocent third agent.
   const mine = collisions.filter((c) => c?.a === id || c?.b === id);
 
-  if (mine.length === 0) return { action: 'allow', ledger: nextLedger };
+  if (mine.length === 0) return { action: 'allow', telemetry: telemetryFor('allow'), ledger: nextLedger };
 
   // § Liveness — the review's HIGH finding. A collision with an agent that has
   // ALREADY FINISHED is a sequential repair pass, not a race. The probe is called
@@ -844,7 +1151,13 @@ export function decide({ input, ledger, ledgerCorrupt, waveKey, knownFiles, coll
     const kept = others.filter((a) => !finishedIds.has(a.id));
     return {
       action: 'allow',
-      ledger: { waveKey, updated: at, agents: [...kept, self].slice(-MAX_LEDGER_AGENTS) },
+      telemetry: telemetryFor('allow-finished', mine.length),
+      ledger: {
+        waveKey,
+        updated: at,
+        agents: [...kept, self].slice(-MAX_LEDGER_AGENTS),
+        scopeSignals: nextLedger.scopeSignals,
+      },
     };
   }
 
@@ -876,7 +1189,7 @@ export function decide({ input, ledger, ledgerCorrupt, waveKey, knownFiles, coll
 
   // Deliberately NOT persisting the ledger on deny: the dispatch did not happen,
   // so recording it would make the retry-after-fix look like a duplicate.
-  return { action: 'deny', reason, suggestion };
+  return { action: 'deny', telemetry: telemetryFor('deny', mine.length), reason, suggestion };
 }
 
 // ---------------------------------------------------------------------------
@@ -964,6 +1277,26 @@ async function main() {
     verdict = cycle();
   }
 
+  // #1092 — one ledger line per dispatch DECISION, awaited BEFORE the terminal
+  // emit: `emitAllow`/`emitDeny`/`emitWarn` all call `process.exit()`, which
+  // discards a pending append (the same ordering `hooks/enforce-scope.mjs`
+  // documents at its own event site). Best-effort in BOTH directions — the
+  // import is dynamic so a checkout without `scripts/lib/events.mjs` degrades to
+  // silence instead of crashing (§ Import safety), and the catch guarantees a
+  // failed write cannot change the verdict or the exit code.
+  if (verdict.telemetry) {
+    try {
+      const { emitEvent, sessionAttribution } = await import(
+        pathToFileURL(path.join(PLUGIN_ROOT, 'scripts', 'lib', 'events.mjs')).href
+      );
+      await emitEvent(
+        SCOPE_EVENT,
+        { hook: HOOK_NAME, ...verdict.telemetry, ...sessionAttribution(projectDir) },
+        { repoRoot: projectDir }
+      );
+    } catch { /* observability is best-effort — it never blocks the decision */ }
+  }
+
   if (verdict.action === 'deny') return emitDeny(verdict.reason, verdict.suggestion);
   if (verdict.action === 'warn') return emitWarn(verdict.note);
   return emitAllow();

package/hooks/skill-invocation-telemetry.mjs

@@ -11,11 +11,13 @@
  *   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. 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.
+ *   5. Daily-fallback telemetry flush check (Epic #841, #844; #1138) — non-blocking:
+ *      when more than 24h have passed since the last successful flush AND either
+ *      the offline queue is non-empty or a session has completed since, AND
+ *      consent resolves to send, spawn a detached child that runs
+ *      `telemetry _flush`. Cheap by construction (env kill-switch pre-check →
+ *      state stat → queue/ledger probe → 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).
@@ -40,7 +42,9 @@ import { loadOwnerConfig } from '../scripts/lib/owner-yaml.mjs';
 // Constants
 // ---------------------------------------------------------------------------
 
-const JSONL_PATH = path.join(SO_PROJECT_DIR, '.orchestrator', 'metrics', 'skill-invocations.jsonl');
+const METRICS_DIR = path.join(SO_PROJECT_DIR, '.orchestrator', 'metrics');
+
+const JSONL_PATH = path.join(METRICS_DIR, 'skill-invocations.jsonl');
 
 /** Absolute path to the telemetry CLI (carries the hidden `_flush` subcommand). */
 const TELEMETRY_CLI_PATH = path.resolve(
@@ -95,8 +99,9 @@ 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.
+ *   2. shouldDailyFlush (one telemetry.json read; a queue stat + a sessions.jsonl
+ *      read only once the 24h gate has passed) — the common case (flushed within
+ *      24h) returns here WITHOUT loading owner.yaml or the roster.
  *   3. full consent resolution — spawn a detached `telemetry _flush` only when it
  *      resolves to send.
  *
@@ -108,6 +113,8 @@ function readStdinJson() {
  * @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).
+ * @param {string} [opts.metricsDir]      Metrics dir for shouldDailyFlush's catch-up
+ *                                        probe (default: this repo's metrics dir).
  * @returns {{ spawned: boolean, reason: string }}
  */
 export function maybeSpawnDailyFlush({
@@ -116,6 +123,7 @@ export function maybeSpawnDailyFlush({
   now = Date.now(),
   statePath,
   queuePath,
+  metricsDir = METRICS_DIR,
 } = {}) {
   try {
     // 1. Cheapest gate: env kill-switches, no file I/O.
@@ -123,8 +131,11 @@ export function maybeSpawnDailyFlush({
       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 })) {
+    // 2. Backlog / catch-up check — bails out before owner.yaml load in the
+    //    common case. Since #1138 this is due EITHER on a stale non-empty queue
+    //    OR on a session that completed after the last successful flush, so the
+    //    fallback can originate a ping instead of only retrying failed sends.
+    if (!shouldDailyFlush({ statePath, queuePath, metricsDir, now })) {
       return { spawned: false, reason: 'not-due' };
     }
 

package/monitors/monitors.json

@@ -10,5 +10,11 @@
     "command": "node \"${CLAUDE_PLUGIN_ROOT}\"/scripts/lib/convergence-monitor.mjs --tail",
     "description": "Wave convergence telemetry monitor — tails .orchestrator/metrics/events.jsonl + sessions.jsonl, surfaces convergence signals (shrinking diff, pass-rate plateau, velocity).",
     "when": "on-skill-invoke:wave-executor"
+  },
+  {
+    "name": "wave-transcript-tail",
+    "command": "node \"${CLAUDE_PLUGIN_ROOT}\"/scripts/lib/wave-transcript-tail.mjs --tail",
+    "description": "FA-1 wave supervision — tails live subagent transcripts of the OWN session and emits stagnation_detected(source:tail) to .orchestrator/metrics/events.jsonl (#1114)",
+    "when": "on-skill-invoke:wave-executor"
   }
 ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "3.22.0",
+  "version": "3.23.0",
   "description": "Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.",
   "type": "module",
   "homepage": "https://session-orchestrator.com",

package/pi/prompts/journey-audit.md

@@ -0,0 +1,12 @@
+---
+description: Outside-in product audit as a deep session — 7 read-only roles check what the site promises against what the code does, what a user experiences, what arrives by mail, and what the data says is used. Writes a dossier; needs a per-repo journey-manifest.
+argument-hint: "[manifest-path]"
+---
+
+# /journey-audit
+
+Use the Session Orchestrator command definition at `commands/journey-audit.md`.
+
+Arguments: $@
+
+Read that command file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/rules/_index.md

@@ -30,9 +30,17 @@ baseline project type (`nextjs-saas`, `express-service`, `docker-service`,
 
 ## always-on (vendored to every consumer repo)
 
-- `always-on/parallel-sessions.md` — PSA-001/002/003/004 multi-session discipline
+- `always-on/parallel-sessions.md` — PSA-001..007 multi-session discipline (detect / pause / destructive-ops / commit / STATE.md lock / grep-verification / subagent git-write ban)
 - `always-on/commit-discipline.md` — atomic commits, stage-by-name, no `git add .`
 - `always-on/npm-quality-gates.md` — the typecheck + test + lint triad before commit
+- `always-on/verification-before-completion.md` — VBC-001..005: no completion claim without fresh, quoted verification evidence
+- `always-on/receiving-review.md` — RCR-001..009: the 6-step review-handling pattern, four-class finding triage, push-back posture
+- `always-on/ask-via-tool.md` — AUQ-001..006: route before you ask; structured options over prose question lists
+- `always-on/test-value.md` — TV-001..005: name the bug a test catches, or do not write it; deletion is a feature
+- `always-on/build-value.md` — BV-001..004: the seven-rung build ladder, the four protections never simplified away
+- `always-on/cross-session-messaging.md` — CSM-001..005: messaging is transport, not shared state; no permission laundering
+- `always-on/loop-and-monitor.md` — LM-001..008: routing between `/goal`, Workflows, Channels, Monitor, `/loop`, and Routines
+- `always-on/bash-harness-pitfalls.md` — six false-green shell-harness failure classes (path-scoped via its own `globs:`/`paths:` frontmatter)
 
 ## opt-in-stack (vendored on match)