@event4u/agent-config 9.25.0 → 9.26.0

package/src/scripts/language_mirror_hook.ts

@@ -33,15 +33,35 @@
  * context does not otherwise contain — which language the human wrote in.
  *
  * State: `agents/state/language-mirror.json`
- *   { "language": "de"|"en"|"und", "detected_at": iso8601,
- *     "prompt_chars": int, "de_markers": int, "en_markers": int,
- *     "session_id": str }
+ *   { "language": "de"|"en"|"und", "source": "prompt"|"system-locale",
+ *     "detected_at": iso8601, "prompt_chars": int, "de_markers": int,
+ *     "en_markers": int, "session_id": str }
  *
  * Undetermined prompts (a bare "1", "ok", a pasted URL) leave a previous pin
  * UNTOUCHED rather than clearing it — a short continuation does not change the
  * conversation's language, and clearing on every terse turn would reproduce the
  * exact drift this hook removes.
  *
+ * FIRST TURN OF A SESSION — the system-locale fallback.
+ *
+ * The keep-previous-pin rule has nothing to keep on the very first prompt. If
+ * that prompt is terse ("weiter", "1", a pasted URL) the verdict is `und`, no
+ * pin is written, and the turn runs with no pin at all — which is the drift
+ * this hook exists to remove, occurring precisely where the conversation has
+ * the least other evidence. So when there is no previous pin AND the prompt is
+ * undetermined, the environment's locale supplies a starting language, recorded
+ * as `source: "system-locale"` so the weaker provenance is legible rather than
+ * indistinguishable from a read of the user's own words.
+ *
+ * A locale pin is a floor, never a ceiling: the FIRST prompt carrying real
+ * markers replaces it, because `source: "prompt"` always wins. That is what
+ * makes "any later explicit statement by the user overrides it" true without a
+ * second mechanism — the ordinary path already outranks the fallback.
+ *
+ * Locales outside the classifier's two languages stay `und` on purpose. Mapping
+ * `fr_FR` to English because the classifier has no French would pin a language
+ * the user never wrote, which is worse than carrying no pin.
+ *
  * Never blocks (`fail_closed: false`, `severity: advisory`). Exit 0 always.
  */
 import fs from "node:fs";
@@ -52,6 +72,13 @@ import { atomic_write_json } from "./hooks/state_io.js";
 import { readHookStdin } from "./hooks/hook_stdin.js";
 
 const EXIT_ALLOW = 0;
+// Severity is taken from the EXIT CODE, not from the `decision` field in the
+// stdout payload. This hook shipped returning EXIT_ALLOW while writing
+// {"decision":"warn", …}, so the dispatcher reduced it to `allow`, emitted
+// nothing, and the pin reached the model on no path — a state write with no
+// delivery, for the audit's largest failure class (626 turns). Round 2, found
+// by tracing the delivery rather than re-reading the unit tests.
+const EXIT_WARN = 2;
 
 export const STATE_FILE = path.join("agents", "state", "language-mirror.json");
 
