@event4u/agent-config 16.0.0 → 16.2.0

package/src/scripts/hooks/run_continuation_hook.ts

@@ -152,10 +152,9 @@ import {
     sessionRefusalFile,
 } from '../_lib/turn_end_refusals.js';
 import { phaseLines } from '../_lib/roadmap_checkboxes.js';
+import { commandBearing, renderVerifyLine, type VerifyClause } from '../_lib/verify_clause.js';
 
-const EXIT_ALLOW = 0;
 /** Dispatcher-internal block code; the dispatcher maps stop-slot 1 → host 2. */
-const EXIT_BLOCK = 1;
 
 /**
  * The gate's cap, IMPORTED rather than restated — the two must agree by
@@ -185,6 +184,7 @@ import { premiseMoved, readContextObservation } from '../_lib/context_observatio
 import { RUN_TERMINAL_VOCABULARY_VERSION } from '../_lib/outcome_vocabularies.js';
 import {
     HALT_ACTIONS,
+    buildLedgerEvent, parseDeliveryState, type DeliveryState,
     ladder,
     MAX_ITERATIONS,
     parseHaltStamp,
@@ -193,6 +193,7 @@ import {
     WALL_CLOCK_CAP_MS,
     type LadderAction,
 } from '../_lib/continuation_ladder.js';
+import { EXIT_ALLOW, EXIT_BLOCK } from './exit_codes.js';
 
 /**
  * DECLARED in `_lib/continuation_ladder.ts`, re-exported here: one declaration,
@@ -322,6 +323,8 @@ export interface RunState {
      * observed one, which is never a disagreement (`premiseMoved`).
      */
     context_fingerprint?: string;
+    /** DELIVERY position (8.1), written by the run; absent is no hold. */
+    delivery?: DeliveryState;
 }
 
 /**
@@ -372,8 +375,8 @@ export function isDuplicateFire(
 export interface NextStep {
     /** The step's own line, checkbox stripped, truncated for the message. */
     text: string;
