@event4u/agent-config 16.5.0 → 17.0.0

package/src/scripts/_lib/roadmap_slug_lock.ts

@@ -0,0 +1,254 @@
+/**
+ * One lock file per roadmap slug — the exclusive half of a roadmap claim.
+ *
+ * The per-session claim file (`sessions:claim`) holds ONE slug per session and
+ * reaches peers only when the next heartbeat lifts it into the register. Both
+ * properties let two sessions build one roadmap on 2026-10-20 (#2533 / #2534,
+ * ten conflicting files): an orchestrator running two lanes overwrote its first
+ * claim with its second, and a claim written mid-turn was invisible to a peer
+ * screening in that same turn.
+ *
+ * A lock fixes both without changing the claim file:
+ *
+ * - **Keyed by slug, not by session**, so one session can hold one lock per lane.
+ * - **Created with `wx`**, so two sessions racing on one slug get one winner — an
+ *   exclusive create, not an advisory read-then-write.
+ * - **Read directly** from `<git-common-dir>/agent-claims/by-slug/`, shared by
+ *   every worktree of the repo, so a peer sees it the moment it is written.
+ * - **Carries the worktree and branch** the work happens in, so a killed holder —
+ *   a session or a lane stopped by the spend limit — leaves the place its
+ *   commits and uncommitted edits sit, and the next run continues there.
+ *
+ * Liveness is the holder's register record, never the lock's age: a live record
+ * keeps the lock, an expired record frees it. A holder with no record at all (a
+ * host without hooks, or a record pruned a day after expiry) holds the lock for
+ * {@link UNRECORDED_HOLDER_MS} from its last write.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { write_atomic } from './fs_atomic.js';
+import { git_common_dir } from './git_common_dir.js';
+import { read_live_records, register_dir, safe_stem } from './session_register.js';
+
+export const LOCK_DIRNAME = path.join('agent-claims', 'by-slug');
+
+/** How long a lock whose holder never registered stays held. */
+export const UNRECORDED_HOLDER_MS = 6 * 60 * 60 * 1000;
+
+export interface SlugLock {
+    slug: string;
+    session_id: string | null;
+    /** A lane lock is held for a subagent; its own session does not dispatch onto it. */
+    lane: boolean;
+    worktree: string;
+    branch: string | null;
+    written_at: string;
+}
+
+/** Liveness inputs, read once from the register by the caller. */
+export interface HolderView {
+    /** Session ids (as `safe_stem`) with a live register record. */
+    live: ReadonlySet<string>;
+    /** Session ids (as `safe_stem`) with any register record, live or expired. */
+    known: ReadonlySet<string>;
+}
+
+/** Who is live and who is known, from the session register. */
+export function read_holders(workspace_root: string, now: Date = new Date()): HolderView {
+    const dir = register_dir(workspace_root);
+    if (dir === null) return { live: new Set(), known: new Set() };
+    const live = new Set(read_live_records(dir, { now }).map((r) => safe_stem(r.session_id)));
+    let known = new Set<string>(live);
+    try {
+        known = new Set([
+            ...live,
+            ...fs.readdirSync(dir).filter((n) => n.endsWith('.json')).map((n) => n.slice(0, -5)),
+        ]);
+    } catch {
+        /* no register yet — nobody is known */
+    }
+    return { live, known };
+}
+
+export function lock_dir(workspace_root: string): string | null {
+    const common = git_common_dir(workspace_root);
+    return common === null ? null : path.join(common, LOCK_DIRNAME);
+}
+
+function lock_path(dir: string, slug: string): string {
+    return path.join(dir, `${safe_stem(slug)}.json`);
+}
+
+function parse_lock(raw: string): SlugLock | null {
+    try {
+        const o = JSON.parse(raw) as Record<string, unknown>;
+        if (typeof o['slug'] !== 'string' || typeof o['worktree'] !== 'string') return null;
+        const sid = o['session_id'];
+        const branch = o['branch'];
+        return {
+            slug: o['slug'],
+            session_id: typeof sid === 'string' && sid !== '' ? sid : null,
+            lane: o['lane'] === true,
+            worktree: o['worktree'],
+            branch: typeof branch === 'string' && branch !== '' ? branch : null,
+            written_at: typeof o['written_at'] === 'string' ? o['written_at'] : '',
+        };
+    } catch {
+        return null;
+    }
+}
+
+export function read_locks(workspace_root: string): SlugLock[] {
+    const dir = lock_dir(workspace_root);
+    if (dir === null) return [];
+    let names: string[] = [];
+    try {
+        names = fs.readdirSync(dir).filter((n) => n.endsWith('.json'));
+    } catch {
+        return [];
+    }
+    const out: SlugLock[] = [];
+    for (const n of names.sort()) {
+        try {
+            const lock = parse_lock(fs.readFileSync(path.join(dir, n), 'utf-8'));
+            if (lock !== null) out.push(lock);
+        } catch {
+            /* removed between readdir and read — not held */
+        }
+    }
+    return out;
+}
+
+export function holder_is_live(lock: SlugLock, holders: HolderView, now: Date = new Date()): boolean {
+    if (lock.session_id !== null) {
+        const stem = safe_stem(lock.session_id);
+        if (holders.live.has(stem)) return true;
+        if (holders.known.has(stem)) return false;
+    }
+    const written = Date.parse(lock.written_at);
+    return Number.isFinite(written) && now.getTime() - written < UNRECORDED_HOLDER_MS;
+}
+
+function same_holder(a: string | null, b: string | null, a_wt: string, b_wt: string): boolean {
+    if (a !== null && b !== null) return safe_stem(a) === safe_stem(b);
+    // No session id on either side: the worktree is the only identity there is.
+    return a === null && b === null && path.resolve(a_wt) === path.resolve(b_wt);
+}
+
+export type AcquireResult =
+    | { ok: true; lock: SlugLock; took_over: SlugLock | null }
+    | { ok: false; holder: SlugLock };
+
+/**
+ * Take the lock for `lock.slug`. Refuses when a live different holder has it;
+ * takes it over from a dead one and reports who that was. `force` takes it from
+ * a live holder too.
+ */
+export function acquire_lock(
+    workspace_root: string,
+    lock: SlugLock,
+    holders: HolderView,
+    options: { force?: boolean; now?: Date } = {},
+): AcquireResult {
+    const dir = lock_dir(workspace_root);
+    if (dir === null) return { ok: true, lock, took_over: null };
+    fs.mkdirSync(dir, { recursive: true });
+    const file = lock_path(dir, lock.slug);
+    const body = `${JSON.stringify(lock, null, 2)}\n`;
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            fs.writeFileSync(file, body, { flag: 'wx' });
+            return { ok: true, lock, took_over: null };
+        } catch (exc) {
+            if ((exc as NodeJS.ErrnoException).code !== 'EEXIST') throw exc;
+        }
+        let existing: SlugLock | null = null;
+        try {
+            existing = parse_lock(fs.readFileSync(file, 'utf-8'));
+        } catch {
+            continue; // released between our create and our read — try the create again
+        }
+        if (
+            existing === null ||
+            same_holder(existing.session_id, lock.session_id, existing.worktree, lock.worktree)
+        ) {
+            write_atomic(file, body);
+            return { ok: true, lock, took_over: null };
+        }
+        if (!options.force && holder_is_live(existing, holders, options.now)) {
+            return { ok: false, holder: existing };
+        }
+        // Dead (or forced) holder. Move the file aside instead of unlinking it:
+        // a rename is atomic, so of two takers only one moves it, and the mover
+        // can check it moved the dead lock it read. If it moved a fresh lock a
+        // faster taker had just created, that lock is put back with link(),
+        // which never overwrites, and the fresh holder wins.
+        const aside = `${file}.${process.pid}.${Date.now()}.taken`;
+        try {
+            fs.renameSync(file, aside);
+        } catch {
+            continue; // another taker moved it first: race for the create again
+        }
+        let moved: SlugLock | null = null;
+        try {
+            moved = parse_lock(fs.readFileSync(aside, 'utf-8'));
+        } catch {
+            moved = null;
+        }
+        if (moved !== null && JSON.stringify(moved) !== JSON.stringify(existing)) {
+            try {
+                fs.linkSync(aside, file);
+            } catch {
+                /* a third lock already stands there; it wins either way */
+            }
+            fs.rmSync(aside, { force: true });
+            return { ok: false, holder: moved };
+        }
+        fs.rmSync(aside, { force: true });
+        try {
+            fs.writeFileSync(file, body, { flag: 'wx' });
+            return { ok: true, lock, took_over: existing };
+        } catch (exc) {
+            if ((exc as NodeJS.ErrnoException).code !== 'EEXIST') throw exc;
+        }
+    }
+    let raw: string | null;
+    try {
+        raw = fs.readFileSync(file, 'utf-8');
+    } catch {
+        raw = null; // released in the meantime: nobody holds it now, but this taker has not either
+    }
+    const winner = raw === null ? null : parse_lock(raw);
+    if (winner !== null) return { ok: false, holder: winner };
+    try {
+        fs.writeFileSync(file, body, { flag: 'wx' });
+        return { ok: true, lock, took_over: null };
+    } catch {
+        const now = parse_lock(fs.readFileSync(file, 'utf-8'));
+        return now === null ? { ok: true, lock, took_over: null } : { ok: false, holder: now };
+    }
+}
+
+/** Remove this holder's locks — one slug, or all of them. Returns the slugs released. */
+export function release_locks(
+    workspace_root: string,
+    session_id: string | null,
+    slug: string | null = null,
+): string[] {
+    const released: string[] = [];
+    for (const l of read_locks(workspace_root)) {
+        if (slug !== null && l.slug !== slug) continue;
+        if (!same_holder(l.session_id, session_id, l.worktree, workspace_root)) continue;
+        const dir = lock_dir(workspace_root);
+        if (dir === null) break;
+        try {
+            fs.unlinkSync(lock_path(dir, l.slug));
+            released.push(l.slug);
+        } catch {
+            /* already gone */
+        }
+    }
+    return released;
+}

