@event4u/agent-config 14.2.0 → 14.5.0

package/src/scripts/_lib/council_fallback_wiring.ts

@@ -0,0 +1,126 @@
+/**
+ * council_fallback_wiring — the api-twin factory and the event sink that
+ * `build_members` hands to the orchestrator.
+ *
+ * Lives here rather than in `council_cli.ts` because that file is 2,700 lines
+ * over the source ceiling and the documented fix is extraction
+ * (`gate-violation-baselines.json` § check_source_size_budget).
+ *
+ * Deps are injected rather than imported: `council_cli.ts` owns the provider
+ * table, the api constructor and the error classes, and importing them back
+ * here would make this module a second place that decides which providers
+ * exist. It decides nothing — it wires.
+ */
+
+import type { CliFallbackOptions, FallbackEvent } from '../ai_council/mid_flight_fallback.js';
+import { CouncilConfigError } from '../ai_council/config.js';
+
+type Dict = Record<string, unknown>;
+
+/** Anything the twin factory needs that `council_cli.ts` owns. */
+export interface FallbackWiringDeps {
+    readonly apiOnQuota: boolean;
+    /** Does this provider have an api constructor at all? */
+    readonly hasApiRung: (provider: string) => boolean;
+    /** This provider's `members.<name>` block, or `{}`. */
+    readonly memberConfig: (provider: string) => Dict;
+    /** A `--model` override for this provider, or `null`. */
+    readonly modelOverride: (provider: string) => string | null;
+    /** The strict api constructor. Throws to refuse; see the catch below. */
+    readonly constructApi: (
+        name: string,
+        model: string | null,
+        opts: {
+            api_key_ref?: string | null;
+            enable_prompt_cache?: boolean;
+            prompt_cache_ttl?: '5m' | '1h' | undefined;
+        },
+    ) => unknown;
+    /** The events-log appender. */
+    readonly emit: (record: Dict) => unknown;
+}
+
+/**
+ * Errors that mean "no api rung for this provider" rather than "something
+ * broke".
+ *
+ * `CouncilConfigError` is in this set because it is what key resolution throws
+ * on a rotated or removed key — the ORDINARY case. It was missing once, and
+ * the escalation escaped the factory, left `consult`, and took down the pass
+ * the fallback exists to rescue. A mechanism that turns a recoverable seat
+ * loss into a total loss is worse than no mechanism.
+ *
+ * The other two are matched by NAME rather than by identity: importing
+ * `CouncilDisabledError` and `CliClientError` back from `council_cli.ts` would
+ * be a cycle, and this module deliberately owns no provider knowledge.
+ */
+const REFUSAL_NAMES: ReadonlySet<string> = new Set([
+    'CouncilDisabledError',
+    'CliClientError',
+    'CouncilConfigError',
+    // R2 round 6, critical finding 1 — and the docblock above already told the
+    // story one name short. `KeyGateError` is what an api-twin construction
+    // raises when the provider key is absent or violates the 0600 contract,
+    // which is the ORDINARY shape of the very configuration this fallback
+    // targets: a cli member under subscription auth, no `api_key_ref`, no
+    // local key. It escaped `construct()`, escaped `consult()`, and is not in
+    // `main`'s catch list — so instead of losing one seat, the whole pass died
+    // with an unhandled exception. A mechanism that turns a recoverable seat
+    // loss into a total loss is worse than no mechanism, which is the sentence
+    // directly above this list.
+    'KeyGateError',
+]);
+
+function isRefusal(exc: unknown): boolean {
+    if (exc instanceof CouncilConfigError) return true;
+    return exc instanceof Error && REFUSAL_NAMES.has(exc.constructor.name);
+}
+
+export function buildFallbackOptions(deps: FallbackWiringDeps): CliFallbackOptions {
+    return {
+        api_on_quota: deps.apiOnQuota,
+        // The orchestrator is a pure library and holds no sink; this is it.
+        // One line per establishing escalation, so attendance analysis can
+        // tell a seat SAVED by the fallback from one that was natively api.
+        on_event: (e: FallbackEvent): void => {
+            // Wrapped, for the reason `appendQuorumEvent` states for the
+            // identical call: an events-log write is best-effort telemetry, and
+            // a failed one (read-only mount, full disk, a permission change on
+            // agents/runtime) must not take the council pass down with it.
+            //
+            // R2 round 2, finding 7. Unwrapped, this throws out of `on_event`,
+            // out of `establishTwin`, and out of `consult` — so a disk problem
+            // during a fallback kills the whole round, and the mechanism whose
+            // entire purpose is to SAVE a seat becomes the thing that loses
+            // every seat. Losing the log line is the strictly smaller failure.
+            try {
+                deps.emit({
+                    action: 'transport_fallback',
+                    provider: e.provider,
+                    failure_class: e.failure,
+                    outcome: e.outcome,
+                    api_on_quota: e.api_on_quota,
+                });
+            } catch {
+                /* best-effort telemetry — never fail the pass */
+            }
+        },
+        construct: (provider: string) => {
+            if (!deps.hasApiRung(provider)) return null;
+            const cfg = deps.memberConfig(provider);
+            // Same model resolution the cli member got: override, then
+            // config, then the api constructor's own default.
+            const model = deps.modelOverride(provider) ?? (cfg['model'] as string | undefined) ?? null;
+            try {
+                return deps.constructApi(provider, model, {
+                    api_key_ref: (cfg['api_key_ref'] as string | null) ?? null,
+                    enable_prompt_cache: cfg['prompt_cache'] !== false,
+                    prompt_cache_ttl: cfg['prompt_cache_ttl'] as '5m' | '1h' | undefined,
+                }) as ReturnType<CliFallbackOptions['construct']>;
+            } catch (exc) {
+                if (isRefusal(exc)) return null;
+                throw exc;
+            }
+        },
+    };
+}

