@event4u/agent-config 14.18.0 → 14.20.0

package/src/scripts/_lib/self_repair.ts

@@ -30,14 +30,27 @@ import { createHash } from 'node:crypto';
 import { redact_low_impact_entry } from '../ai_council/redact_low_impact_entry.js';
 import { is_kernel_rule } from './kernel_rules.js';
 
-/** Where a record came from. */
-export type DefectSource = 'user-reported' | 'self-detected';
+/**
+ * Where a record came from.
+ *
+ * `user-reported` and `self-detected` both require something to have FIRED — a
+ * user complaint, or a deterministic detector. `model-noticed` is the third
+ * intake: a model notices an edge case in a rule, or a methodology the user
+ * just explained that no skill carries. Nothing fired, and before this source
+ * existed such an observation had no record type at all and was handed to a
+ * host-native memory tool no reader of this repository can query.
+ *
+ * It is a SOURCE and not a second store: the record shape, the fingerprint
+ * derivation, the noclobber path and the creation cap are all unchanged.
+ */
+export type DefectSource = 'user-reported' | 'self-detected' | 'model-noticed';
 
 /** The defect classes a record can carry. One class = one detector. */
 export type DefectClass =
     | 'user-reported'
     | 'council-availability-claim'
-    | 'language-mirror';
+    | 'language-mirror'
+    | 'model-noticed';
 
 /**
  * Runtime mirror of `DefectClass`, in declaration order. The upstream issue
@@ -49,6 +62,7 @@ export const DEFECT_CLASSES: readonly DefectClass[] = [
     'user-reported',
     'council-availability-claim',
     'language-mirror',
+    'model-noticed',
 ];
 
 /** How far a record may travel outward. */
@@ -61,14 +75,94 @@ export interface DefectFinding {
     evidence: string;
     /** One line naming what the fix should change. */
     suggested_surface: string;
+    /**
+     * The assets this record is ABOUT, drawn from a closed vocabulary and
+     * resolved against the tree at write time (see `partitionTargets`).
+     *
+     * `suggested_surface` is free text, so no record could ever be JOINED to
+     * the asset it describes — two records about one rule's weakness were two
+     * unrelated strings. A target is machine-addressable, which is what makes
+     * the per-target occurrence count in `targetCounts` possible at all.
+     *
+     * An EMPTY list stays legal: a real observation with no identified home is
+     * information, not an error. That is deliberately different from an
+     * UNRESOLVABLE entry, which lands in `proposes` instead.
+     */
+    target?: string[];
+    /**
+     * Target-shaped strings that do not resolve in the tree — a rule that does
+     * not exist yet, a skill the record is proposing. Kept rather than
+     * rejected, because "this should exist" is a legitimate observation; kept
+     * SEPARATE from `target`, because a silently accepted unresolvable id is
+     * worse than free text — it looks joined and joins to nothing.
+     */
+    proposes?: string[];
 }
 