package/src/scripts/_lib/roadmap_step_size.ts

@@ -0,0 +1,75 @@
+/**
+ * A roadmap step is at most `STEP_WORD_CAP` words.
+ *
+ * A step that has grown into a work package is read whole every time the run
+ * reaches it, and its Done note grows into it. The cap counts the checkbox line
+ * and its indented continuation lines; HTML comments (a receipt, a skip marker)
+ * are excluded, because they are machine annotations, not reading load.
+ *
+ * Folded into `lint_roadmap_complexity` rather than shipped as a gate of its own,
+ * for the reason `roadmap_granularity.ts` states: the gate that already owns the
+ * roadmap corpus adds a check without adding a gate. Today's oversized steps are
+ * held by `src/config/roadmap-step-size-baseline.json`; the baseline only
+ * shrinks — a held step that fits under the cap is reported so its entry can go.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export const STEP_WORD_CAP = 150;
+export const STEP_SIZE_BASELINE_REL = 'src/config/roadmap-step-size-baseline.json';
+
+const STEP_LINE = /^- \[[ x~\-/]\] \*\*(\d+\.\d+[a-z]?)\b/;
+const COMMENT = /<!--[\s\S]*?-->/g;
+
+export interface OversizedStep {
+    key: string;
+    words: number;
+}
+
+function countWords(text: string): number {
+    const bare = text.replace(COMMENT, ' ').trim();
+    return bare === '' ? 0 : bare.split(/\s+/).length;
+}
+
+export function oversizedSteps(file: string, text: string): OversizedStep[] {
+    const out: OversizedStep[] = [];
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const m = STEP_LINE.exec(lines[i] as string);
+        if (m === null) continue;
+        const body = [lines[i] as string];
+        // A blank line ends the step only when no indented line follows it: a
+        // continuation may hold several paragraphs, and each still counts.
+        for (let j = i + 1; j < lines.length; j++) {
+            const line = lines[j] as string;
+            if (/^\s{2,}\S/.test(line)) body.push(line);
+            else if (line.trim() !== '' || !/^\s{2,}\S/.test(lines.slice(j + 1).find((l) => l.trim() !== '') ?? '')) break;
+        }
+        const words = countWords(body.join(' '));
+        if (words > STEP_WORD_CAP) out.push({ key: `${file}#${m[1]!}`, words });
+    }
+    return out;
+}
+
+export function stepSizeProblems(file: string, text: string, baseline: ReadonlySet<string>): string[] {
+    return oversizedSteps(file, text)
+        .filter((s) => !baseline.has(s.key))
+        .map(
+            (s) =>
+                `step ${s.key.split('#')[1]!} is ${String(s.words)} words (cap ${String(STEP_WORD_CAP)}) — ` +
+                'split it, or move evidence to the commit and, for R2/R3, the artefact',
+        );
+}
+
+/** Held keys of this file whose step now fits under the cap, or no longer exists. */
+export function staleHeld(file: string, text: string, baseline: ReadonlySet<string>): string[] {
+    const over = new Set(oversizedSteps(file, text).map((s) => s.key));
+    return [...baseline].filter((k) => k.startsWith(`${file}#`) && !over.has(k)).sort();
+}
+
+export function loadStepSizeBaseline(root: string): Set<string> {
+    const p = path.join(root, STEP_SIZE_BASELINE_REL);
+    if (!fs.existsSync(p)) return new Set();
+    const j = JSON.parse(fs.readFileSync(p, 'utf8')) as { held: string[] };
+    return new Set(j.held);
+}

