@event4u/agent-config 9.27.0 → 9.29.0

package/src/scripts/_lib/auto_dispatch.ts

@@ -7,19 +7,24 @@
  * Decides whether a task is delegable to subagents and which
  * `subagent-orchestration` mode fits — with NO per-turn LLM meta-call.
  *
+ * Always-on orchestration (road-to-always-on-orchestration Phase 1): there is
+ * no more `subagents.enabled` / `subagents.auto` setting gating this. The
+ * layer activates on any host reporting a subagent primitive, unless the one
+ * audited incident switch (`emergency.orchestration_halt`) is set.
+ *
  * Contract highlights:
  * - A task is delegable only on an enumerated structural signal.
  * - Trivial tasks below the size floor never delegate.
- * - Ambiguity → `ask` (when `auto == 'ask'`) or in-session, never speculative
- *   spawn.
- * - The activation gate (`enabled`, `auto != off`, `subagent_spawn`) runs
- *   first; any failure short-circuits to in-session.
+ * - A matched signal always DISPATCHES (there is no more ask-before-dispatch
+ *   mode); an AMBIGUOUS verdict (no enumerated signal matched) is always an
+ *   `ask` VERDICT to the user, never a speculative spawn.
+ * - The activation gate (`halted`, `subagent_spawn`) runs first; any failure
+ *   short-circuits to in-session.
  */
 
 /** Minimum task-size estimate (exclusive) below which a task never delegates. */
 export const SIZE_FLOOR = 1;
 
-export type AutoMode = 'off' | 'ask' | 'on';
 export type DispatchMode = 'do-in-steps' | 'do-in-parallel';
 export type DispatchAction = 'dispatch' | 'ask' | 'in-session';
 
@@ -35,10 +40,14 @@ export interface TaskSignals {
     size_estimate: number;
 }
 
-/** Activation inputs resolved from settings + the host-capability manifest. */
+/**
+ * Activation inputs resolved from the emergency incident switch + the
+ * host-capability manifest. No `enabled`/`auto` fields — always-on
+ * orchestration carries no per-layer setting to resolve them from.
+ */
 export interface ActivationInputs {
-    enabled: boolean;
-    auto: AutoMode;
+    /** `emergency.orchestration_halt` — the one audited incident switch. */
+    halted: boolean;
     subagent_spawn: boolean;
 }
 
@@ -59,8 +68,7 @@ function inSession(reason: string): Classification {
  */
 export function classifyTask(signals: TaskSignals, activation: ActivationInputs): Classification {
     // ── Activation gate — any failure short-circuits to in-session ──
-    if (!activation.enabled) return inSession('subagents.enabled is false');
-    if (activation.auto === 'off') return inSession('subagents.auto is off');
+    if (activation.halted) return inSession('emergency.orchestration_halt is set');
     if (!activation.subagent_spawn) return inSession('host has no subagent_spawn primitive');
 
     // ── Size floor — trivial tasks never delegate ──
@@ -82,16 +90,13 @@ export function classifyTask(signals: TaskSignals, activation: ActivationInputs)
     }
 
     if (mode === null) {
-        // No enumerated signal matched → ambiguous. Ask under `ask`, else in-session.
-        if (activation.auto === 'ask') {
-            return { delegable: false, action: 'ask', mode: null, reason: 'no delegable signal — borderline, ask' };
-        }
-        return inSession('no enumerated delegable signal matched');
+        // No enumerated signal matched → ambiguous. Always an `ask` VERDICT —
+        // there is no more setting under which this silently stays in-session.
+        return { delegable: false, action: 'ask', mode: null, reason: 'no delegable signal — borderline, ask' };
     }
 
-    // Matched a signal. Dispatch under `on`, ask under `ask`.
-    const action: DispatchAction = activation.auto === 'on' ? 'dispatch' : 'ask';
-    return { delegable: true, action, mode, reason };
+    // Matched a signal → always dispatch (always-on: no ask-before-dispatch mode).
+    return { delegable: true, action: 'dispatch', mode, reason };
 }
 
 // ── Lookup-class routing (L0 — road-to-lean-agent-init) ──

