@event4u/agent-config 14.19.0 → 14.20.0

package/dist/scripts/mcp_server/telemetry.js

@@ -0,0 +1,148 @@
+// MCP telemetry sink — Phase 1 J4 instrumentation.
+//
+// Per `agents/roadmaps/archive/road-to-mcp-full-coverage.md` §Phase 1 J4 +
+// `docs/contracts/mcp-tool-stub-envelope.md`, both transports log every
+// `tools/call` with `{tool_name, client_id_hash, ts, transport,
+// outcome}`. The stdio-lite surface (`src/cli/mcp/`) appends a sixth,
+// optional `host` field; callers that do not know their client omit it and
+// their records stay byte-identical to the frozen five-field envelope. Payload bodies are never logged; the client identifier is
+// hashed at the server boundary so the queryable store never sees raw
+// identity.
+//
+// Outcomes:
+//
+// - `implemented` — real handler ran (no envelope returned).
+// - `stub` — catalog entry missing this transport; `not_implemented`
+//   envelope returned.
+// - `latent_demand` — caller asked for a tool not in the catalog.
+//
+// The sink writes JSONL to `agents/runtime/mcp-telemetry/calls.jsonl` under the
+// consumer root. Failure to write must not break the wire surface: the
+// `record_call` helper swallows OSError + ValueError and emits a single
+// warning to stderr.
+//
+// TS port of the retired Python telemetry.py (ADR-200). Preserves the full public surface:
+//   - Outcome type, TELEMETRY_REL_DIR, TELEMETRY_FILENAME, hash_client_id,
+//     build_record, record_call.
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+// Stable file location relative to consumer_root. Phase 2 K1 routes
+// this into a queryable store; Phase 1 only needs the file to exist.
+export const TELEMETRY_REL_DIR = 'agents/runtime/mcp-telemetry';
+export const TELEMETRY_FILENAME = 'calls.jsonl';
+// Truncation length for the client_id hash. 12 hex chars = 48 bits of
+// entropy — enough to distinguish hundreds of consumers without
+// becoming a re-identification vector.
+const _HASH_LEN = 12;
+/**
+ * Identity components that together pin a consumer install.
+ *
+ * USER + machine hostname + repo path is a stable triple that survives
+ * sessions without leaking PII into the log. The hash never reverses.
+ */
+function _client_id_seed() {
+    const user = process.env.USER || process.env.USERNAME || 'unknown';
+    let host = process.env.HOSTNAME;
+    if (!host) {
+        // Mirrors Python `os.uname().nodename` (POSIX) — Node exposes
+        // `os.hostname()`. Guarded so an empty value falls through to "unknown".
+        try {
+            host = os.hostname();
+        }
+        catch {
+            host = undefined;
+        }
+    }
+    host = host || 'unknown';
+    const cwd = _resolvePath(process.cwd());
+    return `${user}|${host}|${cwd}`;
+}
+/** SHA-256(seed) truncated to 12 hex chars. Boundary-only call. */
+export function hash_client_id(seed) {
+    const raw = seed !== undefined ? seed : _client_id_seed();
+    const digest = crypto.createHash('sha256').update(Buffer.from(raw, 'utf-8')).digest('hex');
+    return digest.slice(0, _HASH_LEN);
+}
+/**
+ * Resolve a path like Python `Path(...).resolve()` — absolutize + realpath
+ * the existing prefix, tolerating a non-existent tail (Python resolve does
+ * not require the path to exist; `fs.realpathSync` does, so fall back to a
+ * plain absolute path on ENOENT).
+ */
+function _resolvePath(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+/** Pick the JSONL location. Defaults to CWD when no override given. */
+function _resolve_log_path(consumer_root) {
+    const root = _resolvePath(consumer_root ?? process.cwd());
+    return path.join(root, TELEMETRY_REL_DIR, TELEMETRY_FILENAME);
+}
+/** ISO-8601 UTC timestamp, seconds precision. */
+function _now_iso() {
+    // Mirrors Python `time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())`.
+    return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+/**
+ * Pure helper — assemble the record without touching the filesystem.
+ *
+ * Field insertion order matches the Python dict literal so the
+ * compact-JSON serialization is byte-identical.
+ */
+export function build_record(options) {
+    const { tool_name, outcome, transport, client_id_hash_value, ts, host } = options;
+    const record = {
+        tool_name,
+        client_id_hash: client_id_hash_value || hash_client_id(),
+        ts: ts || _now_iso(),
+        transport,
+        outcome,
+    };
+    // `host` is APPENDED, and only when a caller supplies one, so a record
+    // written by a caller that does not know its client stays byte-identical
+    // to the five-field envelope the stub contract froze. It is a closed
+    // vocabulary resolved at the boundary (see `src/cli/mcp/telemetry.ts`),
+    // never a free-form string: a record type that cannot hold arbitrary text
+    // has no scrubber to fail.
+    if (typeof host === 'string' && host !== '') {
+        record.host = host;
+    }
+    return record;
+}
+/**
+ * Append one JSONL record. Returns the record or null on failure.
+ *
+ * Failures are swallowed: telemetry must never break the wire surface.
+ * A single `mcp-server: warn: telemetry` line is emitted to stderr
+ * so silent-failure windows show up in the boot log and the J6
+ * healthcheck can detect them.
+ */
+export function record_call(options) {
+    const { tool_name, outcome, transport, consumer_root, client_id_hash_value, host } = options;
+    const record = build_record({
+        tool_name,
+        outcome,
+        transport,
+        client_id_hash_value,
+        host,
+    });
+    const target = _resolve_log_path(consumer_root ?? undefined);
+    try {
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        // json.dumps(record, separators=(",", ":")) — compact, no spaces.
+        fs.appendFileSync(target, JSON.stringify(record) + '\n', { encoding: 'utf-8' });
+    }
+    catch (exc) {
+        const message = exc instanceof Error ? exc.message : String(exc);
+        process.stderr.write(`mcp-server: warn: telemetry write failed: ${message}\n`);
+        return null;
+    }
+    return record;
+}
+//# sourceMappingURL=telemetry.js.map

package/docs/guidelines/agent-infra/naming.md

@@ -34,7 +34,7 @@ source: package
 |---|---|---|
 | `{concern}` | Behavioral constraint | `scope-control`, `ask-when-uncertain` |
 | `{domain}-{concern}` | Domain-specific rule | `php-coding`, `e2e-testing` |
-| `{action}-{target}` | Trigger-based auto rule | `capture-learnings`, `downstream-changes` |
+| `{action}-{target}` | Trigger-based auto rule | `invite-challenge`, `downstream-changes` |
 
 ### Commands
 

package/docs/guidelines/agent-infra/security-lint-containment.md

@@ -45,18 +45,51 @@ are *expected* to contain illustrative patterns. Only a full-weight (1.0×)
 **HIGH** finding in a real artifact fails the build. (`is_example_path()` in the
 shared lib defines the path set.)
 
-### 3. Per-file pragma
+### 3. Bound pragma
 
-A single check can be suppressed for one file with an auditable, reasoned
-marker placed anywhere in the file:
+A single check can be suppressed for **specific evidence** in one file with an
+auditable, reasoned, content-bound marker placed anywhere in the file:
 
 ```
-<!-- security-lint: allow instruction-smuggling "teaching example: quotes a prompt-injection string" -->
+<!-- security-lint: allow instruction-smuggling "teaching example: quotes a prompt-injection string" sha256:<hex> -->
 ```
 
 - The `<check>` token is the linter's check id (`hidden-unicode`,
-  `instruction-smuggling`, `mcp-config-security`, `dangerous-frontmatter`).
+  `mixed-script-confusable`, `instruction-smuggling`, `mcp-config-security`,
+  `dangerous-frontmatter`).
 - The `"<reason>"` is **mandatory** — an empty reason does not parse.