-    /** The step's `verify:` command, when its line carries one. */
-    verify: string | null;
+    /** The step's `verify:` clause — command plus optional expectation. */
+    verify: VerifyClause | null;
 }
 
 export interface ScanResult {
@@ -478,15 +481,15 @@ export function scanOpenSteps(text: string): ScanResult {
  * The comment form wins when both are present: it is the machine-readable one,
  * and a step carrying both has a human-facing line and a tooling-facing line
  * rather than two commands.
+ *
+ * The hook's narrowing only — a prose clause is not a command, and the
+ * continuation message renders commands. It parses nothing itself: a second
+ * copy of the arrow grammar is how this hook and `closure_scan` would drift,
+ * and a drifted grammar stops reading expectations without failing anything.
+ * `_lib/verify_clause.ts` owns the grammar and the sweep that keeps it single.
  */
-export function extractVerify(stepText: string): string | null {
-    const html = /<!--\s*verify:\s*(.*?)\s*-->/.exec(stepText);
-    if (html !== null) return (html[1] as string).trim() || null;
-    // `verify:` then the command, both backticked. The label's own backticks
-    // are optional because the tree carries `verify:` and `` `verify:` ``.
-    const backticked = /`?verify:`?\s*`([^`]+)`/.exec(stepText);
-    if (backticked !== null) return (backticked[1] as string).trim() || null;
-    return null;
+export function extractVerify(stepText: string): VerifyClause | null {
+    return commandBearing(stepText);
 }
 
 /**
@@ -651,6 +654,10 @@ function readState(file: string): RunState | null {
         if (o['inert_reported'] === true) {
             rec.inert_reported = true;
         }
+        // Round-tripped for the same reason `history_source` is: without this the
+        // 8.1 hold is dead code that reads as shipped.
+        const dlv = parseDeliveryState(o['delivery']);
+        if (dlv !== undefined) rec.delivery = dlv;
         // Round-tripped for the same reason `history_source` is: dropped, the
         // premise would be re-recorded every fire from the newest observation, so
         // the two sides could never differ and the rung would be dead code.
@@ -1252,7 +1259,6 @@ export function main(): number {
         return EXIT_ALLOW;
     }
 
-
     // The two-tree provenance, carried on every event this run emits. See
     // `provenance()` for the six fields and why none of them is a boolean.
     //
@@ -1384,14 +1390,14 @@ export function main(): number {
     const observed = readContextObservation(workspaceRoot)?.fingerprint ?? null;
     const premiseInvalidated = premiseMoved(state.context_fingerprint, observed);
 
+    const delivery = parseDeliveryState(state.delivery) ?? null;
     const action = ladder(
-        state,
-        scan.open,
-        Date.now(),
+        state, scan.open, Date.now(),
         scan.blocked,
         undefined,
         unavailable,
         premiseInvalidated,
+        delivery,
     );
 
     if (action !== 'engage') {
@@ -1408,23 +1414,13 @@ export function main(): number {
         const alreadyBlocked =
             action === 'blocked' && eventAlreadyLogged(workspaceRoot, runId, slug, 'blocked');
         if (!alreadyStamped && !alreadyBlocked) {
-            appendEvent(workspaceRoot, {
-                event: action,
-                run_id: runId,
-                roadmap: slug,
-                turn: turnOrdinal,
-                iterations: state.iterations,
-                open: scan.open,
-                blocked: scan.blocked,
-                // A ledger line is a persisted shape carrying a `RunTerminalState`,
-                // so it names the vocabulary version it was written against: a
-                // reader meeting an unknown value can then tell a newer writer
-                // from a corrupt row.
-                terminal_state: terminalStateFor(action),
-                terminal_vocabulary_version: RUN_TERMINAL_VOCABULARY_VERSION,
-                at: new Date().toISOString(),
-                ...roots,
-            });
+            const line = buildLedgerEvent(
+                { action, runId, slug, turn: turnOrdinal, iterations: state.iterations,
+                  open: scan.open, blocked: scan.blocked, delivery },
+                RUN_TERMINAL_VOCABULARY_VERSION,
+                new Date(),
+            );
+            appendEvent(workspaceRoot, { ...line, ...roots } as JsonObject);
         }
         if (action === 'complete') {
             // Only a COMPLETION clears the state, so a later run on the same
@@ -1490,8 +1486,7 @@ export function main(): number {
 
 function _continuationText(slug: string, scan: ScanResult, iteration: number): string {
     const stepLine = scan.next
-        ? `Next step: ${scan.next.text}` +
-          (scan.next.verify ? `\n  verify: ${scan.next.verify}` : '')
+        ? `Next step: ${scan.next.text}${renderVerifyLine(scan.next.verify)}`
         : 'Next step: (first open checkbox in the roadmap)';
     return (
         `run-continuation: the contracted roadmap \`${slug}\` has ${scan.open} open ` +

package/src/scripts/hooks/skill_route_hook.ts

@@ -143,10 +143,9 @@ import { isSyntheticPrompt } from "../_lib/prompt_shape.js";
 import { OBSERVATION_LOG, readObservationLog, resolveSkillCatalogueRoots } from "../_lib/skill_catalogue.js";
 import { knownBareNames } from "../_lib/skill_catalogue_series.js";
 import { _tokenize, rank, type RankRow } from "../skill_tools/score_skill_relevance.js";
+import { EXIT_ALLOW, EXIT_WARN } from './exit_codes.js';
 
-const EXIT_ALLOW = 0;
 /** See the header: reduced to a real exit of 0 by `emitFor`'s warn branch. */
-const EXIT_WARN = 2;
 
 /**
  * Minimum top-1 ranker score before this concern speaks.

package/src/scripts/hooks/source_first_gate_hook.ts

@@ -95,8 +95,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { is_replay_mode } from './state_io.js';
 import { readHookStdin } from './hook_stdin.js';
 import { resolveConsumerRoot } from './subagent_ledger_hook.js';
-
-const EXIT_ALLOW = 0;
+import { EXIT_ALLOW } from './exit_codes.js';
 
 /** Would-warns per session before the valve goes silent — `MAX_NUDGES` shape. */
 export const MAX_SHADOW_WARNS = 2;

package/src/scripts/hooks/spawn_guard_shadow_hook.ts

@@ -55,8 +55,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { appendLedgerLine, openRecordStats, resolveConsumerRoot } from './subagent_ledger_hook.js';
 import { readHookStdin } from './hook_stdin.js';
-
-const EXIT_ALLOW = 0;
+import { EXIT_ALLOW } from './exit_codes.js';
 
 type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
 type JsonObject = { [k: string]: JsonValue };

package/src/scripts/hooks/subagent_ledger_hook.ts

@@ -115,8 +115,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { countContractFields, validateResponse } from '../_lib/subagent_response.js';
 import { atomic_write_json, is_replay_mode } from './state_io.js';
 import { readHookStdin } from './hook_stdin.js';
-
-const EXIT_ALLOW = 0;
+import { EXIT_ALLOW } from './exit_codes.js';
 
 type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
 type JsonObject = { [k: string]: JsonValue };

package/src/scripts/hooks/suggestion_capture_hook.ts

@@ -51,8 +51,8 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { unwrap } from './envelope.js';
 import { readHookStdin } from './hook_stdin.js';
 import { humanTypedThisTurn } from '../_lib/machine_wake.js';
+import { EXIT_ALLOW } from './exit_codes.js';
 
-const EXIT_ALLOW = 0;
 const SETTINGS_FILE = '.agent-settings.yml';
 const SINK_REL = path.join('agents', 'runtime', 'state', 'audit', 'suggestion-capture.jsonl');
 const LATCH_REL = path.join('agents', 'runtime', 'state', 'suggestion-latch.json');

package/src/scripts/hooks/table_fingerprint.ts

@@ -0,0 +1,49 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * table_fingerprint — the content fingerprint a compiled plumbing table is
+ * validated against.
+ *
+ * Extracted from `dispatch_hook._manifest_fingerprint` so a SECOND table
+ * (`host_lowering.yaml`) can use the same helper without importing the
+ * dispatcher: `dispatch_hook` → `host_semantics` → `host_lowering` is a live
+ * import chain, so the reverse edge would be a cycle.
+ *
+ * DELIBERATELY CONTENT-DERIVED, NOT MTIME. The first version of the manifest
+ * fast path compared mtimes and that was a measured defect, not a theoretical
+ * one: on a fresh `actions/checkout` both files carry the checkout timestamp in
+ * whatever order git wrote them, so whether the optimisation applied at all was
+ * a coin flip — it won on a PR run (p95 129 ms) and lost on the trunk
+ * (p95 186 ms) for the same commit. A fingerprint is deterministic wherever the
+ * tree came from.
+ *
+ * SHA-256 over the UTF-8 bytes, plus the length. This replaced an FNV-1a loop
+ * in step 3.1 of `road-to-a-kernel-that-guards-its-plumbing`, and the reason
+ * the old one existed no longer holds. Its header said a cryptographic hash was
+ * refused because `require('node:crypto')` costs 8 ms of process start, which
+ * is most of what the precompiled table saves. Both halves were re-measured
+ * against the tree as it now stands, and both had gone stale:
+ *
+ * - The module is ALREADY LOADED. `dist/hooks/dispatch.js` carries 23
+ *   top-level `import … from "node:crypto"` statements from other parts of the
+ *   graph, so the 8 ms is paid on every dispatch whether this function uses it
+ *   or not. There is no startup cost left to avoid.
+ * - SHA-256 is FASTER here, not slower: 0.106 ms against 0.113 ms over the
+ *   99,792-byte manifest, because Node's digest is native and the FNV-1a loop
+ *   was 99,792 interpreted `charCodeAt` calls.
+ *
+ * The change is therefore free, and it buys the property the old comment had to
+ * disclaim: this now guards against a CRAFTED sibling as well as a stale one,
+ * which is what a file called a fingerprint should mean when the roadmap around
+ * it is about integrity.
+ *
+ * Producer and both consumers import THIS function — `compile_hook_manifest`
+ * writes the value, `dispatch_hook` and `host_lowering` check it — so the
+ * algorithm can never drift between the two sides. A mismatch is not a failure
+ * either way: the reader falls through to parsing the YAML source, which is
+ * correct and merely slower.
+ */
+export function tableFingerprint(text: string): string {
+    const digest = createHash('sha256').update(text, 'utf-8').digest('hex');
+    return `${digest}:${String(text.length)}`;
+}

package/src/scripts/hooks/telemetry_flush_hook.ts

@@ -45,8 +45,7 @@ import {
 import { is_replay_mode } from './state_io.js';
 import { readHookStdin } from './hook_stdin.js';
 import { _resolveRoot, readSettingsFor } from './telemetry_usage_hook.js';
-
-const EXIT_ALLOW = 0;
+import { EXIT_ALLOW } from './exit_codes.js';
 
 /**
  * Where `flush_sender.mjs` lives, relative to this module.

package/src/scripts/hooks/telemetry_usage_hook.ts

@@ -57,8 +57,7 @@ import {
 } from '../../agent-src/templates/scripts/telemetry/transport.js';
 import { is_replay_mode } from './state_io.js';
 import { readHookStdin } from './hook_stdin.js';
-
-const EXIT_ALLOW = 0;
+import { EXIT_ALLOW } from './exit_codes.js';
 
 /** The tool name Phase 0 spike 1 confirmed for a skill invocation. */
 export const SKILL_TOOL_NAME = 'Skill';

package/src/scripts/hooks/tool_result_bytes_hook.ts

@@ -24,10 +24,10 @@
  *
  * PRIVACY BY CONSTRUCTION — never widen this file to record content.
  *
- * The record type has exactly three fields and NONE of them can hold free
+ * The record type has exactly four fields and NONE of them can hold free
  * text: a timestamp, a tool NAME (an id-shaped enum — `Read`, `Bash`,
  * `Grep` — the same single host string `orchestration_record_hook` already
- * records), and a BYTE COUNT. A tool result routinely carries file
+ * records), and TWO BYTE COUNTS. A tool result routinely carries file
  * contents, command output, secrets in an env dump, and customer data from
  * an API response. None of it reaches this file's output, because the
  * output has no field able to carry it. A record shape that cannot hold a
@@ -47,6 +47,34 @@
  * identical while the cost came back. The `RESULT_KEYS` literals below are the
  * key NAMES this concern looks under, not a read of the body.
  *
+ * TWO COUNTS, ONE OF THEM REDUNDANT TODAY. `raw_bytes` is what
+ * the host handed the dispatcher; `delivered_bytes` is what reached the
+ * model. Today they are EQUAL BY CONSTRUCTION, and the construction is
+ * checkable: nothing under `src/` or `docs/` emits the host's result-rewrite
+ * field, so no concern can rewrite a tool result on its way past. That
+ * absence is a grep, and the grep lives in this concern's test rather than
+ * in this sentence - a claim in a comment is not falsifiable, and naming the
+ * field here would put a match in the very tree the grep sweeps.
+ *
+ * Recording both NOW is what makes a later reduction measurable instead of
+ * asserted. With one field, a future release that starts trimming results
+ * has no before-number and can only claim an improvement; with two, the
+ * delta is in the census the day the trimming lands. The cost of the second
+ * field is one integer per line in one workspace — see the gate below.
+ *
+ * DEFAULT OFF OUTSIDE THE MAINTAINER WORKSPACE. A byte counter on every
+ * tool call in every consumer install is
+ * the cheapest possible way to add a second unread instrument: it costs a
+ * write per tool call, accumulates volume, and answers a question only this
+ * package's maintainers have asked. So {@link resolvesMaintainerWorkspace}
+ * gates the write, and with no maintainer workspace resolved a dispatch
+ * writes nothing at all — not an empty line, not a file.
+ *
+ * A consumer who WANTS the census sets `AGENT_CONFIG_TOOL_BYTE_CENSUS=1`.
+ * That is a deliberate opt-in and it is the only other way the write
+ * happens; there is no settings key, because a key would put the decision in
+ * a file this concern would then have to parse on the hot path.
+ *
  * ── Always exit 0 ─────────────────────────────────────────────────────
  *
  * A `warn` (exit 2) is read as a hard BLOCK on this host, and this concern
@@ -56,8 +84,8 @@
  *
  * ── Absence is recorded, not inferred ─────────────────────────────────
  *
- * A payload carrying no readable result writes a line with `bytes: null`
- * and `measurable: false` rather than writing nothing. The two cases are
+ * A payload carrying no readable result writes a line with both byte fields
+ * null and `measurable: false` rather than writing nothing. The two cases are
  * otherwise byte-identical in the output — "this host does not carry tool
  * results in its PostToolUse payload" and "no tools ran" would produce the
  * same empty file, and the first is a finding about the instrument's own
@@ -72,8 +100,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { is_replay_mode } from './state_io.js';
 import { readHookStdin } from './hook_stdin.js';
 import { stubbedBytes } from './payload_stub.js';
-
-const EXIT_ALLOW = 0;
+import { EXIT_ALLOW } from './exit_codes.js';
 
 type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
 type JsonObject = { [k: string]: JsonValue };
@@ -85,7 +112,7 @@ function isObject(v: unknown): v is JsonObject {
 /**
  * Census file, relative to the consumer repo root. Sibling of
  * `injection-census.jsonl` in the same directory and the same
- * `{ts, …, bytes}` line shape — one family, two units: that file counts
+ * `{ts, …, bytes}` line family — one family, two units: that file counts
  * bytes this suite injects, this one counts bytes the host's tools do.
  * Gitignored via `/agents/runtime/`.
  */
@@ -169,13 +196,65 @@ function censusFile(consumerRoot: string): string {
 export interface CensusLine {
     ts: string;
     tool: string | null;
-    bytes: number | null;
+    /** UTF-8 bytes the host handed the dispatcher. `null` ⇒ unmeasurable. */
+    raw_bytes: number | null;
+    /**
+     * UTF-8 bytes that reached the model.
+     *
+     * Equal to {@link CensusLine.raw_bytes} by construction today — nothing in
+     * this tree rewrites a tool result. It is recorded anyway so that a later
+     * reduction is a measured delta rather than a claim. See the header.
+     */
+    delivered_bytes: number | null;
     /** `false` ⇒ the payload carried no readable result. See the header. */
     measurable: boolean;
 }
 
+/** `package.json.name` of the workspace this census is for. */
+export const MAINTAINER_PACKAGE_NAME = '@event4u/agent-config';
+
+/** Deliberate consumer opt-in. Any other value, or unset, leaves the census off. */
+export const CENSUS_OPT_IN_ENV = 'AGENT_CONFIG_TOOL_BYTE_CENSUS';
+
+/** Memoised per root: this is read once per dispatched tool call otherwise. */
+const _maintainerCache = new Map<string, boolean>();
+
+/** Test seam — the cache would otherwise outlive a fixture root's contents. */
+export function _resetMaintainerCache(): void {
+    _maintainerCache.clear();
+}
+
+/**
+ * Does this root resolve the maintainer workspace?
+ *
+ * Read off `package.json.name`, which is the cheapest unambiguous marker of
+ * the one workspace whose `workspaces: [agent-config-maintainer]` artefacts
+ * are active. A settings key was rejected: it would put a YAML parse on the
+ * post_tool_use path for a decision that never changes within a checkout.
+ *
+ * Any failure — no `package.json`, unreadable, unparseable, a different name
+ * — resolves to FALSE. The default is silence, which is the safe direction
+ * for an instrument nobody in that workspace is going to read.
+ */
+export function resolvesMaintainerWorkspace(consumerRoot: string): boolean {
+    if (process.env[CENSUS_OPT_IN_ENV] === '1') return true;
+    const cached = _maintainerCache.get(consumerRoot);
+    if (cached !== undefined) return cached;
+    let verdict = false;
+    try {
+        const raw = fs.readFileSync(path.join(consumerRoot, 'package.json'), 'utf8');
+        const parsed = JSON.parse(raw) as unknown;
+        verdict = isObject(parsed) && parsed['name'] === MAINTAINER_PACKAGE_NAME;
+    } catch {
+        verdict = false;
+    }
+    _maintainerCache.set(consumerRoot, verdict);
+    return verdict;
+}
+
 export function _appendCensusLine(consumerRoot: string, line: CensusLine): void {
     if (is_replay_mode()) return;
+    if (!resolvesMaintainerWorkspace(consumerRoot)) return;
     const file = censusFile(consumerRoot);
     fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.appendFileSync(file, `${JSON.stringify(line)}\n`, 'utf8');
@@ -193,7 +272,12 @@ export function processEnvelope(envelope: JsonValue, consumerRoot: string): numb
         _appendCensusLine(consumerRoot, {
             ts: new Date().toISOString(),
             tool: _toolName(payload, envelope),
-            bytes,
+            raw_bytes: bytes,
+            // Equal BY CONSTRUCTION, not by copy-as-convenience: no concern
+            // can rewrite a result between the host and the model, because
+            // nothing under src/ or docs/ emits the host's rewrite field. The
+            // test pins that as a grep; naming the field here would match it.
+            delivered_bytes: bytes,
             measurable: bytes !== null,
         });
     } catch {