package/src/scripts/_lib/run_checkpoint.ts

@@ -31,6 +31,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { write_atomic } from './fs_atomic.js';
 import { CHECKBOX_LINE, phaseLines } from './roadmap_checkboxes.js';
 
 export const CHECKPOINT_DIR_REL = path.join('agents', 'runtime', 'state', 'checkpoints');
@@ -239,12 +240,15 @@ export function buildCheckpoint(
     };
 }
 
-/** Write a checkpoint. Best-effort: a failed write must never break a Stop. */
+/**
+ * Write a checkpoint. Best-effort: a failed write must never break a Stop.
+ * Atomic, because a session killed mid-write left a torn newest file that the
+ * lookup then skipped in favour of an older one.
+ */
 export function writeCheckpoint(repoRoot: string, cp: RunCheckpoint): string | null {
     const file = checkpointFile(repoRoot, cp.run_id);
     try {
-        fs.mkdirSync(path.dirname(file), { recursive: true });
-        fs.writeFileSync(file, `${JSON.stringify(cp, null, 2)}\n`, 'utf-8');
+        write_atomic(file, `${JSON.stringify(cp, null, 2)}\n`);
         return file;
     } catch {
         return null;
@@ -460,3 +464,56 @@ export function renderVerification(cp: RunCheckpoint, res: VerifyResult): string
     }
     return lines.join('\n');
 }