+- Each `sha256:<hex>` **binds the suppression to one accepted match**. Repeat the
+  token once per accepted match; a file with three accepted matches carries three
+  hashes. Anything the check finds that is not in that set is still reported.
+- The fingerprint covers the **check id**, the artifact's **source identity**, and
+  the **normalized text of the matched line** — ASCII whitespace runs collapse so
+  a reflow does not break the binding, and nothing else is stripped, because the
+  zero-width characters this suite hunts are exactly what a wider normalizer
+  would erase. It is deliberately NOT the line number (an unrelated insert above
+  would break every pragma in the file) and NOT the whole file (every unrelated
+  edit would re-fire it, which is how blanket suppressions get written).
+  A `dist/agent-src/` path folds to its `src/` original first: the projection is
+  byte-exact by contract, so an artifact and its copy are one identity.
+- **A pair pinned equal by a parity test carries ONE HASH PER IDENTITY.** The
+  fold above covers `dist/agent-src/` and nothing else, so where a second
+  hand-maintained copy exists and a test asserts the two are byte-identical —
+  `src/subagents/<stem>.md` and `docs/wedge/<stem>/<stem>.md`, pinned by
+  `tests/scripts/subagent_distribution.test.ts` — one hash cannot satisfy both:
+  giving each file its own makes the lines differ and reds the parity test,
+  which is exactly how this was found. Put BOTH hashes in BOTH files. That is
+  what the repeatable token is for, and it is why the grammar has one. A purely
+  GENERATED third copy (`.claude/agents/<stem>.md`) needs no hash of its own:
+  nothing scans it and nobody edits it, so binding it would be a fingerprint
+  for an identity no finding can arise at.
+- Compute one with the linter itself, never by hand — a hash typed from memory
+  is a suppression nobody audited.
+
+**The unbound form still parses**, suppresses the whole file as it always did,
+and reports itself as a `legacy-pragma` LOW finding. That is a migration signal,
+not a mode to choose: a key lookup with no content binding accepts whatever the
+matched text is later changed to say, which is the defect the hash exists to
+close. There are zero unbound pragmas in the tree.
+
 - Pragmas are **counted and capped**: crossing **20** across the repo means the
   linter is mis-scoped. Stop adding pragmas; redesign or narrow the check
   (escalate per `autonomous-execution` — the allowlist-growth antipattern).