package/src/scripts/_lib/capsule_trigger.ts

@@ -0,0 +1,124 @@
+/**
+ * Capsule-emission triggers — the two arms Phase 1 compares in shadow
+ * (road-to-worker-generation-recycling).
+ *
+ * Pure, no-I/O. Two candidate answers to "when should a worker hand off?":
+ *
+ *   - **watermark** — cumulative tokens reach `CAPSULE_WATERMARK_FRACTION` of
+ *     the stop-loss budget (`worker_budget.ts`). Cheap, already instrumented,
+ *     and indifferent to whether the worker is still learning anything.
+ *   - **saturation** — novelty per step, by term frequency, falls below a
+ *     threshold. The hypothesis it encodes: a worker near its budget should
+ *     have stopped EARLIER, not summarised harder — a worker that has stopped
+ *     surfacing new terms is done discovering regardless of its token count.
+ *
+ * Deliberately term-frequency only. Embeddings would add a model dependency,
+ * a similarity threshold nobody can defend, and a second thing to explain when
+ * the arm loses — and the arm has to be able to lose cheaply for the shadow
+ * comparison to mean anything.
+ *
+ * NOTHING ACTS ON THESE. Phase 1 logs the step at which each trigger WOULD have
+ * fired and the worker runs to stop-loss exactly as before, so the measurement
+ * is not confounded by the mechanism it is measuring.
+ */
+
+import { CAPSULE_WATERMARK_FRACTION } from './worker_budget.js';
+
+/** Trailing steps averaged before saturation can fire. */
+export const SATURATION_WINDOW = 3;
+/** Mean novelty below this over the window = saturated. */
+export const SATURATION_THRESHOLD = 0.2;
+
+/** One observed worker step. `terms` is whatever the step surfaced — paths, symbols, words. */
+export interface StepObservation {
+    /** Tokens this step consumed (per-step, not cumulative). */
+    tokens: number;
+    /** Terms surfaced by this step. Normalised and deduped internally. */
+    terms: string[];
+}
+
+export interface TriggerComparison {
+    /** Steps observed. */
+    steps: number;
+    /** 1-based step at which the token watermark was crossed; null = never. */
+    watermark_step: number | null;
+    /** 1-based step at which novelty saturated; null = never. */
+    saturation_step: number | null;
+    /** Per-step novelty ratio (new terms / distinct terms in that step). */
+    novelty: number[];
+    /** Cumulative tokens after each step. */
+    cumulative_tokens: number[];
+}
+
+/** Lowercase, strip surrounding punctuation. No stemming — a stemmer is a second thing to defend. */
+function normalise(term: string): string {
+    return term.toLowerCase().replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, '');
+}
+
+function distinctTerms(terms: string[]): Set<string> {
+    const out = new Set<string>();
+    for (const raw of terms) {
+        if (typeof raw !== 'string') continue;
+        const t = normalise(raw);
+        if (t.length > 0) out.add(t);
+    }
+    return out;
+}
+
+/**
+ * Run both arms over an observed step sequence and report where each WOULD
+ * have fired. Both may be null (neither fired) — which is a publishable result,
+ * not a failure of the instrument.
+ */
+export function compareTriggers(steps: StepObservation[], budget: number): TriggerComparison {
+    const watermark = Math.floor(budget * CAPSULE_WATERMARK_FRACTION);
+    const seen = new Set<string>();
+    const novelty: number[] = [];
+    const cumulative_tokens: number[] = [];
+    let cumulative = 0;
+    let watermark_step: number | null = null;
+    let saturation_step: number | null = null;
+
+    for (const [i, step] of steps.entries()) {
+        cumulative += Number.isFinite(step.tokens) ? step.tokens : 0;
+        cumulative_tokens.push(cumulative);
+        if (watermark_step === null && budget > 0 && cumulative >= watermark) {
+            watermark_step = i + 1;
+        }
+
+        const terms = distinctTerms(step.terms ?? []);
+        let fresh = 0;
+        for (const t of terms) {
+            if (!seen.has(t)) {
+                fresh += 1;
+                seen.add(t);
+            }
+        }
+        // A step that surfaced nothing is fully saturated by definition: it
+        // learned nothing. Scoring it as 1.0 ("all new") would let an idle
+        // worker look maximally productive.
+        novelty.push(terms.size === 0 ? 0 : fresh / terms.size);
+
+        if (saturation_step === null && novelty.length >= SATURATION_WINDOW) {
+            const window = novelty.slice(-SATURATION_WINDOW);
+            const mean = window.reduce((a, b) => a + b, 0) / window.length;
+            if (mean < SATURATION_THRESHOLD) saturation_step = i + 1;
+        }
+    }
+
+    return { steps: steps.length, watermark_step, saturation_step, novelty, cumulative_tokens };
+}
+
+/**
+ * Which arm fired first, for the paired comparison in `docs/CLAIMS.md`
+ * (`worker-capsule-trigger-arm`). `null` = neither fired; `'tie'` = same step.
+ */
+export function earlierArm(c: TriggerComparison): 'watermark' | 'saturation' | 'tie' | null {
+    const w = c.watermark_step;
+    const s = c.saturation_step;
+    if (w === null && s === null) return null;
+    if (w === null) return 'saturation';
+    if (s === null) return 'watermark';
+    if (w === s) return 'tie';
+    return w < s ? 'watermark' : 'saturation';
+}

