@event4u/agent-config 9.24.0 → 9.26.0

package/src/scripts/lint_skill_descriptions.ts

@@ -44,6 +44,17 @@
  * construction and wake up exactly when a new skill lands close to an existing
  * one. That is the point.
  *
+ * A seventh check runs on EVERY skill and is neither absence nor presence — it
+ * is a prohibition:
+ *
+ *   (g) preemption-phrase  — the description claims priority over a sibling, or
+ *                            instructs activation regardless of the request.
+ *                            Unlike (a)-(f), this defect harms OTHER skills: it
+ *                            wins turns that belonged to them, and the loss is
+ *                            invisible at the source. See PREEMPTION_PATTERNS
+ *                            for why every pattern is anchored on the directive
+ *                            rather than on a vocabulary word.
+ *
  * Deterministic, static-config only. Allowlist mirrors lint_skill_originality:
  * `lint_skill_descriptions_allowlist.json`, capped at 20 (autonomous-execution
  * allowlist-growth antipattern — over-cap means the linter is wrong).
@@ -78,6 +89,62 @@ const CONDITION_RE =
 const IMPERATIVE_LEAD_RE =
     /^["'`]*\s*(write|author|convert|review|run|add|build|generate|create|fix|wire|detect|analy[sz]e|optimi[sz]e|draft|extract|route|turn|produce|score|consolidate|rate|model|estimate|plan|check|audit|ship|emit|render|guide|poll|capture|explain|map|prepare|handle|manage|track|compare|validate|verify|enforce|choose|pick|enumerate|investigate|format|scaffold|design|define|describe|gate|block|refactor|migrate|transcribe|summari[sz]e|orchestrate|surface|propose|walk|stress-test|red-team|challenge|bootstrap|seed|install|deploy|package|split|merge|condense|harvest|evaluate|assess|diagnose|reproduce|trace|inspect|lint|test)/i;
 
+/**
+ * (g) Preemption phrases — a description that argues for itself against the
+ * rest of the catalogue.
+ *
+ * Every other check here asks whether a description carries ENOUGH signal.
+ * This one is the opposite: a description claiming priority over a sibling, or
+ * instructing activation regardless of the request, degrades routing **globally
+ * and invisibly**. It does not misroute its own skill — it wins turns that
+ * belonged to other skills, and the loss surfaces as those skills mysteriously
+ * under-firing. The sweep behind this check found the class live in a shipped
+ * third-party description and in a second suite's own catalogue.
+ *
+ * Every pattern is anchored on the **directive**, never on a vocabulary word,
+ * and that is the whole design. A first pass keyed on the words alone
+ * (`overrides`, `supersedes`, `for every …`) returned three hits on this corpus
+ * and **all three were false positives**: `override-management` manages
+ * overrides, `decision-review` asks whether an ADR should be superseded, and
+ * `prediction-pool-optimizer` answers "every question" in a prediction pool.
+ * Those are subjects, not claims. The patterns below therefore require the
+ * shape of an instruction to the router (`always use`, `use this instead of`,
+ * `this skill takes precedence`), which no domain noun produces.
+ */
+const PREEMPTION_PATTERNS: ReadonlyArray<readonly [string, RegExp]> = [
+    [
+        'unconditional activation',
+        /\b(?:always|invariably|unconditionally)\s+(?:use|load|apply|run|activate|invoke|prefer)\b/i,
+    ],
+    [
+        'activation regardless of the request',
+        /\b(?:regardless of|no matter)\s+(?:the|what|which)\b|\b(?:for|on)\s+(?:every|all|any)\s+(?:request|turn|prompt|conversation|session)s?\b|\beven if not (?:asked|requested)\b/i,
+    ],
+    [
+        'priority over a sibling',
+        /\b(?:use|load|apply|invoke|prefer)\s+(?:this|these|it)\b[^.;]{0,60}?\b(?:instead of|rather than|over|in preference to)\b/i,
+    ],
+    [
+        'authority claim over the catalogue',
+        /\bthis (?:skill|one|artifact)\s+(?:takes precedence|outranks|supersedes|overrides|wins)\b|\b(?:takes precedence over|outranks)\s+(?:all|any|every)\b/i,
+    ],
+    [
+        'load-order claim',
+        /\b(?:before|prior to)\s+(?:any|all)\s+other\s+(?:skill|tool|rule)s?\b|\bload (?:this )?first\b/i,
+    ],
+];
+
+/** The first preemption claim in a description, or null. */
+function preemptionPhrase(desc: string): { kind: string; match: string } | null {
+    for (const [kind, rx] of PREEMPTION_PATTERNS) {
+        const m = rx.exec(desc);
+        if (m) {
+            return { kind: kind as string, match: m[0] };
+        }
+    }
+    return null;
+}
+
 interface Violation {
     slug: string;
     code:
@@ -86,7 +153,8 @@ interface Violation {
         | 'triggers-are-name'
         | 'no-routing-signal'
         | 'clustered-no-sibling-routing'
-        | 'clustered-no-quoted-phrase';
+        | 'clustered-no-quoted-phrase'
+        | 'preemption-phrase';
     detail: string;
 }
 
@@ -204,6 +272,22 @@ function analyseSkill(slug: string, fm: Record<string, string>, siblings: readon
         });
     }
 
