@event4u/agent-config 16.0.0 → 16.2.0

package/src/scripts/update_prices.ts

@@ -23,6 +23,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { DEFAULT_PRICES, as_rows } from './ai_council/_default_prices.js';
+import { sanitize_text } from './_lib/retrieval_sanitize.js';
 import { PRICES_FILE, _render_markdown, is_stale, load_prices } from './ai_council/pricing.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -39,6 +40,40 @@ type Json = any;
 // from the LiteLLM payload. set(DEFAULT_PRICES.keys()) → "provider model" keys.
 const ALLOW_LIST: ReadonlySet<string> = new Set(DEFAULT_PRICES.keys());
 
+/**
+ * The only shape a remote identifier may have to be considered at all.
+ *
+ * Pure ASCII letters, digits and the punctuation real provider/model names use.
+ * Every allow-list entry is ASCII, so nothing outside this can be a member —
+ * and asserting it on the UNTOUCHED bytes is what makes the case fold below
+ * safe, because within ASCII folding is lossless. A Unicode character that
+ * folds onto an ASCII letter never reaches the comparison.
+ */
+const _CANONICAL_ID = /^[A-Za-z0-9._-]+$/;
+
+/** ASCII-only case fold — never `toLowerCase`, which folds Unicode too. */
+function _asciiLower(s: string): string {
+    return s.replace(/[A-Z]/g, (c) => String.fromCharCode(c.charCodeAt(0) + 32));
+}
+
+/**
+ * Report a rejected identifier that WOULD have matched after transformation.
+ *
+ * A raw miss whose normalised form hits the allow list is a different event
+ * from an ordinary unlisted name, and printing both as the same silence is what
+ * would hide an admission attempt. Ordinary misses stay silent — the fetched
+ * catalogue carries hundreds of models nobody here lists.
+ */
+function _reportCollision(rawProvider: string, rawModel: string): void {
+    const normalised = `${sanitize_text(rawProvider).toLowerCase()} ${sanitize_text(rawModel)}`;
+    if (!ALLOW_LIST.has(normalised)) return;
+    process.stderr.write(
+        'update_prices: DROPPED a remote row whose raw identifier is not allow-listed ' +
+            `but normalises onto \`${normalised}\`. A fetched name that folds or sanitizes ` +
+            'onto a listed one is an admission attempt, not a typo.\n',
+    );
+}
+
 /**
  * Synchronous HTTPS GET so the CLI stays a straight-line script (Python uses
  * a blocking urlopen). Returns parsed JSON dict, or null on any failure
@@ -99,13 +134,60 @@ export function _toRowsFromLitellm(
         if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
             continue;
         }
-        const provider = String((entry.litellm_provider as Json) ?? '').toLowerCase();
+        // Sanitize BEFORE the allow-list compare, not after. These two strings
+        // come off the wire and end up in a tracked markdown file that agents
+        // read, so they are the model-facing copy this floor exists for. Doing
+        // it before the compare is also the only order that works: a vector
+        // inside a model name would otherwise fail the allow-list lookup and
+        // drop the row, turning an injection attempt into a silent data loss.
+        // The fetched payload itself is never written anywhere — only this
+        // rendering is transformed.
+        const rawProvider = String((entry.litellm_provider as Json) ?? '');
         // LiteLLM keys are sometimes "provider/model"; strip the prefix.
         const slash = key.indexOf('/');
-        const model = slash !== -1 ? key.slice(slash + 1) : key;
-        if (!ALLOW_LIST.has(`${provider} ${model}`)) {
+        const rawModel = slash !== -1 ? key.slice(slash + 1) : key;
+
+        // THE ADMISSION BOUNDARY: a canonical ASCII grammar first, then a
+        // comparison on values nothing has transformed.
+        //
+        // Two earlier orders were both wrong and the second is the instructive
+        // one. The first sanitized before comparing, so a poisoned name could
+        // normalise onto a listed one and be admitted as it. The fix compared
+        // "raw" values — but `.toLowerCase()` ran before the compare, and THAT
+        // IS ITSELF A LOSSY UNICODE TRANSFORM: the Kelvin sign and the Turkish
+        // dotted capital both fold onto ASCII letters, so the provider field
+        // still carried the collision the model field no longer did. An
+        // independent review named it and was right; closing one field and
+        // calling the class closed is the failure mode, not the typo.
+        //
+        // The reachable fold is ONE character: `U+212A KELVIN SIGN -> k`.
+        // Measured, not recalled — U+212B ANGSTROM folds to `å`, which is not
+        // ASCII, and an earlier note here claimed otherwise. No provider in the
+        // current list carries a `k`, so this boundary guards nothing reachable
+        // TODAY; it guards the day one is added, which is the only time a
+        // boundary of this shape can be added without a migration.
+        //
+        // So the grammar is asserted on the UNTOUCHED bytes. Pure ASCII, with
+        // the punctuation real identifiers use. Nothing outside it can be an
+        // allow-list member, because every entry is ASCII — and within ASCII,
+        // case folding is lossless, which is what makes the fold below safe to
+        // apply after the gate rather than before it.
+        if (!_CANONICAL_ID.test(rawProvider) || !_CANONICAL_ID.test(rawModel)) {
+            _reportCollision(rawProvider, rawModel);
             continue;
         }
+        const provider = _asciiLower(rawProvider);
+        if (!ALLOW_LIST.has(`${provider} ${rawModel}`)) {
+            _reportCollision(rawProvider, rawModel);
+            continue;
+        }
+
+        // Only now, and only for the rendering: the row reaches a tracked
+        // markdown file that agents read, so the model-facing copy carries the
+        // floor. The fetched payload itself is never written anywhere. Both
+        // values are already canonical ASCII here, so this is a no-op in
+        // practice and a belt on the rendering in principle.
+        const model = sanitize_text(rawModel);
         const inCost = entry.input_cost_per_token;
         const outCost = entry.output_cost_per_token;
         if (!_isNumber(inCost) || !_isNumber(outCost)) {

package/src/scripts/write_bundle_digest.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * write_bundle_digest.mjs — the sidecar `dist/hooks/dispatch.sha256`.
+ *
+ * Step 3.1 of `road-to-a-kernel-that-guards-its-plumbing`. The dispatcher
+ * verifies at runtime that the bundle it is executing is the bundle the build
+ * produced, and it needs something to compare against. This writes that
+ * something, in the same `npm run build:hooks` invocation that writes the
+ * bundle, so the two cannot be produced separately and cannot disagree.
+ *
+ * Plain `.mjs` rather than a TS script under `scripts-run`: it is chained into
+ * `build:hooks`, which runs before anything is compiled and on machines where
+ * a `tsx` startup is pure cost. `prepack-check.mjs` sets the precedent.
+ *
+ * Format is one line, `<64 hex>  <basename>`, i.e. what `shasum -a 256`
+ * emits — so an operator can verify the claim with a tool they already have
+ * instead of trusting this script:
+ *
+ *     shasum -a 256 -c dist/hooks/dispatch.js.sha256
+ *
+ * This is NOT a signature and does not pretend to be. Anyone who can rewrite
+ * the bundle can rewrite the sidecar beside it. What it defends against is the
+ * hand edit — a bundle changed in place between builds, which until now
+ * survived until the next build, reached every dispatch meanwhile, and was
+ * invisible in a source review. `block_plumbing_writes` refuses that edit at
+ * tool-call time; this catches one that arrived by some other route.
+ */
+import { createHash } from 'node:crypto';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { argv, exit, stderr, stdout } from 'node:process';
+
+const bundle = resolve(argv[2] ?? 'dist/hooks/dispatch.js');
+// `dispatch.sha256`, not `dispatch.js.sha256` — the name the roadmap step
+// wrote. Either works with `shasum -c`, which reads the subject filename from
+// INSIDE the file rather than from the sidecar's own name, so the choice is
+// free and the step's spelling wins.
+const sidecar = bundle.replace(/\.js$/u, '') + '.sha256';
+
+let bytes;
+try {
+    bytes = readFileSync(bundle);
+} catch (err) {
+    stderr.write(`write_bundle_digest: cannot read ${bundle}: ${err.message}\n`);
+    // Exit non-zero: a build that produced no bundle must not report success,
+    // and a sidecar written from a missing file would be a digest of nothing.
+    exit(1);
+}
+
+const digest = createHash('sha256').update(bytes).digest('hex');
+writeFileSync(sidecar, `${digest}  ${basename(bundle)}\n`, 'utf-8');
+
+// Read back what was just written and confirm it describes the bundle beside
+// it. An independent review called a post-build verification the
+// highest-leverage addition here, and the reason is the runtime posture: a
+// MISSING or unreadable sidecar is `unverifiable` at dispatch time and ALLOWS,
+// deliberately, so that a consumer whose package predates the sidecar is not
+// wedged. That choice means a half-written or unreadable sidecar degrades the
+// check silently instead of failing anything.
+//
+// `prepack-check.mjs` catches it at packaging time, which covers the published
+// tarball and nothing else. This covers every path that produces a bundle at
+// all — local build, CI build, packaging — because it is part of producing one.
+// It costs one re-read of 78 bytes.
+const readBack = readFileSync(sidecar, 'utf-8');
+const claimed = /^([0-9a-f]{64})\s/u.exec(readBack.trim())?.[1] ?? null;
+if (claimed !== digest) {
+    stderr.write(
+        `write_bundle_digest: wrote ${sidecar} but read back ${claimed ?? '(unparseable)'} ` +
+            `instead of ${digest} — the sidecar does not describe the bundle it was written for.\n`,
+    );
+    exit(1);
+}
+stdout.write(`write_bundle_digest: ${digest}  ${basename(bundle)} (${String(bytes.length)} bytes, verified)\n`);