package/src/scripts/_lib/carrier_divergence.ts

@@ -0,0 +1,135 @@
+/**
+ * One definition of "these two carriers deliver the same rule" — shared by the
+ * C-3 reachability harness and the advisory divergence report.
+ *
+ * WHY THIS IS A LIBRARY AND NOT TWO COPIES. Two surfaces need the comparison
+ * and they ask different questions of it. `measure_scope_dedup` asks *how many*
+ * installed twins a byte-identity dedup could skip, anchored on the projection
+ * source. `report_carrier_divergence` asks *which* rules a reader must look at,
+ * anchored on the union of both carriers. The directory walks are legitimately
+ * different; the comparison is not, and a second copy of it is how "differs only
+ * in the ownership stamp" and "differs in body" drift into meaning two things.
+ *
+ * The comparison itself is the load-bearing part, so it is stated once:
+ *
+ *   1. bytes equal                     → `identical`
+ *   2. equal after removing the two
+ *      installer ownership keys        → `provenance-only`
+ *   3. otherwise                       → `body-diff`
+ *
+ * Class 2 exists because `install.ts` stamps `package:` and `source_path:` into
+ * every rule it installs while the in-repo projection stamps nothing, so a
+ * provenance-only difference survives even a perfect version alignment. Keeping
+ * it apart from class 3 is what turns a bare "0 identical twins" into an answer:
+ * `provenanceOnly == shared` means aligning versions would buy nothing, and
+ * `bodyDiff > 0` means the two carriers are delivering different text — the only
+ * class where a reader has to act.
+ *
+ * NOT A LICENCE TO DEDUP. Classifying a pair `provenance-only` says the bodies
+ * match; it does NOT say the rule is safe to drop from one carrier. Byte-identity
+ * remains the dedup predicate, deliberately — see
+ * `agents/settings/contexts/dedup-reachability-refusal.md`, which records that
+ * decision and its five reopen conditions. Nothing here relaxes it.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * The keys `install.ts` adds to every installed rule (`_set_key(fm_lines,
+ * 'package', …)` and `source_path` at install.ts:2733). Removing them is what
+ * separates an installer stamp from a content change.
+ */
+export const OWNERSHIP_KEYS = ['package', 'source_path'] as const;
+
+export type PairVerdict = 'identical' | 'provenance-only' | 'body-diff';
+
+/**
+ * Drop the ownership stamp lines, wherever they appear in the FILE.
+ *
+ * Not scoped to the frontmatter, and the docstring says so because the scope is
+ * wider than the intent. Two reasons it stays this way: `install.ts` writes the
+ * keys without any guarantee about fence position, and `scope_dedup.test.ts`
+ * deliberately pins the fence-less shape (a stamp with no `---` around it) as the
+ * install condition. Residual risk, stated rather than hidden: a rule body that
+ * contains a line literally starting `package:` or `source_path:` — a YAML
+ * example, an indent-free config snippet — has that line removed from both sides,
+ * so a genuine difference confined to such a line would read `provenance-only`
+ * instead of `body-diff`. Measured over the shipped corpus: no rule body carries
+ * one. Re-check that before treating the class as impossible rather than absent.
+ */
+export function stripOwnershipKeys(text: string): string {
+    return text
+        .split('\n')
+        .filter((line) => !OWNERSHIP_KEYS.some((k) => line.startsWith(`${k}:`)))
+        .join('\n');
+}
+
+/**
+ * Compare one rule's two copies.
+ *
+ * Takes buffers rather than paths: the callers already hold them, and a pure
+ * function is what lets both surfaces pin the same three-way split in tests
+ * without a filesystem.
+ */
+export function comparePair(a: Buffer, b: Buffer): PairVerdict {
+    if (a.equals(b)) {
+        return 'identical';
+    }
+    if (stripOwnershipKeys(a.toString('utf-8')) === stripOwnershipKeys(b.toString('utf-8'))) {
+        return 'provenance-only';
+    }
+    return 'body-diff';
+}
+
+export interface RuleDirCensus {
+    files: number;
+    /**
+     * BYTES, not characters — `statSync().size`. The name is kept because every
+     * consumer of this figure (`preamble_byte_census`, `measure_scope_dedup`, the
+     * conformance scan) already divides it by 4 under that name, and one honest
+     * docstring beats a rename that would silently move three published baselines.
+     *
+     * The gap is measured, not assumed: over the 110-rule project tree, 406 502
+     * bytes against 402 823 characters — **0.91 %** overhead from the em-dashes,
+     * arrows and status glyphs the prose uses. So the published token estimate
+     * reads 101 626 where a character basis gives 100 706. Under 1 % and in the
+     * conservative direction for a payload figure, which is why it is documented
+     * rather than repaired; re-measure before quoting it as negligible on a corpus
+     * with more non-ASCII than this one.
+     */
+    chars: number;
+}
+
+/**
+ * How much rule text one carrier delivers.
+ *
+ * `statSync`, not `lstatSync`, on purpose: a project-scope entry is a symlink
+ * into `dist/`, and the bytes the HOST reads are the target's. Measuring the link
+ * would report ~50 bytes per rule and make the whole payload vanish.
+ *
+ * Moved here from `preamble_byte_census` when `conformance_scan` needed it:
+ * that module pulls `yaml` and the cold-start report, and importing a dependency
+ * chain into a bundled CLI path to reach fifteen lines of `statSync` is the wrong
+ * trade. `preamble_byte_census` re-exports this so its own callers are unchanged
+ * and there is still exactly one definition.
+ */
+export function censusRuleDir(dir: string): RuleDirCensus {
+    let files = 0;
+    let chars = 0;
+    let entries: string[];
+    try {
+        entries = fs.readdirSync(dir);
+    } catch {
+        return { files: 0, chars: 0 };
+    }
+    for (const name of entries) {
+        if (!name.endsWith('.md')) continue;
+        try {
+            chars += fs.statSync(path.join(dir, name)).size;
+            files += 1;
+        } catch {
+            // Unreadable entry — skip rather than fail the whole census.
+        }
+    }
+    return { files, chars };
+}