@@ -72,7 +105,14 @@ marker placed anywhere in the file:
 
 `security-example` fence → confidence weight → pragma. A HIGH finding survives
 to fail the build only when it is full-weight (not in an example path), not
-inside a `security-example` fence, and not covered by a matching pragma.
+inside a `security-example` fence, and not covered by a pragma whose fingerprint
+set contains that match.
+
+One consumer deliberately departs from the weighting rung: `skill_scout`'s
+`security_licence` gate refuses a quarantined candidate on **any** HIGH finding,
+whatever its weight. Path-based confidence is a false-positive containment device
+for a corpus whose provenance is known; a third-party candidate has none, and a
+directory named `examples/` in it is the submitter's word for it.
 
 ## See also
 

package/docs/guidelines/agent-infra/self-improvement-pipeline.md

@@ -4,10 +4,10 @@ Five-stage flow that turns real project experience into reviewed
 rule / skill / command / guideline changes. No autonomous self-edits;
 every upstream change ships via a human-reviewed PR.
 
-Referenced by `road-to-curated-self-improvement.md`. Consumed by the
-existing skills `capture-learnings`, `learning-to-rule-or-skill`,
-`skill-improvement-pipeline`, and `upstream-contribute` — each becomes
-a stage, not a standalone invocation.
+Referenced by `road-to-curated-self-improvement.md`. Consumed by the live
+artifacts — the `skill-improvement-trigger` rule and the existing skills
+`learning-to-rule-or-skill`, `skill-improvement-pipeline`, and
+`upstream-contribute` — each becomes a stage, not a standalone invocation.
 
 ## The five stages
 

