@event4u/agent-config 16.1.0 → 16.2.0

package/src/config/hook-token-budget.json

@@ -108,8 +108,8 @@
   },
   "tool_result_bytes": {
    "definition": "road-to-inbox-harvest-2026-08-d-context-ledger 1.1: UTF-8 bytes of every tool RESULT entering context, per call, keyed by tool name. Closes the gap `unbounded_output_advisory_rate` registered above - the injection census measures what this suite puts into context, this measures what the host's tools do, and the second is the larger term. CAPTURE ONLY: the concern emits zero bytes to the model, so it carries no per-concern injection cap; it is registered here because this file already owns the owner/review discipline for context-cost instruments.",
-   "instrument": "the `tool-result-bytes` concern (src/scripts/hooks/tool_result_bytes_hook.ts) on post_tool_use, appending {ts, tool, bytes, measurable} to agents/runtime/state/tool-result-census.jsonl",
-   "privacy": "census lines carry a tool NAME, a byte COUNT and a timestamp - the record type has no field able to hold file contents, command output or any free text, so there is no scrubber that can fail",
+   "instrument": "the `tool-result-bytes` concern (src/scripts/hooks/tool_result_bytes_hook.ts) on post_tool_use, appending {ts, tool, raw_bytes, delivered_bytes, measurable} to agents/runtime/state/tool-result-census.jsonl, and ONLY where the maintainer workspace resolves (or AGENT_CONFIG_TOOL_BYTE_CENSUS=1) - a per-call write in every consumer install would be a second unread instrument",
+   "privacy": "census lines carry a tool NAME, two byte COUNTS and a timestamp - the record type has no field able to hold file contents, command output or any free text, so there is no scrubber that can fail",
    "threshold": "none committed before data - baseline first, threshold at review date. A `measurable: false` line means the host's payload carried no readable result; that absence is itself a coverage finding and is never counted as zero bytes"
   },
   "turns_per_task": {

package/src/config/metric-registry.yml

@@ -26,6 +26,26 @@
 # that is a review judgement — so the honest claim is that the lint makes the
 # OMISSION impossible, not that it makes the answer true. Stated here rather
 # than discovered by someone who trusted it further than it goes.
+#
+# ## `unit` and `basis` — how the number was obtained, beside the number
+#
+# An entry MAY carry `unit:` and MUST carry `basis:` when its unit is `bytes`.
+# `basis` is one of:
+#
+#   measured     — something counted it. A length, a sum, a row count.
+#   derived      — arithmetic over a measured quantity. Never a count.
+#   proxy        — a different quantity standing in for the one named.
+#   unavailable  — not observable from this package. No figure is produced.
+#
+# The field exists because a derived byte figure and a counted one look
+# identical in a cell, and this tree has already been burned by a number quoted
+# onward without the conditions that produced it. `git count-objects -v` is the
+# standing example of the confusion: it measures a LOCAL object store and is
+# never a transfer figure, whatever the unit says.
+#
+# An `unavailable` entry declares a term that is out of reach, so that a total
+# built without it is visibly incomplete rather than quietly wrong. It produces
+# no value and must never be estimated into a sum.
 
 metrics:
   - id: attribution-shape-block-count
@@ -122,3 +142,97 @@ metrics:
       assumption that widening helped -- which is the assumption the whole
       roadmap exists to test rather than to make. Without it the estate grows
       and nothing can say whether it should have.
+
+  # ── Bytes ───────────────────────────────────────────────────────────────
+  #
+  # `road-to-a-bytes-row-that-exists`. Before these, a statement of the form
+  # "this change moved N bytes" could not be made at all: the tree measured
+  # tokens well and bytes not at all, and no row here could have held one.
+
+  - id: tool-raw-bytes
+    unit: bytes
+    basis: measured
+    producer: src/scripts/hooks/tool_result_bytes_hook.ts (`raw_bytes`, per post_tool_use dispatch)
+    consumer: >-
+      the `tool_result_bytes` stream registered in `src/config/hook-token-budget.json`,
+      and the maintainer reading `agents/runtime/state/tool-result-census.jsonl`
+      before a tool-result distribution is published.
+    decision: >-
+      whether a cap on tool-result size is worth introducing, and at what
+      value. The distribution has never been observed, so the threshold stays
+      uncommitted until this counter has written one.
+    absent: >-
+      every context-cost claim this package makes is computed against a
+      denominator that excludes its own dominant term — the hook-injection
+      census measures what this suite puts into context and nothing measures
+      what the host's tools do.
+
+  - id: tool-delivered-bytes
+    unit: bytes
+    basis: measured
+    producer: src/scripts/hooks/tool_result_bytes_hook.ts (`delivered_bytes`, same record)
+    consumer: >-
+      the same census reader, comparing it against `tool-raw-bytes` on the same
+      line. Equal by construction today, because nothing in this tree rewrites
+      a tool result on its way to the model.
+    decision: >-
+      whether a result-rewriting mechanism, if one ever lands, reduced anything.
+      A non-zero gap between the two columns is the reduction; no gap is no
+      reduction.
+    absent: >-
+      a later release that starts trimming tool results has no before-figure
+      and can only assert an improvement. The two columns exist now precisely
+      so that claim is a measured delta later rather than a story.
+
+  - id: transcript-bytes-per-token
+    unit: bytes_per_token
+    basis: measured
+    producer: src/scripts/_lib/cc_transcript.ts (`measureBytesPerToken`)
+    consumer: >-
+      `cache_realization_report` and `session_eol_report`, which multiply a
+      token column by it, and any reader checking that division — the two sums
+      it was divided from travel with it on every emitted value.
+    decision: >-
+      whether a byte figure may be derived from this corpus at all. A corpus
+      that supplies no ratio produces no byte figure, rather than borrowing one
+      measured somewhere else.
+    absent: >-
+      the only remaining way to turn a token count into bytes is a constant in
+      a script, which is correct for the content that produced it and silently
+      wrong for everything else — the third conflicting figure this tree has
+      already paid to learn about twice.
+
+  - id: provider-bytes-per-call
+    unit: bytes
+    basis: derived
+    producer: >-
+      src/scripts/_lib/cc_transcript.ts (`derivedBytes`), surfaced as
+      `provider_bytes` by `cache_realization_report` and `session_eol_report`.
+    consumer: >-
+      the maintainer sizing what a round re-sends, and `check_claims`, which
+      refuses a public byte figure whose metric marker resolves to no entry here.
+    decision: >-
+      whether the volume a stateless chat round re-sends is large enough to act
+      on. Every existing reading of that cost is a token count; this is the
+      first one in the unit a network is billed in.
+    absent: >-
+      the re-send cost has no byte figure at all, so any statement about it is
+      either a token count wearing the wrong unit or an estimate with nothing
+      behind it. That is the state this metric was added to end.
+
+  - id: host-fetch-and-transport-bytes
+    unit: bytes
+    basis: unavailable
+    producer: >-
+      none — the host's own fetch tool and the model transport are not
+      observable from inside this package, and no producer is planned.
+    consumer: >-
+      any reader of a byte total, who needs to see which terms the total does
+      NOT contain. The entry is the disclosure; there is no value to read.
+    decision: >-
+      whether a byte total may be published as complete. It may not: these
+      terms are out of reach, so every total is a partial one and says so.
+    absent: >-
+      the two unreachable terms get estimated into a sum to make it look whole,
+      and the estimate becomes the figure everybody quotes. Declaring them
+      unavailable is what stops a guess from entering a total.

package/src/config/placeholder-drift-budget.json

@@ -0,0 +1,10 @@
+{
+  "owner": "maintainer",
+  "review_by": "2027-09-29",
+  "seeded_at": "2026-09-29",
+  "note": "Shrink-only ceilings on FOREIGN placeholder syntaxes in prose, per road-to-an-invocation-contract-that-reaches-the-wire 1.2. The unit is a token outside fenced blocks, indented blocks and inline code spans — defined and argued in src/scripts/report_invocation_surface.ts's module header, with the per-file breakdown in agents/evidence/analysis/invocation-surface-census.md. Seeded at what this tree measures, not at the roadmap's figures: those counted tokens inside demonstrated code (JS template literals, HCL, a table-cell marker the prose talks about) and do not reproduce. The plurality form is deliberately ungated. Raising a ceiling is a reviewable diff, and the reason belongs in it.",
+  "ceilings": {
+    "angle-upper": 3,
+    "double-brace": 0
+  }
+}

package/src/config/routing-coverage-seed.json

@@ -10,12 +10,12 @@
     },
     "seed": {
         "rules": 0.9623,
-        "skills": 0.3378
+        "skills": 0.3445
     },
     "seed_provenance": {
         "rules": "102 covered of 106 routed rules on 2026-09-13; was 101 of 105 on 2026-09-08 and 94 of 105 (tier-1 21/24, tier-2 73/81) on 2026-08-25.",
-        "skills": "101 of 299 skills carry evals/triggers.json on 2026-09-19; was 100 on 2026-08-30.",
-        "finding": "The gap between the two seeds IS the roadmap defect D1, quantified. The rules surface is ~90% covered by a deterministic corpus that can fail a PR; the skills surface -- the one production routes on -- is 25%, covered only by a harness that is advisory only, never gating (rule_trigger_eval.ts:4)."
+        "skills": "103 of 299 skills carry evals/triggers.json on 2026-10-01; was 102 on 2026-09-30, 101 on 2026-09-19 and 100 on 2026-08-30.",
+        "finding": "The gap between the two seeds IS the roadmap defect D1, quantified. The rules surface is ~90% covered by a deterministic corpus that can fail a PR; the skills surface -- the one production routes on -- is far lower and is covered only by a harness that is advisory only, never gating (rule_trigger_eval.ts:4). The figure is deliberately not restated here (corrected 2026-10-01): it read `25%` against a seed that had since moved to 0.3445, which is the same count-drift this file's own history entries keep repairing one field away. The live value is `seed.skills`, two keys above."
     },
     "history": [
         {
@@ -51,7 +51,7 @@
             "scope": "rules",
             "from": 0.9619,
             "to": 0.9623,
-            "reason": "road-to-adversarial-verification-and-long-runs Phase 1.1 added `test-first` as a routed rule, which moved the DENOMINATOR from 105 to 106 -- the ratio-falls-two-ways case this file's own _comment names, and the one that is a defect to record rather than repair. The repair is the corpus file, not the seed: `tests/eval/routing-matrix/test-first.yaml` landed in the same change (101 -> 102 of 106), so the ratio ROSE across a denominator increase rather than merely holding. The rule is trigger-less by design, so its positives describe the situations it governs rather than strings that summon it, and its near-misses are its own \u00a7 Does NOT fire set. The seed follows the gain because this file's test asserts seed == live measurement in both directions; it may never be LOWERED."
+            "reason": "road-to-adversarial-verification-and-long-runs Phase 1.1 added `test-first` as a routed rule, which moved the DENOMINATOR from 105 to 106 -- the ratio-falls-two-ways case this file's own _comment names, and the one that is a defect to record rather than repair. The repair is the corpus file, not the seed: `tests/eval/routing-matrix/test-first.yaml` landed in the same change (101 -> 102 of 106), so the ratio ROSE across a denominator increase rather than merely holding. The rule is trigger-less by design, so its positives describe the situations it governs rather than strings that summon it, and its near-misses are its own § Does NOT fire set. The seed follows the gain because this file's test asserts seed == live measurement in both directions; it may never be LOWERED."
         },
         {
             "date": "2026-09-19",
@@ -59,6 +59,20 @@
             "from": 0.3344,
             "to": 0.3378,
             "reason": "road-to-release-holds-that-refuse step 1.4 authored one corpus file for `roadmap-writing` (100 -> 101 of 299) and removed its now-false entry from trigger_eval_grandfather.json. ONE file rather than a wave: the step asked for a single positive case whose expected output is a re-sequenced phase rather than a hold, and the eval set is where that expectation is pinned. The seed rises so the gain cannot be given back silently; it may never be LOWERED. Two published measurements moved with it and were re-taken in the same change -- routing-body-signal-verdict.json and the measure_delivery_sets record -- because the trigger corpus is their input, so any skill gaining an eval set re-takes both."
+        },
+        {
+            "date": "2026-09-30",
+            "scope": "skills",
+            "from": 0.3378,
+            "to": 0.3411,
+            "reason": "road-to-a-component-taxonomy-we-follow-but-never-force authored one corpus file for `ui-component-architect` (101 -> 102 of 299). Not a sought gain: the branch edits that skill's placement section, and check_routing_coverage requires a corpus for every skill a diff touches, so the file is the gate's own remedy rather than a coverage push. Five should-trigger cases, one per shape the skill decides, and five near misses whose vocabulary overlaps hardest -- styling an existing component, inventorying what the project owns (existing-ui-audit, which runs first and feeds this one), a backend composition question, a prop rename, and general React knowledge with no component to shape. The seed rises so the gain cannot be given back silently; it may never be LOWERED. The two published measurements the 2026-09-19 entry names -- routing-body-signal-verdict.json and the measure_delivery_sets record -- are re-taken in the same change, for the reason that entry gives: the trigger corpus is their input."
+        },
+        {
+            "date": "2026-10-01",
+            "scope": "skills",
+            "from": 0.3411,
+            "to": 0.3445,
+            "reason": "road-to-corpus-refresh-cadence-shape step 1.2a authored one corpus file for `accessibility-auditor` (102 -> 103 of 299). Same shape as the 2026-09-30 entry and for the same reason: that step re-checked the skill's grounding corpus against WCAG 2.2 and the APG, which edited src/skills/accessibility-auditor/data/, and check_routing_coverage requires a corpus for every skill a diff touches. Ten cases -- five exemplars including the German phrasing the skill's own description names, three near-misses -- tailwind-engineer for token-level contrast and ui-component-architect for landmarks and heading order, both named in that skill's SKILL.md, plus existing-ui-audit for component inventory, which it does not name and which is included because it runs first over the same surface -- and two counterexamples, one guarding the 'accessible' homonym. The seed rises so the gain cannot be given back silently; it may never be LOWERED. The trigger-corpus holdout pin is re-taken in the same change -- and this growth moves it for the first time on the HOLDOUT side (18 -> 19), because sha256('accessibility-auditor')[0:2] is 0x2f = 47, below the ceiling of 51. That is recorded in the holdout artefact with its ordering claim explicitly scoped to the 18 originally sealed rows. The two published measurements the 2026-09-19 and 2026-09-30 entries name -- routing-body-signal-verdict.json and the measure_delivery_sets record -- are deliberately NOT re-taken here, and the departure from those two entries is stated rather than left to be noticed. The reason is the partition, not the date: this growth is HOLDOUT-side, so the train input both measurements read is byte-identical to what it was before this change -- all 84 train rows reproduce -- and re-taking them would publish the same measurement under a newer date, which is a freshness claim nothing earned. The two artefacts are NOT in the same state, and conflating them would repeat the error this sentence replaces: routing-body-signal-verdict.json carries `corpus.partition: train` and `train_corpora: 84` and is current for the train partition; delivery-set-result-2026-08-31.md still reads `82 train corpora, 764 distinct prompts` and carries no re-take section for either the 2026-09-19 or the 2026-09-30 growth, so it is two corpora stale and those two entries' claim that it `is re-taken in the same change` is not backed by the tree. Repairing it is a train-side measurement re-run, out of scope for a holdout-side growth, and is named here so the gap is attributed rather than inherited silently. A FUTURE train-side growth owes both re-takes. Separately, TWO entries were removed from trigger_eval_grandfather.json, and the two reds are of different kinds. `ui-component-architect` was red ON MAIN: it gained a corpus on 2026-09-30 and its now-false allowlist entry was not removed then, which is the convention the 2026-09-19 entry sets and the 2026-09-30 entry omitted. `accessibility-auditor` was NOT red on main -- on main it ships no corpus at all, and check_trigger_eval_presence fires only on an allowlist entry whose skill HAS one, so its entry went stale the moment this change added the corpus. That red is created here and removed here, in the same change. Stated separately because a reader auditing why two entries were dropped would otherwise be told one pre-existing condition explains both."
         }
     ]
 }

