@event4u/agent-config 14.5.0 → 14.7.0

package/src/agent-src/templates/scripts/telemetry/remote.ts

@@ -35,8 +35,14 @@ import { check_id_redaction, py_json_dumps_compact_sorted } from './engagement.j
 
 export const CLASS_A_SCHEMA_VERSION = 1;
 
-/** Usage classes. Phase 5 adds the self-repair class; Phase 1 emits one. */
-export const ALLOWED_RECORD_CLASSES = ['usage'] as const;
+/**
+ * Record classes. `usage` is Phase 1; `self-repair` is Phase 5 step 5.1.
+ *
+ * Both are Class A — structural fields only — and both travel the same log,
+ * spool and transport, discriminated by this field. `skill_usage_report`
+ * filters on it so a defect report can never be counted as an invocation.
+ */
+export const ALLOWED_RECORD_CLASSES = ['usage', 'self-repair'] as const;
 
 /**
  * Discipline-profile values, the knob that actually decides which rule
@@ -279,6 +285,122 @@ export function build_class_a_record(input: BuildClassAInput): ClassARecord {
     };
 }
 
+/**
+ * One Class-A SELF-REPAIR record (Phase 5, step 5.1).
+ *
+ * The shadow of a queued defect: it says a defect of a named class occurred,
+ * on which host, at which package version, under which declared profile, for
+ * which pseudonymous user. It says nothing about WHAT happened.
+ *
+ * A SEPARATE TYPE, NOT A WIDENED `ClassARecord`, AND THAT IS THE WHOLE POINT.
+ * `DefectFinding` carries `evidence` (a quoted span of the offending text) and
+ * `suggested_surface` (a free sentence). Those are the Class-B payload and
+ * they ship only on explicit per-case approval. Adding either to a
+ * telemetry record type — even optionally, even "sanitized" — would give this
+ * type a field capable of holding project content, and the privacy property
+ * this whole surface rests on is that no such field exists. There is then no
+ * scrubber to fail. Keeping the automatic class in its own interface is how
+ * that stays checkable by reading the type instead of auditing every writer.
+ *
+ * WHAT IS DELIBERATELY ABSENT: an enumerated active-rule / active-skill list.
+ * The roadmap Context asks Class A to carry "the active rule and skill
+ * snapshot" so that "this rule was loaded in six of seven reports of this
+ * class" localizes an artefact. No producer for that exists on a hook path:
+ * `match_prompt` needs the compiled router, which nothing in the hook surface
+ * loads today and which is not established as present in a consumer install.
+ * `discipline_profile` is recorded instead — the knob that decides which rule
+ * surfaces load at all — and it is a profile-level snapshot, NOT the
+ * per-artefact attribution key. That attribution claim stays unavailable, and
+ * saying so here is cheaper than a reader inferring it from a field name.
+ */
+export interface ClassADefectRecord {
+    schema_version: number;
+    record_class: string;
+    ts_bucket: string;
+    /** Detector / intake class — a closed vocabulary owned by the caller. */
+    defect_class: string;
+    /** Which intake produced it — also a closed vocabulary. */
+    defect_source: string;
+    /** How many times this fingerprint has been seen. A counter, not content. */
+    occurrences: number;
+    host: string | null;
+    package_version: string | null;
+    discipline_profile: string | null;
+    org_id: string;
+    user_hash: string;
+    session_hash: string | null;
+}
+
+export interface BuildClassADefectInput {
+    defect_class: string;
+    defect_source: string;
+    occurrences: number;
+    host: string | null;
+    org_id: string;
+    salt: string;
+    hostname: string;
+    username: string;
+    session_id: string;
+    package_version?: string | null;
+    discipline_profile?: string | null;
+    now?: Date;
+}
+
+/**
+ * Build one validated Class-A self-repair record. Pure, and throws rather
+ * than returning a partial record — same contract as its usage sibling.
+ *
+ * `defect_class` and `defect_source` go through the same id-redaction floor as
+ * every other id here, so a caller that ever passed a path, an extension or
+ * an over-long free string gets an exception instead of an egress.
+ */
+export function build_class_a_defect_record(
+    input: BuildClassADefectInput,
+): ClassADefectRecord {
+    check_id_redaction('defect_class', input.defect_class);
+    check_id_redaction('defect_source', input.defect_source);
+    check_id_redaction('org_id', input.org_id);
+
+    const host = input.host ?? null;
+    if (host !== null) {
+        check_id_redaction('host', host);
+    }
+
+    const discipline_profile = input.discipline_profile ?? null;
+    if (
+        discipline_profile !== null
+        && !(ALLOWED_DISCIPLINE_PROFILES as readonly string[]).includes(discipline_profile)
+    ) {
+        throw new ClassARecordError(
+            `discipline_profile must be one of ${ALLOWED_DISCIPLINE_PROFILES.join(', ')} or null`,
+        );
+    }
+
+    const package_version = input.package_version ?? null;
+    if (package_version !== null) {
+        check_id_redaction('package_version', package_version);
+    }
+
+    if (!Number.isInteger(input.occurrences) || input.occurrences < 1) {
+        throw new ClassARecordError('occurrences must be a positive integer');
+    }
+
+    return {
+        schema_version: CLASS_A_SCHEMA_VERSION,
+        record_class: 'self-repair',
+        ts_bucket: hour_bucket(input.now ?? new Date()),
+        defect_class: input.defect_class,
+        defect_source: input.defect_source,
+        occurrences: input.occurrences,
+        host,
+        package_version,
+        discipline_profile,
+        org_id: input.org_id,
+        user_hash: derive_user_hash(input.salt, input.hostname, input.username),
+        session_hash: derive_session_hash(input.salt, input.session_id),
+    };
+}
+
 // ── Retention — the growth budget for the local record log ──────────────
 //
 // Phase 1 shipped this file as append-only with no cap and no pruning, and