package/src/scripts/_lib/host_capability.ts

@@ -1,9 +1,9 @@
 /**
- * Host-capability manifest normalizer.
+ * Host-capability manifest normalizer + committed capability registry.
  *
- * Pure, no-I/O helper that takes a partial / unknown object (typically the
- * `subagents.host_capabilities` override from `.agent-settings.yml`, or the
- * agent's own host-knowledge object) and returns a fully-populated manifest.
+ * Pure, no-I/O helper that takes a partial / unknown object (an explicit
+ * caller-supplied override, or the agent's own host-knowledge object) and
+ * returns a fully-populated manifest.
  *
  * Contract — see `src/agent-src/contexts/execution/host-capability-manifest.md`:
  *
@@ -11,7 +11,28 @@
  *   have no subagent primitive.
  * - A missing or non-boolean field resolves to `false`, never `true`.
  * - `schema_version` is always forced to `1`.
+ *
+ * `resolveHostCapabilities` (F5, road-to-orchestrator-discipline-carriers)
+ * adds a resolution order in front of the safe default so a fresh install on
+ * a KNOWN host does not ship delegation dead by default:
+ *
+ *   explicit override (wins, whole-object, unchanged semantics) → committed
+ *   registry row for the detected host (`HOST_CAPABILITY_REGISTRY`) →
+ *   `SAFE_DEFAULT` (all false).
+ *
+ * The registry lists only OBSERVED capabilities for a host this repo has
+ * actually measured (see the roadmap's transcript evidence) — never a
+ * speculative entry for a host nobody has verified.
+ *
+ * `probeHostCapabilities` (road-to-always-on-orchestration Phase 1) is the
+ * production entry point as of this change: capability is a FACT about the
+ * host, never a settings decision, so the former `subagents.host_capabilities`
+ * settings override was deleted. `resolveHostCapabilities`'s `override`
+ * parameter stays for back-compat (tests, and any caller that genuinely has a
+ * host-knowledge object of its own) — no production caller passes a
+ * settings-derived value into it any more.
  */