@@ -68,7 +95,7 @@ function _isObject(v: unknown): v is JsonObject {
  * ("fixe die ci", "mach weiter") where content words carry no signal.
  */
 const DE_MARKERS =
-  /\b(der|die|das|den|dem|und|ist|sind|nicht|kein|keine|mach|mache|bitte|warum|wieso|weshalb|weiter|kannst|sollst|soll|musst|muss|hast|habe|haben|wir|ich|du|dann|noch|auch|schon|wenn|aber|alle|mit|ohne|damit|dass|wurde|werden|gibt|nochmal|erstell|erstelle|erstelle|fehler|regeln|arbeite|analysiere|fixe|nimm|lege|prüfe|pruefe|schau|zeig|mir|dir|sich|eine|einen|einem|einer|vom|zum|zur|beim|im|am)\b|[äöüÄÖÜß]/gi;
+  /\b(der|die|das|den|dem|und|ist|sind|nicht|kein|keine|mach|mache|bitte|warum|wieso|weshalb|weiter|kannst|sollst|soll|musst|muss|hast|habe|haben|wir|ich|du|dann|noch|auch|schon|wenn|aber|alle|mit|ohne|damit|dass|wurde|werden|gibt|nochmal|erstell|erstelle|erstelle|fehler|regeln|arbeite|analysiere|fixe|nimm|lege|prüfe|pruefe|schau|zeig|mir|dir|sich|eine|einen|einem|einer|vom|zum|zur|beim|im)\b|[äöüÄÖÜß]/gi;
 
 /**
  * English function words that a German sentence would not contain. Chosen to
@@ -96,9 +123,45 @@ export interface Classification {
  * Below `MIN_MARKERS` on both sides the verdict is `und` (undetermined) and the
  * caller keeps any previous pin.
  */
+/**
+ * Strip the parts of a prompt that are PASTED rather than written.
+ *
+ * Without this the classifier reproduced the very defect it exists to fix: one
+ * German instruction plus a pasted English stack trace scored `en=18 / de=2`
+ * and pinned English — then asserted emphatically that English was the mirror
+ * target. The maintainer's most common prompt shape is exactly that.
+ */
+export function instructionText(prompt: string): string {
+  const OUTPUT_HEAD =
+    /^\s*(To\s+\S+|remote:|error:|fatal:|hint:|warning:|npm ERR!|Error:|Traceback|Exception|[A-Za-z]*Error\b|at\s+\S+:\d+|\s{4,}\S|[-+]{3}\s|@@\s|\$\s|>\s|\||\d+\s*\|)/i;
+  const kept: string[] = [];
+  let inPaste = false;
+  for (const line of prompt.replace(/```[\s\S]*?```/g, "\n\n").split("\n")) {
+    if (!line.trim()) {
+      // A blank line ends a pasted block — this is how pastes actually look,
+      // and it is what makes the filter work on a MULTI-LINE trace whose
+      // continuation lines carry no marker of their own.
+      inPaste = false;
+      kept.push(line);
+      continue;
+    }
+    if (OUTPUT_HEAD.test(line)) {
+      inPaste = true;
+      continue;
+    }
+    if (inPaste) {
+      continue;
+    }
+    kept.push(line);
+  }
+  return kept.join("\n");
+}
+
+
 export function classify(prompt: string): Classification {
-  const de = (prompt.match(DE_MARKERS) ?? []).length;
-  const en = (prompt.match(EN_MARKERS) ?? []).length;
+  const text = instructionText(prompt);
+  const de = (text.match(DE_MARKERS) ?? []).length;
+  const en = (text.match(EN_MARKERS) ?? []).length;
   if (de < MIN_MARKERS && en < MIN_MARKERS) {
     return { language: "und", de_markers: de, en_markers: en };
   }
@@ -110,9 +173,97 @@ const LANGUAGE_NAME: Record<Exclude<Verdict, "und">, string> = {
   en: "English",
 };
 
+/**
+ * How a pin came to be — the provenance the roadmap's Phase 4 asks for.
+ *
+ * `prompt` means the user's own words carried the markers. `system-locale`
+ * means they did not and the environment answered instead. The distinction is
+ * load-bearing rather than decorative: a locale pin is the one a user may
+ * legitimately want to contradict, and the notice says which it is so that
+ * contradicting it does not require guessing where it came from.
+ */
+export type PinSource = "prompt" | "system-locale";
+
+/**
+ * The env vars that carry a POSIX locale, most specific first.
+ *
+ * `LC_ALL` overrides everything by definition; `LC_MESSAGES` governs the
+ * language of messages specifically, which is exactly this question; `LANG` is
+ * the fallback for both. `LANGUAGE` is deliberately last — it is a GNU
+ * extension holding a colon-separated PREFERENCE LIST, so it answers a
+ * different question and only its first entry is comparable.
+ */
+const LOCALE_ENV_KEYS = ["LC_ALL", "LC_MESSAGES", "LANG", "LANGUAGE"] as const;
+
+/**
+ * Map an environment locale onto the classifier's verdict space.
+ *
+ * Returns `und` for a locale the classifier cannot mirror, for `C`/`POSIX`
+ * (which name no human language), and for an unset environment. Only the
+ * primary subtag is read: `de_AT.UTF-8`, `de-CH`, and `de` are one answer.
+ */
+export function systemLocaleVerdict(env: NodeJS.ProcessEnv = process.env): Verdict {
+  for (const key of LOCALE_ENV_KEYS) {
+    const raw = (env[key] ?? "").trim();
+    if (!raw) {
+      continue;
+    }
+    // `LANGUAGE` may hold `de:en:fr`; the leading entry is the preference.
+    const first = raw.split(":")[0] ?? "";
+    // Strip the territory and codeset: `de_AT.UTF-8@euro` → `de`.
+    const primary = (first.split(/[._@-]/)[0] ?? "").toLowerCase();
+    if (primary === "c" || primary === "posix" || !primary) {
+      continue;
+    }
+    if (primary === "de") {
+      return "de";
+    }
+    if (primary === "en") {
+      return "en";
+    }
+    // A locale the classifier has no markers for. Stop rather than fall
+    // through to a less specific variable: the user HAS stated a language and
+    // it is neither of the two, so the honest answer is "no pin".
+    return "und";
+  }
+  return "und";
+}
+
+/**
+ * The one-line notice the dispatcher surfaces for this turn.
+ *
+ * A locale-sourced pin says so and says how to override it. A prompt-sourced
+ * pin keeps its original wording, because that line is what the conformance
+ * audit measured and a reworded pin is a changed instrument.
+ */
+export function noticeText(language: Exclude<Verdict, "und">, source: PinSource): string {
+  const name = LANGUAGE_NAME[language];
+  if (source === "system-locale") {
+    return (
+      `Reply language for this turn: ${name} — the prompt carried no language ` +
+      `markers, so this fell back to the system locale. Write in another ` +
+      `language and the next turn follows the prompt instead.`
+    );
+  }
+  return `Reply language for this turn: ${name}.`;
+}
+
 /** The context block handed back to the model for this turn. */
-export function pinText(language: Exclude<Verdict, "und">): string {
+export function pinText(language: Exclude<Verdict, "und">, source: PinSource = "prompt"): string {
   const name = LANGUAGE_NAME[language];
+  if (source === "system-locale") {
+    return (
+      `<language-pin>\n` +
+      `No language markers were found in this turn's prompt and no language was ` +
+      `pinned yet, so the mirror target falls back to the environment's locale: ` +
+      `${name}. Use it for EVERY user-visible token this turn.\n\n` +
+      `This is the WEAKER of the two provenances — it reflects the machine, not ` +
+      `the user's own words. The first prompt that carries real markers replaces ` +
+      `it. Do not treat it as a standing preference, and do not argue with the ` +
+      `user about it if they write in something else.\n` +
+      `</language-pin>`
+    );
+  }
   return (
     `<language-pin>\n` +
     `The user submitted this turn's prompt in ${name}. That is the mirror target ` +
@@ -130,6 +281,7 @@ export function pinText(language: Exclude<Verdict, "und">): string {
 
 export interface PinState extends JsonObject {
   language: Verdict;
+  source: PinSource;
   detected_at: string;
   prompt_chars: number;
   de_markers: number;
@@ -157,13 +309,30 @@ export function nextState(
   prompt_chars: number,
   session_id: string,
   now: string,
+  locale: Verdict = "und",
 ): PinState | null {
   if (classification.language === "und") {
     // Terse continuation ("1", "ok", "weiter") — keep whatever was pinned.
-    return null;
+    if (previous.language === "de" || previous.language === "en") {
+      return null;
+    }
+    // FIRST turn and nothing to keep: the locale is better than no pin at all.
+    if (locale === "und") {
+      return null;
+    }
+    return {
+      language: locale,
+      source: "system-locale",
+      detected_at: now,
+      prompt_chars,
+      de_markers: classification.de_markers,
+      en_markers: classification.en_markers,
+      session_id,
+    };
   }
   return {
     language: classification.language,
+    source: "prompt",
     detected_at: now,
     prompt_chars,
     de_markers: classification.de_markers,
@@ -182,7 +351,10 @@ function _extractPrompt(payload: JsonObject): string {
   return "";
 }
 
-export function run(stdin_text: string, options: { consumer_root: string }): number {
+export function run(
+  stdin_text: string,
+  options: { consumer_root: string; env?: NodeJS.ProcessEnv },
+): number {
   let envelope: JsonObject = {};
   if (stdin_text.trim()) {
     try {
@@ -205,9 +377,25 @@ export function run(stdin_text: string, options: { consumer_root: string }): num
   const target = path.join(options.consumer_root, STATE_FILE);
   const previous = _loadState(target);
   const classification = classify(prompt);
-  const next = nextState(previous, classification, prompt.length, session_id, new Date().toISOString());
+  const next = nextState(
+    previous,
+    classification,
+    prompt.length,
+    session_id,
+    new Date().toISOString(),
+    // Injectable so the suite can pin a locale instead of inheriting the
+    // machine's — a test whose verdict depends on the developer's `LANG` is a
+    // test that passes here and fails in CI for reasons unrelated to the diff.
+    systemLocaleVerdict(options.env ?? process.env),
+  );
 
   const effective = next?.language ?? (previous.language as Verdict | undefined);
+  // A state file written before `source` existed carries only what the old
+  // version could produce — a prompt reading. Absent is therefore `prompt`,
+  // never "unknown": treating it as unknown would reword the audited notice
+  // for every pre-existing session.
+  const effectiveSource: PinSource =
+    next?.source ?? (previous.source === "system-locale" ? "system-locale" : "prompt");
   if (next) {
     try {
       atomic_write_json(target, next);
@@ -218,8 +406,9 @@ export function run(stdin_text: string, options: { consumer_root: string }): num
 
   if (effective === "de" || effective === "en") {
     process.stdout.write(
-      `${JSON.stringify({ decision: "warn", reason: `Reply language for this turn: ${LANGUAGE_NAME[effective]}.`, additional_context: pinText(effective) })}\n`,
+      `${JSON.stringify({ decision: "warn", reason: noticeText(effective, effectiveSource), additional_context: pinText(effective, effectiveSource) })}\n`,
     );
+    return EXIT_WARN;
   }
   return EXIT_ALLOW;
 }

package/src/scripts/lint_abstraction_thresholds.ts

@@ -16,10 +16,18 @@
  *    `abstraction-thresholds` (the canon citation). A bare number is drift.
  *    A heading is its own block; a threshold-stating heading is satisfied
  *    when the block immediately below it carries the citation.
- * 2. PINNING — the six deliberate sites are pinned to their current
- *    number + scope (SITES), and the canon's four table rows are pinned
- *    (CANON_ROWS). Changing either side without the other is a finding:
- *    the canon and its citing sites move together or not at all.
+ * 2. PINNING — every deliberate site is pinned to its current scope
+ *    (SITES), and the canon's four table rows are pinned (CANON_ROWS).
+ *    Changing either side without the other is a finding: the canon and
+ *    its citing sites move together or not at all.
+ *
+ *    The site COUNT is deliberately not written here. This comment and
+ *    the one above `check_pins` both said "six" while `SITES` held seven
+ *    (two entries share `component-oriented-and-oop-development.md`, so
+ *    six distinct files became seven pins). Nothing pinned the literal —
+ *    the test derives its expectation from `SITES.length` — so the number
+ *    was free to rot, and did. Read the count off `SITES`; do not restate
+ *    it in prose that no gate checks.
  *
  * ## Regex tuning record (2026-08-03, measured against the real tree)
  *
@@ -65,12 +73,37 @@ export const CANON_CITATION = 'abstraction-thresholds';
 export const THRESHOLD_VERB = /\b(extract\w*|componenti[sz]\w*|abstraction)\b/i;
 
 /**
- * … and (b) states a numeric repetition bar. Three branches:
+ * … and (b) states a numeric repetition bar. Four branches:
  * cardinal count + repetition-noun · ordinal (repetition|occurrence only —
- * see the tuning record above) · `≥ N` + repetition-noun.
+ * see the tuning record above) · `≥ N` + repetition-noun · a repetition VERB
+ * carrying its count as a word-form adverb (`once` / `twice` / `thrice`).
+ *
+ * The fourth branch closes a measured hole: "extract when duplicated twice"
+ * states a real numeric bar and matched NOTHING. The cardinal branch needs a
+ * numeral from its own alternation immediately before a repetition-noun, and in
+ * that phrasing the count IS the adverb — there is no numeral and no noun. So
+ * the most natural English phrasing of the bar was the one shape that passed
+ * the gate silently.
+ *
+ * It is verb-anchored on purpose. A bare `\b(once|twice|thrice)\b` would fire on
+ * any block that happens to say "run it twice" near the word "extract"; binding
+ * the adverb to a duplication verb keeps the qualitative prose the tuning record
+ * protects finding-free, and adds no allowlist.
+ *
+ * The verb set is narrow because a wider one was MEASURED and rejected. A first
+ * cut also accepted `appears|occurs|used`, ran against the real tree, and
+ * returned exactly one hit: `gated-reach/SKILL.md`'s reddit-parsing gotcha, "one
+ * id **appears twice**, once as the real comment and once as a … stub". Its block
+ * is the whole Gotcha bullet list, which separately contains "extraction" — in
+ * the yt-dlp sense, an unrelated meaning of the word. Both halves fired on
+ * vocabulary coincidence. Dropping the three weak verbs kills that hit without an
+ * allowlist and still catches the reported phrasing (`duplicat\w+` covers
+ * "duplicated twice"). Widening the verb set again means re-measuring: the block
+ * granularity is blank-line-coarse, so a weak verb only has to co-occur with a
+ * homonym of "extract" somewhere in the same paragraph run.
  */
 export const NUMERIC_REPETITION =
-    /(\b(one|two|three|four|five|\d+)\s*(\+|×|x)?\s*(real\s+)?(repetitions?|repeats?|times|uses?|duplications?|occurrences?)\b)|(\b(second|third|fourth)\s+(real\s+)?(repetitions?|occurrences?)\b)|(≥\s*\d+\s*(real\s+)?(repetitions?|repeats?|times|uses?|duplications?|occurrences?))/i;
+    /(\b(one|two|three|four|five|\d+)\s*(\+|×|x)?\s*(real\s+)?(repetitions?|repeats?|times|uses?|duplications?|occurrences?)\b)|(\b(second|third|fourth)\s+(real\s+)?(repetitions?|occurrences?)\b)|(≥\s*\d+\s*(real\s+)?(repetitions?|repeats?|times|uses?|duplications?|occurrences?))|(\b(duplicat\w+|repeat\w+|recur\w+)\s+(only\s+)?(once|twice|thrice)\b)/i;
 
 /** The canon's four table rows — all must match CANON_FILE. */
 export const CANON_ROWS: ReadonlyArray<{ row: RegExp; why: string }> = [
@@ -249,7 +282,7 @@ export function scan_citations(repoRoot: string): { findings: Finding[]; scanned
     return { findings, scanned };
 }
 
-/** Bidirectional pins: canon rows + the six citing sites. */
+/** Bidirectional pins: canon rows + every citing site in SITES. */
 export function check_pins(repoRoot: string): Finding[] {
     const findings: Finding[] = [];
 

package/src/scripts/lint_agents_layout.ts

@@ -63,6 +63,7 @@ const ALLOWED_SOURCE_DIRS: ReadonlySet<string> = new Set([
     'notes',        // legacy; new files go to evidence/notes/
     'reports',      // legacy; new files go to evidence/reports/ (see agents-layout.md)
     'overrides',    // * consumer
+    'proposals',    // * consumer — curated self-improvement proposals, tracked
     'recruit-sessions',
     'reference',
     'roadmap-assets',
@@ -88,6 +89,7 @@ const CONSUMER_EXPECTED_ENTRIES: ReadonlySet<string> = new Set([
     // Optional but legitimate consumer entries (will not trigger warnings)
     'knowledge',
     'memory',
+    'proposals',
     'roadmaps',
     'tmp',
     'tmp.old',

package/src/scripts/lint_hook_manifest.ts

@@ -148,6 +148,35 @@ function _check_concerns(manifest: YamlObject, errors: string[]): Set<string> {
     if (!_isFile(path.join(REPO_ROOT, script))) {
       errors.push(`concerns.${name}: script not found at '${script}'`);
     }
+    // `tools:` — the optional per-concern tool filter the dispatcher applies
+    // in-process (`_concern_matches_tool`). Validated because the failure mode
+    // is silent: the dispatcher fails toward RUNNING the concern on anything
+    // malformed, so a typo (`tool:`, a bare string, `[]`) would look like a
+    // working filter while filtering nothing. An unvalidated key is worse than
+    // no key.
+    if ("tools" in spec) {
+      const tools = spec["tools"];
+      if (!Array.isArray(tools)) {
+        errors.push(
+          `concerns.${name}: 'tools' must be a list of tool names ` +
+            `(got ${pyTypeName(tools)}) — omit the key for "every event"`,
+        );
+      } else if (tools.length === 0) {
+        errors.push(
+          `concerns.${name}: 'tools' is an empty list — omit the key, or use ` +
+            `["*"], rather than a filter that reads as "no tools"`,
+        );
+      } else {
+        for (const t of tools) {
+          if (typeof t !== "string" || t.trim() === "") {
+            errors.push(
+              `concerns.${name}: 'tools' entries must be non-empty strings, ` +
+                `got ${pyTypeName(t)}`,
+            );
+          }
+        }
+      }
+    }
     names.add(name);
   }
   return names;

package/src/scripts/memory_learn_hook.ts

@@ -29,6 +29,20 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+// This hook is the first in the tree to import from `src/shared/`, and its
+// contract is fail-open — but the `try/catch` that delivers that lives in
+// `main()`, so an import-time throw would escape it. The concern is real and
+// the answer is measured rather than assumed: esbuild INLINES both modules into
+// `dist/hooks/dispatch.js` (verified by building the bundle to a scratch path
+// and grepping for `consentVerdict` and `withheld-machine-inferred`), so the
+// installed path performs no runtime module resolution at all. Both modules are
+// also pure declarations with zero top-level side effects, so there is nothing
+// at import time that can throw. If either fact stops holding — a dynamic
+// import, a module-level read — the fail-open guarantee weakens and this
+// import has to move inside the guard.
+import type { SettingsClass } from '../shared/settingsClasses.js';
+import { consentVerdict, type ConsentVerdict } from '../shared/settingsConsent.js';
+
 import {
     buildSidecar,
     LESSONS_NAME,
@@ -40,18 +54,54 @@ const SETTINGS_FILE = '.agent-settings.yml';
 /** Wall-clock budget for the whole aggregation (ms). */
 export const BUDGET_MS = 2000;
 
+/** The key this hook is gated on. */
+export const LEARN_KEY = 'memory.learn_on_session_end';
+
 /**
- * Minimal `.agent-settings.yml` reader for `memory.learn_on_session_end`
- * (same hand-rolled mini-parser pattern as the sibling hooks — no YAML
- * dependency in the hook hot path).
+ * The key's class, pinned rather than parsed.
+ *
+ * `classOfPath` would give the same answer, but only after reading and parsing
+ * `docs/contracts/settings-classes.md` — a multi-hundred-row markdown file — on
+ * every session teardown, which is exactly the cost the 2 s budget above exists
+ * to avoid. The drift risk a hardcoded constant carries is neutralised the
+ * cheap way instead: `tests/scripts/memory_learn_hook.test.ts` asserts the
+ * contract still classifies this key `B`, so a reclassification reds CI rather
+ * than silently unbinding the gate.
  */
-export function enabled(root: string): boolean {
+export const LEARN_KEY_CLASS: SettingsClass = 'B';
+
+/**
+ * Whether `memory.learn_on_session_end` reads as enabled, or `undefined` when
+ * the file or the key is absent (same hand-rolled mini-parser pattern as the
+ * sibling hooks — no YAML dependency in the hook hot path).
+ *
+ * Normalised strictly: the literal `true` and nothing else enables the hook. A
+ * crude parser must not let `yes` / `1` / `maybe` read as a permission, and
+ * `isConservativeDefault` would treat any non-empty string as permissive — so
+ * the normalisation happens here, before the consent check, not inside it.
+ *
+ * WHAT THE TRI-STATE DOES AND DOES NOT SAY. `undefined` means "no answer was
+ * found" — the key is absent, the file is absent, OR the file could not be read
+ * at all (permissions, a directory at the path, an I/O error). `false` means
+ * EITHER a deliberate `false` OR a present-but-malformed scalar. So there are
+ * two collapses, not one: a user who writes `learn_on_session_end: yes` and a
+ * user whose settings file is unreadable both get a silent, permanent no-op
+ * with no diagnostic.
+ *
+ * The fail-safe direction is deliberate in both cases — a hook that writes
+ * files must not be enabled by a value nobody typed on purpose, nor by a file
+ * nobody could read. The ambiguity is the cost, and it is stated here rather
+ * than implied by a "raw scalar" this function does not actually return.
+ * Diagnosing either shape belongs to `settings:check`, not to a fail-open
+ * teardown hook.
+ */
+export function readLearnValue(root: string): boolean | undefined {
     const p = path.join(root, SETTINGS_FILE);
     let text: string;
     try {
         text = fs.readFileSync(p, 'utf8');
     } catch {
-        return false;
+        return undefined;
     }
     let inMemory = false;
     for (const rawLine of text.split('\n')) {
@@ -69,7 +119,60 @@ export function enabled(root: string): boolean {
             if (m) return m[1] === 'true';
         }
     }
-    return false;
+    return undefined;
+}
+
+/**
+ * The consent verdict for running the aggregation.
+ *
+ * This is the first production caller of `consentVerdict` — Phase 5 step 4 of
+ * `road-to-zero-ceremony-settings` asks the consent-gated action to verify the
+ * recorded DECISION rather than read the bare value, and this session_end
+ * concern is the only action in the tree that a class-B key actually gates.
+ *
+ * `handEdited: true` is a fact about the path, not a shortcut: the file read
+ * here is the PROJECT-LOCAL `.agent-settings.yml`, which
+ * `docs/contracts/settings-classes.md` names as a file only a human writes —
+ * `settings:set` and the GUI both write the user-global file instead. So on
+ * this path a permissive value IS the recorded decision and the verdict is
+ * `granted`.
+ *
+ * WHAT THIS CHANGES TODAY: nothing observable. Stated plainly because the
+ * opposite was claimed first and it was wrong. With `cls` a constant,
+ * `handEdited` a constant `true`, and the value already reduced to a boolean by
+ * `readLearnValue`, every discriminating input to `consentVerdict` is fixed, so
+ * `enabled()` returns exactly what the previous `=== 'true'` read returned —
+ * including for `yes` / `1` / `on`, which that read already rejected. The
+ * normalisation is not new and this call did not narrow it.
+ *
+ * WHAT IT DOES BUY, which is smaller than it sounds and worth being exact
+ * about: the obligation is expressed in code instead of prose, so
+ * `consentVerdict` has a real caller and stops being a library nobody invokes;
+ * the class binding is asserted against the contract by a test, so a
+ * reclassification reds CI (it does NOT re-route the hook at runtime — the
+ * class is a hardcoded constant); and the day this hook learns to read the
+ * user-global file, the sidecar check is already the thing standing in front of
+ * it rather than a change someone must remember to make.
+ *
+ * KNOWN GAP, recorded rather than fixed here: the hook reads only the
+ * project-local file, so a user who enables this in the GUI — which writes the
+ * user-global file plus the provenance sidecar — never triggers it. Reading the
+ * user-global file is where the sidecar's `auto-detected`-refusing power would
+ * actually discriminate, but it is also a behaviour change (a hook that writes
+ * files would start firing for users it does not fire for today), so it belongs
+ * to a decision rather than to this step. Filed in the roadmap.
+ */
+export function learnConsent(root: string): ConsentVerdict {
+    return consentVerdict({
+        cls: LEARN_KEY_CLASS,
+        value: readLearnValue(root) ?? false,
+        handEdited: true,
+    });
+}
+
+/** `true` only when the recorded decision permits the aggregation. */
+export function enabled(root: string): boolean {
+    return learnConsent(root) === 'granted';
 }
 
 /** Run the aggregation. Returns the one-line marker to emit, or null. */

package/src/scripts/pr_url_reminder_hook.ts

@@ -66,6 +66,20 @@ function _isObject(v: unknown): v is JsonObject {
 }
 
 /** Return [tool_name, command_text] from a tool-event payload. */
+/**
+ * Unwrap the dispatcher envelope.
+ *
+ * The dispatcher hands every concern `{event, platform, payload: <native>}`,
+ * but this hook read `tool_name` / `tool_response` off the TOP level. Fed a raw
+ * payload it worked; fed the real envelope it found nothing and returned ALLOW.
+ * Measured 2026-08-06: standalone 624 bytes of output, through the built
+ * dispatcher 0 bytes — the reminder had never fired in production.
+ */
+function _unwrap(envelope: JsonObject): JsonObject {
+  const inner = envelope["payload"];
+  return _isObject(inner) ? inner : envelope;
+}
+
 function _extractCommand(payload: JsonObject): [string | null, string | null] {
   const toolRaw = payload["tool_name"] ?? payload["toolName"] ?? payload["tool"];
   const tool = typeof toolRaw === "string" ? toolRaw : null;
@@ -124,12 +138,13 @@ export function main(): number {
     return EXIT_ALLOW;
   }
 
-  const [tool, command] = _extractCommand(envelope);
+  const inner = _unwrap(envelope);
+  const [tool, command] = _extractCommand(inner);
   if (!_isPrCreate(tool, command)) {
     return EXIT_ALLOW;
   }
 
-  const match = _PR_URL.exec(_toolOutput(envelope));
+  const match = _PR_URL.exec(_toolOutput(inner));
   if (match === null) {
     return EXIT_ALLOW; // create attempted but no URL produced (failed / dry-run) — do not nag
   }

package/src/scripts/release.ts

@@ -767,11 +767,48 @@ function watch_pr_checks(branch: string): void {
  * 2026-08-03, 9.15.0). Same-branch commits are never ours to drop, so the
  * recovery is merge-and-retry, never force-push.
  */
+/**
+ * True when git rejected the push because the remote ref moved ahead — the
+ * ONLY failure the merge-and-retry recovery below can repair.
+ *
+ * git's wording for this is stable across versions: the hint is `fetch first`
+ * / `Updates were rejected`, and the ref line carries `[rejected]` with
+ * `non-fast-forward` or `fetch first`.
+ */
+export function _is_non_fast_forward(stderr: string, stdout: string): boolean {
+    const text = `${stderr}\n${stdout}`;
+    return (
+        /\[rejected\]/i.test(text) &&
+        /(non-fast-forward|fetch first|behind its remote counterpart)/i.test(text)
+    );
+}
+
 function push_release_branch(branch: string): void {
-    const first = run(['git', 'push', '-u', REMOTE, branch], { check: false });
+    const first = run(['git', 'push', '-u', REMOTE, branch], { check: false, capture: true });
     if (first.returncode === 0) {
+        process.stdout.write(first.stdout);
+        process.stderr.write(first.stderr);
         return;
     }
+
+    // A push can fail for many reasons — a pre-push hook refusing the commit,
+    // no credentials, a protected branch. Only ONE of them is repaired by
+    // fetch+merge+retry, and the recovery's first step (`git fetch <branch>`)
+    // exits 128 for a branch that was never pushed. Taking that path
+    // unconditionally replaced every real error with
+    // `couldn't find remote ref <branch>` — measured 2026-08-06 on 9.26.0,
+    // where a pre-push gate rejection surfaced as a git-fetch crash and cost
+    // an hour of diagnosis pointed at the wrong layer.
+    if (!_is_non_fast_forward(first.stderr, first.stdout)) {
+        process.stdout.write(first.stdout);
+        process.stderr.write(first.stderr);
+        die(
+            `push of ${branch} failed (exit ${first.returncode}) and the remote ref did not move — ` +
+                'this is not the fetch-and-retry case. The push output above is the real error ' +
+                '(a pre-push gate, credentials, or branch protection); fix that and re-run.',
+        );
+    }
+
     process.stdout.write(`↻  ${REMOTE}/${branch} moved — integrating and retrying push\n`);
     run(['git', 'fetch', REMOTE, branch]);
     run(['git', 'merge', '--no-edit', `${REMOTE}/${branch}`]);