@event4u/agent-config 16.5.0 → 17.0.0

package/src/scripts/_lib/session_register.ts

@@ -52,7 +52,9 @@
  *    millisecond. Nothing here provides exclusion, and no later feature may be
  *    built on it as if it did. `sessions:claim` refusing to WRITE a claim a peer
  *    holds is a consistency check on its own write, not exclusion: it protects
- *    the record from being false, never the peer from being duplicated.
+ *    the record from being false, never the peer from being duplicated. The
+ *    exclusion lives beside the register, not in it: `_lib/roadmap_slug_lock.ts`
+ *    creates one file per slug with `wx`, which `sessions:claim` takes first.
  * 3. **The claim is per SESSION, and the bridge file has to be too.** The
  *    paragraph above rules `agents/runtime/state/` out for the register and the
  *    same argument applies to the claim that feeds it: one shared file per
@@ -73,6 +75,7 @@ import path from 'node:path';
 
 import { write_atomic } from './fs_atomic.js';
 import { git_common_dir } from './git_common_dir.js';
+import { type EnvMap, event4u_root } from './user_global_paths.js';
 
 /** Directory name under the common git dir. Never tracked; git ignores unknown
  *  directories inside `.git` by construction. */
@@ -278,6 +281,26 @@ export function register_dir(workspace_root: string): string | null {
     return common === null ? null : path.join(common, REGISTER_DIRNAME);
 }
 