package/docs/guidelines/agent-infra/untrusted-input-spotlighting.md

@@ -1,4 +1,4 @@
-<!-- security-lint: allow instruction-smuggling "defense guideline: quotes role-takeover phrases (ignore previous instructions, you are now, <IMPORTANT>) to teach refusal" -->
+<!-- security-lint: allow instruction-smuggling "defense guideline: quotes role-takeover phrases (ignore previous instructions, you are now, <IMPORTANT>) to teach refusal" sha256:d84759534e0fd3ebc5a66533b4a9f52364ef5286eaf3674a611c9c2adf89b969 sha256:f08c68182232149c7ecd881e88ca81dc98a9313c06ba6d010b065f9feef2c149 sha256:4f5936bb0a57de8ff3ce590fb12607cdcb046a31262b5e4d40377c6e6184f494 -->
 
 # untrusted-input spotlighting + least-agency mapping
 

package/docs/guidelines/redundancy-taxonomy.md

@@ -86,6 +86,34 @@ translation frequently denote different mechanisms — here `route`, `dispatch`,
 five ways — so a sweep over them destroys information the echo classes exist to
 protect.
 
+## The avoid-list — one term, one concept
+
+A homonym collision is only half-diagnosed when it is classified. The other
+half is the **decision**: which concept keeps the word, and what every other
+sense is called instead. This list carries the decided ones. A word is added
+here when the same term has been observed denoting more than one shipped
+mechanism; it is removed only when the collision is gone from the tree, never
+because the entry became inconvenient.
+
+Read the columns as a rename instruction for **prose you write from now on**.
+The identifier layer is decided separately and per cluster, exactly as the
+prose/identifier split above requires — a term may be `canonicalize-term` in
+prose and `keep-distinct` in identifiers, and both verdicts are recorded.
+
+| Term | Concept that keeps the word | Other senses, and what to call them | Identifier verdict |
+|---|---|---|---|
+| `envelope` | The **transport wrapper** around a payload — `OutcomeEnvelope` (a run's terminal outcome, `src/scripts/_lib/outcome_envelope.ts`) and the `CHECKPOINT` envelope a worker capsule rides in. | The **session continuity record** is a **capsule**. The word is not chosen for readability — it is the shipped discriminator (`CAPSULE_SCHEMA_VERSION`, `CAPSULE_VARIANTS = ['worker','main_session']`, `src/scripts/_lib/subagent_capsule.ts`), so the surviving term is read off what ships rather than off what reads best. | `keep-distinct` for now. `MainSessionRecycleEnvelope` and `RECYCLE_ENVELOPE_*` keep their names until a rename is costed on its own; the prose rule binds immediately and the symbols are a separate blast radius. |
+| `handoff` | The **session-to-session continuity handover** a developer invokes — the `handoff` verb and the `/agent-handoff` command. | The lint over senior-tier skills' `## Related Skills` edges is a **cross-wing skill link**, never "a handoff". | `keep-distinct`, recorded reason: `lint_handoffs.ts` mirrors a ported CLI contract (ADR-200) whose name is an external surface. Its module docstring already says "cross-wing", which is the disambiguation the prose rule now requires everywhere else. |
+
+**Why a list and not a linter.** `lint_canonical_terms` decides *spelling*
+pairs, where one side is mechanically wrong. A homonym is not mechanically
+wrong anywhere — every occurrence is a legitimate word for a legitimate
+concept, and only the reader's inability to tell them apart is the defect. A
+gate that flagged `envelope` would flag the entry that is supposed to survive.
+So this list is enforced at review, by citation, and its cost of being ignored
+is the cost the taxonomy already names: the model telling you it has not
+decided.
+
 ## Why any of this is worth a gate at all
 
 Generated code trends toward duplication rather than reuse: measured

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@event4u/agent-config",
     "mcpName": "io.github.event4u-app/agent-config",
-    "version": "14.19.0",
+    "version": "14.20.0",
     "description": "Governed skills, rules and commands for AI coding tools (Claude Code, Cursor, Windsurf, Copilot) — every claim machine-checked, including the counts in these badges.",
     "license": "MIT",
     "private": false,

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

@@ -0,0 +1,213 @@
+/**
+ * MCP-lite call reading for `telemetry:report` (roadmap step 4.2).
+ *
+ * Reads the sink the stdio-lite MCP server writes — the same
+ * `agents/runtime/mcp-telemetry/calls.jsonl` the kernel MCP server already
+ * used, not a second store — and aggregates it per tool and per host.
+ *
+ * WHY THIS IS A SEPARATE MODULE. The engagement aggregator models artefacts
+ * with a consulted/applied ratio; a `tools/call` has neither. Forcing MCP rows
+ * through it would have meant either widening the engagement schema or
+ * mislabelling a tool call as a "skill consulted", and both would have made the
+ * quartile buckets mean two different things at once.
+ *
+ * PUBLISH THE ZERO. `render_mcp_lite_markdown` emits the section even when the
+ * count is zero, and says so in words. The adjacent archived roadmaps in this
+ * family closed at `measured-null` precisely because nulls were published
+ * rather than buried; a section that disappears when empty would make "nobody
+ * used it" and "nobody looked" indistinguishable.
+ *
+ * WHAT A ZERO DOES NOT MEAN. The emitter that fills this sink did not exist
+ * before this roadmap, and it is gated off by default. A zero is therefore a
+ * statement about the age and the default of the instrument first, and about
+ * consumer behaviour only once a machine has run with the gate on. The rendered
+ * section says this itself, so a reader cannot lift the number away from it.
+ */
+
+import * as fs from 'node:fs';
+import { check_id_redaction } from './engagement.js';
+
+/** Where the stdio-lite server writes, relative to the consumer root. */
+export const MCP_LITE_LOG_REL = 'agents/runtime/mcp-telemetry/calls.jsonl';
+
+/** The transport label the stdio-lite surface stamps on every row it writes. */
+export const MCP_LITE_TRANSPORT = 'stdio-lite';
+
+export interface McpLiteAggregate {
+    /** The file that was read, whether or not it existed. */
+    log_path: string;
+    /** Rows on this transport that parsed and fell inside the window. */
+    calls: number;
+    /** Lines that did not parse as JSON, or carried no usable tool name. */
+    skipped_lines: number;
+    /** Rows that parsed but belong to another transport (the kernel server). */
+    other_transport: number;
+    by_tool: Map<string, number>;
+    by_host: Map<string, number>;
+    by_outcome: Map<string, number>;
+    earliest_ts: string | null;
+    latest_ts: string | null;
+}
+
+function _empty(log_path: string): McpLiteAggregate {
+    return {
+        log_path,
+        calls: 0,
+        skipped_lines: 0,
+        other_transport: 0,
+        by_tool: new Map(),
+        by_host: new Map(),
+        by_outcome: new Map(),
+        earliest_ts: null,
+        latest_ts: null,
+    };
+}
+
+function _bump(m: Map<string, number>, k: string): void {
+    m.set(k, (m.get(k) ?? 0) + 1);
+}
+
+/** Epoch ms for an ISO-8601 stamp, or `null` when it does not parse. */
+function _ms(ts: unknown): number | null {
+    if (typeof ts !== 'string') return null;
+    const v = Date.parse(ts);
+    return Number.isNaN(v) ? null : v;
+}
+
+/**
+ * Aggregate the lite surface's calls.
+ *
+ * A missing file is an empty reading, never an error: the overwhelmingly common
+ * case is a machine that has simply never run the server, and that is a zero,
+ * not a failure. `since` is an epoch-ms lower bound, matching the engagement
+ * aggregator's own window semantics; a row with an unreadable timestamp is
+ * kept when there is no window and dropped when there is, because it cannot be
+ * shown to fall inside one.
+ */
+export function aggregate_mcp_lite(
+    log_path: string,
+    opts: { since?: number | null } = {},
+): McpLiteAggregate {
+    const since = opts.since ?? null;
+    const out = _empty(log_path);
+    let text: string;
+    try {
+        text = fs.readFileSync(log_path, 'utf-8');
+    } catch {
+        return out;
+    }
+    for (const raw of text.split(/\r\n|\r|\n/)) {
+        if (raw.trim() === '') continue;
+        let rec: Record<string, unknown>;
+        try {
+            const parsed: unknown = JSON.parse(raw);
+            if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+                out.skipped_lines += 1;
+                continue;
+            }
+            rec = parsed as Record<string, unknown>;
+        } catch {
+            out.skipped_lines += 1;
+            continue;
+        }
+        if (rec.transport !== MCP_LITE_TRANSPORT) {
+            out.other_transport += 1;
+            continue;
+        }
+        const tool = typeof rec.tool_name === 'string' ? rec.tool_name : '';
+        if (tool === '') {
+            out.skipped_lines += 1;
+            continue;
+        }
+        const ms = _ms(rec.ts);
+        if (since !== null && (ms === null || ms < since)) continue;
+
+        out.calls += 1;
+        _bump(out.by_tool, tool);
+        _bump(out.by_host, typeof rec.host === 'string' && rec.host !== '' ? rec.host : 'unknown');
+        _bump(out.by_outcome, typeof rec.outcome === 'string' ? rec.outcome : 'unknown');
+        const ts = typeof rec.ts === 'string' ? rec.ts : null;
+        if (ts !== null) {
+            if (out.earliest_ts === null || ts < out.earliest_ts) out.earliest_ts = ts;
+            if (out.latest_ts === null || ts > out.latest_ts) out.latest_ts = ts;
+        }
+    }
+    return out;
+}
+
+/** Descending by count, then by name, so the rendering is deterministic. */
+function _sorted(m: Map<string, number>): [string, number][] {
+    return [...m.entries()].sort((a, b) => (b[1] - a[1]) || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+}
+
+const ZERO_NOTE =
+    '_No calls recorded. The lite-surface emitter is default-off '
+    + '(`telemetry.artifact_engagement.enabled`), so a zero here says the '
+    + 'instrument was off or unused on this machine — it is not a measurement '
+    + 'of what consumers do._';
+
+/**
+ * The markdown section. Always renders, zero included.
+ *
+ * Ids are re-validated through the engagement redaction floor even though the
+ * emitter already clamps them: this renderer prints whatever is in the file,
+ * and a file is not a boundary the emitter controls.
+ */
+export function render_mcp_lite_markdown(agg: McpLiteAggregate): string {
+    const lines: string[] = [];
+    lines.push('## MCP lite surface');
+    lines.push('');
+    lines.push(`- calls recorded: **${agg.calls}**`);
+    if (agg.earliest_ts && agg.latest_ts) {
+        lines.push(`- ts range: \`${agg.earliest_ts}\` → \`${agg.latest_ts}\``);
+    }
+    lines.push('');
+    if (agg.calls === 0) {
+        lines.push(ZERO_NOTE);
+        lines.push('');
+        return `${lines.join('\n')}`;
+    }
+    lines.push('| tool | calls |');
+    lines.push('|---|---:|');
+    for (const [tool, n] of _sorted(agg.by_tool)) {
+        check_id_redaction('mcp_lite.by_tool.id', tool);
+        lines.push(`| ${tool} | ${n} |`);
+    }
+    lines.push('');
+    lines.push('| host | calls |');
+    lines.push('|---|---:|');
+    for (const [host, n] of _sorted(agg.by_host)) {
+        check_id_redaction('mcp_lite.by_host.id', host);
+        lines.push(`| ${host} | ${n} |`);
+    }
+    lines.push('');
+    return `${lines.join('\n')}`;
+}
+
+/** Plain object for the JSON format. Same validation as the markdown path. */
+export function mcp_lite_json(agg: McpLiteAggregate): Record<string, unknown> {
+    const by_tool: Record<string, number> = {};
+    for (const [tool, n] of _sorted(agg.by_tool)) {
+        check_id_redaction('mcp_lite.by_tool.id', tool);
+        by_tool[tool] = n;
+    }
+    const by_host: Record<string, number> = {};
+    for (const [host, n] of _sorted(agg.by_host)) {
+        check_id_redaction('mcp_lite.by_host.id', host);
+        by_host[host] = n;
+    }
+    const by_outcome: Record<string, number> = {};
+    for (const [outcome, n] of _sorted(agg.by_outcome)) {
+        by_outcome[outcome] = n;
+    }
+    return {
+        log_path: agg.log_path,
+        calls: agg.calls,
+        skipped_lines: agg.skipped_lines,
+        by_tool,
+        by_host,
+        by_outcome,
+        earliest_ts: agg.earliest_ts,
+        latest_ts: agg.latest_ts,
+    };
+}

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

@@ -12,6 +12,7 @@ import {
     rank_artefacts,
 } from './aggregator.js';
 import { ALLOWED_OUTCOMES, check_id_redaction } from './engagement.js';
+import { mcp_lite_json, render_mcp_lite_markdown, type McpLiteAggregate } from './mcp_lite.js';
 
 export const QUARTILE_TOP_RATIO = 0.20;
 export const QUARTILE_BOTTOM_RATIO = 0.20;
@@ -57,6 +58,17 @@ export function bucketise(stats: ArtefactStat[]): BucketedStat[] {
 export interface RenderOptions {
     top?: number | null;
     since_label?: string | null;
+    /**
+     * The MCP-lite reading, when the caller resolved one (step 4.2).
+     *
+     * Optional, and ABSENT is the default: a caller that does not supply it
+     * gets exactly the report this renderer produced before, byte for byte.
+     * That matters concretely — the Python→TS parity goldens for this script
+     * are frozen snapshots of a `.py` that no longer exists and can never be
+     * re-captured, so a section that rendered unconditionally would break a
+     * pin that cannot be repaired.
+     */
+    mcp_lite?: McpLiteAggregate | null;
 }
 
 /** Render a markdown report. `top` truncates each bucket; null keeps all. */
@@ -137,6 +149,9 @@ export function render_markdown(aggregate: AggregateResult, opts: RenderOptions
         }
         lines.push('');
     }
+    if (opts.mcp_lite) {
+        lines.push(render_mcp_lite_markdown(opts.mcp_lite));
+    }
     return `${_pyRStrip(lines.join('\n'))}\n`;
 }
 