+    // (g) a claim of priority over the rest of the catalogue. Unlike (a)-(d),
+    // this defect harms OTHER skills, so it is checked on every skill and is
+    // never scoped to a cluster — a preemption phrase costs turns regardless of
+    // whether the router already had a near-neighbour to confuse it with.
+    const preemption = preemptionPhrase(desc);
+    if (preemption) {
+        out.push({
+            slug,
+            code: 'preemption-phrase',
+            detail:
+                `description claims ${preemption.kind} ("${preemption.match}") — a description ` +
+                'argues for its own routing conditions, never against its siblings; this wins ' +
+                'turns that belonged to other skills and the loss is invisible at the source',
+        });
+    }
+
     // (e) + (f) fire ONLY for skills the canonical tool put in a cluster.
     if (siblings.length > 0) {
         const unrouted = siblings.filter((s) => !desc.includes(s));
@@ -332,4 +416,4 @@ if (path.resolve(process.argv[1] ?? '') === path.resolve(_HERE)) {
     process.exit(main(process.argv.slice(2)));
 }
 
-export { analyseSkill, normalize, triggerPhrases, main };
+export { analyseSkill, normalize, triggerPhrases, preemptionPhrase, main };

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}`]);

package/src/scripts/schemas/review-findings.schema.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "review-findings.schema.json",
+  "title": "Review findings",
+  "description": "ONE findings shape for both review tracks. All six external reviewers of 9.18.1 converged on a single ask: the R2 gate hand-parses Markdown and carries `unbalanced-fence` and `malformed-row` as first-class violation kinds — i.e. it has defect classes FOR ITS OWN PARSER. This schema is deliberately NOT a new format: it is the shape `self_review_gate.ts` already emits under `--findings-out` and `check_finding_dispositions.ts` already hand-validates in code, lifted into a file both tracks can point at. Inventing a second JSON shape here would have been the exact fragmentation the reviewers complained about.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "findings"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "schema_version": {
+      "enum": [
+        1
+      ],
+      "description": "Pinned. `check_finding_dispositions.parse_ledger` already rejects anything else, so this is a promotion of an existing check rather than a new constraint. Spelled as a one-member `enum` rather than `const`: the repo's own Draft-07 subset validator (validate_frontmatter.ts) enforces `enum` and silently ignores `const`, so `const` here would have been a pin nothing checked."
+    },
+    "release": {
+      "type": "string",
+      "description": "Version the ledger belongs to. Present on the release-findings ledger (agents/evidence/release-findings/<version>.json); absent on a bare --findings-out emission, which is why it is not required here."
+    },
+    "findings": {
+      "type": "array",
+      "description": "May be empty. An empty array is an honest null, not a missing field — the distinction the Markdown track spells with its own §2.3 line. The item shape is INLINED rather than `$ref`-ed for the same measured reason: the subset validator does not resolve `$ref`, so a referenced definition would have validated nothing.",
+      "items": {
+        "type": "object",
+        "required": [
+          "severity",
+          "kind",
+          "title"
+        ],
+        "additionalProperties": true,
+        "properties": {
+          "finding_id": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{12}$",
+            "description": "First 12 hex of sha256(`kind|title|file`), per findingId() in self_review_gate.ts. Stable across runs, which is what lets the disposition ledger key on it. NOT required: an in-flight finding may not have been keyed yet, and requiring it would make the schema reject the shape the model returns before the gate stamps it."
+          },
+          "severity": {
+            "enum": [
+              "critical",
+              "high",
+              "medium",
+              "low"
+            ],
+            "description": "The JSON track's four levels. The Markdown track's own severity vocabulary is a superset in spirit but a different list; mapping between them is a caller's job, not this schema's — see the mapping note in the description of `kind`."
+          },
+          "kind": {
+            "enum": [
+              "security",
+              "claim",
+              "correctness",
+              "style"
+            ],
+            "description": "Finding class. Load-bearing for the id: findingId() hashes kind|title|file, so a kind change is a new finding rather than an edit of the old one."
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 300,
+            "description": "Truncated at 300 by parseFindings() in self_review_gate.ts; the bound is pinned here so a producer cannot emit a title the consumer will silently cut."
+          },
+          "detail": {
+            "type": "string",
+            "maxLength": 2000,
+            "description": "Truncated at 2000 by parseFindings(). Same reasoning as `title`."
+          },
+          "file": {
+            "type": "string",
+            "description": "Repo-relative path. Optional because a finding can be about the change as a whole; findingId() folds an absent file to the empty string so the id stays stable either way."
+          },
+          "status": {
+            "enum": [
+              "open",
+              "fixed",
+              "accepted_risk",
+              "false_positive"
+            ],
+            "description": "Disposition. `fixed` / `false_positive` / `accepted_risk` are the three terminal states check_finding_dispositions accepts; `open` is the initial state. NOTE the underscore spelling — the Markdown track writes `accepted-risk` with a hyphen in its Status cell, and the two vocabularies are deliberately not unified here: renaming either would break committed artefacts on that track."
+          },
+          "rationale": {
+            "type": "string",
+            "description": "Why the disposition. Required by check_finding_dispositions for a non-`fixed` terminal status; enforced there rather than here because the requirement is conditional on the workflow stage, not on the document."
+          },
+          "verified_by": {
+            "type": "string",
+            "description": "Who or what confirmed the disposition."
+          },
+          "date": {
+            "type": "string",
+            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+            "description": "ISO calendar date of the disposition."
+          }
+        }
+      }
+    }
+  }
+}

package/src/scripts/schemas/rule.schema.json

@@ -18,6 +18,16 @@
       "enum": ["package", "project"],
       "default": "package"
     },
+    "decision_impact": {
+      "type": "string",
+      "enum": ["overrides-model-default", "encodes-house-choice", "already-complied-with"],
+      "description": "What is at stake when this rule fires — distinct from `type`, which is a DELIVERY class (how the rule reaches the model). `overrides-model-default`: the model's base behaviour is wrong here, so the rule is load-bearing. `encodes-house-choice`: the model would make *a* defensible choice but not *our* choice. `already-complied-with`: the model does this unprompted — the one value that permits removal, and therefore the one carrying an evidence bar (`decision_impact_evidence`, enforced by lint_decision_impact). OPTIONAL by design: classifying all 111 rules in one batch is exactly the shape that trips check_kernel_prefix_stability, so it lands on new rules and on rules touched for another reason."
+    },
+    "decision_impact_evidence": {
+      "type": "string",
+      "minLength": 20,
+      "description": "Required when `decision_impact: already-complied-with`, forbidden otherwise. A pointer a reviewer can follow to the observation that the model complies without this rule — an eval report, a PR discussion, a trajectory sample. The bar exists because that classification is what permits deleting a rule, and 'the model probably does this anyway' is the cheapest possible way to remove a floor that was working precisely because nothing had crossed it."
+    },
     "description": {
       "type": "string",
       "minLength": 1,

package/src/shared/interactiveContext.ts

@@ -0,0 +1,98 @@
+/**
+ * Is there a human at the other end of this execution?
+ *
+ * Phase 4 of `road-to-zero-ceremony-settings`: *"Skip cleanly in non-TTY, CI,
+ * and headless contexts: no file, defaults, no questions, ever."* A settings
+ * question posed where nobody can answer it is not a question — it is either a
+ * hang or a silently-taken default wearing a prompt's clothes.
+ *
+ * WHY THIS MODULE EXISTS RATHER THAN A FOURTH INLINE CHECK. The tree already
+ * carries several CI-detection shapes that disagree:
+ *
+ * - `set && !== '0'` — `src/cli/firstRunNotice.ts`, `src/cli/initRouting.ts`
+ * - truthy only — `src/scripts/install.ts`, `src/scripts/release.ts`
+ * - exact match — `src/scripts/_lib/exec_evidence.ts` (`'true' | '1'`)
+ * - widest, three variables — `src/scripts/reach_doctor.ts`
+ *   (`CI`, `GITHUB_ACTIONS`, `AGENT_CONFIG_CI`)
+ *
+ * This module takes the **widest** shape, because the failure modes are
+ * asymmetric: a false "interactive" hangs an automated run or fabricates a
+ * consent, while a false "non-interactive" merely declines to ask and takes a
+ * conservative default — which is the documented behaviour anyway.
+ *
+ * It deliberately does NOT rewrite those four call sites. Their behaviour is
+ * correct for what they gate (a printed notice, a browser launch), and
+ * converting them here would be a drive-by change to code this concern does not
+ * own. The divergence is recorded rather than repaired — see the roadmap note on
+ * Phase 4 step 3.
+ *
+ * Pure — the environment and the TTY flags are arguments, never read from
+ * `process` inside the predicate, so a test never depends on the machine it
+ * runs on.
+ */
+
+/** Why an execution cannot host a question. `null` means it can. */
+export type NonInteractiveReason =
+    | 'ci'
+    | 'no-ui-requested'
+    | 'not-a-tty'
+    | 'headless';
+
+export interface SessionProbe {
+    /** `process.env`, or a fixture. */
+    env: NodeJS.ProcessEnv;
+    /** `process.stdin.isTTY === true`. */
+    stdinTty: boolean;
+    /** `process.stdout.isTTY === true`. */
+    stdoutTty: boolean;
+    /**
+     * A display-less environment (SSH without forwarding, Linux without
+     * `DISPLAY`). Supplied by the caller because probing it is platform work,
+     * and `src/cli/commands/uiServe.ts` already owns that probe.
+     */
+    headless?: boolean;
+}
+
+/**
+ * The CI variables this predicate honours, widest-first.
+ *
+ * A variable counts as set when it is present and not the literal `0` — the
+ * `set && !== '0'` convention already used by the first-run notice, kept so a
+ * consumer who exports `CI=0` to mean "not CI" is believed.
+ */
+const CI_ENV_KEYS = ['CI', 'GITHUB_ACTIONS', 'AGENT_CONFIG_CI'] as const;
+
+function _flagSet(env: NodeJS.ProcessEnv, key: string): boolean {
+    const raw = (env[key] ?? '').trim();
+    return raw !== '' && raw !== '0';
+}
+
+/**
+ * The reason this execution may not ask, or `null` when a human is reachable.
+ *
+ * Order is deliberate and is the order a reader should think in: an explicit
+ * request not to be asked outranks a capability probe, and CI outranks
+ * everything because a CI run that asks is a CI run that hangs.
+ */
+export function nonInteractiveReason(probe: SessionProbe): NonInteractiveReason | null {
+    for (const key of CI_ENV_KEYS) {
+        if (_flagSet(probe.env, key)) {
+            return 'ci';
+        }
+    }
+    if (_flagSet(probe.env, 'AGENT_CONFIG_NO_UI')) {
+        return 'no-ui-requested';
+    }
+    if (!probe.stdinTty || !probe.stdoutTty) {
+        return 'not-a-tty';
+    }
+    if (probe.headless === true) {
+        return 'headless';
+    }
+    return null;
+}
+
+/** Convenience inverse — `true` when a question is answerable. */
+export function isInteractiveSession(probe: SessionProbe): boolean {
+    return nonInteractiveReason(probe) === null;
+}

package/src/shared/nicknamePrefill.ts

@@ -0,0 +1,96 @@
+/**
+ * What to put in the nickname field before the user types anything.
+ *
+ * Phase 4 step 2 of `road-to-zero-ceremony-settings`: *"Ask the nickname once,
+ * prefilled from git user name then `$USER`, so accepting is one keypress."*
+ * `src/rules/settings-ask-protocol.md` states the chain and closes it with a
+ * negation — **"Never `$USER` alone."**
+ *
+ * WHY THIS MODULE EXISTS. The rule shipped that chain; the one surface that
+ * actually prefills shipped a different one. `src/server/routes/ping.ts` read
+ * `userInfo().username` and nothing else — precisely the `$USER`-alone shape the
+ * rule forbids. A rule and the code it describes disagreeing is drift, not a
+ * preference, so the chain now has exactly one implementation and both the
+ * server route and the tests read it from here.
+ *
+ * WHY GIT COMES FIRST. `$USER` is a login handle (`mathiasberg`); `git config
+ * user.name` is the name the human chose to be called by (`Mathias Berg`). The
+ * whole point of the prefill is that accepting costs one keypress, and that only
+ * holds when the prefilled value is the one they would have typed. Note the
+ * lookup is deliberately NOT `--local`: the merged config includes
+ * `~/.gitconfig`, so the wizard still finds a name when it runs outside a repo.
+ *
+ * Pure: the git lookup is injected, so the resolver is a function of its probe
+ * alone and a test never depends on the machine it runs on — the same shape as
+ * `interactiveContext.ts` and `settingsConsent.ts`. The Node-side half (running
+ * git, falling back to `userInfo()`) lives in `src/server/nicknameResolver.ts`,
+ * because `src/shared/**` may not import Node built-ins and the lint enforces it.
+ *
+ * @see src/server/nicknameResolver.ts — the impure half
+ * @see src/rules/settings-ask-protocol.md § Worked example — the nickname
+ * @see docs/contracts/settings-classes.md
+ */
+
+/**
+ * Where a candidate name came from, so a caller can say so.
+ *
+ * `os-account` is the `userInfo()` floor, and it is a distinct member rather
+ * than a reuse of `env-user` on purpose: the whole claim of the floor is that
+ * its RANK changed (last, not first), and a rank nothing can observe is not a
+ * rank. A caller reporting provenance would otherwise name the wrong rung on
+ * exactly the path the floor exists to serve.
+ *
+ * `none` is a real outcome, not an error: a machine with no git identity, no
+ * `USER` and no resolvable account is unusual but legal, and the ask still
+ * works — it just starts empty.
+ */
+export type NicknameSource =
+    | 'git-user-name'
+    | 'env-user'
+    | 'env-username'
+    | 'os-account'
+    | 'none';
+
+export interface NicknamePrefill {
+    /** The prefill value, or `''` when nothing resolved. */
+    name: string;
+    source: NicknameSource;
+}
+
+export interface NicknameProbe {
+    /** `process.env`, or a fixture. */
+    env: NodeJS.ProcessEnv;
+    /**
+     * `git config user.name`, or `undefined` when git is absent, unconfigured,
+     * or too slow. Injected so the resolver stays pure.
+     */
+    gitUserName?: string | undefined;
+}
+
+/** Trim, and treat a whitespace-only value as absent. */
+function _clean(value: string | undefined): string {
+    return (value ?? '').trim();
+}
+
+/**
+ * The prefill for the nickname ask, following the documented chain.
+ *
+ * Order is the rule's, and the negation at the end of it is the load-bearing
+ * part: `$USER` is a fallback, never the first answer.
+ */
+export function nicknamePrefill(probe: NicknameProbe): NicknamePrefill {
+    const git = _clean(probe.gitUserName);
+    if (git !== '') {
+        return { name: git, source: 'git-user-name' };
+    }
+    const user = _clean(probe.env['USER']);
+    if (user !== '') {
+        return { name: user, source: 'env-user' };
+    }
+    // Windows spells it differently; the rule names it explicitly.
+    const username = _clean(probe.env['USERNAME']);
+    if (username !== '') {
+        return { name: username, source: 'env-username' };
+    }
+    return { name: '', source: 'none' };
+}