@@ -544,6 +666,20 @@ export function enforce_retention(
     return { kept: kept_lines.length, dropped_by_age, dropped_by_size };
 }
 
+/** Append one line to one bounded JSONL file. Both targets share it. */
+function _append_and_bound(
+    target: string,
+    payload: string,
+    policy: RetentionPolicy,
+    now: Date,
+): void {
+    fs.mkdirSync(path.dirname(target) || '.', { recursive: true });
+    fs.appendFileSync(target, payload, { encoding: 'utf-8' });
+    if (retention_due(target, policy, now)) {
+        enforce_retention(target, policy, now);
+    }
+}
+
 /**
  * Append one record as a JSONL line, then enforce the retention policy.
  *
@@ -555,17 +691,34 @@ export function enforce_retention(
  * which makes the common append one extra `stat` plus one bounded read. It
  * lives here rather than in a separate sweep because this is the only writer:
  * a policy a caller has to remember to run is a policy that stops running.
+ *
+ * THE SPOOL IS WRITTEN HERE, IN THE SAME CALL (Phase 2, step 2.1). When
+ * `spool_path` is given, the SAME bytes are appended to the outbound spool
+ * under the SAME retention policy, and the session-end flush then only has
+ * to drain a file. The alternative — a flush that works out for itself which
+ * logged records are still unsent — needs a byte watermark into a file that
+ * `enforce_retention` rewrites in place, and a watermark over a compacting
+ * file is a silent-corruption pair: the offset survives the prune, the
+ * records it points at do not. Enqueue-at-write has no watermark to
+ * invalidate and spools each record exactly once, by the only writer.
+ *
+ * The spool inherits the log's growth budget rather than getting its own,
+ * which is what answers Phase 0's unmeasured "queue growth bound across a
+ * multi-day outage": a sink that is down for days cannot push the spool past
+ * `max_bytes`. The cost of that bound is that the oldest UNSENT records are
+ * dropped rather than kept — the same trade the log already makes, stated
+ * here rather than discovered later in a truncated file.
  */
 export function append_class_a_record(
     log_path: string,
-    record: ClassARecord,
+    record: ClassARecord | ClassADefectRecord,
     policy: RetentionPolicy = DEFAULT_RETENTION_POLICY,
     now: Date = new Date(),
+    spool_path: string | null = null,
 ): void {
     const payload = `${py_json_dumps_compact_sorted(record as unknown as Record<string, unknown>)}\n`;
-    fs.mkdirSync(path.dirname(log_path) || '.', { recursive: true });
-    fs.appendFileSync(log_path, payload, { encoding: 'utf-8' });
-    if (retention_due(log_path, policy, now)) {
-        enforce_retention(log_path, policy, now);
+    _append_and_bound(log_path, payload, policy, now);
+    if (spool_path !== null && spool_path !== '') {
+        _append_and_bound(spool_path, payload, policy, now);
     }
 }

package/src/agent-src/templates/scripts/telemetry/transport.ts

@@ -0,0 +1,169 @@
+/**
+ * Class-A transport — the enqueue half (road-to-org-telemetry Phase 2, step 2.1).
+ *
+ * WHY THIS IS NOT AN INLINE `fetch` AT SESSION END. Phase 0's second spike
+ * pre-registered "added latency at or below one second at p95" for an inline
+ * flush and measured it FAILING: a healthy sink costs 0.4 ms p95 and a
+ * refused connection 0.3 ms, but a BLACKHOLE — a socket that accepts and
+ * never answers, the shape a wedged sink actually takes — costs 1002 ms p95
+ * against a 1000 ms bar, because the timeout IS the cost. The step's own text
+ * defers to that result ("per the second spike's result"), and the result is:
+ * session end ENQUEUES ONLY, a detached sender flushes, and local retention
+ * carries what did not go out. The same spike measured that fallback at
+ * 20.5 ms p95 against the same blackhole — dominated by process spawn — and
+ * that is the number this module must not regress.
+ *
+ * SO THE SPOOL IS WRITTEN BY THE APPENDER, NOT BY THE FLUSH. A session-end
+ * flush that had to work out which records were already sent would need a
+ * byte watermark into the log, and the log is rewritten in place by
+ * `enforce_retention` — a watermark and a compacting file are a
+ * silent-corruption pair (offsets survive the prune; the records they point
+ * at do not). Enqueue-at-write has no watermark to invalidate: a record is
+ * spooled exactly once, by the only writer, in the same call that logs it.
+ *
+ * TWO PROPERTIES PHASE 0 SAID PHASE 2 MUST MEASURE, AND WHERE THEY LANDED.
+ * (1) Does a detached child survive teardown of the session process group —
+ * measured, see `agents/evidence/eval-findings/org-telemetry-p2-transport.md`.
+ * (2) The queue's growth bound across a multi-day outage — answered by
+ * construction here: the spool carries the SAME `RetentionPolicy` as the log,
+ * enforced by the same code, so a sink that is down for days cannot grow it
+ * past `max_bytes`. That bound is a decision to drop the oldest unsent
+ * records rather than to keep all of them, and it is stated rather than left
+ * for an operator to find in a truncated file.
+ *
+ * NO SINK EXISTS YET. `sink-choice` is transferred (a private repository is
+ * the council's preferred architecture, but creating it is an org-admin
+ * action outside this repository), so nothing in this tree can name a real
+ * endpoint. What ships here is the transport an org's own endpoint value
+ * activates; with no endpoint the settings never resolve `active` and not a
+ * byte moves.
+ */
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import {
+    DEFAULT_RETENTION_POLICY,
+    enforce_retention,
+    retention_due,
+    type RetentionPolicy,
+} from './remote.js';
+
+/**
+ * The outbound-flush timeout, in ms.
+ *
+ * The step says "at or below one second"; this is the bar itself rather than
+ * a value under it, because the spike measured the timeout as the dominant
+ * cost only for an INLINE flush. In the detached child the wait costs the
+ * session nothing, so shortening it would only turn recoverable slow sinks
+ * into dropped batches.
+ */
+export const DEFAULT_FLUSH_TIMEOUT_MS = 1000;
+
+/** `never` means no transport at all — no spool is written. */
+export const FLUSH_NEVER = 'never';
+
+/** The one flush policy that spools and sends. */
+export const FLUSH_SESSION_END = 'session-end';
+
+/**
+ * The spool that sits beside a record log.
+ *
+ * Derived rather than configured: a second path key would let an install
+ * point the spool somewhere the appender does not write, and the failure —
+ * records logged locally, nothing ever sent — is invisible. `.jsonl` is
+ * replaced rather than appended to so the spool is not itself picked up by a
+ * reader globbing `*.jsonl` for records.
+ */
+export function spool_path_for(log_path: string): string {
+    const dir = path.dirname(log_path);
+    const base = path.basename(log_path).replace(/\.jsonl$/u, '');
+    return path.join(dir, `${base}.spool.jsonl`);
+}
+
+/**
+ * Append one already-serialised record line to the spool and bound it.
+ *
+ * The line is passed in rather than re-serialised so the spooled bytes are
+ * byte-identical to the logged bytes: a sink and a local inspection of the
+ * same record must not be able to disagree.
+ */
+export function enqueue_line(
+    spool_path: string,
+    line: string,
+    policy: RetentionPolicy = DEFAULT_RETENTION_POLICY,
+    now: Date = new Date(),
+): void {
+    fs.mkdirSync(path.dirname(spool_path) || '.', { recursive: true });
+    fs.appendFileSync(spool_path, line, { encoding: 'utf-8' });
+    if (retention_due(spool_path, policy, now)) {
+        enforce_retention(spool_path, policy, now);
+    }
+}
+
+export interface SpawnSenderInput {
+    /** Absolute path to `flush_sender.mjs`. */
+    readonly sender_script: string;
+    readonly spool_path: string;
+    readonly endpoint: string;
+    readonly timeout_ms?: number;
+    /** Node binary. Defaults to the one running this process. */
+    readonly node_path?: string;
+}
+
+/**
+ * Spawn the detached sender and return immediately.
+ *
+ * `detached: true` + `stdio: 'ignore'` + `unref()` is the exact shape the
+ * spike measured at 20.5 ms p95, and all three are load-bearing: without
+ * `detached` the child dies with the session's process group, without
+ * `ignore` the parent holds pipe fds open, and without `unref` the parent's
+ * event loop waits for the child — which would reintroduce the very latency
+ * the spool exists to remove.
+ *
+ * The sender is a PLAIN-NODE `.mjs` on purpose. Its siblings in this
+ * directory are TypeScript resolved by `tsx` at import time; a detached child
+ * has no such resolution to inherit, so a `.ts` sender would depend on a
+ * `tsx` binary being findable in a consumer install at teardown — the least
+ * observable moment there is. `process.execPath` is the node already running
+ * this hook, so it exists by construction.
+ *
+ * Returns `true` when the child was spawned. Never throws: a transport that
+ * can fail a session is worse than a transport that loses a batch, and the
+ * batch is not lost — it stays in the spool for the next flush.
+ */
+export function spawn_detached_sender(input: SpawnSenderInput): boolean {
+    try {
+        const child = spawn(
+            input.node_path ?? process.execPath,
+            [
+                input.sender_script,
+                '--spool',
+                input.spool_path,
+                '--endpoint',
+                input.endpoint,
+                '--timeout',
+                String(input.timeout_ms ?? DEFAULT_FLUSH_TIMEOUT_MS),
+            ],
+            { detached: true, stdio: 'ignore' },
+        );
+        child.unref();
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Is there anything to send?
+ *
+ * Checked before the spawn so an idle session pays a `stat` rather than a
+ * process. Most sessions invoke no skill at all.
+ */
+export function spool_has_work(spool_path: string): boolean {
+    try {
+        return fs.statSync(spool_path).size > 0;
+    } catch {
+        return false;
+    }
+}

package/src/config/agent-settings.template.yml

@@ -395,8 +395,9 @@ project:
   #   public   -> a product with an intended market. Full three-question gate
   #               and the full ladder.
   # Default `public` = the behaviour every install had before this key existed.
-  # Absent resolves to `public` for the same reason: this package has no
-  # defaults layer, so absent means nobody said.
+  # Absent resolves to `public` too, mechanically: the template-defaults layer
+  # supplies this value beneath every file layer (agent_settings.ts:873) and
+  # this is not a settingsCarveOut key, so absent == an explicit `public`.
   audience: public
 
 # --- GitHub integration ---
@@ -587,6 +588,30 @@ roadmap:
   # only if your team genuinely commits work on a calendar plate.
   horizon_weeks: 0
 
+  # --- Class-1 gate budget (road-to-gate-autonomy Phase 2) ---
+  #
+  # The standing spend bound for CLASS-1 roadmap blockers — the gate class
+  # that is billable but reversible, where the human ingredient is spend
+  # consent rather than judgment (`agent-config gates --execute <id>`).
+  # Decided at `b-gate-budget-preauth`, option (a): TWO caps, because a
+  # per-run cap alone bounds one mistake and not a week of them. Every
+  # authorised run appends a receipt to
+  # `agents/runtime/state/gate-budget-ledger.jsonl`, which is the audit
+  # surface the rolling cap reads back.
+  #
+  # These caps bound the SIZE of an authorised spend. They never supply the
+  # authorisation: `gates --execute` still requires `--confirm` on every
+  # class-1 run, and a class-1 entry over either cap renders its consent
+  # line instead of running.
+  gate_budget:
+    # Per-run ceiling in USD. A class-1 entry whose `Budget:` field states a
+    # larger figure renders instead of running.
+    max_cost_per_run_usd: 5
+
+    # Rolling-window ceiling in USD over the last 7 days, summed from the
+    # receipt ledger. A run whose estimate would cross it renders instead.
+    max_cost_per_rolling_7d_usd: 25
+
 # --- Plan governance gates ---
 #
 # Three governance gates around the plan/delivery workflow (contract:

package/src/config/ci-local-parity.yml

@@ -184,6 +184,24 @@ ci_only:
 # worth remote enforcement, OR it should simply be added to a workflow. Prefer
 # adding it: a local-only gate is the direction that let real defects merge.
 local_only:
+  - id: check_single_delivery
+    class: developer-machine-scoped
+    reason: >
+      Compares the two host artefact layers — `~/.claude/**` against
+      `<project>/.claude/**` — and the overlap it looks for is a property of the
+      DEVELOPER MACHINE, not of the branch. In CI there is nothing to compare:
+      `.claude/` is gitignored and no workflow leg installs at user scope, so a
+      run finds zero layers on both sides and can only ever report "nothing was
+      compared". Measured, not assumed — that is why the gate carries an
+      OPTIONAL_SURFACE `allowEmpty` reason rather than treating the absence as a
+      dead scope. Declared rather than wired for the same reason
+      `check_pr_ci_current` below is: there is no remote equivalent to write, and
+      writing one would measure a topology no contributor has. The AI council
+      (2/2, 2026-08-19) converged on preflight for exactly this argument. Note the
+      gate is registered in REPORT mode while `road-to-single-delivery` Phase 2 is
+      halted; the `--enforce` flip lands with the partition and does not change
+      this declaration, because enforcing remotely would still have nothing to
+      enforce against.
   - id: check_pr_ci_current
     class: pre-push-scoped
     reason: >