package/src/scripts/_cli/cmd_doctor.ts

@@ -114,7 +114,8 @@ import {
     resolve_project_root,
     type TraceRecord,
 } from '../_lib/agent_settings.js';
-import { executionJson, forgeProtectionJson, UNREAD_FORGE } from './doctor_execution.js';
+import { executionJson, forgeProtectionJsonFor } from './doctor_execution.js';
+import { checkOfflineReadiness, trafficEnvironmentJson } from './doctor_network_posture.js';
 import * as ai_council_clients from '../ai_council/clients.js';
 import * as ai_council_config from '../ai_council/config.js';
 import {
@@ -1450,23 +1451,7 @@ function _check_mcp_mode(project_root: string): Dict {
     };
 }
 
-function _check_offline_readiness(): Dict {
-    const script = path.join(_package_root(), 'src', 'scripts', 'hermetic-install.sh');
-    if (!pathExists(script)) {
-        return {
-            id: 'offline-readiness',
-            status: 'warn',
-            message: 'src/scripts/hermetic-install.sh not found in package',
-            remedy: 'reinstall @event4u/agent-config or pull missing files',
-        };
-    }
-    return {
-        id: 'offline-readiness',
-        status: 'ok',
-        message: 'verified-offline install entrypoint present',
-        remedy: '',
-    };
-}
+const _check_offline_readiness = (): Dict => checkOfflineReadiness(_package_root());
 
 function _check_stale_orphans(): Dict {
     const gdi = global_deploy_inventory;
@@ -3077,7 +3062,8 @@ function _emit_json(
     };
     if (origin !== null) payload['project_root_origin'] = origin;
     payload['execution'] = executionJson(() => iter_setting_overrides({ cwd: project_root }));
-    payload['forge_protection'] = forgeProtectionJson(UNREAD_FORGE); // 3.2
+    payload['forge_protection'] = forgeProtectionJsonFor(String(project_root)); // 3.2 · AC-5
+    payload['traffic_environment'] = trafficEnvironmentJson(process.env);
     if (checks !== null) {
         payload['checks'] = checks;
         const drift = missing.length + modified.length + foreign.length + tag_drift.length;

package/src/scripts/_cli/doctor_execution.ts

@@ -23,6 +23,15 @@ import {
     protectionActions,
     type ForgeReading,
 } from '../_lib/forge_protection.js';
+import {
+    FORGE_TOTAL_BUDGET_MS,
+    budgetOf,
+    forgeReadingFor,
+    liveForgeApi,
+    originUrl,
+    resolveForgeRepo,
+    type Runner,
+} from '../_lib/forge_reader.js';
 
 type Dict = Record<string, unknown>;
 
@@ -52,12 +61,17 @@ export function executionJson(overrides: () => OverrideStream): Dict {
 /**
  * The `forge_protection` block of `doctor --json` — Phase 3.2.
  *
- * **`doctor` does NOT reach the network on its own.** A diagnostic that makes a
- * `gh` call on every invocation is one nobody runs offline, and the sibling
- * anchor gate already declined that cost for the same reason. So the reading is
- * INJECTED: a caller that has queried the forge passes it, and a caller that has
- * not passes the all-null reading, which produces five `unread` rows that still
- * name the call each value would come from.
+ * **THIS function does not reach the network; `doctor` now does.** The mapper
+ * stays pure and takes an INJECTED reading — a caller that queried the forge
+ * passes it, one that did not passes the all-null reading, which produces five
+ * `unread` rows that still name the call each value would come from. What
+ * changed is the caller: `forgeProtectionJsonFor` below acquires that reading,
+ * so `doctor --json` does make `gh` calls. Phase 3.2's "`doctor` does not reach
+ * the network" is SUPERSEDED, and this header said otherwise for three review
+ * rounds while the function forty lines down called it a reversal — the third
+ * copy of a refuted argument in this diff, each found by a different round.
+ * Corrected here for the reason the others were: a header is where a dead
+ * argument gets reused.
  *
  * That is the honest shape for *read, never guessed*: the block is always
  * present, a value appears only when a named call produced it, and `unread` is a
@@ -67,24 +81,93 @@ export function executionJson(overrides: () => OverrideStream): Dict {
  * `actions` carries the human ACTION lines — the step's own words are that a
  * missing row is a blocker entry and NOT a halt, so this reports and returns.
  */
-export function forgeProtectionJson(reading: ForgeReading): Dict {
+export function forgeProtectionJson(reading: ForgeReading, repo: string | null = null): Dict {
     const rows = forgeProtectionRows(reading);
+    const readFromForge = rows.some((r) => r.state !== 'unread');
+    // **The slug is reported only when something was actually read, and that
+    // invariant is structural rather than a caller's promise.** The first
+    // version reported whatever the git remote resolved to, which is a LOCAL
+    // read that succeeds with no network — so an ordinary offline run (GitHub
+    // remote present, no connectivity, no opt-out) emitted a named repository
+    // and substituted sources while every row was `unread`. That made the
+    // claim this change rests on — offline output is what Phase 3.2 shipped —
+    // false on exactly the failed-live path the council condition names. The
+    // earlier verification only ever exercised the opt-out switch and read it
+    // as offline; the two are not the same path.
+    const anonymous = repo === null || !readFromForge;
+    const name = (s: string): string =>
+        anonymous ? s : s.replace(/\{owner\}\/\{repo\}/g, () => repo);
     return {
+        repository: readFromForge ? repo : null,
         rows: rows.map((r) => ({
             id: r.id,
             state: r.state,
-            source: r.source,
+            source: name(r.source),
             detail: r.detail,
         })),
-        actions: protectionActions(rows),
-        read_from_forge: rows.some((r) => r.state !== 'unread'),
+        actions: protectionActions(rows).map(name),
+        read_from_forge: readFromForge,
     };
 }
 
-/** The all-null reading: nothing was queried. */
-export const UNREAD_FORGE: ForgeReading = {
-    rulesets: null,
-    defaultBranch: null,
-    allowAutoMerge: null,
-    deployRestricted: null,
-};
+/**
+ * The block as `doctor` itself builds it — AC-5.
+ *
+ * Phase 3.2 left `forgeProtectionJson` with no production caller, so the
+ * command the criterion names reported five `unread` rows while the forge
+ * satisfied all five, and the rows were only ever established by a human
+ * running `gh api` and reading the mapper in a test. This is the wiring that
+ * makes the named command answer for itself.
+ *
+ * **This IS a reversal of Phase 3.2's module boundary, and the roadmap records
+ * the supersession.** An earlier draft of this comment argued the opposite —
+ * "an addition rather than a reversal" — which a 2/2 convergent council pass
+ * refuted: that note recorded two boundaries, `doctor` does not reach the
+ * network AND the reading is injected, and this reverses both. The refuted
+ * argument is corrected here rather than left standing, because a comment is
+ * what the next reader of this module finds first and is where a refuted
+ * reasoning would get reused.
+ *
+ * What survives is the AVAILABILITY property, which is narrower than the
+ * earlier claim and is the one the supersession rests on: every failure path in
+ * `forgeReadingFor` — opt-out switch, no GitHub remote, no `gh`, no
+ * credentials, timeout, unparseable payload, a throw — returns the same
+ * `UNREAD_FORGE` reading, so offline the ROWS, their `source` templates and the
+ * action lines are what Phase 3.2 printed. Not the whole document: the block
+ * gained a top-level `repository` key, which is `null` on every such path. A
+ * consumer validating `forge_protection` against a closed schema sees that one
+ * added key; "prints exactly what it printed before" was too strong and is not
+ * claimed.
+ *
+ * `process.env` and the git remote are read HERE rather than inside the reader,
+ * so the reader stays injectable and every branch above is reachable from a
+ * test without spawning anything.
+ */
+export interface ForgeDeps {
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    /** The subprocess runner for both `git` and `gh`. */
+    readonly run?: Runner;
+}
+
+export function forgeProtectionJsonFor(root: string, deps: ForgeDeps = {}): Dict {
+    // The composition root — budget, thunk, host and cwd wired together — had
+    // no seam and therefore no test, so the opt-out-before-spawn and host
+    // binding were asserted one layer down against fakes while a regression in
+    // the real wiring stayed invisible. `deps` is that seam; production passes
+    // nothing and gets `process.env` plus the real spawn.
+    const env = deps.env ?? process.env;
+    const run = deps.run;
+    const remaining = budgetOf(FORGE_TOTAL_BUDGET_MS);
+    const read = forgeReadingFor({
+        env,
+        // A thunk, so the opt-out short-circuits before `git` spawns.
+        resolveRepo: () => resolveForgeRepo(originUrl(root, run)),
+        // Built from the RESOLVED target, so `gh` is addressed at the host and
+        // directory the slug came from. The per-call ceiling is whatever is
+        // left of the whole-read budget, so a call admitted near the deadline
+        // cannot run past it.
+        apiFor: (t) => liveForgeApi(remaining, run, { host: t.host, cwd: root }),
+        remaining,
+    });
+    return forgeProtectionJson(read.reading, read.repo);
+}

package/src/scripts/_cli/doctor_network_posture.ts

@@ -0,0 +1,226 @@
+/**
+ * What this install does on the network — the two `doctor` surfaces that
+ * answer that question, in one module under the source-size cap.
+ *
+ * `road-to-host-traffic-knobs-that-ship` Phases 2.1 and 2.2. Its own module
+ * rather than a function inside `cmd_doctor.ts` for the reason
+ * `_lib/doctor_runtime_checks.ts` states for itself: that file is ~3,600 lines
+ * and `check_source_size_budget` counts every line above 1,500, so a change
+ * that adds lines there pays for them by taking lines away. Wiring the traffic
+ * section in costs two lines; `checkOfflineReadiness` moving here returns more
+ * than that, and lands beside a cohesive sibling rather than in an arbitrary
+ * bin — "can this install work with no registry" and "which host traffic is
+ * switched off" are the same question asked from two ends.
+ *
+ * `checkOfflineReadiness` is a PURE MOVE: same id, same statuses, same message
+ * and remedy strings. Its `pathExists` is `fs.statSync` in a try, matching the
+ * helper it used in `cmd_doctor.ts` — `existsSync` would differ on a path whose
+ * parent denies traversal, and this is a move, not a repair.
+ *
+ * Why the traffic section reports rather than decides: the variables below belong to the HOST, not to this package. Writing one into
+ * a consumer environment changes behaviour the consumer never asked to change,
+ * and — per the mapping measured in `docs/setup/host-traffic-environment.md` —
+ * could stop their background security updates as a side effect of a telemetry
+ * preference. So this module reads `env` and returns; it writes nothing, opens
+ * no socket, and touches no settings file. Two consecutive calls return equal
+ * payloads and leave the tree byte-identical.
+ *
+ * Why an inapplicable row is PRESENT and says so: the obvious implementation lists only the variables that resolve on the
+ * current host, which produces a short, clean section on a host that documents
+ * none of them. An operator reading that concludes their traffic is governed,
+ * when in fact the package simply had nothing to say. An omission that reads as
+ * a clean bill of health is the precise failure this surface exists to prevent,
+ * so a row that does not apply is emitted with the literal state
+ * {@link NOT_APPLICABLE} instead of being dropped.
+ *
+ * A variable that is SET on a host that does not document it still reports its
+ * value beside that state. The state says "this host is not known to read it";
+ * dropping the value as well would hide a fact the reader has.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** The doctor's structured check row. Mirrors `cmd_doctor`'s internal `Dict`. */
+export interface NetworkCheck {
+    id: string;
+    status: 'ok' | 'warn' | 'fail' | 'skipped';
+    message: string;
+    remedy: string;
+    /** Structural compatibility with `cmd_doctor`'s `Dict` row type. */
+    [k: string]: string;
+}
+
+/** The literal a row carries where the host has no documented meaning for it. */
+export const NOT_APPLICABLE = 'not applicable on this host';
+
+/** The documentation surface every row points at. One copy of the mapping. */
+export const TRAFFIC_DOC = 'docs/setup/host-traffic-environment.md';
+
+/** Host id used when nothing in the environment identifies the host. */
+export const UNKNOWN_HOST = 'unknown';
+
+/**
+ * One documented host traffic variable.
+ *
+ * `hosts` lists the host ids whose shipped build was actually READ for this
+ * variable — never a host somebody expects to behave the same way. A host
+ * absent from the list gets {@link NOT_APPLICABLE}, which is the honest answer
+ * and also the safe one.
+ */
+export interface TrafficVariable {
+    readonly variable: string;
+    readonly hosts: readonly string[];
+    /** Host build and date the row was read from, e.g. `claude-code 2.1.284 · 2026-09-29`. */
+    readonly checked_against: string;
+    /**
+     * May THIS PACKAGE write the variable into the host env block?
+     *
+     * `false` on both traffic variables and it is not a policy setting — it is a
+     * structural fact: `install.ts`'s `WRITABLE_HOST_ENV` is a two-row allow
+     * table and the settings schema admits only those two keys, so neither
+     * traffic variable is expressible anywhere in the write path. Reported
+     * because a consumer reading `set` on a row deserves to know whether this
+     * package could have been the one that set it.
+     */
+    readonly writable_by_this_package: boolean;
+}
+
+/** The host build every row below was read from. One place to bump on a re-check. */
+const CHECKED = 'claude-code 2.1.284 · 2026-09-29';
+
+/**
+ * The documented set, in the order `docs/setup/host-traffic-environment.md`
+ * lists it. What each one governs — and does not — lives in that page and is
+ * deliberately not duplicated here: a second copy is a second thing to keep
+ * true, and this one would be the copy nobody re-reads.
+ */
+export const TRAFFIC_VARIABLES: readonly TrafficVariable[] = [
+    // Both traffic variables reach the host's update-disabled resolver, the
+    // blanket one as its third rung, so neither is writable by this package —
+    // owner-decided 2026-09-30.
+    { variable: 'CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC', hosts: ['claude-code'], checked_against: CHECKED, writable_by_this_package: false },
+    { variable: 'DISABLE_AUTOUPDATER', hosts: ['claude-code'], checked_against: CHECKED, writable_by_this_package: false },
+    // Size caps. Neither reaches the updater resolver, and neither suppresses a
+    // call, an update check or a download.
+    { variable: 'BASH_MAX_OUTPUT_LENGTH', hosts: ['claude-code'], checked_against: CHECKED, writable_by_this_package: true },
+    { variable: 'MAX_MCP_OUTPUT_TOKENS', hosts: ['claude-code'], checked_against: CHECKED, writable_by_this_package: true },
+];
+
+/** An environment map, in the shape `process.env` has. */
+export type EnvMap = Readonly<Record<string, string | undefined>>;
+
+/** Which host this process is running under, and whether that was observed. */
+export interface TrafficHost {
+    host: string;
+    observed: boolean;
+}
+
+/**
+ * Resolve the host from the environment it exported.
+ *
+ * `observed` carries the same distinction `routing:doctor` draws for its own
+ * platform field: a host that identified itself is a fact, and the absence of
+ * any marker is NOT evidence of a different host — only evidence that nobody
+ * said. An unidentified host resolves to {@link UNKNOWN_HOST}, which documents
+ * no variable, so every row reads {@link NOT_APPLICABLE} rather than reporting
+ * against a host this code guessed at.
+ */
+export function resolveTrafficHost(env: EnvMap): TrafficHost {
+    const claude =
+        (env['CLAUDECODE'] ?? '').trim() !== '' || (env['CLAUDE_CODE_SESSION_ID'] ?? '').trim() !== '';
+    if (claude) return { host: 'claude-code', observed: true };
+    return { host: UNKNOWN_HOST, observed: false };
+}
+
+/** One emitted row: the variable, its state on this host, and its value if set. */
+export interface TrafficRow {
+    variable: string;
+    state: string;
+    value: string | null;
+    checked_against: string;
+    writable_by_this_package: boolean;
+}
+
+/**
+ * Build one row. A variable the host does not document reports
+ * {@link NOT_APPLICABLE} whether or not it happens to be exported.
+ */
+function trafficRow(spec: TrafficVariable, env: EnvMap, host: string): TrafficRow {
+    const raw = env[spec.variable];
+    const present = raw !== undefined && raw !== '';
+    const applicable = spec.hosts.includes(host);
+    return {
+        variable: spec.variable,
+        state: applicable ? (present ? 'set' : 'unset') : NOT_APPLICABLE,
+        value: present ? String(raw) : null,
+        checked_against: spec.checked_against,
+        writable_by_this_package: spec.writable_by_this_package,
+    };
+}
+
+/**
+ * The `traffic_environment` block of `agent-config doctor --json`.
+ *
+ * Read-only by construction: the only input is the injected `env` map, and the
+ * only output is a fresh object. `hostOverride` is the test seam Phase 2.2's
+ * non-Claude fixture needs, and is never passed by the production call site.
+ *
+ * `reporting_read_only` replaced a flat `read_only: true` on 2026-09-30, and the
+ * rename is the point rather than cosmetics: this REPORT is still read-only, but
+ * the PACKAGE is no longer, so the old key had become a true statement about the
+ * wrong subject. Two of the four rows are now writable by the installer when the
+ * consumer sets a cap, and `writable_by_this_package` says which — a consumer
+ * reading `set` deserves to know whether we could have been the one who set it.
+ */
+export function trafficEnvironmentJson(
+    env: EnvMap,
+    hostOverride?: TrafficHost,
+): Record<string, unknown> {
+    const resolved = hostOverride ?? resolveTrafficHost(env);
+    return {
+        host: resolved.host,
+        host_observed: resolved.observed,
+        doc: TRAFFIC_DOC,
+        reporting_read_only: true,
+        writable_by_this_package: TRAFFIC_VARIABLES.filter((v) => v.writable_by_this_package).map(
+            (v) => v.variable,
+        ),
+        rows: TRAFFIC_VARIABLES.map((spec) => trafficRow(spec, env, resolved.host)),
+    };
+}
+
+/** `fs.statSync` in a try — the `cmd_doctor.ts` helper this move preserves. */
+function pathExists(p: string): boolean {
+    try {
+        fs.statSync(p);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * The `offline-readiness` check — a pure move out of `cmd_doctor.ts`.
+ *
+ * `packageRoot` is passed IN rather than resolved here for the reason
+ * `doctor_runtime_checks.ts` gives for its `which` parameter: `_package_root`
+ * lives in `cmd_doctor.ts` and importing it back would make the two modules
+ * circular.
+ */
+export function checkOfflineReadiness(packageRoot: string): NetworkCheck {
+    const script = path.join(packageRoot, 'src', 'scripts', 'hermetic-install.sh');
+    if (!pathExists(script)) {
+        return {
+            id: 'offline-readiness',
+            status: 'warn',
+            message: 'src/scripts/hermetic-install.sh not found in package',
+            remedy: 'reinstall @event4u/agent-config or pull missing files',
+        };
+    }
+    return {
+        id: 'offline-readiness',
+        status: 'ok',
+        message: 'verified-offline install entrypoint present',
+        remedy: '',
+    };
+}