+/** The four asset kinds a `target` entry may address. */
+export const TARGET_KINDS = ['rule', 'skill', 'command', 'hook'] as const;
+export type TargetKind = (typeof TARGET_KINDS)[number];
+
+/** `<kind>:<id>` — closed prefix, id-shaped remainder. Never free text. */
+export const TARGET_RE = /^(rule|skill|command|hook):([a-z0-9][a-z0-9._-]*)$/;
+
+/** Shape only — says nothing about whether the id exists. */
+export function isWellFormedTarget(value: string): boolean {
+    return TARGET_RE.test(value);
+}
+
+/** Split a well-formed target into its kind and id, or null. */
+export function parseTarget(value: string): { kind: TargetKind; id: string } | null {
+    const m = TARGET_RE.exec(value);
+    return m === null ? null : { kind: m[1] as TargetKind, id: m[2] as string };
+}
+
+/**
+ * What a record is doing now.
+ *
+ * The pair `open | released` could express neither a DECLINED record (which
+ * stayed `open` in the queue line for ever) nor a partially actioned one, so
+ * the only way a record left the queue was to be released. Six states, closed:
+ *
+ *   - `open`       — queued, nothing decided.
+ *   - `candidate`  — accepted as worth acting on, not yet acted on.
+ *   - `actioned`   — a fix or a decision landed.
+ *   - `declined`   — deliberately not acted on. Terminal, and NOT a failure.
+ *   - `superseded` — another record covers it.
+ *   - `parked`     — waiting on a named condition; REQUIRES `parked_until`,
+ *                    because a park with no wake condition is a deferral
+ *                    wearing a condition's clothes.
+ */
+export type DefectStatus =
+    | 'open'
+    | 'candidate'
+    | 'actioned'
+    | 'declined'
+    | 'superseded'
+    | 'parked';
+
+export const DEFECT_STATUSES: readonly DefectStatus[] = [
+    'open',
+    'candidate',
+    'actioned',
+    'declined',
+    'superseded',
+    'parked',
+];
+
+/** Statuses that keep a record in the queue line. */
+export const ACTIVE_STATUSES: readonly DefectStatus[] = ['open', 'candidate'];
+
 export interface DefectRecord extends DefectFinding {
     fingerprint: string;
     first_seen: string;
     last_seen: string;
     occurrences: number;
-    status: 'open' | 'released';
+    status: DefectStatus;
+    /** MANDATORY when `status === 'parked'`: when the record comes back. */
+    parked_until?: string;
+    /** One line saying why the record reached a terminal status. */
+    resolution?: string;
     /**
      * Failed egress attempts from the most recent `release` call, sanitized at
      * write time. Local-only bookkeeping: `renderReport` never includes them,
@@ -617,6 +711,38 @@ export function creationCapReached(
     return recentCreations(existing, finding.source, now) >= NEW_RECORDS_PER_SOURCE_PER_WINDOW;
 }
 
+/**
+ * Shape validation for a stored record. Returns the problems, `[]` when valid.
+ *
+ * The one obligation that is NOT a style nit: a `parked` record without a
+ * `parked_until` is a deferral nothing can wake. Everything else here is the
+ * closed-vocabulary check the free-text era could not perform.
+ */
+export function validateRecord(record: DefectRecord): string[] {
+    const out: string[] = [];
+    if (!(DEFECT_STATUSES as readonly string[]).includes(record.status)) {
+        out.push(`status '${String(record.status)}' is outside the closed enum`);
+    }
+    if (record.status === 'parked' && (record.parked_until ?? '').trim() === '') {
+        out.push('status is `parked` but `parked_until` is missing — a park with no wake condition is a deferral, not a park');
+    }
+    for (const value of record.target ?? []) {
+        if (!isWellFormedTarget(value)) {
+            out.push(`target '${value}' is not \`<rule|skill|command|hook>:<id>\``);
+        }
+    }
+    return out;
+}
+
+/** Union of two id lists, order-stable and de-duplicated. */
+function _mergeIds(a: readonly string[] | undefined, b: readonly string[] | undefined): string[] {
+    const out: string[] = [];
+    for (const v of [...(a ?? []), ...(b ?? [])]) {
+        if (!out.includes(v)) out.push(v);
+    }
+    return out;
+}
+
 export function mergeRecord(
     existing: DefectRecord | null,
     finding: DefectFinding,
@@ -624,13 +750,22 @@ export function mergeRecord(
 ): DefectRecord {
     const fp = fingerprint(finding.defect_class, finding.evidence);
     if (existing !== null && existing.fingerprint === fp) {
-        return {
+        const target = _mergeIds(existing.target, finding.target);
+        const proposes = _mergeIds(existing.proposes, finding.proposes);
+        const merged: DefectRecord = {
             ...existing,
             last_seen: now,
             occurrences: existing.occurrences + 1,
-            // A record the user re-reports after a release is open again.
+            // A record re-reported after it left the queue is open again. The
+            // widened enum does not change this: a recurrence refutes whatever
+            // disposition was taken, which is exactly `recurring-criticism`.
             status: 'open',
+            ...(target.length > 0 ? { target } : {}),
+            ...(proposes.length > 0 ? { proposes } : {}),
         };
+        // `open` carries no wake condition; a stale one would read as a park.
+        delete merged.parked_until;
+        return merged;
     }
     return {
         ...finding,

package/src/scripts/_lib/self_repair_store.ts

@@ -12,12 +12,16 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 
 import {
+    ACTIVE_STATUSES,
     creationCapReached,
     type DefectFinding,
     type DefectRecord,
     type DefectSource,
     fingerprint,
+    isWellFormedTarget,
     mergeRecord,
+    parseTarget,
+    validateRecord,
 } from './self_repair.js';
 
 export const STORE_REL = path.join('agents', 'runtime', 'self-repair');
@@ -48,7 +52,16 @@ export function readRecord(root: string, fp: string): DefectRecord | null {
     }
 }
 
+/**
+ * Write one record. VALIDATES first — a `parked` record with no wake condition
+ * or a malformed target never reaches the store, because a store that accepts
+ * an unwakeable park has the same defect the park was supposed to fix.
+ */
 export function writeRecord(root: string, record: DefectRecord): void {
+    const problems = validateRecord(record);
+    if (problems.length > 0) {
+        throw new Error(`refusing to write an invalid record: ${problems.join('; ')}`);
+    }
     const dir = storeDir(root);
     fs.mkdirSync(dir, { recursive: true });
     fs.writeFileSync(
@@ -71,7 +84,7 @@ export function listRecords(root: string): DefectRecord[] {
         // The overflow counter shares the directory and the extension but is not
         // a record. `isRecord` would reject it anyway; naming it here keeps the
         // exclusion intentional rather than incidental.
-        if (!n.endsWith('.json') || n === OVERFLOW_FILE) {
+        if (!n.endsWith('.json') || n === OVERFLOW_FILE || n === TARGET_INDEX_FILE) {
             continue;
         }
         const rec = readRecord(root, n.slice(0, -'.json'.length));
@@ -83,8 +96,16 @@ export function listRecords(root: string): DefectRecord[] {
     return out;
 }
 
+/**
+ * The records still in the queue. Since the status enum widened past
+ * `open | released`, "still queued" is `open` OR `candidate` — a record someone
+ * accepted but has not yet acted on has not left the queue, and a `declined`,
+ * `superseded`, `actioned` or `parked` one has.
+ */
 export function openRecords(root: string): DefectRecord[] {
-    return listRecords(root).filter((r) => r.status === 'open');
+    return listRecords(root).filter((r) =>
+        (ACTIVE_STATUSES as readonly string[]).includes(r.status),
+    );
 }
 
 /**
@@ -134,29 +155,60 @@ export function upsertFinding(
     root: string,
     finding: DefectFinding,
     now: string,
+    // The tree the targets resolve against. Defaults to the store root, which
+    // is the production case (both are the repo). A test sandboxes the STORE in
+    // a tmp dir while still resolving `rule:scope-control` against the real
+    // tree, and folding the two roots together would make that untestable.
+    opts?: { treeRoot?: string },
 ): DefectRecord | null {
     const fp = fingerprint(finding.defect_class, finding.evidence);
+    // Targets are resolved against the tree HERE, at the write boundary: the
+    // pure half cannot read the filesystem, and validating anywhere later would
+    // mean a dangling id had already been stored.
+    const split = partitionTargets(opts?.treeRoot ?? root, [
+        ...(finding.target ?? []),
+        ...(finding.proposes ?? []),
+    ]);
+    const resolved: DefectFinding = {
+        ...finding,
+        ...(split.target.length > 0 ? { target: split.target } : {}),
+        ...(split.proposes.length > 0 ? { proposes: split.proposes } : {}),
+    };
+    if (split.target.length === 0) delete resolved.target;
+    if (split.proposes.length === 0) delete resolved.proposes;
     const existing = readRecord(root, fp);
     // The fold path never consults the cap: a fingerprint already in the store
     // adds no file, so capping it would silence a tracked defect for no bound.
-    if (existing === null && creationCapReached(listRecords(root), finding, now)) {
-        bumpOverflow(root, finding.source, now);
+    if (existing === null && creationCapReached(listRecords(root), resolved, now)) {
+        bumpOverflow(root, resolved.source, now);
         return null;
     }
-    const merged = mergeRecord(existing, finding, now);
+    const merged = mergeRecord(existing, resolved, now);
     writeRecord(root, merged);
     return merged;
 }
 
-/** Mark a record released (a PR or issue now carries it). */
+/**
+ * Mark a record released — a PR or issue now carries it.
+ *
+ * The stored status is `actioned`, not the retired `released`: releasing IS the
+ * action, and the widened enum has no separate slot for it. The function name
+ * is kept because the CALLER's event is still "a release happened".
+ */
 export function markReleased(root: string, fp: string, now: string): DefectRecord | null {
     const rec = readRecord(root, fp);
     if (rec === null) {
         return null;
     }
     // A successful release supersedes any earlier failed attempts.
-    const next: DefectRecord = { ...rec, status: 'released', last_seen: now };
+    const next: DefectRecord = {
+        ...rec,
+        status: 'actioned',
+        resolution: rec.resolution ?? 'released — a pull request or issue now carries this record',
+        last_seen: now,
+    };
     delete next.release_errors;
+    delete next.parked_until;
     writeRecord(root, next);
     return next;
 }
@@ -186,3 +238,217 @@ export function attachReleaseErrors(
     writeRecord(root, next);
     return next;
 }
+
+// target resolution
+//
+// `suggested_surface` is free text, so nothing could join a record to the asset
+// it is about. A `target` entry is `<kind>:<id>` from a closed vocabulary AND it
+// is resolved against the tree at WRITE time — an unresolvable entry is not
+// rejected (a record proposing an asset that should exist is real information)
+// and is not silently accepted either (a dangling id looks joined and joins to
+// nothing). It is moved to `proposes`, where a reader can see it for what it is.
+
+/** Where each target kind lives in the source tree. */
+function _targetExists(root: string, kind: string, id: string): boolean {
+    if (kind === 'rule') {
+        return fs.existsSync(path.join(root, 'src', 'rules', `${id}.md`));
+    }
+    if (kind === 'skill') {
+        return fs.existsSync(path.join(root, 'src', 'skills', id, 'SKILL.md'));
+    }
+    if (kind === 'command') {
+        return _commandIds(root).has(id);
+    }
+    if (kind === 'hook') {
+        return _concernIds(root).has(id);
+    }
+    return false;
+}
+
+/**
+ * Command ids, read from the pack tree: every `command.md` under
+ * `src/domains/<pack>/…` contributes the name of its containing directory, plus
+ * the `parent-child` form a clustered command is referred to by.
+ */
+function _commandIds(root: string): ReadonlySet<string> {
+    const out = new Set<string>();
+    const base = path.join(root, 'src', 'domains');
+    const walk = (dir: string, trail: string[]): void => {
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const ent of entries) {
+            if (ent.isDirectory()) {
+                walk(path.join(dir, ent.name), [...trail, ent.name]);
+            } else if (ent.name === 'command.md' && trail.length > 0) {
+                out.add(trail[trail.length - 1] as string);
+                if (trail.length > 1) {
+                    out.add(trail.slice(-2).join('-'));
+                }
+            }
+        }
+    };
+    walk(base, []);
+    return out;
+}
+
+/**
+ * Hook-concern ids, read from the compiled manifest rather than re-parsing the
+ * YAML: `hook_manifest.json` is the artifact the dispatcher itself reads, so a
+ * concern that resolves here is a concern that actually exists at runtime.
+ */
+function _concernIds(root: string): ReadonlySet<string> {
+    try {
+        const raw = fs.readFileSync(
+            path.join(root, 'src', 'scripts', 'hook_manifest.json'),
+            'utf-8',
+        );
+        const parsed = JSON.parse(raw) as { manifest?: { concerns?: Record<string, unknown> } };
+        return new Set(Object.keys(parsed.manifest?.concerns ?? {}));
+    } catch {
+        return new Set<string>();
+    }
+}
+
+/**
+ * Split a caller's target list into the entries that resolve in the tree and
+ * the entries that do not. Malformed entries go to `proposes` too — a string
+ * that is not `<kind>:<id>` cannot be resolved, and dropping it would lose the
+ * observation.
+ */
+export function partitionTargets(
+    root: string,
+    values: readonly string[],
+): { target: string[]; proposes: string[] } {
+    const target: string[] = [];
+    const proposes: string[] = [];
+    for (const raw of values) {
+        const value = raw.trim();
+        if (value === '') continue;
+        const parsed = isWellFormedTarget(value) ? parseTarget(value) : null;
+        if (parsed !== null && _targetExists(root, parsed.kind, parsed.id)) {
+            if (!target.includes(value)) target.push(value);
+        } else if (!proposes.includes(value)) {
+            proposes.push(value);
+        }
+    }
+    return { target, proposes };
+}
+
+// per-target occurrence index
+//
+// `occurrences` counts a FINGERPRINT, which is class plus normalised evidence
+// shape — so two different manifestations of one rule's weakness are two
+// records with one occurrence each, and the third-recurrence escalation stated
+// in `skill-improvement-pipeline` had nothing that could ever establish a third
+// recurrence. This is a DERIVED read over the record files: regenerable,
+// byte-stable, and gitignored with the rest of `agents/runtime/`.
+
+// cache-invalidation: regenerated WHOLESALE from the record files on every run
+// (`writeTargetIndex` recomputes from scratch — no incremental or partial
+// state), and the output is deterministic by construction, so a stale read is
+// impossible and a version namespace would name a format nothing reads across
+// runs. The shape change that would matter is a shape change to the records
+// themselves, which `validateRecord` already gates.
+export const TARGET_INDEX_FILE = '_target-index.json';
+
+export interface TargetCount {
+    target: string;
+    /** Sum of `occurrences` across every record naming this target. */
+    occurrences: number;
+    /** Fingerprints naming it — a per-target count of DISTINCT manifestations. */
+    records: string[];
+}
+
+function targetIndexPath(root: string): string {
+    return path.join(storeDir(root), TARGET_INDEX_FILE);
+}
+
+/** Aggregate occurrences by target. Pure over the store's record files. */
+export function targetCounts(root: string): TargetCount[] {
+    const acc = new Map<string, { occurrences: number; records: string[] }>();
+    for (const rec of listRecords(root)) {
+        for (const value of rec.target ?? []) {
+            const prev = acc.get(value) ?? { occurrences: 0, records: [] };
+            prev.occurrences += Number.isFinite(rec.occurrences) ? rec.occurrences : 0;
+            if (!prev.records.includes(rec.fingerprint)) prev.records.push(rec.fingerprint);
+            acc.set(value, prev);
+        }
+    }
+    return [...acc.entries()]
+        .map(([target, v]) => ({
+            target,
+            occurrences: v.occurrences,
+            records: [...v.records].sort(),
+        }))
+        .sort((a, b) => (a.target < b.target ? -1 : a.target > b.target ? 1 : 0));
+}
+
+/**
+ * Write the derived index. Deterministic by construction — sorted keys, sorted
+ * fingerprints, no timestamp — so deleting it and rebuilding produces the same
+ * bytes. A timestamp here would make the artifact look fresh while saying
+ * nothing, and would destroy the one property that makes a rebuild routine.
+ */
+export function writeTargetIndex(root: string): TargetCount[] {
+    const counts = targetCounts(root);
+    fs.mkdirSync(storeDir(root), { recursive: true });
+    fs.writeFileSync(targetIndexPath(root), `${JSON.stringify(counts, null, 2)}\n`, 'utf-8');
+    return counts;
+}
+
+// status transitions
+
+/**
+ * Migrate `released` records — the retired status — to `actioned`, carrying a
+ * resolution line that says the migration is why. Idempotent: a record already
+ * on the new enum is left byte-identical, so running it twice over a store
+ * produces no second diff.
+ *
+ * Returns the fingerprints it changed.
+ */
+export function migrateReleasedRecords(root: string): string[] {
+    const changed: string[] = [];
+    for (const rec of listRecords(root)) {
+        if ((rec.status as string) !== 'released') continue;
+        const next: DefectRecord = {
+            ...rec,
+            status: 'actioned',
+            resolution:
+                rec.resolution ??
+                'migrated from the retired `released` status; the release itself is the action recorded',
+        };
+        writeRecord(root, next);
+        changed.push(rec.fingerprint);
+    }
+    return changed.sort();
+}
+
+/** Move a record to a terminal or parked status, validating the result. */
+export function setStatus(
+    root: string,
+    fp: string,
+    next: DefectRecord['status'],
+    now: string,
+    extra?: { parked_until?: string; resolution?: string },
+): DefectRecord | null {
+    const rec = readRecord(root, fp);
+    if (rec === null) return null;
+    const updated: DefectRecord = {
+        ...rec,
+        status: next,
+        last_seen: now,
+        ...(extra?.parked_until !== undefined ? { parked_until: extra.parked_until } : {}),
+        ...(extra?.resolution !== undefined ? { resolution: extra.resolution } : {}),
+    };
+    if (next !== 'parked') delete updated.parked_until;
+    const problems = validateRecord(updated);
+    if (problems.length > 0) {
+        throw new Error(`refusing to write an invalid record: ${problems.join('; ')}`);
+    }
+    writeRecord(root, updated);
+    return updated;
+}

package/src/scripts/_lib/session_register.ts

@@ -175,14 +175,19 @@ export function stop_means_session_end(platform: string | null | undefined): boo
  * Deliberately **not** derived from the frequency lattice. That instrument
  * models *slot presence*, and two hosts have a slot that never fires:
  *
- * - `cursor` — `user_prompt_submit` and `stop` are **IDE-only**; the CLI fires
- *   only shell-execution hooks (`hook_manifest.yaml:365-366`,
- *   `chat-history-platform-hooks.md:214`). The lattice has no IDE/CLI dimension,
- *   so it reports cursor covered.
+ * - `cursor` — excluded because reachability there is UNESTABLISHED, not
+ *   because it is known absent. The earlier wording asserted the CLI fires only
+ *   shell-execution hooks, sourced to a 2026-01 reading that carried no expiry
+ *   and could not be re-verified in either direction. The safe direction is the
+ *   one taken: an unverified slot must not read as covered. The lattice has no
+ *   IDE/CLI dimension of its own, so it would report cursor covered; the
+ *   envelope now carries a `surface` field (`_lib/surface.ts`) that records
+ *   which surface a dispatch came from, and it answers `unknown` on cursor
+ *   because no marker distinguishes the two.
  * - `cowork` — slots are structurally wired but lifecycle events do not fire
  *   (`hook_manifest.yaml:346-351`).
- * - `copilot` — no hook surface at all (`hook_manifest.yaml:428-429`), excluded
- *   from the join by declaration.
+ * - `copilot` — nothing bound by this package (`fallback_only: true` in the
+ *   manifest), excluded from the join by declaration.
  *
  * A session on an excluded host still *registers* if a `session_start` reaches
  * it, and simply stops being visible after its TTL. It is never reported as

package/src/scripts/_lib/sqlite_schema.ts

@@ -0,0 +1,22 @@
+/**
+ * Schema helpers for the `node:sqlite` stores in this tree.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+
+/**
+ * Add a column to an existing table when it is absent.
+ *
+ * `CREATE TABLE IF NOT EXISTS` is a no-op on a database that predates a
+ * column, so a store created by an earlier build needs the explicit add or the
+ * field is silently missing from every read.
+ *
+ * `PRAGMA table_info` rather than a catch around `ALTER TABLE`: swallowing the
+ * error would also swallow a genuine schema failure, and a store that silently
+ * fails to migrate reads exactly like one that never needed to.
+ */
+export function addColumnIfMissing(db: DatabaseSync, table: string, column: string, decl: string): void {
+    const cols = db.prepare(`PRAGMA table_info(${table})`).all() as { name: string }[];
+    if (cols.length === 0) return;
+    if (cols.some((c) => c.name === column)) return;
+    db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${decl}`);
+}