package/src/scripts/_lib/council_settings_block.ts

@@ -0,0 +1,152 @@
+/**
+ * council_settings_block — the `CouncilConfig` → settings-dict projection.
+ *
+ * A pure mapping with no I/O and one responsibility, relocated out of
+ * `council_cli.ts` UNCHANGED. That file sits ~2,600 lines over the source
+ * ceiling, and this repository answers growth with extraction rather than a
+ * raised baseline (`gate-violation-baselines.json`
+ * § check_source_size_budget: "extract, then measure").
+ *
+ * Nothing is redesigned, renamed or re-ordered: the body below is the one that
+ * lived in `council_cli.ts`, so a reviewer diffs a MOVE rather than a rewrite,
+ * and the existing describe block over it keeps passing untouched.
+ *
+ * ## The defect this projection has shipped three times
+ *
+ * `load_settings` does not hand `build_members` the config FILE — it hands it
+ * this block. So a key the loader validates and this projection drops is
+ * enforced at load and invisible at runtime. That has now happened to
+ * `quorum`, to `quorum_min_present`, and to `fallback.api_on_quota` in turn;
+ * each carries its own comment below. A new key belongs in BOTH places or in
+ * neither.
+ */
+
+import type { CouncilConfig } from '../ai_council/config.js';
+import { _mapToObject } from './map_to_object.js';
+
+type Dict = Record<string, unknown>;
+
+export function synthesizeAiCouncilBlock(cfg: CouncilConfig): Dict {
+    const members: Dict = {};
+    for (const [name, m] of cfg.members) {
+        const entry: Dict = { enabled: m.enabled, model: m.model };
+        if (m.api_key_ref !== null) {
+            entry['api_key_ref'] = m.api_key_ref;
+        }
+        if (m.mode !== null) {
+            entry['mode'] = m.mode;
+        }
+        if (m.binary !== null) {
+            entry['binary'] = m.binary;
+        }
+        if (m.model_ladder && m.model_ladder.length > 0) {
+            entry['model_ladder'] = [...m.model_ladder];
+        }
+        // road-to-cache-economy Phase 4: forward only an explicit override —
+        // the '5m' default needs no key, keeping the synthesized block
+        // byte-identical to pre-Phase-4 output when nobody opted in.
+        if (m.prompt_cache_ttl !== '5m') {
+            entry['prompt_cache_ttl'] = m.prompt_cache_ttl;
+        }
+        members[name] = entry;
+    }
+    const advisors: Dict = {};
+    for (const [name, a] of cfg.advisors) {
+        const entry: Dict = {
+            enabled: a.enabled,
+            member: a.member,
+            persona: a.persona,
+        };
+        if (a.model !== null) {
+            entry['model'] = a.model;
+        }
+        advisors[name] = entry;
+    }
+    const lensCostDisclosure: Dict = {};
+    for (const [lens, cd] of cfg.lens_overrides.cost_disclosure) {
+        lensCostDisclosure[lens] = {
+            mode: cd.mode,
+            threshold_usd: cd.threshold_usd,
+            show_per_member: cd.show_per_member,
+        };
+    }
+    const lensModelDowngrade: Dict = {};
+    for (const [lens, md] of cfg.lens_overrides.model_downgrade) {
+        lensModelDowngrade[lens] = { enabled: md.enabled, auto_apply: md.auto_apply };
+    }
+    return {
+        enabled: cfg.enabled,
+        mode: cfg.defaults.mode,
+        min_rounds: cfg.defaults.min_rounds,
+        deep_min_rounds: cfg.defaults.deep_min_rounds,
+        max_output_tokens: cfg.defaults.max_output_tokens,
+        session_retention_days: cfg.defaults.session_retention_days,
+        debate_max_rounds: cfg.defaults.debate_max_rounds,
+        cost_budget: {
+            max_input_tokens: cfg.cost_budget.max_input_tokens,
+            max_output_tokens: cfg.cost_budget.max_output_tokens,
+            max_calls: cfg.cost_budget.max_calls,
+            max_total_usd: cfg.cost_budget.max_total_usd,
+            daily_limit_usd: cfg.cost_budget.daily_limit_usd,
+        },
+        consensus_scoring: {
+            enabled: cfg.consensus_scoring.enabled,
+            strong_threshold: cfg.consensus_scoring.strong_threshold,
+            minority_threshold: cfg.consensus_scoring.minority_threshold,
+            lenses: [...cfg.consensus_scoring.lenses],
+        },
+        cli_call_budget: {
+            max_calls_per_day: _mapToObject(cfg.cli_call_budget.max_calls_per_day),
+            warn_at: cfg.cli_call_budget.warn_at,
+        },
+        // Phase 3.3 (road-to-always-on-orchestration): was validated by
+        // `_build_config`/`_build_quorum` but never forwarded into the
+        // synthesized block, so `build_members` always saw `undefined` and
+        // silently fell back to `'majority'` regardless of the user's
+        // configured `quorum: <k>`. Additive key — callers that never read
+        // it observe no change.
+        quorum: cfg.quorum,
+        // Forwarded for the same reason `quorum` above had to be: a key that
+        // `_build_config` validates and this block drops is a key the loader
+        // enforces and the runtime never sees. That defect shipped once here
+        // already; repeating it for the shadow floor would silently pin every
+        // `floor_would_hold` to the default no matter what the operator set.
+        quorum_min_present: cfg.quorum_min_present,
+        // Third instance of the same defect the two comments above describe,
+        // and the most expensive of the three: `build_members` reads
+        // `ai_council.fallback.api_on_quota` off THIS block, so before the key
+        // was forwarded no config file could turn quota fall-through on. The
+        // documentation, the contract section and the tests all described a
+        // switch that production could not flip.
+        fallback: { api_on_quota: cfg.fallback.api_on_quota },
+        necessity_classifier: {
+            enabled: cfg.necessity_classifier.enabled,
+            mode: cfg.necessity_classifier.mode,
+            user_explicit_mode: cfg.necessity_classifier.user_explicit_mode,
+        },
+        model_downgrade: {
+            enabled: cfg.model_downgrade.enabled,
+            auto_apply: cfg.model_downgrade.auto_apply,
+        },
+        debate: {
+            max_cost_usd: cfg.debate.max_cost_usd,
+            cost_disclosure: {
+                mode: cfg.debate.cost_disclosure.mode,
+                threshold_usd: cfg.debate.cost_disclosure.threshold_usd,
+                show_per_member: cfg.debate.cost_disclosure.show_per_member,
+            },
+        },
+        lens_overrides: {
+            necessity_classifier_mode: _mapToObject(
+                cfg.lens_overrides.necessity_classifier_mode,
+            ),
+            necessity_classifier_user_explicit_mode: _mapToObject(
+                cfg.lens_overrides.necessity_classifier_user_explicit_mode,
+            ),
+            model_downgrade: lensModelDowngrade,
+            cost_disclosure: lensCostDisclosure,
+        },
+        members,
+        advisors,
+    };
+}