+
+/** Checkpoint files that do not parse as a checkpoint, with their mtime. */
+function unreadableCheckpoints(repoRoot: string): Array<{ name: string; mtimeMs: number }> {
+    const dir = path.join(repoRoot, CHECKPOINT_DIR_REL);
+    let names: string[];
+    try {
+        names = fs.readdirSync(dir).filter((n) => n.endsWith('.json'));
+    } catch {
+        return [];
+    }
+    const out: Array<{ name: string; mtimeMs: number }> = [];
+    for (const name of names.sort()) {
+        const file = path.join(dir, name);
+        let ok = false;
+        try {
+            const o: unknown = JSON.parse(fs.readFileSync(file, 'utf-8'));
+            ok = o !== null && typeof o === 'object' && !Array.isArray(o) && typeof (o as Record<string, unknown>)['run_id'] === 'string';
+        } catch {
+            ok = false;
+        }
+        if (ok) continue;
+        try {
+            out.push({ name, mtimeMs: fs.statSync(file).mtimeMs });
+        } catch {
+            // Gone between the listing and the stat — nothing left to name.
+        }
+    }
+    return out;
+}
+
+/**
+ * The resumed run's first act, as one call: find the roadmap's newest readable
+ * checkpoint, recompute it, render the per-field report — and name every
+ * unreadable checkpoint file newer than the one used. Such a file cannot say
+ * which roadmap it belonged to, so it is named rather than guessed at; the
+ * lookup still skips it, because a torn file must not block a resume.
+ */
+export function verifyLatestCheckpoint(
+    repoRoot: string,
+    roadmap: string,
+    currentFingerprint?: string | null,
+): { report: string; agrees: boolean } {
+    const cp = latestCheckpointFor(repoRoot, roadmap);
+    const usedAt = cp === null ? Number.NEGATIVE_INFINITY : Date.parse(String(cp.written_at ?? ''));
+    const torn = unreadableCheckpoints(repoRoot)
+        .filter((f) => Number.isNaN(usedAt) || f.mtimeMs > usedAt)
+        .map((f) => `  unreadable: ${f.name} — newer than the checkpoint used, its roadmap cannot be read`);
+    if (cp === null) {
+        return { report: [`no checkpoint for '${roadmap}' — nothing to verify against.`, ...torn].join('\n'), agrees: false };
+    }
+    const res = verifyCheckpoint(repoRoot, cp, currentFingerprint);
+    return { report: [renderVerification(cp, res), ...torn].join('\n'), agrees: res.agrees };
+}