package/src/server/schemas/settings.ts

@@ -36,6 +36,8 @@ const leanProjectionHost = z.enum(['claude-code', 'cursor', 'cline']);
 const projectionMode = z.enum(['legacy-all', 'scoped']);
 const memoryCadence = z.enum(['auto', 'always', 'never']);
 const projectAudience = z.enum(['self', 'internal', 'client', 'public']);
+const deliveryMerge = z.enum(['off', 'on-green']);
+const prTopology = z.enum(['single', 'stacked']);
 
 export const settingsSchema = z.object({
     agent_config_version: z.string().default('').describe(
@@ -65,7 +67,7 @@ export const settingsSchema = z.object({
     ),
     lean_projection: z.object({
         mode: leanProjectionMode.default('eager-all').describe(
-            'How the per-tool projector emits the rule layer. eager-all = every rule body inlined into every projection (safe; what an ABSENT key still resolves to, per ADR-267 decision point 4). thin = kernel rules full-bodied + non-kernel rules as router-resolved pointers (~45k GPT-tok lighter per session), with no delivery mechanism. delivery = thin stubs PLUS the rule-inject hook concern, which delivers a body back on a trigger match; this is the value the SHIPPED TEMPLATE carries for Claude Code since ADR-267, and the activation charge for it is paid in src/config/hook-token-budget.json (user_prompt_submit slot sum 4,096 -> 16,384).',
+            'How the per-tool projector emits the rule layer. eager-all = every rule body inlined into every projection (safe; what an ABSENT key still resolves to, per ADR-267 decision point 4). thin = kernel rules full-bodied + non-kernel rules as router-resolved pointers (~45k GPT-tok lighter per session, exact-BPE — a different unit from the chars/4 figures below, never compare the two directly), with no delivery mechanism. delivery = thin stubs PLUS the rule-inject hook concern, which delivers a body back on a trigger match; this is the value the SHIPPED TEMPLATE carries for Claude Code since ADR-267. SAVING AND CHARGE, MEASURED TOGETHER so neither is published alone (2026-09-12, `check_preamble_payload_budget`): the rule bucket falls 122,769 -> 24,537 chars/4 tok per session on a thinned host (-80.0%), and a trigger match costs p50 6,728 B / p90 14,016 B / max 16,297 B per fire over 318 gate-open fires of the frozen tests/eval/routing-matrix corpus at the concern\'s 16,384 B cap. Bytes per fire and tokens per session are different denominators and are never summed; re-read both rather than quoting this line. The ceiling for that charge is registered in src/config/hook-token-budget.json (user_prompt_submit slot sum 4,096 -> 16,384).',
         ),
         hosts: z.array(leanProjectionHost).default(['claude-code']).describe(
             'Which hosts a thinning mode may thin (ADR-267). Absent resolves to [claude-code]. '
@@ -161,6 +163,48 @@ export const settingsSchema = z.object({
             'How the agent replies to PR review comments. create_review_comment = post a new review comment (works on every GitHub plan). replies_endpoint = thread the reply under the original comment (needs the newer REST endpoint). auto = detect at runtime, prefer threaded replies when available.',
         ),
     }),
+    delivery: z.object({
+        merge: deliveryMerge.default('off').describe(
+            'Whether a run may merge the pull request it produced. off (default) = the run ends at mergeable-green-and-open and says so. on-green = merge is permitted, and only when an object-bound grant covering {op: prod_merge, target: <base>} exists and the final head is required-check-green, target-current and tamper-checked. This key is a precondition, never the authorisation by itself; forge auto-merge is the mechanism, so branch protection stays the gate.',
+        ),
+        wait_for_ci: z.boolean().default(true).describe(
+            'Whether the run stays alive until the required checks settle. true (default) = the run drives CI and reports the settled verdict. false = the run ends once the branch is pushed and the PR is open, leaving the checks to be read later. Independent of merge: a run may wait for CI without being allowed to merge.',
+        ),
+        pr_topology: prTopology.default('single').describe(
+            'How a mission\'s work is shaped into pull requests. single (default) = one branch, one pull request. stacked = a dependent series. stacked is never chosen by the agent and never asked about at roadmap creation — the owner plans it or it does not happen.',
+        ),
+    }),
+    /**
+     * What this package may write into the HOST's own environment.
+     *
+     * THE GUARANTEE IS THE SHAPE, not a check. Only two keys exist here, and
+     * both are request-SIZE caps. Neither traffic variable is expressible —
+     * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` and `DISABLE_AUTOUPDATER` both
+     * reach the host's update-disabled resolver (the blanket one as its third
+     * rung, measured on Claude Code 2.1.284), so a profile able to write either
+     * could disable a consumer's security updates. Owner-decided 2026-09-30:
+     * they are not writable through this package at all, and the strongest way
+     * to hold that is a schema that cannot say them rather than an exclusion
+     * list somebody has to maintain.
+     *
+     * `null` is the default on both, and it is the off switch: nothing is
+     * written. There is no separate enable flag, because a flag plus a value is
+     * two ways to say off and one of them would drift.
+     */
+    host_environment: z.object({
+        request_size_caps: z.object({
+            bash_max_output_length: z.number().int().positive().max(150_000).nullable().default(null).describe(
+                'Character cap on Bash tool output the host places inline into a model request. null (default) = this package writes nothing and the host default of 30000 applies. A number is written into the host env block. Values above 150000 are capped by the host itself, so the schema refuses them here rather than writing a value the host silently changes. Bounds request SIZE, never request COUNT: lowering it suppresses no telemetry, no update check and no download.',
+            ),
+            max_mcp_output_tokens: z.number().int().positive().nullable().default(null).describe(
+                'Token cap on a single MCP tool result the host places into a model request. null (default) = nothing written, host default 25000 applies. Same size-not-count caveat: it does not govern MCP connections, timeouts, or whether a tool runs.',
+            ),
+        }).default({}).describe(
+            'Request-size caps this package may write into the host env block. Both null by default. No traffic or auto-updater variable is expressible here, by construction — see the block comment.',
+        ),
+    }).default({}).describe(
+        'What this package may write into the host environment. ABSENT resolves to the all-null shape, which is the same thing as off — a settings file predating this section must not fail to parse, and "no section" and "both caps null" both mean write nothing.',
+    ),
     augment: z.object({
         rules_use_symlinks: z.boolean().default(false).describe(
             'When true, .augment/rules/*.md are symlinks into dist/agent-src/rules/ — edits flow back to source on save. When false (default), they are copies — safer on Windows and shared volumes, but rule edits in .augment/ are lost on the next `task sync`.',
@@ -202,8 +246,8 @@ export const settingsSchema = z.object({
         skip_pre_run_gate: z.boolean().default(true).describe(
             'Skip the /roadmap:process-* pre-run confirmation gate. true (default) starts processing immediately and surfaces the resolved config inline; false shows the numbered-options gate and waits. A genuine "which roadmap?" ambiguity always prompts regardless.',
         ),
-        quality_cadence: qualityCadence.default('end_of_roadmap').describe(
-            'When the agent runs the full quality / test suite during /roadmap:process-* runs. end_of_roadmap = once, after the last step (fastest, default). per_phase = after each phase boundary. per_step = after every single step (slowest, highest confidence).',
+        quality_cadence: qualityCadence.default('per_phase').describe(
+            'When the agent runs the full quality / test suite during /roadmap:process-* runs. per_phase = after each phase boundary (default since 2026-09-13 — end_of_roadmap lets errors compound across phases, which is expensive in a multi-phase autonomous run nobody is watching). end_of_roadmap = once, after the last step (fastest). per_step = after every single step (slowest, highest confidence).',
         ),
         dashboard_regen_cadence: regenCadence.default('every_5_steps').describe(
             'How often the agent regenerates agents/roadmaps/dashboard.md during a roadmap run. every_5_steps = batch the regen (default). per_step = after every step (freshest dashboard, highest subprocess overhead). phase_boundary = only at phase edges. A rename, phase add, or archive always regenerates immediately regardless.',
@@ -221,8 +265,8 @@ export const settingsSchema = z.object({
         }).default({ max_cost_per_run_usd: 5, max_cost_per_rolling_7d_usd: 25 }),
     }),
     planning: z.object({
-        challenge_on_create: z.boolean().default(true).describe(
-            'Gate C — plan-confidence gate before authoring. true (default) = a plan-artifact ask (/roadmap:create, roadmap-writing, /feature:plan, /feature:roadmap) first checks the four 95%-confidence conditions from /challenge-me vision; any gap routes into the interview (or the inline degrade protocol) before authoring, and a confident pass emits exactly one marker line. false = inert, plan asks author directly. An explicit user bypass always wins for that turn and is counted.',
+        closure_pass: z.boolean().default(true).describe(
+            'Gate C — plan-closure pass. true (default) = a plan-artifact ask (/roadmap:create, roadmap-writing, /feature:plan, /feature:roadmap, /roadmap:materialize, /implement-ticket, /jira-ticket, /analyze:inbox, /analyze:roadmap-repos) ends in a closure pass (/challenge-me closure): every foreseeable decision is closed at the lowest rung that owns it and written into the roadmap\'s "## Decisions" table, so a long run never meets a question planning could have closed. false = inert, plan asks author directly. An explicit user bypass always wins for that turn and is counted as a bypass rather than as an absent closure.',
         ),
         risk_review: z.boolean().default(true).describe(
             'Gate R1 — plan-risk review. true (default) = every ready (non-draft) plan must carry a schema-valid "## Risk Register" section (ranked risks, mitigation + anchor per row, freshness marker, exact honest-null grammar), enforced by lint_plan_risk_register at pre-push + CI. false = escape hatch, the validator skips.',
@@ -238,9 +282,20 @@ export const settingsSchema = z.object({
         // test whose fixture predates the section. With the default, an absent
         // section materialises as the three `true` leaves the contract promises.
         .default({}),
+    execution: z.object({
+        fix_loop_max: z.number().int().min(1).default(10).describe(
+            'Consecutive failed fix attempts against one validation target before the escalation ladder reaches its terminal rung. Reaching the bound triggers a strategy change, never a question. Overridable globally, per project and per prompt.',
+        ),
+        escalation: z.array(z.string()).default(['independent', 'council', 'team', 'owner_owned_check']).describe(
+            'The escalation rungs, in order, walked when the fix-loop bound is reached: independent (another session or a provider-diverse reviewer), council, team, then owner_owned_check — which asks whether the residue is owner-owned, not whether to ask the owner now.',
+        ),
+    }).default({}),
     quality: z.object({
         local_auto_run: z.boolean().default(false).describe(
-            'Run quality tools (linters, type-checks, formatters) and the local test suite autonomously after edits. Off by default — the agent never runs quality tools proactively and does not ask; the user runs them manually (e.g. /quality-fix) and remote CI is the authoritative gate. The agent only runs a quality tool on an explicit ask, a concrete CI failure, or the new-gate carve-out. Turn on to restore autonomous pipeline runs.',
+            'Run quality tools (linters, type-checks, formatters) and the local test suite autonomously after edits, IN CHAT. Off by default — in a chat turn a human is present and remote CI is the authoritative gate, so a local full-pipeline run duplicates it at wall-clock cost. The agent only runs a quality tool on an explicit ask, a concrete CI failure, or the new-gate carve-out. A mission is governed by local_auto_run_in_mission instead.',
+        ),
+        local_auto_run_in_mission: z.boolean().default(true).describe(
+            'Run quality tools autonomously inside a mission — an autonomous roadmap run with a claimed contract. On by default: nobody is waiting, the next action belongs to the agent itself, and a red found twenty steps later costs more than the run that would have caught it at step one. Inert outside a mission, and a mission never lowers local_auto_run: true.',
         ),
     }),
     design: z.object({
@@ -547,7 +602,7 @@ export const settingsSchema = z.object({
         }).default({}),
         rtk_wrap: z.object({
             enabled: z.boolean().default(false).describe(
-                'PreToolUse RTK-wrap nudge (token-saving Phase 3). Default off. When on AND the binary on PATH is verified as Rust Token Killer (a live two-stage identity probe — not a self-reported flag, and never a colliding same-name binary), warns (never blocks) "re-run wrapped with rtk" before a single verbose CLI command (git/npm/cargo/docker/…) — upstream reports 60–90% output-token savings (their estimate). Skips completeness-critical / piped / compound commands and git diff. No-op when rtk is absent, unverified, or a different tool.',
+                'PreToolUse RTK-wrap nudge (token-saving Phase 3). Default off. When on AND the binary on PATH is verified as Rust Token Killer (a live two-stage identity probe — not a self-reported flag, and never a colliding same-name binary), warns (never blocks) "re-run wrapped with rtk" before a single verbose CLI command (git/npm/cargo/docker/…) — upstream reports 60–90% output-token savings (their estimate). Skips completeness-critical / piped / compound commands and git diff. No-op when rtk is absent, unverified, or a different tool. Its own activation charge is one advisory line under the 1,024 B default concern cap in src/config/hook-token-budget.json; the per-fire distribution is UNMEASURED — stated rather than estimated, because the saving above is a third-party output-token claim and not a standing-payload reduction this package measured.',
             ),
         }).default({}),
         design_slop: z.object({

package/src/shared/missionExecution.ts

@@ -0,0 +1,126 @@
+/**
+ * Mission execution posture — the loop bound, its escalation ladder, and the
+ * one setting whose value differs inside a mission.
+ *
+ * `road-to-adversarial-verification-and-long-runs` Phase 0. Three facts that
+ * were previously either absent or stated only in prose get one module, because
+ * all three are read by more than one surface (`doctor --json`, `settings:get`,
+ * the recovery ladder) and a constant restated per reader is the standard way a
+ * default drifts.
+ *
+ * **Why a mission changes `quality.local_auto_run` and nothing else does.** The
+ * template's own justification for shipping `false` is that remote CI is the
+ * authoritative gate and a local full-pipeline run duplicates it at wall-clock
+ * cost. That argument is about a CHAT turn, where the human is present, the next
+ * action is theirs, and the pipeline's result arrives long after the reply. It is
+ * not an argument about an autonomous mission, where nobody is waiting, the next
+ * action is the agent's own, and a red found after twenty more steps costs more
+ * than the pipeline run that would have found it at step one. The roadmap
+ * template already says as much about the sibling cadence knob — that
+ * `end_of_roadmap` lets errors compound across phases — so the two knobs are
+ * corrected together rather than one at a time.
+ *
+ * The resolution is deliberately NOT a settings-layer precedence trick. A layer
+ * is a place a human wrote a value; a mission is a runtime condition. Folding
+ * the condition into the layer stack would make `settings:get` report a source
+ * file for a value no file contains.
+ */
+
+/** The escalation rungs, in the order the recovery ladder walks them. */
+export const ESCALATION_LADDER: readonly string[] = [
+    'independent',
+    'council',
+    'team',
+    'owner_owned_check',
+] as const;
+
+/** Default bound on consecutive failed fix attempts against one target. */
+export const FIX_LOOP_MAX_DEFAULT = 10;
+
+/** Default for `quality.local_auto_run_in_mission`. */
+export const MISSION_AUTO_RUN_DEFAULT = true;
+
+/** Where a resolved `quality.local_auto_run` value came from. */
+export type AutoRunOrigin = 'mission' | 'settings';
+
+export interface AutoRunResolution {
+    /** The value a reader should act on. */
+    readonly value: boolean;
+    /** `mission` when the mission condition decided, `settings` otherwise. */
+    readonly origin: AutoRunOrigin;
+}
+
+export interface AutoRunInputs {
+    /** `quality.local_auto_run` as the settings layers resolved it. */
+    readonly configured: boolean;
+    /** `quality.local_auto_run_in_mission`, or `undefined` for the default. */
+    readonly missionValue?: boolean | undefined;
+    /** True only inside an autonomous mission (a claimed roadmap run). */
+    readonly inMission: boolean;
+}
+
+/**
+ * Resolve `quality.local_auto_run` for the current run.
+ *
+ * Outside a mission the configured value wins unchanged — that is the whole
+ * point of leaving chat alone. Inside one, `local_auto_run_in_mission` decides.
+ *
+ * One asymmetry is deliberate: a mission never LOWERS the configured value. An
+ * operator who set `local_auto_run: true` asked for pipeline runs everywhere,
+ * and a mission is not a reason to give them fewer.
+ */
+export function resolveLocalAutoRun(inputs: AutoRunInputs): AutoRunResolution {
+    if (inputs.configured) return { value: true, origin: 'settings' };
+    if (!inputs.inMission) return { value: false, origin: 'settings' };
+    const mission = inputs.missionValue ?? MISSION_AUTO_RUN_DEFAULT;
+    return mission ? { value: true, origin: 'mission' } : { value: false, origin: 'settings' };
+}
+
+/**
+ * Fold `execution.*` out of a settings-override stream, last layer wins.
+ *
+ * Takes the same `[dotted, value, file]` tuples `iter_setting_overrides` emits,
+ * so a caller never re-implements the cascade. Keys outside the `execution.`
+ * prefix are ignored rather than collected: this is a narrow reader, and a
+ * reader that accidentally carries the whole settings tree is how a doctor
+ * payload grows a field nobody declared.
+ */
+export function executionPostureFromOverrides(
+    layers: Iterable<readonly [string, unknown, string]>,
+): ExecutionPosture {
+    const raw: Record<string, unknown> = {};
+    for (const [key, value] of layers) {
+        if (key === 'execution.fix_loop_max') raw['fix_loop_max'] = value;
+        else if (key === 'execution.escalation') raw['escalation'] = value;
+    }
+    return resolveExecutionPosture(raw);
+}
+
+export interface ExecutionPosture {
+    readonly fix_loop_max: number;
+    readonly escalation: readonly string[];
+}
+
+/**
+ * The `execution:` block as a reader should see it, defaults filled in.
+ *
+ * A non-integer, non-positive or absent `fix_loop_max` falls back to the default
+ * rather than propagating: a bound of `0` would make every first attempt
+ * terminal, which is a configuration that can only be a mistake.
+ */
+export function resolveExecutionPosture(raw: unknown): ExecutionPosture {
+    const block = (raw ?? {}) as Record<string, unknown>;
+    const rawMax = block['fix_loop_max'];
+    const max =
+        typeof rawMax === 'number' && Number.isInteger(rawMax) && rawMax > 0
+            ? rawMax
+            : FIX_LOOP_MAX_DEFAULT;
+    const rawLadder = block['escalation'];
+    const ladder =
+        Array.isArray(rawLadder) &&
+        rawLadder.length > 0 &&
+        rawLadder.every((r) => typeof r === 'string')
+            ? (rawLadder as string[])
+            : ESCALATION_LADDER;
+    return { fix_loop_max: max, escalation: ladder };
+}

package/src/templates/consumer-settings/ONBOARDING.md

@@ -39,3 +39,4 @@ This surfaces every registration across all six tools and flags `DUPLICATE` / `D
 - [`docs/contracts/install-scopes.md`](../../docs/contracts/install-scopes.md) — when to use project-local vs user-global.
 - [`docs/customization.md` § Troubleshooting](../../docs/customization.md#troubleshooting) — the troubleshooting front door.
 - [`agents/reference/docs/onboarding.md`](../../agents/reference/docs/onboarding.md) — the longer, package-side onboarding doc.
+- [`docs/setup/host-traffic-environment.md`](../../docs/setup/host-traffic-environment.md) — which host environment variables suppress non-essential network traffic, and which only look as if they do; `agent-config doctor --json` reports their observed state.

package/dist/cli-delegate/chunk-523HCFYO.js

@@ -1,90 +0,0 @@
-import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);
-
-// src/install/plan.ts
-import { createHash } from "node:crypto";
-import { readFileSync, readdirSync, statSync } from "node:fs";
-import { join, relative, resolve } from "node:path";
-function sha256File(path) {
-  try {
-    const data = readFileSync(path);
-    return createHash("sha256").update(data).digest("hex");
-  } catch {
-    return null;
-  }
-}
-function fileEntry(path, kind, options) {
-  return {
-    path,
-    kind,
-    sha256: options.hashContent ? sha256File(path) : null
-  };
-}
-function walkSourceTree(dir) {
-  const out = [];
-  walkInto(dir, out);
-  return out;
-}
-function walkInto(dir, out) {
-  let entries;
-  try {
-    entries = readdirSync(dir).sort();
-  } catch {
-    return;
-  }
-  for (const name of entries) {
-    const full = join(dir, name);
-    let isDir;
-    try {
-      isDir = statSync(full).isDirectory();
-    } catch {
-      continue;
-    }
-    if (isDir) {
-      walkInto(full, out);
-    } else {
-      out.push(full);
-    }
-  }
-}
-function buildInstallPlan(inputs) {
-  const filesByTool = {};
-  for (const source of inputs.sources) {
-    const bucket = filesByTool[source.toolId] ?? [];
-    let files = walkSourceTree(source.srcDir);
-    if (source.fileFilter !== void 0) {
-      files = files.filter(source.fileFilter);
-    }
-    for (const srcFile of files) {
-      const rel = relative(source.srcDir, srcFile);
-      const destPath = resolve(source.destDir, rel);
-      bucket.push(
-        fileEntry(srcFile, source.kind, {
-          hashContent: source.kind !== "bridge"
-        })
-      );
-      bucket[bucket.length - 1] = {
-        ...bucket[bucket.length - 1],
-        path: destPath
-      };
-    }
-    filesByTool[source.toolId] = bucket;
-  }
-  for (const source of inputs.sources) {
-    if (!(source.toolId in filesByTool)) {
-      filesByTool[source.toolId] = [];
-    }
-  }
-  return {
-    version: 2,
-    target: inputs.target,
-    root: inputs.root,
-    filesByTool,
-    mergedKeysByTool: {},
-    policy: inputs.policy
-  };
-}
-
-export {
-  sha256File,
-  buildInstallPlan
-};