+import process from 'node:process';
 
 /** Resolved host-capability manifest. All booleans, `schema_version` fixed at 1. */
 export interface HostCapabilityManifest {
@@ -20,6 +41,27 @@ export interface HostCapabilityManifest {
     parallel_spawn: boolean;
     status_polling: boolean;
     separate_quota_pool: boolean;
+    /**
+     * Claude Code's experimental multi-instance Agent Teams primitive
+     * (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`). Resolved ONLY by
+     * {@link probeHostCapabilities}'s live environment probe — the registry
+     * and `normalizeHostManifest` never infer it from a host id, because
+     * this repo has not observed the flag's shape on any host, only its
+     * documented existence.
+     */
+    agent_teams: boolean;
+    /**
+     * The host can kill a running worker and spawn a fresh one that continues
+     * the SAME task mid-flight — the primitive worker-generation recycling
+     * needs (road-to-worker-generation-recycling, `blocker: host-worker-respawn`).
+     *
+     * `false` on every host today, deliberately: like `status_polling` and
+     * `separate_quota_pool`, this field is set `true` only once the capability
+     * is OBSERVED on a host, never by inference from the fact that spawning and
+     * killing both exist separately. A host without it degrades to today's
+     * stop-loss behaviour — loudly, never silently.
+     */
+    worker_respawn: boolean;
 }
 
 /** Safe default — unknown host assumes no subagent primitive. */
@@ -29,6 +71,8 @@ const SAFE_DEFAULT: HostCapabilityManifest = {
     parallel_spawn: false,
     status_polling: false,
     separate_quota_pool: false,
+    agent_teams: false,
+    worker_respawn: false,
 };
 
 /** Coerce one field: only a strict boolean `true` survives; everything else is `false`. */
@@ -55,5 +99,101 @@ export function normalizeHostManifest(input: unknown): HostCapabilityManifest {
         parallel_spawn: asBool(src.parallel_spawn),
         status_polling: asBool(src.status_polling),
         separate_quota_pool: asBool(src.separate_quota_pool),
+        agent_teams: asBool(src.agent_teams),
+        worker_respawn: asBool(src.worker_respawn),
     };
 }