package/src/scripts/_lib/headless_invocation.ts

@@ -0,0 +1,285 @@
+/**
+ * headless_invocation — the resume command a dead run would be restarted with,
+ * constructed and PRINTED, never executed.
+ *
+ * road-to-long-horizon-execution Phase 4.0, second half. The first half is
+ * `unattended_guard.ts` (the preconditions). This is the seam between the
+ * watcher and a process that does not exist.
+ *
+ * ## The live spawn is a published refusal, not a pending item
+ *
+ * Phase 4.0 shipped the guard and deferred the spawn, and a deferral with no
+ * end condition is the exact defect the roadmap opens with (D-5: "pending,
+ * indefinitely"). The AI council (2026-08-19, anthropic/claude-sonnet-4-5 +
+ * openai/codex-default, blind peer review) split on what to do — build a
+ * dry-run seam, or cancel the capability — and named the SAME defect from both
+ * sides: `run:supervise --relaunch` advertised a capability that did not
+ * exist. The resolution taken, recorded HERE and in the roadmap step rather
+ * than behind a pointer — a decision memo is gitignored, run-scoped and
+ * auto-pruned, so a tracked file resting its rationale on one leaves a reader
+ * with an unreachable citation (R2 round 2, finding 8):
+ *
+ *   The invocation seam SHIPS, print-only. Executing it is refused, and the
+ *   refusal has a falsifiable reopen condition rather than a date.
+ *
+ * ## Why print-only is not a half-measure
+ *
+ * A printed command is the human-in-the-loop shape this suite already commits
+ * to everywhere else — merge stays human, the supervisor may open a PR and
+ * never merges one. An operator reading a digest can paste the line and watch
+ * the run; nothing about that needs a daemon. What a daemon would add is
+ * exactly the part nobody has validated: an auth path, a sandbox posture, and
+ * a process that spends money with nobody watching.
+ *
+ * **There is no `spawn`, `exec` or `fork` in this file, and that is asserted
+ * by a test rather than promised by this comment.**
+ *
+ * Scoped precisely, because the wider reading is false (R2 round 2, finding
+ * 5): what cannot start from here is an AGENT. A plan DOES cause a subprocess
+ * — `planResume` calls `preflight`, which runs `git remote -v` in the target
+ * worktree to answer the production-remote precondition, one per plan. Reading
+ * a git remote is not the capability under refusal, and a claim that "nothing
+ * here runs a process" would be the kind of over-read this module's own
+ * reopen-condition paragraph warns about in the other direction.
+ *
+ * ## Reopen condition — falsifiable, not a date
+ *
+ * The live arm is reconsidered when the watcher has actually had an input:
+ * **the first time `agents/runtime/state/checkpoints/` holds a checkpoint
+ * written by a real dying run.** Measured 2026-08-19 on the main checkout,
+ * that directory does not exist — no session has ever both crossed the
+ * recycle threshold and held a roadmap claim, so the resume path has never
+ * had a single input to resume from. Building an unattended spawn on top of
+ * that is the fourth floor of an untenanted building.
+ *
+ * Stated the other way round so it cannot be over-read: the empty directory
+ * is a CONJUNCTION of two rare conditions, not evidence that sessions never
+ * die with work left. It licenses "do not build the spawn yet". It does not
+ * license "the need does not exist".
+ */
+
+// Both imports resolve inside the shipped tree. They used to reach into
+// `src/cli/python/`, which is NOT in the package.json `files` whitelist, so a
+// global install of this module would have died on ERR_MODULE_NOT_FOUND —
+// caught by `prepack-check`, not by anything local. See `host_launch.ts`.
+import { HOST_INVENTORY, LAUNCH_ARGV } from './host_launch.js';
+import { CHECKPOINT_DIR_REL } from './run_checkpoint.js';
+import { preflight, type PreflightVerdict } from './unattended_guard.js';
+
+/**
+ * Session-register `platform` → `HOST_INVENTORY` key.
+ *
+ * The two vocabularies genuinely differ — a live record carries
+ * `"platform": "claude"` while the inventory keys the same host as
+ * `"claude-code"` — and an unlisted platform resolves to `undefined` rather
+ * than to a guessed binary. Fail-closed, matching `unattended_guard`'s posture
+ * on an unreadable git config: "I do not recognise this host" and "this host
+ * can be driven" must never resolve the same way.
+ */
+export const PLATFORM_TO_HOST: Readonly<Record<string, string>> = Object.freeze({
+    claude: 'claude-code',
+    codex: 'codex',
+    gemini: 'gemini',
+});
+
+/** The prompt a resumed run is started with. */
+export function resumePrompt(roadmapSlug: string): string {
+    return (
+        `Resume the claimed roadmap \`${roadmapSlug}\`. ` +
+        `First act: look the checkpoint up by slug (latestCheckpointFor) and verify it ` +
+        `against the worktree before acting on any of it — resume by evidence, never by ` +
+        `bookkeeping. Then run /roadmap:process-full ${roadmapSlug}.`
+    );
+}
+
+/**
+ * The argv a resume would be launched with, or `null` when the host cannot be
+ * driven headlessly.
+ *
+ * Only Tier-1 hosts from `HOST_INVENTORY` have a documented non-interactive
+ * surface (`docs/contracts/host-agent-protocol.md`); every Tier-3 host is
+ * observe-only and there is nothing to construct. The shape is read off that
+ * contract rather than invented here.
+ */
+export function buildResumeArgv(
+    platform: string,
+    roadmapSlug: string,
+    inventory: Readonly<Record<string, { tier: number; cli: string | null }>> = HOST_INVENTORY,
+    launch: Readonly<Record<string, (prompt: string) => string[]>> = LAUNCH_ARGV,
+): readonly string[] | null {
+    const hostId = PLATFORM_TO_HOST[platform];
+    if (hostId === undefined) return null;
+
+    // The tier check is NOT dead code, and the reason is worth stating because
+    // it looks dead: `PLATFORM_TO_HOST` maps only Tier-1 hosts today, so every
+    // unmapped platform returns above and this guard is currently unreachable.
+    // It is the guard that has to hold the day a host is DEMOTED — an entry
+    // going `tier: 1 -> 3` in `HOST_INVENTORY` while its row here stays — and
+    // that is a one-line edit in a different file with no reason to look here.
+    //
+    // R2 round 2, finding 6 caught the test certifying this guard while
+    // short-circuiting at the mapping and never reaching it. The fix is the
+    // test, not the deletion — hence the injectable `inventory`, which lets a
+    // test demote a mapped host without waiting for a real demotion.
+    const entry = inventory[hostId];
+    if (entry === undefined || entry.tier !== 1 || entry.cli === null) return null;
+
+    // The argv comes from `HOST_CONFIGS`, the config the drive loop actually
+    // executes — never re-derived here.
+    //
+    // R2 round 2, finding 12 flagged that `host-agent-protocol.md`
+    // contradicts itself about gemini (its inventory row reads
+    // `gemini --output-format json` over stdin; a later row reads
+    // `gemini -p … --output-format json`), and it was right that picking a
+    // side silently leaves an auditor at a coin flip. It turned out to be
+    // sharper than a documentation nit: the first version of this function
+    // hand-built BOTH codex and gemini as stdin consumers, and the tree's own
+    // executable configs pass the prompt as an argv member for both. A pasted
+    // command would have piped a prompt into a CLI that was not reading one.
+    //
+    // So the fix is not to choose a row. Prose can contradict itself; the
+    // table the drive loop runs on cannot, and there is no reason for a second
+    // derivation of the same argv to exist. `promptOnStdin` is gone with it —
+    // no supported host takes the prompt on stdin.
+    const build = launch[hostId];
+    if (build === undefined) return null;
+    return build(resumePrompt(roadmapSlug));
+}
+
+/**
+ * The smallest REAL unit of each budget axis, used to probe whether the
+ * unattended lane is open at all.
+ *
+ * One cent and one token — the smallest amounts either axis can actually be
+ * charged. Not a forecast of what a resume costs, which is unknowable before
+ * it runs.
+ *
+ * The first version used `Number.EPSILON`, and a test caught it: EPSILON is
+ * the representable gap at 1.0, so `10 + Number.EPSILON === 10` and an
+ * EXHAUSTED $10/$10 budget read as open. A "smallest positive number" that
+ * disappears under addition at the magnitudes budgets actually use is not a
+ * probe, it is a zero wearing a careful name. A real minimum unit is exact at
+ * those magnitudes and is the smaller claim besides.
+ */
+export const SPEND_PROBE_USD = 0.01;
+export const SPEND_PROBE_TOKENS = 1;
+
+export interface ResumeTarget {
+    readonly roadmapSlug: string;
+    readonly worktree: string;
+    readonly platform: string;
+    /** Commit the resume would start from — the dedup key's second half. */
+    readonly head: string;
+}
+
+export interface ResumePlan {
+    readonly target: ResumeTarget;
+    /** The command a HUMAN can paste, or `null` when the host has no headless surface. */
+    readonly command: string | null;
+    /** Why no command could be built. Empty when `command` is non-null. */
+    readonly hostRefusal: string | null;
+    /**
+     * What an UNATTENDED lane would decide about this same run.
+     *
+     * Reported next to the command and never conflated with it: a human
+     * pasting the command is not the unattended lane, so a budget refusal here
+     * does not mean the operator may not run it. It means nothing may run it
+     * *without* the operator.
+     */
+    readonly unattended: PreflightVerdict;
+}
+
+/** Quote one argv member for a copy-pasteable POSIX shell line. */
+function shQuote(arg: string): string {
+    return /^[A-Za-z0-9_@%+=:,./-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`;
+}
+
+export function planResume(repoRoot: string, target: ResumeTarget, now?: Date): ResumePlan {
+    const argv = buildResumeArgv(target.platform, target.roadmapSlug);
+    const unattended = preflight({
+        repoRoot,
+        worktree: target.worktree,
+        roadmapSlug: target.roadmapSlug,
+        head: target.head,
+        // A resume's cost is NOT knowable before it runs, so this projection
+        // is a probe, not an estimate, and the question it asks is "is the
+        // lane open at all" rather than "would it afford this run".
+        //
+        // The probe is each axis's smallest REAL unit: zero would let a
+        // disabled-by-zero ceiling read as allowed (`checkBudget` refuses a 0
+        // ceiling only against a positive projection), while a
+        // plausible-looking `1` USD would refuse a budget with $0.50 of
+        // headroom and report a closed lane that is open. A made-up cost is
+        // worse than an admittedly minimal one, because only the second is
+        // obviously not a forecast.
+        projectedUsd: SPEND_PROBE_USD,
+        projectedTokens: SPEND_PROBE_TOKENS,
+        ...(now === undefined ? {} : { now }),
+    });
+
+    if (argv === null) {
+        return {
+            target,
+            command: null,
+            hostRefusal:
+                `host: platform '${target.platform}' has no documented headless surface ` +
+                `(docs/contracts/host-agent-protocol.md) — a resume must be started by hand`,
+            unattended,
+        };
+    }
+
+    // Every supported host takes the prompt in argv — the stdin branch this
+    // line used to carry was built on a prose row that the tree's own drive
+    // configs contradict, and it would have piped a prompt into a CLI that was
+    // not reading one (R2 round 2, finding 12).
+    const command = `cd ${shQuote(target.worktree)} && ${argv.map(shQuote).join(' ')}`;
+
+    return { target, command, hostRefusal: null, unattended };
+}
+
+/**
+ * The refusal `run:supervise --relaunch` emits.
+ *
+ * Names a DECISION, never a pending implementation. The wording matters: the
+ * flag used to say "not implemented yet", which is the sentence that makes an
+ * operator wait for a release that is not coming.
+ */
+export const LIVE_SPAWN_REFUSAL =
+    'run:supervise: starting a session unattended is a published refusal, not an unbuilt ' +
+    'feature — road-to-long-horizon-execution 4.0, resolved by AI council 2026-08-19. ' +
+    'Use --print-relaunch for the exact command to run by hand. The refusal is reopened ' +
+    'when a real dying run first writes agents/runtime/state/checkpoints/ — until then the ' +
+    'resume path has never had an input.';
+
+export function renderResumePlans(plans: readonly ResumePlan[]): string {
+    if (plans.length === 0) {
+        return 'run:supervise --print-relaunch: nothing to resume.\n';
+    }
+    const out: string[] = ['run:supervise --print-relaunch · run these by hand:', ''];
+    for (const p of plans) {
+        out.push(`  ${p.target.roadmapSlug}  (${p.target.platform}, head ${p.target.head})`);
+        out.push(p.command === null ? `    REFUSED  ${p.hostRefusal ?? 'no command'}` : `    ${p.command}`);
+        out.push(
+            p.unattended.ok
+                ? '    unattended: an unattended lane would also be permitted to run this'
+                : `    unattended: would be REFUSED — ${p.unattended.refusals.join('; ')}`,
+        );
+        out.push('');
+    }
+    out.push(
+        'The command above is for YOU. The unattended line describes what an automated',
+        'lane would decide about the same run; it never gates what you may run by hand.',
+        '',
+    );
+    return out.join('\n');
+}
+
+/**
+ * Where the reopen condition is measured — re-exported, never re-declared.
+ *
+ * The path already has one owner (`run_checkpoint.ts`). A second literal here
+ * would be a second source of truth for the one directory this module's reopen
+ * condition is written against, which is the way a reopen condition quietly
+ * starts watching a directory nothing writes.
+ */
+export { CHECKPOINT_DIR_REL };

package/src/scripts/_lib/host_launch.ts

@@ -0,0 +1,72 @@
+/**
+ * host_launch — which host agents exist, which can be driven headlessly, and
+ * the exact argv each one is launched with.
+ *
+ * ## Why this file exists, and why HERE
+ *
+ * These two facts used to live under `src/cli/python/` — the inventory in
+ * `workspace_hosts.ts`, the argv in `workspace_drive.ts`'s `HOST_CONFIGS`.
+ * That directory is **not in the package.json `files` whitelist**, so anything
+ * under `src/scripts/` (which IS shipped) that imports from it resolves fine in
+ * this checkout and crashes a global install with `ERR_MODULE_NOT_FOUND`.
+ *
+ * `prepack-check` caught exactly that when `_lib/headless_invocation.ts`
+ * reached across for both constants. The two available answers were to ship
+ * `src/cli/python/` (396 KB, 14 modules including `workspace_secrets` and
+ * `workspace_crypto` — a consumer-facing surface nobody asked to widen) or to
+ * move the ~40 lines the shipped side actually needs. This is the second.
+ *
+ * The dependency is therefore INVERTED rather than duplicated: the shipped
+ * module owns the facts, and the unshipped drive layer imports them back.
+ * Re-deriving them on the shipped side would be a second source of truth for
+ * one host's argv — the defect an R2 round found in `headless_invocation`
+ * itself, where a hand-built copy modelled codex and gemini as stdin consumers
+ * while the real configs pass the prompt in argv.
+ *
+ * ## What stays behind
+ *
+ * Everything with a runtime: the spawn, the timeout, the per-host stdout
+ * parsers, resume-session handling. Those belong to the driver. What moved is
+ * only the declarative part — a table a reader could check against
+ * `docs/contracts/host-agent-protocol.md` by eye.
+ */
+
+export interface InventoryEntry {
+    tier: number;
+    cli: string | null;
+}
+
+/**
+ * Mirrors `docs/contracts/host-agent-protocol.md` § Today's inventory.
+ *
+ * `cli` is the PATH binary that proves the Tier-1 surface is reachable;
+ * Tier-3 hosts have no drivable CLI (`null`). Insertion order matches the
+ * table in the contract, and `tests/test_workspace_hosts.ts` asserts the two
+ * agree — the assertion imports through `workspace_hosts.ts`, which re-exports
+ * this, so the move is invisible to it.
+ */
+export const HOST_INVENTORY: Record<string, InventoryEntry> = {
+    'claude-code': { tier: 1, cli: 'claude' },
+    codex: { tier: 1, cli: 'codex' },
+    gemini: { tier: 1, cli: 'gemini' },
+    augment: { tier: 3, cli: null },
+    cursor: { tier: 3, cli: null },
+    cline: { tier: 3, cli: null },
+    windsurf: { tier: 3, cli: null },
+};
+
+/**
+ * The launch argv per Tier-1 host — one entry, one source of truth.
+ *
+ * **Every supported host takes the prompt in ARGV.** None reads it from
+ * stdin, and that is worth stating because the contract prose said otherwise
+ * for two of the three until 2026-08-19: a consumer that built its own argv
+ * off the prose modelled codex and gemini as stdin consumers and would have
+ * piped a prompt into a CLI that was not reading one. The contract now
+ * describes this table rather than the other way round.
+ */
+export const LAUNCH_ARGV: Readonly<Record<string, (prompt: string) => string[]>> = Object.freeze({
+    'claude-code': (prompt: string) => ['claude', '-p', prompt, '--output-format', 'json'],
+    codex: (prompt: string) => ['codex', 'exec', '--json', prompt],
+    gemini: (prompt: string) => ['gemini', '-p', prompt, '--output-format', 'json'],
+});

package/src/scripts/_lib/map_to_object.ts

@@ -0,0 +1,16 @@
+/**
+ * map_to_object — a `ReadonlyMap` as a plain object.
+ *
+ * Relocated out of `council_cli.ts` unchanged so the settings-block
+ * projection could move with it without importing back into that file (a
+ * cycle). Both call sites now import it from here.
+ */
+export function _mapToObject<V>(m: ReadonlyMap<string, V>): Record<string, V> {
+    const out: Record<string, V> = {};
+    for (const [k, v] of m) {
+        out[k] = v;
+    }
+    return out;
+}
+
+export { _mapToObject as mapToObject };