+/**
+ * The MACHINE-wide register directory, under the user-global event4u root.
+ *
+ * `register_dir` above is anchored to a git common dir, so it answers "is a
+ * session live on this repository" and cannot answer anything else. The
+ * unattended upgrade needs the other question: swapping the global binary
+ * breaks the hooks of **every** running session, not only the ones in the tree
+ * the swap happens to run from, so the register that gates it has to be
+ * machine-scoped.
+ *
+ * Unlike `register_dir` this never returns `null`: the global root always
+ * resolves (an env override, else `~/.event4u/agent-config`), and a missing
+ * directory is a legitimate "nothing registered" that `any_live_session`
+ * reports as false rather than as an error. Does **not** create the directory —
+ * writers do.
+ */
+export function global_register_dir(env?: EnvMap | null): string {
+    return path.join(event4u_root(env), 'runtime', 'sessions');
+}
+
 /** ISO-8601 UTC at seconds precision, matching the chat-history stamp format. */
 export function iso_now(now: Date = new Date()): string {
     return now.toISOString().replace(/\.\d{3}Z$/, '+00:00');
@@ -435,6 +458,33 @@ export function foreign_live_records(
     return read_live_records(dir, options).filter((r) => safe_stem(r.session_id) !== own);
 }
 
+/**
+ * Is any session live in `dir`, excluding `session_id` when one is given?
+ *
+ * The question `upgrade --unattended` asks before it swaps the global install.
+ * Deliberately a boolean: the caller refuses or proceeds, and the identity of
+ * the peer does not change that answer — reporting it would invite a reader to
+ * decide which peers are safe to break, which is the judgement this gate
+ * exists to remove.
+ *
+ * Fails OPEN on an unreadable record: `read_live_records` drops a record it
+ * cannot parse, so a corrupt file reads as no session rather than as a live
+ * one, and the swap may proceed. On its own that is the wrong direction for
+ * this question; what protects a live session is the swap's other gates — the
+ * lock and the age checks — and the caller states which it relies on.
+ */
+export function any_live_session(
+    dir: string,
+    session_id?: string | null,
+    now: Date = new Date(),
+): boolean {
+    const records =
+        session_id === undefined || session_id === null
+            ? read_live_records(dir, { now })
+            : foreign_live_records(dir, session_id, { now });
+    return records.length > 0;
+}
+
 // ---------------------------------------------------------------------------
 // Collisions — and why `branch` alone was the wrong axis
 // ---------------------------------------------------------------------------

package/src/scripts/_lib/session_tag.ts

@@ -0,0 +1,51 @@
+/**
+ * The session tag — a deterministic 16-character prefix of a session id's
+ * SHA-256, and the sentinel used when there is no id to derive one from.
+ *
+ * WHY THIS IS ITS OWN MODULE. The tag lives logically in `chat_history.ts`,
+ * which defines the JSONL schema that carries it. But `chat_history.ts` is a
+ * 2,300-line module whose transitive closure is about 121 KB of the hook
+ * dispatch bundle, and `hooks/interruption_ledger_hook.ts` — a concern on a
+ * different event — needs five lines of it. One `import { derive_session_tag }`
+ * was enough to pull the whole closure into a bundle every hook event loads.
+ *
+ * So the five lines moved here and `chat_history.ts` re-exports them: its
+ * public API is unchanged, every existing caller keeps working, and the
+ * dependency edge that defeated the extraction is gone.
+ *
+ * Byte-parity note: `fingerprint` normalises exactly as the retired Python
+ * `chat_history.py` did — collapse every whitespace run to one space, strip the
+ * ends, hash the UTF-8 of that. The normalisation is part of the on-disk
+ * contract, not a convenience, so it is reproduced here verbatim rather than
+ * tidied.
+ */
+import { createHash } from 'node:crypto';
+
+const _WS_RE = /\s+/g;
+
+/** Characters of the SHA-256 hex digest a session tag keeps. */
+export const SESSION_ID_LEN = 16;
+
+/** The tag for an entry whose session id is absent or unreadable. */
+export const SESSION_ID_UNKNOWN = '<unknown>';
+
+/** The tag for a row written before session tagging existed. */
+export const SESSION_ID_LEGACY = '<legacy>';
+
+function _strip(s: string): string {
+    return s.replace(/^\s+/u, '').replace(/\s+$/u, '');
+}
+
+/** The full SHA-256 hex digest of `value` after whitespace normalisation. */
+export function fingerprint(value: string): string {
+    const normalized = _strip((value || '').replace(_WS_RE, ' '));
+    return createHash('sha256').update(normalized, 'utf-8').digest('hex');
+}
+
+/** The session tag for `session_id`, or {@link SESSION_ID_UNKNOWN} when it is empty. */
+export function derive_session_tag(session_id: string): string {
+    if (!session_id) {
+        return SESSION_ID_UNKNOWN;
+    }
+    return fingerprint(session_id).slice(0, SESSION_ID_LEN);
+}

package/src/scripts/_lib/settings_removed_keys.ts

@@ -63,6 +63,22 @@ type SettingsDict = Record<string, unknown>;
  * default; what a consumer who had set a non-default value loses is named by
  * the reason.
  *
+ * The 2026-10-20 batch (ADR-293) is a fifth doctrine: keys that WERE read and
+ * whose decision is now COMPUTED rather than configured. They are not
+ * default-neutral — `lean_projection.mode: delivery` written user-globally
+ * thinned a real machine — which is why they ship in a major and why
+ * `_lib/projection_key_migration.ts` reads the two values that meant "keep the
+ * full layer" one more time and converts them into the install receipt's pin.
+ * Every other prior value is dropped with a line. When that window closes the
+ * migration module goes and these entries are what remains.
+ *
+ * Release class: A settings key may be removed or renamed in a minor release
+ * only when no consumer project can rely on it — default-neutral and
+ * derivable, proven by a named test; any other removal or rename ships only in
+ * a major, and a renamed key's alias is dropped only in a major. An entry here
+ * is what tells a consumer the key went; it is not the licence for a minor —
+ * {@link MINOR_REMOVAL_PROOFS} is, and the cut reads it.
+ *
  * Every reason string must name what decides INSTEAD, never just "removed".
  * Exported so `lint_settings_classes` can check the deletion side of the
  * surface: a reason that names no replacement, or an entry whose key is live in
@@ -137,8 +153,22 @@ export const REMOVED_KEYS: ReadonlyMap<string, string> = new Map([
     ['consistency.cross_source', 'the cross-source-consistency rule, always on; batching and the no-cheap-questions floor bound the noise'],
     ['subagents.downshift', 'the model_tier each sub-task declares; downshift is always on'],
     ['ai_team.suppress_setup_hint', 'nothing: the one-line team-mode setup hint is always shown'],
+    // 2026-10-20 — the projection keys (ADR-293, road-to-a-setup-that-decides-itself Phase 4)
+    ['lean_projection.mode', 'the computed layer-form decision (_lib/layer_form_decision.ts), plus `install --full` and src/config/layer-form-brakes.json as the two brakes. For one release window an installer converts a leftover `eager-all` into the install receipt pin and drops any other value, saying which (_lib/projection_key_migration.ts); the project tree reads the package-owned src/config/project-tree-form.json, never this key'],
+    ['lean_projection.hosts', 'THINNABLE_HOSTS in _lib/lean_projection_mode.ts and the per-host row in src/config/host-injection-effect.json; no reader of this key remains'],
+    ['projection.rule_workspaces', 'consumerRuleWorkspaces() in _lib/scoped_projection.ts, which derives the consumer workspace set from src/config/discovery/packs.yml — every id minus `agent-config-maintainer` — so a new pack reaches consumers without a settings edit'],
 ]);
 
+/**
+ * Keys removed or renamed below a major, each mapped to the named test that
+ * proves no consumer project can rely on it, as `<test file>::<it title>`.
+ * The release cut (`release_settings_surface.ts`) refuses a non-major target
+ * whose carried removal has no entry here, or whose entry names a test the
+ * tree does not contain. Empty until a minor needs it: the keys removed before
+ * this map existed shipped under the rule as it was then written.
+ */
+export const MINOR_REMOVAL_PROOFS: ReadonlyMap<string, string> = new Map<string, string>();
+
 /** Keys already warned about in THIS process — the "once per run" dedupe. */
 const _warnedRemovedKeys = new Set<string>();
 

package/src/scripts/_lib/settings_renamed_keys.ts

@@ -7,9 +7,12 @@
  * `false` to the shipped default, which is the opposite of accepting the old
  * key — so the two maps stay separate even though both warn once.
  *
- * An entry is dropped one minor after it lands. The new key always wins when
- * one layer carries both: a reader who has already migrated is not overridden
- * by a stale line they forgot to delete.
+ * Release class: A settings key may be removed or renamed in a minor release
+ * only when no consumer project can rely on it — default-neutral and
+ * derivable, proven by a named test; any other removal or rename ships only in
+ * a major, and a renamed key's alias is dropped only in a major. The new key
+ * always wins when one layer carries both: a reader who has already migrated
+ * is not overridden by a stale line they forgot to delete.
  *
  * Its own module rather than more lines in `agent_settings.ts`, which sits
  * three lines under the 1500-line source ceiling — a sixty-line addition there
@@ -18,6 +21,17 @@
 
 export type SettingsLayer = Record<string, unknown>;
 
+/**
+ * The release rule for removing or renaming a settings key, as the one string
+ * every statement of it repeats (blocker `what-a-minor-may-remove`, owner
+ * answer (c), 2026-10-14). Exported so the warning below prints it and the
+ * cut names it, rather than each carrying its own paraphrase.
+ */
+export const SETTINGS_REMOVAL_RULE =
+    'A settings key may be removed or renamed in a minor release only when no consumer project can ' +
+    'rely on it — default-neutral and derivable, proven by a named test; any other removal or rename ' +
+    "ships only in a major, and a renamed key's alias is dropped only in a major.";
+
 export const RENAMED_KEYS: ReadonlyMap<string, string> = new Map([
     ['planning.challenge_on_create', 'planning.closure_pass'],
 ]);
@@ -69,8 +83,8 @@ export function applyRenamedKeys<T extends SettingsLayer>(layer: T): T {
         if (_warned.has(oldKey)) continue;
         _warned.add(oldKey);
         process.stderr.write(
-            `⚠️  settings: \`${oldKey}\` was renamed to \`${newKey}\`. The old key still ` +
-                `works for one minor; rename it in your .agent-settings.yml.\n`,
+            `⚠️  settings: \`${oldKey}\` was renamed to \`${newKey}\`; the old key still works. ` +
+                `${SETTINGS_REMOVAL_RULE} Rename it in your .agent-settings.yml.\n`,
         );
     }
     return layer;

package/src/scripts/_lib/skill_catalogue.ts

@@ -180,7 +180,37 @@ export const DEFAULT_CATALOGUE_ROOTS = [
  *
  * @param home override for the user's home; production callers omit it.
  */
-export function resolveSkillCatalogueRoots(workspaceRoot: string, home?: string): string[] {
+export interface CatalogueRootOptions {
+    /**
+     * A package root whose own `dist/agent-src/skills` is used as a LAST
+     * resort — only when no workspace or host root resolved at all.
+     *
+     * WHY IT IS A PARAMETER AND NOT A FOURTH CANDIDATE. Reproduced before it
+     * was added: a workspace carrying only another host's directory, with an
+     * empty home, resolves to ZERO roots — so a shell on such a machine gets
+     * `no_catalogue` even though the installed package ships 300 skills two
+     * directories away. That is a real gap for a SHELL path, which has nowhere
+     * else to go.
+     *
+     * It is NOT a gap for the MCP handler, and that is why this is opt-in. The
+     * package tree always exists wherever the handler runs, so folding it in
+     * unconditionally would make `status: no_catalogue` unreachable — and that
+     * status is the one thing standing between "I could not read a catalogue"
+     * and "no skill covers this task", which is the conclusion
+     * `missing-skill-recovery` exists to prevent. A caller asks for the
+     * fallback when it has no second answer; the handler does not ask.
+     */
+    packageFallback?: string;
+}
+
+/** Where a package-root fallback looks for the shipped catalogue. */
+export const PACKAGE_FALLBACK_CATALOGUE_ROOT = path.join('dist', 'agent-src', 'skills');
+
+export function resolveSkillCatalogueRoots(
+    workspaceRoot: string,
+    home?: string,
+    opts: CatalogueRootOptions = {},
+): string[] {
     const userHome = home ?? process.env['HOME'] ?? os.homedir();
     const candidates = [
         ...PROJECT_CATALOGUE_ROOTS.map((c) => path.join(workspaceRoot, c)),
@@ -188,19 +218,29 @@ export function resolveSkillCatalogueRoots(workspaceRoot: string, home?: string)
     ];
     const roots: string[] = [];
     const seen = new Set<string>();
+    const readable = (abs: string): boolean => {
+        try {
+            if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) return false;
+            return fs.readdirSync(abs).length > 0;
+        } catch {
+            // Unreadable candidate is not a match; try the next.
+            return false;
+        }
+    };
     for (const abs of candidates) {
         // A workspace that IS the home directory would offer `~/.claude/skills`
         // twice and rank every skill in it twice. Cheap to exclude, and the
         // duplicate would be invisible in the output.
         if (seen.has(abs)) continue;
         seen.add(abs);
-        try {
-            if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) continue;
-            if (fs.readdirSync(abs).length === 0) continue;
-            roots.push(abs);
-        } catch {
-            // Unreadable candidate is not a match; try the next.
-        }
+        if (readable(abs)) roots.push(abs);
+    }
+    // LAST, and only when the list is empty. Appending it to a non-empty list
+    // would rank the package's own projection beside a consumer's real
+    // catalogue and duplicate every shipped skill under two roots.
+    if (roots.length === 0 && opts.packageFallback) {
+        const abs = path.join(opts.packageFallback, PACKAGE_FALLBACK_CATALOGUE_ROOT);
+        if (!seen.has(abs) && readable(abs)) roots.push(abs);
     }
     return roots;
 }
@@ -876,14 +916,17 @@ export interface ProjectionModeCounts {
     /** Pack ids active by default under `scoped`, sorted. */
     activePacks: string[];
     /**
-     * Skills a `projection.mode: tiered` install deploys natively — those
-     * predicted to reach the model WITH their description. `null` when no tier
-     * split exists on this machine, which is the common case and is NOT zero.
+     * Skills predicted to reach the model WITH their description, from the
+     * per-machine tier split. `null` when no split exists on this machine,
+     * which is the common case and is NOT zero. The `tiered` projection mode
+     * that consumed this number was retired on 2026-10-20 (ADR-293); the split
+     * itself still informs the listing-budget advisory and the MCP catalogue.
      */
     tierACount: number | null;
     /**
-     * Skills `tiered` withholds from the native catalogue; still served by the
-     * MCP recovery tools. `null` under the same condition as `tierACount`.
+     * Skills predicted to reach the model WITHOUT their description; served by
+     * the MCP recovery tools whatever the host catalogue carries. `null` under
+     * the same condition as `tierACount`.
      */
     tierBCount: number | null;
 }
@@ -950,13 +993,12 @@ export function formatProjectionModes(
     ];
     if (counts.tierACount === null || counts.tierBCount === null) {
         lines.push(
-            '  tiered:      no split on this machine (agents/runtime/state/skill-tiers.json',
-            '               absent) — not zero, unmeasured. `tiered` ships the full surface',
-            '               until a split exists.',
+            '  tier split:  none on this machine (agents/runtime/state/skill-tiers.json',
+            '               absent) — not zero, unmeasured.',
         );
     } else {
         lines.push(
-            `  tiered:      tier A ${counts.tierACount} native + tier B ${counts.tierBCount} ` +
+            `  tier split:  tier A ${counts.tierACount} described + tier B ${counts.tierBCount} ` +
                 `MCP-only = ${counts.tierACount + counts.tierBCount}`,
         );
         if (counts.tierACount + counts.tierBCount !== counts.legacyAll) {
@@ -1133,7 +1175,6 @@ export interface MigrationEligibility {
         | 'observation-not-comparable'
         | 'no-truncation-observed'
         | 'already-scoped'
-        | 'already-tiered'
         | 'below-observed-skill-volume';
     /** Populated only when eligible, for the message. */
     droppedEntries?: number;
@@ -1156,17 +1197,17 @@ export interface MigrationEligibility {
  */
 export function migrationEligibility(
     host: string,
-    resolvedMode: 'scoped' | 'legacy-all' | 'tiered',
+    resolvedMode: 'scoped' | 'legacy-all',
     currentSkillCount: number,
     limits: ReadonlyMap<string, KnownHostLimit>,
 ): MigrationEligibility {
     if (resolvedMode === 'scoped') return { eligible: false, reason: 'already-scoped' };
-    // `tiered` already withholds skills from the native catalogue, so an offer to
-    // migrate to `scoped` has nothing to buy. It gets its OWN reason rather than
-    // reusing `already-scoped`: the two narrow on different axes (packs vs the
-    // host's listing budget), and a caller reading the reason should be able to
-    // tell which one the install is actually on.
-    if (resolvedMode === 'tiered') return { eligible: false, reason: 'already-tiered' };
+    // There were three modes until 2026-10-20. `tiered` carried its own
+    // `already-tiered` reason because it narrowed on a different axis — the
+    // host's listing budget rather than the pack set. It was retired at
+    // `measured-null` (ADR-293, step 4.5) and a leftover value now resolves to
+    // `legacy-all`, so such an install reaches the real eligibility test below
+    // instead of being told it is already narrowed.
     const limit = limits.get(host);
     if (limit === undefined) return { eligible: false, reason: 'no-observation-for-host' };
     if (limit.projectedSkills === null) return { eligible: false, reason: 'observation-not-comparable' };

package/src/scripts/_lib/skill_fork_pilot.ts

@@ -0,0 +1,121 @@
+/**
+ * The fork pilot — `road-to-skills-that-arrive-when-called` 3.2.
+ *
+ * WHAT A FORK IS FOR. A skill whose job ends in a report does not need to leave
+ * its body in the conversation: it runs, it returns a result, and nothing later
+ * in the task reads its prose again. The first host has a frontmatter key for
+ * exactly that, and this package could not use it until 1.1 renamed the package
+ * key that was squatting on it. D2 limits the pilot to `report` skills, because
+ * a forked run sees no conversation — for a `standing` skill that is not a
+ * saving, it is amnesia.
+ *
+ * WHY THE KEY IS RENDERED AND NOT AUTHORED. 1.2's lint forbids a package-owned
+ * frontmatter key that collides with a host-documented one, and `context` is
+ * host-documented. Writing `context: fork` into an authored SKILL.md would put
+ * the package straight back into the collision it just climbed out of, and it
+ * would apply to every host rather than to the one whose key it is. So the key
+ * is written at projection time, for the hosts in the pilot config, and every
+ * other host gets the body exactly as before.
+ *
+ * NOT WIRED INTO THE INSTALLER. The render exists and is tested; no install
+ * calls it. 3.3 keeps widening an owner question, and 4.6 keeps the first host
+ * on its full install until Phase 5 reads no harm — a pilot that silently
+ * shipped to every consumer would be the widening nobody posed.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export const PILOT_CONFIG_REL = path.join('src', 'config', 'skill-fork-pilot.json');
+export const OUTPUT_SHAPE_REL = path.join('src', 'config', 'skill-output-shape.json');
+
+export interface ForkPilotConfig {
+    status: string;
+    max_names: number;
+    names: string[];
+    hosts: string[];
+}
+
+export function readForkPilot(packageRoot: string): ForkPilotConfig {
+    const raw = JSON.parse(fs.readFileSync(path.join(packageRoot, PILOT_CONFIG_REL), 'utf-8')) as ForkPilotConfig;
+    return {
+        status: String(raw.status),
+        max_names: Number(raw.max_names),
+        names: Array.isArray(raw.names) ? raw.names.map(String) : [],
+        hosts: Array.isArray(raw.hosts) ? raw.hosts.map(String) : [],
+    };
+}
+
+export function readOutputShape(packageRoot: string): Record<string, string> {
+    const raw = JSON.parse(fs.readFileSync(path.join(packageRoot, OUTPUT_SHAPE_REL), 'utf-8')) as {
+        skills?: Record<string, string>;
+        default?: string;
+    };
+    return raw.skills ?? {};
+}
+
+/** The runtime reader `skill-output-shape.json` did not have: a name it does not carry is `standing`. */
+export function outputShapeOf(shape: Record<string, string>, name: string): 'report' | 'standing' {
+    return shape[name] === 'report' ? 'report' : 'standing';
+}
+
+/**
+ * Write the host's `context: fork` into a projected SKILL.md.
+ *
+ * Idempotent, and it never touches a `context:` the document already carries —
+ * a value already there was put there by somebody, and overwriting it is the
+ * silent host-key rewrite 1.3's snapshot exists to catch.
+ */
+export function renderForkContext(md: string): string {
+    // The closing fence is a whole `---` line: `----` or `--- x` inside the
+    // frontmatter must not end it early.
+    const m = /^---\r?\n([\s\S]*?)(\r?\n)---(?=\r?\n|$)/.exec(md);
+    if (m === null) return md;
+    const body = m[1]!;
+    if (/^context:[ \t]/m.test(body)) return md;
+    const nl = m[2]!;
+    return md.slice(0, m.index) + `---${nl}${body}${nl}context: fork${nl}---` + md.slice(m.index + m[0].length);
+}
+
+/** Does this projection carry the host's fork key? */
+export function hasForkContext(md: string): boolean {
+    const m = /^---\r?\n([\s\S]*?)\r?\n---(?=\r?\n|$)/.exec(md);
+    return m !== null && /^context:[ \t]*fork[ \t]*$/m.test(m[1]!);
+}
+
+export interface PilotProblem {
+    name: string;
+    message: string;
+}
+
+/**
+ * Everything that would make the pilot illegal, as data rather than as a throw.
+ *
+ * Checked by the test rather than at runtime: the config is committed, so a
+ * violation is a repository defect that should fail CI, not a condition a
+ * consumer's install has to handle.
+ */
+export function pilotProblems(cfg: ForkPilotConfig, shape: Record<string, string>): PilotProblem[] {
+    const out: PilotProblem[] = [];
+    // A missing cap reads as NaN, and `n > NaN` is false: no cap is a problem, not a pass.
+    if (!Number.isInteger(cfg.max_names) || cfg.max_names < 0) {
+        out.push({ name: '(set)', message: `max_names is not a non-negative integer (${String(cfg.max_names)})` });
+    } else if (cfg.names.length > cfg.max_names) {
+        out.push({ name: '(set)', message: `${cfg.names.length} names exceeds max_names ${cfg.max_names}` });
+    }
+    if (new Set(cfg.names).size !== cfg.names.length) {
+        out.push({ name: '(set)', message: 'duplicate name' });
+    }
+    for (const n of cfg.names) {
+        if (outputShapeOf(shape, n) !== 'report') {
+            out.push({ name: n, message: 'not classified `report` — D2 allows only report skills to fork' });
+        }
+    }
+    for (const h of cfg.hosts) {
+        // `context` is the first host's documented key. Rendering it for a host
+        // that does not document it would be writing a key with no meaning into
+        // somebody else's file.
+        if (h !== 'claude-code') out.push({ name: h, message: 'host does not document a `context` key' });
+    }
+    return out;
+}