+
+/**
+ * Committed registry — known host identifiers → OBSERVED capability sets.
+ *
+ * Keyed by the platform identifier this repo already uses for the same host
+ * across the hook/dispatch layer (`--platform claude`, `platforms['claude']`
+ * in `claude_settings_hooks.ts`, `TOOL_IDS` in `probe_skill_registration.ts`)
+ * — NOT the separate `toolDetection.ts` binary-detection id (`'claude-code'`),
+ * which names a different namespace (installed-CLI presence, not the running
+ * host identity a hook/dispatch envelope carries).
+ *
+ * Each row is partial: an omitted field stays at the `SAFE_DEFAULT` `false`
+ * when the row is applied. Claude Code is the one host this roadmap's
+ * transcript evidence measured spawning and running subagents concurrently
+ * (`Agent` tool dispatch, parallel tool-use blocks); polling and a separate
+ * quota pool were never observed, so they stay `false` — add a field only
+ * once it is itself observed, never by inference.
+ */
+const HOST_CAPABILITY_REGISTRY: Readonly<Record<string, Partial<HostCapabilityManifest>>> = {
+    claude: { subagent_spawn: true, parallel_spawn: true },
+};
+
+/**
+ * Resolve the effective host-capability manifest for `hostId`.
+ *
+ * Resolution order (highest wins), per
+ * `host-capability-manifest.md § Resolution`:
+ *
+ * 1. `override` — the `subagents.host_capabilities` settings value, when
+ *    present as a non-null object. Normalized exactly as {@link normalizeHostManifest}
+ *    always has: a WHOLE-OBJECT override, each field independently coerced,
+ *    a field absent from the override object resolves to `false`. This is
+ *    the pre-existing, unchanged behavior — a present override still wins
+ *    outright over the registry row, it does not merge field-by-field with it.
+ * 2. The committed {@link HOST_CAPABILITY_REGISTRY} row for `hostId`, when no
+ *    override is present and the host is known.
+ * 3. `SAFE_DEFAULT` — unknown `hostId`, or no override and no registry row.
+ *
+ * `hostId` is a caller-supplied identifier (e.g. the same string a hook
+ * envelope's `platform` field carries) — this function does no environment
+ * probing of its own; see `host-capability-manifest.md` for why resolution
+ * stays a per-session, agent/caller-supplied fact rather than a live probe.
+ *
+ * An array override does NOT count as present (F8, review): `typeof [] ===
+ * 'object'` in JS, so a bare `typeof override === 'object'` check let a
+ * stray array reach `normalizeHostManifest`, which reads named properties
+ * off it (`.subagent_spawn`, …) that an array never has — every field
+ * silently coerces to `false`, exactly like an explicit empty-object
+ * override, even though nobody supplied one. An array is not a manifest
+ * shape at all, so it is treated the same as `null`/non-object: fall
+ * through to the registry row.
+ */
+export function resolveHostCapabilities(
+    hostId: string | null | undefined,
+    override?: unknown,
+): HostCapabilityManifest {
+    if (
+        override !== undefined &&
+        override !== null &&
+        typeof override === 'object' &&
+        !Array.isArray(override)
+    ) {
+        return normalizeHostManifest(override);
+    }
+    const row =
+        hostId !== null && hostId !== undefined ? HOST_CAPABILITY_REGISTRY[hostId] : undefined;
+    if (row === undefined) {
+        return { ...SAFE_DEFAULT };
+    }
+    return { ...SAFE_DEFAULT, ...row, schema_version: 1 };
+}
+
+/**
+ * Probe the effective host-capability manifest for `hostId` from OBSERVABLE
+ * FACTS ONLY (road-to-always-on-orchestration Phase 1) — the committed
+ * registry row for the host, merged with a live environment probe. This is
+ * the production entry point: capability is a fact about the host, never a
+ * settings decision, so there is no override parameter here (that stays on
+ * {@link resolveHostCapabilities} for back-compat callers only).
+ *
+ * The one probed fact today: `agent_teams` resolves `true` when
+ * `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` is set (any non-empty value) in the
+ * process environment — the one host fact this repo can observe about Claude
+ * Code's documented-but-unshipped-by-default multi-instance Agent Teams
+ * primitive. A registry row can also carry `agent_teams: true` directly for a
+ * host where it is unconditionally available; the two sources OR together —
+ * a probe never turns a registry-granted capability back off.
+ */
+export function probeHostCapabilities(hostId: string | null | undefined): HostCapabilityManifest {
+    const base = resolveHostCapabilities(hostId);
+    const flag = process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS;
+    const probedAgentTeams = typeof flag === 'string' && flag !== '';
+    return { ...base, agent_teams: base.agent_teams || probedAgentTeams };
+}