@event4u/agent-config 9.30.0 → 9.32.0

package/src/scripts/language_mirror_hook.ts

@@ -72,7 +72,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
-import { atomic_write_json } from "./hooks/state_io.js";
+import { atomic_write_json, atomic_write_text, is_replay_mode } from "./hooks/state_io.js";
 import { readHookStdin } from "./hooks/hook_stdin.js";
 import { humanAuthoredLead, isSyntheticPrompt } from "./_lib/prompt_shape.js";
 
@@ -92,7 +92,21 @@ export const STATE_FILE = path.join("agents", "state", "language-mirror.json");
  * re-emit that follows it (round-5 § 6.1). Its existence — not a counter — is
  * what bounds the re-injection to ONE per compaction event.
  */
-export const PIN_LOST_MARKER = path.join("agents", "state", "language-mirror.pin-lost");
+export const PIN_LOST_DIR = path.join("agents", "state", "language-mirror.pin-lost");
+
+/**
+ * Per-SESSION marker path. R2 finding 10: a single shared marker made the
+ * mechanism cross-talk between concurrent sessions — the normal shape for this
+ * repo's worktree workflow. Session B's next `post_tool_use` consumed the marker
+ * session A's compaction had set, so A never got the one re-emit that is the
+ * whole point of the mechanism, and B got a pin notice derived from whichever
+ * session last wrote the shared state. An empty id degrades to a literal
+ * bucket rather than colliding silently.
+ */
+export function pinLostMarker(session_id: string): string {
+  const safe = (session_id || "unknown-session").replace(/[^A-Za-z0-9._-]/g, "_");
+  return path.join(PIN_LOST_DIR, `${safe}.marker`);
+}
 
 type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
 type JsonObject = { [k: string]: JsonValue };
@@ -387,29 +401,68 @@ function _extractPrompt(payload: JsonObject): string {
   return "";
 }
 