@@ -181,6 +196,7 @@ export function render_json(aggregate: AggregateResult, opts: RenderOptions = {}
         },
         outcomes: outcomes_payload,
         buckets: grouped,
+        ...(opts.mcp_lite ? { mcp_lite: mcp_lite_json(opts.mcp_lite) } : {}),
     };
     return `${_py_json_dumps_indent2_sorted(payload)}\n`;
 }

package/src/agent-src/templates/scripts/telemetry_report.ts

@@ -19,6 +19,7 @@ import { aggregate } from './telemetry/aggregator.js';
 import { EngagementSchemaError } from './telemetry/engagement.js';
 import { render_json, render_markdown } from './telemetry/report_renderer.js';
 import { read_settings } from './telemetry/settings.js';
+import { MCP_LITE_LOG_REL, aggregate_mcp_lite } from './telemetry/mcp_lite.js';
 
 const _DURATION_RE = /^\s*(\d+)\s*([dhm])\s*$/u;
 
@@ -59,6 +60,7 @@ interface ReportArgs {
     format: string;
     log_path: string | null;
     settings: string;
+    mcp_log_path: string | null;
 }
 
 class ArgError extends Error {}
@@ -70,6 +72,7 @@ function _parseArgs(argv: string[]): ReportArgs {
         format: 'markdown',
         log_path: null,
         settings: '.agent-settings.yml',
+        mcp_log_path: null,
     };
     const formatChoices = ['markdown', 'json'];
     for (let i = 0; i < argv.length; i += 1) {
@@ -104,6 +107,7 @@ function _parseArgs(argv: string[]): ReportArgs {
             }
             a.format = v;
         } else if (tok === '--log-path') a.log_path = next();