package/src/scripts/_lib/runtime_wiring_checks.ts

@@ -27,7 +27,9 @@ import process from 'node:process';
 
 import { parse as parseYaml } from 'yaml';
 
+import { readCanaryStatusLine } from './canary_status.js';
 import { inheritedGitOverrides } from './repo_root.js';
+import { layerFormDoctorCheck } from './layer_form_evidence.js';
 import {
     checkHostPermissionSettings,
     defaultHostPermissionDeps,
@@ -295,7 +297,7 @@ export function checkInheritedGitEnv(env: NodeJS.ProcessEnv = process.env): Wiri
  * two spreads.
  */
 /** The four ids, in render order. Spread into `cmd_doctor`'s two id registries. */
-export const WIRING_CHECK_IDS = ['settings-resolution', 'router-artifact', 'hook-resolution', 'inherited-git-env', 'hooks-kill-switch', 'host-permission-settings'] as const;
+export const WIRING_CHECK_IDS = ['settings-resolution', 'router-artifact', 'hook-resolution', 'inherited-git-env', 'hooks-kill-switch', 'host-permission-settings', 'layer-form'] as const;
 
 
 /**
@@ -355,6 +357,10 @@ export function wiringRunners(opts: {
         // for the same host — the question is the same surface, one key over.
         'host-permission-settings': () =>
             checkHostPermissionSettings(defaultHostPermissionDeps(opts.projectRoot)),
+        // Shadow rule-layer form (road-to-a-setup-that-decides-itself 3.2); writes nothing.
+        'layer-form': () => layerFormDoctorCheck(opts.packageRoot),
+        // Here rather than in cmd_doctor, which sits past the source ceiling. Reads state only, never `gh`.
+        'canary-liveness': () => canaryLivenessCheck(opts.projectRoot),
     };
 }
 
@@ -439,3 +445,11 @@ export function checkHookWiring(deps: HookWiringDeps): WiringCheck {
             : 'npm install -g @event4u/agent-config, then agent-config refresh --global',
     };
 }
+
+/** The cross-model canary's red-streak line, as `canary_liveness.ts --refresh` last recorded it. */
+export function canaryLivenessCheck(projectRoot: string): WiringCheck {
+    const line = readCanaryStatusLine(projectRoot);
+    return line === null
+        ? { id: 'canary-liveness', status: 'ok', message: 'no red streak recorded for the cross-model canary', remedy: '' }
+        : { id: 'canary-liveness', status: 'warn', message: line, remedy: './scripts-run src/scripts/canary_liveness --refresh after the canary is green again' };
+}

package/src/scripts/_lib/scope_guard.sh

@@ -75,14 +75,73 @@ installed_version_at() {
     echo "unknown"
 }
 
-# Heuristic: does this look like an agent-config install (vs a vanilla user
-# directory with the same path layout)? We accept "looks like" if the tool
-# directory contains ≥ N entries that ALSO exist in the SOURCE_DIR tree —
-# but we keep the check coarse: simply that the directory is non-empty.
 dir_nonempty() {
     [[ -d "$1" ]] && [[ -n "$(ls -A "$1" 2>/dev/null | head -1)" ]]
 }
 
+# Entry names with their extension stripped, so a skill directory `foo`, a rule
+# `foo.md` and its Cursor projection `foo.mdc` compare as the same name.
+entry_stems() {
+    ls -A "$1" 2>/dev/null | sed 's/\.[^.]*$//' | sort -u
+}
+
+# The names this package ships into a host directory: its skills and its rules.
+shipped_stems() {
+    {
+        ls -A "$SOURCE_DIR/dist/agent-src/skills" 2>/dev/null
+        ls -A "$SOURCE_DIR/dist/agent-src/rules" 2>/dev/null
+    } | sed 's/\.[^.]*$//' | sort -u
+}
+
+# Does the deploy ledger record agent-config writing a file under this
+# directory? The ledger (`deployed-files.json`) is the ownership proof the
+# reaper already trusts to delete safely, so it is the authoritative answer.
+# Needs node to read JSON; without node this returns "no evidence", and the
+# shipped-name test below still runs.
+ledger_owns() {
+    local tool="$1" dir="$2"
+    command -v node >/dev/null 2>&1 || return 1
+    local inv="${AGENT_CONFIG_DEPLOY_INVENTORY:-${EVENT4U_CONFIG_HOME:-$HOME/.event4u/agent-config}/deployed-files.json}"
+    [[ -f "$inv" ]] || return 1
+    node -e '
+        const fs = require("fs"), path = require("path");
+        const [inv, tool, dir, home] = process.argv.slice(1);
+        let d;
+        try { d = JSON.parse(fs.readFileSync(inv, "utf8")); } catch { process.exit(1); }
+        const e = (d && d.tools && d.tools[tool]) || null;
+        if (!e || typeof e.anchor !== "string" || !Array.isArray(e.files)) process.exit(1);
+        const anchor = e.anchor === "~" ? home : e.anchor.startsWith("~/") ? path.join(home, e.anchor.slice(2)) : e.anchor;
+        const want = path.resolve(dir) + path.sep;
+        process.exit(e.files.some((f) => path.resolve(anchor, f).startsWith(want)) ? 0 : 1);
+    ' "$inv" "$tool" "$dir" "$HOME" 2>/dev/null
+}
+
+# Is this directory an agent-config install, as opposed to a host directory
+# that merely holds someone else's files? It used to answer "yes" for ANY
+# non-empty directory, and a host directory such as `~/.claude/skills` has no
+# `package.json` beside it, so the version read `unknown` and `unknown` is
+# DRIFT: a machine whose only Claude skill was a foreign integration was told
+# it had a conflicting agent-config install, and the install stopped.
+#
+# Ownership now needs evidence: the ledger records a file we wrote there, or at
+# least one entry carries a name this package ships. Either is enough. The
+# second covers installs older than the ledger; the first covers an old install
+# whose every name has since been renamed. Foreign entries beside ours never
+# hide ours, because one shared name is sufficient.
+#
+# The trade, stated: an install with NO ledger whose every name was renamed is
+# not recognised, so a real duplicate registration there passes as OK; and a
+# foreign skill that happens to share a stem with a shipped one (`docker`,
+# `security`) is counted as ours. A stem drops everything after its last dot,
+# so a directory `a.b` and a rule `a.md` compare equal. Wrong in both directions only at the
+# edges, where the old any-non-empty-directory test was wrong everywhere.
+ac_owns_dir() {
+    local tool="$1" dir="$2"
+    dir_nonempty "$dir" || return 1
+    ledger_owns "$tool" "$dir" && return 0
+    [[ -n "$(comm -12 <(entry_stems "$dir") <(shipped_stems) 2>/dev/null | head -1)" ]]
+}
+
 # Count entry names present in BOTH scope directories — what a same-version
 # duplicate registration actually delivers twice, which is the cost the WARN
 # verdict used to omit.
@@ -139,7 +198,7 @@ probe_tool() {
         other_scope="project"
     fi
 
-    if ! dir_nonempty "$other_path"; then
+    if ! ac_owns_dir "$tool" "$other_path"; then
         printf 'OK\t%s\t-\t-\t%s\n' "$tool" "$(this_version)"
         return
     fi