-/** Record that compaction is about to drop the context copy of the pin. */
-export function _setPinLost(consumer_root: string): void {
+/** The envelope's session id, or a literal bucket when the host sends none. */
+function _sessionId(envelope: JsonObject): string {
+  const v = envelope["session_id"];
+  return typeof v === "string" && v.trim() !== "" ? v : "unknown-session";
+}
+
+/**
+ * Record that compaction is about to drop the context copy of the pin.
+ *
+ * R2 finding 14: this used to write with a raw `mkdirSync` + `writeFileSync`,
+ * bypassing both conventions the surrounding code follows — the module's own
+ * atomic writer, and the `is_replay_mode()` guard that keeps a replayed event
+ * from mutating live state. A replayed compaction wrote the marker for real.
+ */
+/**
+ * The pre-R2 layout wrote a single FILE at the path that is now a DIRECTORY.
+ * A consumer upgrading with a leftover legacy marker — compaction happened, no
+ * `post_tool_use` followed — hits `EEXIST` on the mkdir and `ENOTDIR` on the
+ * write (reproduced against Node), which the catch below swallows as
+ * "observability only". The failure would then be silent AND permanent for that
+ * root: `existsSync` always false, so the mechanism is dead with no diagnostic.
+ * One unlink at the moment of collision, and only when the path is a file.
+ */
+function _migrateLegacyMarker(consumer_root: string): void {
+  const legacy = path.join(consumer_root, PIN_LOST_DIR);
+  try {
+    if (fs.statSync(legacy).isFile()) {
+      fs.rmSync(legacy, { force: true });
+    }
+  } catch {
+    // Absent, already a directory, or unreadable — nothing to migrate.
+  }
+}
+
+export function _setPinLost(consumer_root: string, session_id: string): void {
+  if (is_replay_mode()) return;
+  _migrateLegacyMarker(consumer_root);
   try {
-    const target = path.join(consumer_root, PIN_LOST_MARKER);
-    fs.mkdirSync(path.dirname(target), { recursive: true });
-    fs.writeFileSync(target, new Date().toISOString());
+    atomic_write_text(path.join(consumer_root, pinLostMarker(session_id)), new Date().toISOString());
   } catch {
     // Observability only — a failed marker write costs one un-restored pin,
     // never a broken turn.
   }
 }
 
-export function _pinLost(consumer_root: string): boolean {
+export function _pinLost(consumer_root: string, session_id: string): boolean {
   try {
-    return fs.existsSync(path.join(consumer_root, PIN_LOST_MARKER));
+    return fs.existsSync(path.join(consumer_root, pinLostMarker(session_id)));
   } catch {
     return false;
   }
 }
 
-function _clearPinLost(consumer_root: string): void {
+function _clearPinLost(consumer_root: string, session_id: string): void {
+  // R2 round 2, finding 8: the replay guard covered only the WRITE. A replayed
+  // `post_tool_use` therefore deleted a live marker it was forbidden to create,
+  // and the real session lost the single re-emit this whole mechanism exists to
+  // deliver — replay destroying live state while blocked from writing it, which
+  // is worse than either direction alone.
+  if (is_replay_mode()) return;
   try {
-    fs.rmSync(path.join(consumer_root, PIN_LOST_MARKER), { force: true });
+    fs.rmSync(path.join(consumer_root, pinLostMarker(session_id)), { force: true });
   } catch {
     // If it cannot be cleared the next tool call re-emits once more. One
     // duplicate line is the failure mode; a loop is not, because the marker
@@ -422,8 +475,8 @@ function _clearPinLost(consumer_root: string): void {
  * and only when a pin actually exists — an absent or undetermined pin is not
  * an obligation, and inventing one here would be worse than the gap.
  */
-export function _reEmitAfterCompaction(consumer_root: string): number {
-  if (!_pinLost(consumer_root)) {
+export function _reEmitAfterCompaction(consumer_root: string, session_id: string): number {
+  if (!_pinLost(consumer_root, session_id)) {
     return EXIT_ALLOW;
   }
   const previous = _loadState(path.join(consumer_root, STATE_FILE));
@@ -431,7 +484,7 @@ export function _reEmitAfterCompaction(consumer_root: string): number {
   const source: PinSource = previous.source === "system-locale" ? "system-locale" : "prompt";
   // Clear FIRST: if the write below throws, the marker must not survive to
   // re-fire on every subsequent tool call — that is the shape § 6.2 refuses.
-  _clearPinLost(consumer_root);
+  _clearPinLost(consumer_root, session_id);
   if (language !== "de" && language !== "en") {
     return EXIT_ALLOW;
   }
@@ -479,11 +532,11 @@ export function run(
   // and this marker is the entire difference between the two.
   const event = typeof envelope["event"] === "string" ? envelope["event"] : "";
   if (event === "pre_compact") {
-    _setPinLost(options.consumer_root);
+    _setPinLost(options.consumer_root, _sessionId(envelope));
     return EXIT_ALLOW;
   }
   if (event === "post_tool_use") {
-    return _reEmitAfterCompaction(options.consumer_root);
+    return _reEmitAfterCompaction(options.consumer_root, _sessionId(envelope));
   }
 
   const prompt = _extractPrompt(payload);

package/src/scripts/measure_turn_end_gate.ts

@@ -11,37 +11,61 @@
  *
  * What it measures, and what it deliberately does NOT:
  *
- *   · FIRE RATE of each detector over every assistant turn in the window.
- *   · For detector B, the CROSS-TAB against `conformance_scan`'s own
- *     independent language check. That scanner reads only the first prose
- *     line and this detector reads the whole stripped reply, so the two are
- *     related instruments, not the same one — which is exactly what makes
- *     the disagreement cells informative.
+ *   · FIRE RATE of each detector PER TURN, over the last assistant text of the
+ *     turn — the population the shipped gate inspects. R2 finding 1: the first
+ *     version scored every assistant ENTRY and published the result as a
+ *     per-turn rate, which inflated the population ~8.6x and scored a
+ *     closing-paragraph detector over mid-turn prose.
+ *   · The independent scanner's own language total, printed for CONTEXT only.
+ *     It is not an agreement figure and no overlap is claimed from it: the two
+ *     instruments read different spans (its first prose line; this one strips
+ *     code/quotes/paths from the reply and then scores lead-first via the same
+ *     classifier), and this script does no per-turn matching between them.
+ *     R2 finding 7 removed the per-session min/max arithmetic that used to
+ *     report disjoint findings of equal count as full agreement.
  *   · It does NOT compute recall against the 20 promissory occurrences the
  *     round-5 audit reported. Those came from subagent transcript READING;
  *     `conformance_scan.ts` states in its own header that promissory
  *     closings are "deliberately NOT scanned", so there is no machine-
  *     readable ground truth to score against. Claiming a recall figure here
  *     would invent one.
+ *   · KNOWN RESIDUAL, R2 finding 8, not fixed here: this script re-derives the
+ *     language pin with `classify` per user entry, while the gate reads the pin
+ *     `language_mirror_hook` persisted — which also applies a system-locale
+ *     fallback and a keep-previous rule. Where those diverge, a turn can move
+ *     between "pinned de", "pinned en" and "no obligation", so detector B's
+ *     rate here is close to but not identical with the gate's. Reaching parity
+ *     means reusing `nextState`, which is a larger change than a measurement
+ *     correction and would itself need re-measuring.
  *
  * Usage:
  *   ./scripts-run src/scripts/measure_turn_end_gate --store <dir> [--limit N]
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import { classify } from './language_mirror_hook.js';
-import { assistantText, isInjectedBody, scanSession, userText } from './conformance_scan.js';
+import { classify, isSyntheticPrompt } from './language_mirror_hook.js';
+import { assistantText, scanSession, userText } from './conformance_scan.js';
 import { detectLanguage, detectPromissory } from './hooks/turn_end_gate_hook.js';
 
 interface Counts {
-    assistant_turns: number;
+    /**
+     * TURNS, not entries. R2 finding 1: the first version incremented a counter
+     * named `assistant_turns` on every assistant entry and ran both detectors on
+     * each one, while the gate only ever evaluates the LAST assistant text of a
+     * turn. A turn with k prose entries contributed k samples to the instrument
+     * and 1 to the gate, so the published "18.0% of turns" was a per-ENTRY rate
+     * wearing a per-turn label — and detector A, a closing-paragraph detector by
+     * construction, was being scored over mid-turn prose.
+     */
+    turns: number;
+    /** Assistant entries seen — kept only to show the ratio the old bug hid. */
+    assistant_entries: number;
     promissory_fires: number;
     language_fires: number;
-    /** Detector B fired AND the scanner also flagged that session-turn. */
-    language_agree: number;
-    /** Detector B fired where the scanner saw nothing — candidate false positives. */
-    language_only: number;
+    /** The independent scanner's own per-session language total, for context. */
+    scanner_language: number;
     sessions: number;
 }
 
@@ -68,11 +92,11 @@ function sessionFiles(store: string, limit: number): string[] {
 
 export function measure(store: string, limit: number): Counts {
     const c: Counts = {
-        assistant_turns: 0,
+        turns: 0,
+        assistant_entries: 0,
         promissory_fires: 0,
         language_fires: 0,
-        language_agree: 0,
-        language_only: 0,
+        scanner_language: 0,
         sessions: 0,
     };
 
@@ -86,20 +110,36 @@ export function measure(store: string, limit: number): Counts {
         c.sessions += 1;
         const sessionId = path.basename(file).slice(0, 8);
 
-        // The scanner's independent verdict for this session, keyed by the
-        // timestamp-free count of language violations. Used only as a
-        // cross-tab total, never as ground truth for this detector.
-        let scannerLanguage = 0;
+        // The independent scanner's own language total for this session,
+        // reported side by side and NOT as agreement — see the header for why
+        // no overlap is derivable from two totals (R2 finding 7).
+        //
+        // A throw is surfaced, not swallowed to zero: swallowing silently
+        // reclassified a whole session's fires as scanner-disagreements.
         try {
-            scannerLanguage = scanSession(sessionId, lines).violations.filter(
+            c.scanner_language += scanSession(sessionId, lines).violations.filter(
                 (v) => v.check === 'language-pin',
             ).length;
-        } catch {
-            scannerLanguage = 0;
+        } catch (err) {
+            process.stderr.write(
+                `measure-turn-end-gate: scanSession failed for ${sessionId} — excluded from the scanner total: ${String(err)}\n`,
+            );
         }
 
         let pinned: 'de' | 'en' | 'und' = 'und';
-        let myLanguage = 0;
+        // The LAST assistant text since the last genuine user prompt. This is
+        // the population the gate inspects; anything else is a different
+        // measurement wearing the same label (R2 finding 1).
+        let pendingReply: string | null = null;
+        let pendingPin: 'de' | 'en' | 'und' = 'und';
+
+        const scoreTurn = (): void => {
+            if (pendingReply === null) return;
+            c.turns += 1;
+            if (detectPromissory(pendingReply) !== null) c.promissory_fires += 1;
+            if (detectLanguage(pendingReply, pendingPin) !== null) c.language_fires += 1;
+            pendingReply = null;
+        };
 
         for (const raw of lines) {
             let entry: Record<string, unknown>;
@@ -111,10 +151,14 @@ export function measure(store: string, limit: number): Counts {
 
             const u = userText(entry);
             if (u !== null) {
-                // A background-task notification occupies the user role but is
-                // not a chat message — the exact shape that made the language
-                // defect invisible. It must never move the pin.
-                if (!isInjectedBody(u)) {
+                // `isSyntheticPrompt`, the SAME filter the gate uses for the
+                // ordinal — not `isInjectedBody`. R2 round 2, finding 10: the
+                // two filters classify differently, and any entry they disagree
+                // about shifts this instrument's turn boundary away from the
+                // gate's own. Population parity is the entire point of this
+                // correction, so the filter has to be the same one.
+                if (!isSyntheticPrompt(u)) {
+                    scoreTurn(); // the previous turn ends here
                     const verdict = classify(u);
                     if (verdict.language !== 'und') pinned = verdict.language;
                 }
@@ -123,39 +167,38 @@ export function measure(store: string, limit: number): Counts {
 
             const a = assistantText(entry);
             if (a === null || a.trim() === '') continue;
-            c.assistant_turns += 1;
-
-            if (detectPromissory(a) !== null) c.promissory_fires += 1;
-            if (detectLanguage(a, pinned) !== null) {
-                c.language_fires += 1;
-                myLanguage += 1;
-            }
+            c.assistant_entries += 1;
+            // Overwrite: only the last one in the turn is the gate's input.
+            pendingReply = a;
+            pendingPin = pinned;
         }
-
-        const agree = Math.min(myLanguage, scannerLanguage);
-        c.language_agree += agree;
-        c.language_only += Math.max(0, myLanguage - scannerLanguage);
+        scoreTurn(); // the transcript's final turn
     }
 
     return c;
 }
 
 export function render(c: Counts): string {
-    const pct = (n: number): string =>
-        c.assistant_turns === 0 ? '0.0' : ((100 * n) / c.assistant_turns).toFixed(1);
+    const pct = (n: number): string => (c.turns === 0 ? '0.0' : ((100 * n) / c.turns).toFixed(1));
     return [
-        `measure-turn-end-gate · ${c.sessions} sessions · ${c.assistant_turns} assistant turns`,
+        `measure-turn-end-gate · ${c.sessions} sessions · ${c.turns} turns · ${c.assistant_entries} assistant entries`,
         '',
         `  detector A (promissory)  fires on ${c.promissory_fires} turns  (${pct(c.promissory_fires)}%)`,
         `  detector B (language)    fires on ${c.language_fires} turns  (${pct(c.language_fires)}%)`,
-        `    of which the independent scanner also flagged: ${c.language_agree}`,
-        `    fired where the scanner saw nothing:           ${c.language_only}`,
         '',
-        '  The second line is the one that matters for a BLOCKING guard: those are',
-        '  the turns this detector would have refused and the other instrument would',
-        '  not. They are candidate false positives, not confirmed ones — the two',
-        '  instruments read different spans (first prose line vs. whole stripped',
-        '  reply), so disagreement is expected in both directions.',
+        '  Rates are per TURN, over the last assistant text of each turn — the same',
+        '  population the shipped gate inspects. The entry count is printed beside',
+        '  the turn count because the first version of this script scored every',
+        '  assistant ENTRY and labelled the result per-turn; the gap between the two',
+        '  numbers is the size of that error.',
+        '',
+        `  For context only, the independent scanner's own language total: ${c.scanner_language}`,
+        '    NOT an agreement figure. The two instruments read different spans (its',
+        '    first prose line vs. this stripped, lead-first-scored reply) and this',
+        '    script does no per-turn matching between them, so no overlap can be claimed from these',
+        '    two totals — the previous version claimed one from per-session min/max',
+        '    arithmetic, which reports disjoint findings of equal count as full',
+        '    agreement.',
         '',
         '  No recall figure for detector A: promissory closings are not machine-',
         '  scanned anywhere in this tree, so there is no ground truth to score.',
@@ -170,7 +213,18 @@ export function main(argv: string[] = process.argv.slice(2)): number {
             store = argv[i + 1]!;
             i += 1;
         } else if (argv[i] === '--limit' && argv[i + 1] !== undefined) {
-            limit = parseInt(argv[i + 1]!, 10);
+            // R2 finding 15: an unvalidated parseInt made `--limit abc` yield
+            // NaN, `slice(0, NaN)` return nothing, and the script exit 2 with
+            // "no .jsonl sessions under <store>" — a real input error reported
+            // as a missing corpus.
+            const parsed = Number.parseInt(argv[i + 1]!, 10);
+            if (!Number.isFinite(parsed) || parsed < 1) {
+                process.stderr.write(
+                    `measure-turn-end-gate: --limit must be a positive integer, got ${JSON.stringify(argv[i + 1])}\n`,
+                );
+                return 2;
+            }
+            limit = parsed;
             i += 1;
         }
     }
@@ -189,6 +243,30 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     return 0;
 }
 
-if (process.argv[1] !== undefined && process.argv[1].includes('measure_turn_end_gate')) {
+// Bundle-safety, same guard as the sibling hook. R2 finding 15: a substring
+// test on argv[1] auto-runs the module when esbuild inlines it into a bundle,
+// where every module shares the bundle's `import.meta.url`.
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) {
+        return false;
+    }
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
     process.exit(main());
 }