@event4u/agent-config 16.1.0 → 16.3.0

package/src/scripts/_cli/cmd_doctor_neighbours.ts

@@ -0,0 +1,293 @@
+/**
+ * `agent-config doctor neighbours` — render the neighbour census.
+ *
+ * A separate entry point rather than another branch inside `cmd_doctor.ts`,
+ * which sits 2,000 lines above the source-size ceiling: a verb this size does
+ * not belong in a file that already cannot grow. The census itself is
+ * `_lib/neighbour_census.ts`; everything here is presentation and the one
+ * summary line the full `doctor` run links to.
+ *
+ * Refuses nothing. No label here removes, blocks, or rewrites a neighbour's
+ * artifact — a label is a report, never a gate.
+ *
+ * It is no longer read-ONLY, and the two writes are named rather than implied.
+ * Both land under `agents/reports/` and both are caches of this run's own
+ * findings: `neighbour-scan.json`, the shape-scan verdicts the ranker reads on
+ * the hook path, and `neighbour-overlap.json`, the cross-root pairs keyed by the
+ * census digest. Nothing outside that directory is touched, and a failed write
+ * is not a failed census.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import * as YAML from 'yaml';
+
+import {
+    census,
+    fileDigest,
+    gatedEventsFrom,
+    scanCachePath,
+    type NeighbourCensus,
+} from '../_lib/neighbour_census.js';
+import { scanNeighbourBody, writeScanCache } from '../_lib/neighbour_scan.js';
+import { resolvePackageRoot } from '../_lib/package_root.js';
+import {
+    OVERLAP_THRESHOLD,
+    CROSS_CACHE_NAME,
+    cachedCrossRootPairs,
+    crossRootOverlapMap,
+} from '../audit_skill_overlap.js';
+
+interface ManifestShape {
+    concerns?: Record<string, { effect?: string }>;
+    platforms?: Record<string, Record<string, unknown>>;
+    native_event_aliases?: Record<string, Record<string, string>>;
+}
+
+/** Read the hook manifest for the events a `permission` concern of ours sits on. */
+function gatedEvents(packageRoot: string): Set<string> {
+    try {
+        // A missing or unreadable manifest yields an empty gate set, which
+        // downgrades `degraded` to `coordinated` rather than inventing a gate
+        // that is not there.
+        const file = path.join(packageRoot, 'src', 'scripts', 'hook_manifest.yaml');
+        const doc = YAML.parse(fs.readFileSync(file, 'utf-8')) as ManifestShape;
+        return gatedEventsFrom(doc, doc.native_event_aliases ?? {});
+    } catch {
+        return new Set<string>();
+    }
+}
+
+/** This package's own skill names, for the `shadowed` warning. */
+function ourSkillNames(packageRoot: string): Set<string> {
+    try {
+        return new Set(
+            fs
+                .readdirSync(path.join(packageRoot, 'src', 'skills'), { withFileTypes: true })
+                .filter((e) => e.isDirectory())
+                .map((e) => e.name),
+        );
+    } catch {
+        return new Set<string>();
+    }
+}
+
+/**
+ * The census, in two passes, and the second one is not an accident.
+ *
+ * The cross-root overlap can only be computed over the neighbour skills the
+ * census FOUND — the unclaimed entries of two roots that also hold claimed ones,
+ * since `agent-config install` writes this package's own skills into
+ * `~/.claude/skills`. Pairing whole roots instead would compare our installed
+ * copies against our own source tree and publish the install as an overlap. So
+ * pass one finds them, the overlap runs over exactly those files, and pass two
+ * labels them.
+ *
+ * The shape scan is memoized across both passes, so the four linters run once
+ * per neighbour body rather than twice. The scan verdicts are then WRITTEN to
+ * the cache the ranker reads on the hook path — this verb is the only producer,
+ * which is why its absence reads there as `no-scan-record` rather than as a pass.
+ */
+export function runCensus(
+    projectRoot: string,
+    packageRoot: string,
+    homeRoot?: string,
+): NeighbourCensus {
+    const scanned = new Map<string, string | null>();
+    const scan = (p: string): string | null => {
+        const hit = scanned.get(p);
+        if (hit !== undefined) return hit;
+        const kind = scanNeighbourBody(p).kind;
+        scanned.set(p, kind);
+        return kind;
+    };
+    const base = {
+        gatedEvents: gatedEvents(packageRoot),
+        templatesRoot: path.join(packageRoot, 'src', 'agent-src', 'templates'),
+        ourSkillNames: ourSkillNames(packageRoot),
+        packageRoot,
+        scan,
+        ...(homeRoot === undefined ? {} : { homeRoot }),
+    };
+    const first = census(projectRoot, base);
+    const ourRoot = path.join(packageRoot, 'src', 'skills');
+    let overlaps = new Map<string, { names: string[]; similarity: number }>();
+    if (first.skills.length > 0 && fs.existsSync(ourRoot)) {
+        try {
+            const { pairs } = cachedCrossRootPairs(
+                first.skills.map((s) => s.source),
+                ourRoot,
+                path.join(projectRoot, 'agents', 'reports', CROSS_CACHE_NAME),
+                OVERLAP_THRESHOLD,
+            );
+            overlaps = crossRootOverlapMap(pairs);
+        } catch {
+            // An overlap pass that cannot run leaves every entry unlabelled by
+            // it, which reads as `unclassified` — the absence of a signal — and
+            // never as a claim that the pair is disjoint.
+        }
+    }
+    const full = census(projectRoot, { ...base, overlaps });
+    writeScanCache(
+        scanCachePath(projectRoot),
+        // `fileDigest`, not the census's own `digest`: the ranker re-digests the
+        // file bytes it is about to index, and a cache written under a different
+        // digest function would read as `digest-changed` on every prompt.
+        full.skills.map((s) => ({
+            qualified: s.qualified,
+            digest: fileDigest(s.source) ?? '',
+            unscanned: s.unscanned,
+        })),
+    );
+    return full;
+}
+
+/** The one line the full `doctor` run prints, linking to this verb. */
+export function summaryLine(c: NeighbourCensus): string {
+    const counts = [
+        `${c.hook_groups.length} hook group(s)`,
+        `${c.skills.length} skill(s)`,
+        `${c.commands.length} command(s)`,
+        `${c.agents.length} agent(s)`,
+        `${c.mcp_servers.length} mcp server(s)`,
+        `${c.rule_files.length} rule file(s)`,
+        `${c.instruction_sections.length} instruction section(s)`,
+    ].join(', ');
+    const labels = c.hosts.map((h) => `${h.host}=${h.label}`).join(' ');
+    return `  🏘️   neighbours: ${counts}${labels === '' ? '' : ` · ${labels}`} (run \`doctor neighbours\` for the census)`;
+}
+
+export function renderText(c: NeighbourCensus): string[] {
+    const out: string[] = [];
+    out.push(`  📍  project_root: ${c.project_root}`);
+    out.push('');
+    for (const h of c.hosts) {
+        out.push(`  ${h.host}: ${h.label} — ${h.label_reason}`);
+        for (const e of h.hook_groups) {
+            const matcher = e.matcher === null ? '' : ` matcher=${e.matcher}`;
+            const timeout = e.timeout === null ? '' : ` timeout=${e.timeout}`;
+            out.push(`      ${e.event}: ${e.command_head}${matcher}${timeout} effect=${e.effect}`);
+        }
+    }
+    const section = (title: string, rows: ReadonlyArray<{ id: string }>): void => {
+        if (rows.length === 0) return;
+        out.push('');
+        out.push(`  ${title} (${rows.length})`);
+        for (const r of rows) out.push(`      ${r.id}`);
+    };
+    if (c.skills.length > 0) {
+        out.push('');
+        out.push(`  skills (${c.skills.length})`);
+        for (const s of c.skills) {
+            const also = s.also.length === 0 ? '' : ` also: ${s.also.join(', ')}`;
+            const why = s.unscanned === null ? '' : ` unscanned: ${s.unscanned}`;
+            out.push(`      ${s.qualified}  compat: ${s.compat}${also}${why}`);
+        }
+    }
+    section('commands', c.commands);
+    section('agents', c.agents);
+    if (c.mcp_servers.length > 0) {
+        out.push('');
+        out.push(`  mcp servers (${c.mcp_servers.length})`);
+        for (const m of c.mcp_servers) {
+            // `used` and `advertised` are printed side by side so the reader
+            // never takes the first for a coverage ratio: the denominator is
+            // not missing by accident, it is not obtainable without launching
+            // the neighbour's process, which this census does not do.
+            out.push(
+                `      ${m.id}  tools used (${m.tools_window_days}d): ${m.tools_used_30d}` +
+                    `  advertised: ${m.tools_advertised}`,
+            );
+        }
+    }
+    section('rule files', c.rule_files);
+    section('instruction sections', c.instruction_sections);
+    if (c.warnings.length > 0) {
+        out.push('');
+        for (const w of c.warnings) out.push(`  ⚠️   ${w.kind}: ${w.detail}`);
+    }
+    out.push('');
+    out.push(
+        '  The host owns load order. This census says what is there and what each entry would do;',
+    );
+    out.push('  it cannot say what ran first, and no label here refuses anything.');
+    return out;
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    let json = false;
+    let root = process.cwd();
+    let home: string | undefined;
+    for (let i = 0; i < argv.length; i += 1) {
+        if (argv[i] === '--json') json = true;
+        else if (argv[i] === '--project') {
+            root = argv[i + 1] ?? root;
+            i += 1;
+        } else if (argv[i] === '--home') {
+            // Fixture-only: the user-scope half of the census is real `$HOME`
+            // in production, and a test must be able to plant one.
+            home = argv[i + 1];
+            i += 1;
+        } else if (argv[i] === 'neighbours') {
+            continue;
+        } else {
+            process.stderr.write(`doctor neighbours: unknown argument: ${argv[i]}\n`);
+            return 2;
+        }
+    }
+    const c = runCensus(path.resolve(root), resolvePackageRoot(import.meta.url), home);
+    if (json) {
+        // Compact, not pretty-printed: this is the machine contract, and the
+        // gate that reads it matches on adjacency rather than on indentation.
+        process.stdout.write(`${JSON.stringify(c)}\n`);
+    } else {
+        for (const line of renderText(c)) process.stdout.write(`${line}\n`);
+    }
+    return 0;
+}
+
+/**
+ * Same entry guard the sibling CLIs use — including the delegate branch, which
+ * an earlier version of this file left out and which the delegate smoke test
+ * caught: `no bundle is a silent no-op` reported `cmd_doctor_neighbours.js (no
+ * output, exit 0)`, the exact shape the paragraph below describes.
+ *
+ * Inside the cli-delegate bundle `--splitting` moves this module's body into a
+ * shared chunk, so the URL comparison weighs the CHUNK against `argv[1]` and
+ * never matches. `agent-config doctor` shipped that way once already — a
+ * diagnostic reporting success while saying nothing. The invoked file name is
+ * the reliable signal there; a miss falls THROUGH to the realpath comparison
+ * rather than returning false, so a symlinked or renamed invocation still
+ * resolves. Inlined into the installer / hook / MCP bundle instead, it must
+ * never auto-run, which is why one "am I bundled" flag cannot answer "may I
+ * run" and both flags are read.
+ */
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+declare const __AGENT_CONFIG_CLI_DELEGATE__: boolean | undefined;
+
+function _isCliEntry(): boolean {
+    const bundled = typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__;
+    const cliDelegate =
+        typeof __AGENT_CONFIG_CLI_DELEGATE__ !== 'undefined' && __AGENT_CONFIG_CLI_DELEGATE__;
+    if (bundled && !cliDelegate) return false;
+    if (process.argv[1] === undefined) return false;
+    if (cliDelegate && path.basename(process.argv[1], '.js') === 'cmd_doctor_neighbours') {
+        return true;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return (
+            fs.realpathSync(fileURLToPath(import.meta.url)) ===
+            fs.realpathSync(path.resolve(process.argv[1]))
+        );
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}

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: '',
+    };
+}