+        else if (tok === '--mcp-log-path') a.mcp_log_path = next();
         else if (tok === '--settings') a.settings = next();
         else throw new ArgError(`unrecognized arguments: ${argv[i]}`);
     }
@@ -155,13 +159,29 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         return 2;
     }
 
+    // The MCP-lite section (step 4.2) renders in the DEFAULT, settings-driven
+    // invocation — which is what `agent-config telemetry:report` is — and when
+    // a caller names the sink explicitly. It does NOT render when the caller
+    // pointed `--log-path` at one specific engagement log and named no MCP
+    // sink: in that mode the report is scoped to the file it was handed and
+    // does not go looking for other stores on the machine. That rule also keeps
+    // the frozen Python-parity goldens intact, since every pinned invocation
+    // passes `--log-path`; the goldens cannot be re-captured, the `.py` having
+    // been retired, so an unconditional section would break a pin permanently.
+    const want_mcp = args.mcp_log_path !== null || args.log_path === null;
+    const mcp_lite = want_mcp
+        ? aggregate_mcp_lite(args.mcp_log_path ?? path.join(process.cwd(), MCP_LITE_LOG_REL), {
+              since: cutoff,
+          })
+        : null;
+
     const top = args.top <= 0 ? null : args.top;
     let rendered: string;
     try {
         if (args.format === 'json') {
-            rendered = render_json(result, { top, since_label });
+            rendered = render_json(result, { top, since_label, mcp_lite });
         } else {
-            rendered = render_markdown(result, { top, since_label });
+            rendered = render_markdown(result, { top, since_label, mcp_lite });
         }
     } catch (exc) {
         if (exc instanceof EngagementSchemaError) {

package/src/config/assurance-capability-registry.json

@@ -154,6 +154,15 @@
       "evidence": "src/scripts/grade_target_readiness.ts — 'semgrep' and 'bandit' tokens; the python fixture reports 'no SAST config'",
       "revisit_if": "the SAST probe stops distinguishing presence from absence on the fixtures"
     },
+    "self-security-scan": {
+      "axis": "self",
+      "owner_surface": "src/scripts/lint_agent_security.ts",
+      "projection": null,
+      "state": "available",
+      "rationale": "This package's own artifact tree is scanned for hidden-instruction payloads by an umbrella that spawns five child linters. Each child now has a closed terminal outcome — completed, failed or skipped(reason) — and a child that did not answer makes the aggregate name it and exit 1, so the umbrella's exit code establishes that all five ran rather than only that none of them spoke. Distinct from the target-axis security-scan entry: that one grades a consumer repository, this one grades this repository's scan of itself. Registered `degraded` on 2026-09-07 and moved here in the same change that repaired the defect; the degraded state is in this file's history rather than erased from it.",
+      "evidence": "tests/scripts/lint_agent_security_fail_closed.test.ts — five child-failure classes (non-zero with empty stdout, exit 0 with unparsable stdout, never spawned, a non-array payload, and the negative control of a non-zero exit WITH valid findings). The first four were written green against the pre-repair aggregation and flipped red-then-named by the repair; the negative control did not move in either direction. Sabotage probe on the real production path, 2026-09-07: a module-level throw in lint_confusables.ts made the umbrella print `mixed-script-confusable: did not complete` and exit 1, where the same sabotage previously printed the clean line and exited 0.",
+      "revisit_if": "a sixth child linter is added to the LINTERS watch list without a terminal outcome, or the aggregate stops failing on a non-completing child — either of which is caught by the failure corpus, so a revisit means that corpus was weakened first."
+    },
     "runtime-probe": {
       "axis": "target",
       "owner_surface": "agents/roadmaps/stubs/road-to-target-project-bootstrap-enforce.md",