@event4u/agent-config 9.29.0 → 9.31.0

package/src/scripts/_lib/agent_settings.ts

@@ -9,6 +9,7 @@
  *
  * Resolution order (deepest wins; user-global is whitelist-filtered only):
  *
+ *   N+1. `src/config/agent-settings.template.yml`     (shipped defaults; base)
  *   N.   `~/.event4u/agent-config/agent-settings.yml` (user-global; whitelist only)
  *   N-1. `<repo-root>/.agent-settings.yml`            (project-wide; all keys)
  *   N-2. `<intermediate-dir>/.agent-settings.yml`     (subsystem-scoped; all keys)
@@ -36,13 +37,22 @@
  * - YAML parse failure / unreadable file → defaults, logged at WARNING.
  * - Missing files → defaults.
  * - No file is ever created or written by this module.
+ *
+ * The template-defaults base ({@link template_defaults}) gives this path the
+ * guarantee the server read path already had: a key absent from every layer
+ * resolves to its shipped default rather than `undefined`. Two sets are
+ * excluded from it — the `settingsCarveOut` keys, whose absence deliberately
+ * means something else, and placeholder-valued leaves the installer fills.
+ * An unreadable template degrades to the pre-existing empty-defaults behaviour.
  */
 import { createRequire } from 'node:module';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import * as user_global_paths from './user_global_paths.js';
+import { carveOutKeys } from '../../shared/settingsCarveOut.js';
 import type * as YamlModule from 'yaml';
 
 // ESM has no `require`; `createRequire(import.meta.url)` restores it so the
@@ -286,7 +296,106 @@ export const MERGEABLE_KEYS: readonly string[] = [
     'knowledge.global_sharing.freshness.stale_after_days',
 ];
 
-const _DEFAULTS: SettingsDict = {};
+/** The shipped template, relative to the package root. */
+const TEMPLATE_RELATIVE = path.join('src', 'config', 'agent-settings.template.yml');
+
+/**
+ * Package root: `src/scripts/_lib/agent_settings.ts` → three levels up.
+ * Same idiom as `cli_wrapper.ts:28`, and it holds in an installed consumer
+ * too because `src/config/` ships (`package.json` `files[]`).
+ */
+const _PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+
+/** Default template path — overridable per call for tests. */
+export function default_template_path(): string {
+    return path.join(_PACKAGE_ROOT, TEMPLATE_RELATIVE);
+}
+
+/**
+ * A leaf whose template value is still an installer placeholder
+ * (`__RULE_LOADING_TIER__`, `__CHAT_HISTORY_FREQUENCY__`, …). The installer
+ * substitutes these from the chosen profile preset; the template alone does
+ * not carry a usable default, so the defaults layer must not inject one.
+ *
+ * Matched by shape rather than against `TEMPLATE_PLACEHOLDER_DEFAULTS`
+ * (`src/server/io/yamlIO.ts:139`) on purpose: the scripts family does not
+ * import from the server family, and a duplicated map would be one more thing
+ * that can drift. A new placeholder is covered the day it is added.
+ */
+function _is_placeholder(value: SettingsValue): boolean {
+    return typeof value === 'string' && /^__[A-Z0-9_]+__$/.test(value);
+}
+
+/**
+ * Prune a parsed template into the tree the defaults layer may contribute:
+ * every placeholder-valued leaf and every carve-out key removed, and any
+ * branch that empties out as a result dropped with them.
+ */
+function _prune_template(tree: SettingsDict, excluded: ReadonlySet<string>, prefix = ''): SettingsDict {
+    const out: SettingsDict = {};
+    for (const [key, value] of Object.entries(tree)) {
+        const dotted = prefix === '' ? key : `${prefix}.${key}`;
+        if (excluded.has(dotted) || _is_placeholder(value)) {
+            continue;
+        }
+        if (_is_plain_dict(value)) {
+            const child = _prune_template(value as SettingsDict, excluded, dotted);
+            if (Object.keys(child).length > 0) {
+                out[key] = child;
+            }
+            continue;
+        }
+        out[key] = value;
+    }
+    return out;
+}
+
+/** Parsed-and-pruned template, memoised for the default path only. */
+let _template_defaults_cache: SettingsDict | null = null;
+
+/**
+ * The template-defaults layer — the base every real settings layer sits on.
+ *
+ * Gives the scripts read path the guarantee the server read path already has:
+ * a key absent from every layer resolves to its shipped default instead of
+ * `undefined`. Two exclusions, both load-bearing:
+ *
+ * - **Carve-out keys** (`src/shared/settingsCarveOut.ts`). For these an absent
+ *   key deliberately resolves to something other than the template default,
+ *   and injecting the default here would flip existing installs — precisely
+ *   the silent narrowing that module exists to prevent (`settingsCarveOut.ts:18-21`).
+ * - **Placeholder-valued leaves**, which carry no default until the installer
+ *   substitutes them.
+ *
+ * Tolerant like the rest of this module: an unreadable or malformed template
+ * yields `{}`, i.e. exactly the pre-existing no-defaults behaviour.
+ *
+ * The result is a full `_deepcopy`, never `_deep_copy_defaults`. The latter is
+ * built on `_deep_merge`, which assigns a nested value by REFERENCE whenever
+ * the destination has no dict at that key — so its "copy" of a fresh `{}`
+ * shares every sub-tree with the source. The caller then merges the real
+ * layers into that shared sub-tree and silently rewrites the cache: the first
+ * settings file read in a process would become the defaults every later read
+ * sees. The predecessor `_DEFAULTS` was `{}`, so the hazard existed but had
+ * nothing to poison; a populated base makes it live.
+ */
+export function template_defaults(template_path?: string): SettingsDict {
+    const use_cache = template_path === undefined;
+    if (use_cache && _template_defaults_cache !== null) {
+        return _deepcopy(_template_defaults_cache);
+    }
+    const parsed = _read_yaml(template_path ?? default_template_path()) ?? {};
+    const pruned = _prune_template(parsed, new Set(carveOutKeys()));
+    if (use_cache) {
+        _template_defaults_cache = pruned;
+    }
+    return _deepcopy(pruned);
+}
+
+/** Drop the memoised template — tests only; production reads it once per process. */
+export function _reset_template_defaults_cache(): void {
+    _template_defaults_cache = null;
+}
 
 /**
  * Defaults applied by `get_modules_config` when a key is absent from both
@@ -730,12 +839,17 @@ export function load_agent_settings(
         user_global_path?: string | null;
         verbose?: boolean;
         cwd?: string | null;
+        template_path?: string | null;
     } = {},
 ): SettingsDict {
     const project_path = options.project_path ?? null;
     const user_global_path = options.user_global_path ?? null;
     const verbose = options.verbose ?? false;
     const cwd = options.cwd ?? null;
+    // Same caller-override contract as `project_path` / `user_global_path`:
+    // a test or tool that pins every other input can pin the defaults base
+    // too, and point it at a nonexistent file to isolate the cascade.
+    const template_path = options.template_path ?? null;
 
     // An explicit path is a caller override (tests, tooling) and stays single;
     // otherwise every user-global file merges in precedence order.
@@ -754,7 +868,10 @@ export function load_agent_settings(
 
     const cascade = _resolve_cascade_paths(cwd, project_path);
 
-    const merged: SettingsDict = _deep_copy_defaults(_DEFAULTS);
+    // Template defaults sit BELOW every real layer — never above one. The
+    // precedence here is the inverse of the server family's, so the order of
+    // these three statements is the whole contract.
+    const merged: SettingsDict = template_defaults(template_path ?? undefined);
     _deep_merge(merged, user_global_filtered);
     for (const p of cascade) {
         const layer = _read_yaml(p) ?? {};

package/src/scripts/_lib/carrier_divergence.ts

@@ -81,6 +81,53 @@ export function comparePair(a: Buffer, b: Buffer): PairVerdict {
     return 'body-diff';
 }
 
+/**
+ * Drop a leading YAML frontmatter block, returning the prose the host actually
+ * delivers.
+ *
+ * A file with no `---` fence, or an unterminated one, is returned unchanged —
+ * the same tolerance `report_carrier_divergence`'s own `type:` reader applies,
+ * because a malformed fence must not silently swallow a rule's whole text.
+ */
+export function stripFrontmatter(text: string): string {
+    if (!text.startsWith('---')) return text;
+    const end = text.indexOf('\n---', 3);
+    if (end === -1) return text;
+    const afterFence = text.indexOf('\n', end + 1);
+    return afterFence === -1 ? '' : text.slice(afterFence + 1);
+}
+
+/**
+ * Do the two copies carry the same governed PROSE, ignoring frontmatter?
+ *
+ * WHY THIS IS SEPARATE FROM `comparePair`, AND MUST STAY SEPARATE
+ * --------------------------------------------------------------
+ * `comparePair` answers *can a byte-identity dedup skip this pair* — it is the
+ * dedup predicate, and a frontmatter difference is a real byte difference, so
+ * folding this in would relax the predicate that
+ * `agents/settings/contexts/dedup-reachability-refusal.md` deliberately keeps
+ * strict. `measure_scope_dedup` asks exactly that question and its arithmetic
+ * stays untouched.
+ *
+ * This answers the different, reader-facing question `report_carrier_divergence`
+ * asks: *must a human act on this pair*. Measured 2026-08-10 over the live
+ * carriers at commit `a5b2f4cb7`: 109 shared rules, **0** byte-identical, **109**
+ * classified `body-diff` — and after this strip, **0** of the 109 differ in
+ * prose. The whole divergence was the metadata block. Reporting that as body
+ * divergence manufactures the one class the report tells a reader to act on,
+ * which is precisely the failure `compareCarriers` already refuses to commit for
+ * an unreadable copy.
+ *
+ * Edge trimming only, on purpose: the frontmatter fence leaves the two sides one
+ * leading newline apart, and that is not a content difference. Internal
+ * whitespace and line endings are NOT normalized — a CRLF-vs-LF body stays a
+ * prose difference, so this stays no softer than the dedup predicate on the text
+ * the host reads.
+ */
+export function proseEqual(a: string, b: string): boolean {
+    return stripFrontmatter(a).trim() === stripFrontmatter(b).trim();
+}
+
 export interface RuleDirCensus {
     files: number;
     /**

package/src/scripts/_lib/judgment_ladder.ts

@@ -37,14 +37,18 @@ import {
 } from './auto_dispatch.js';
 
 /** The five dispatch rungs, or `null` for the silent ∅ (in-session / ask). */
-export type LadderRung = 0 | 1 | 2 | 3 | 4 | null;
+export type LadderRung = 0 | 0.5 | 1 | 2 | 3 | 4 | null;
 
 export type LadderVerdict =
     | 'script' // rung 0 — deterministic transform/primitive, no spawn at all
     | 'subagent' // rung 1/2 — one, or several downshifted, subagent dispatch(es)
     | 'team' // rung 3 — communicating slices, dispatched via the host teams primitive
     | 'council' // rung 4 — contested judgment
-    | 'ask' // ∅ — ambiguous; a VERDICT to the user, never a speculative spawn
+    // 'ask' carries TWO shapes, split by rung (road-to-token-economy-dispatch
+    // Phase 4): rung 0.5 = a bounded question routed to ONE completion via
+    // `ask_transport` (no session, no tools, hard-capped — never the user);
+    // rung null = ambiguity, a VERDICT to the user, never a speculative spawn.
+    | 'ask'
     | 'in-session'; // ∅ — halted, no host primitive, trivial, approval-required, or recursive guard
 
 export interface LadderResult {
@@ -279,6 +283,62 @@ export function detectContestedJudgment(text: string): { matched: boolean; reaso
  * `point-of-action-carrier` blocker already names as its pre-registered
  * null ("no discriminator" is publishable and does not block this roadmap).
  */
+/**
+ * Rung-0.5 signal — a single bounded question (token-economy-dispatch 4.2).
+ *
+ * Deliberately conservative, regex-only (the F3-lite discipline): the cost
+ * of a false NEGATIVE is one avoidable spawn; the cost of a false POSITIVE
+ * is an ask that returns INSUFFICIENT_CONTEXT and gets escalated — which the
+ * registered `ask_economy` kill criterion counts against the rung. So every
+ * ambiguity falls through (no match), and four hard exclusions apply:
+ *
+ *   1. Multi-line prompts — a bounded question is one sentence.
+ *   2. Length > 240 chars — beyond that it is a briefing, not a question.
+ *   3. Imperative work verbs (fix/implement/write/…) — those are tasks.
+ *   4. No interrogative shape — must lead with an interrogative (EN/DE) and
+ *      end with `?`, OR be an explicit classify/categorize instruction
+ *      (the one imperative the roadmap names as ask-shaped).
+ */
+const _QUESTION_IMPERATIVE_RE =
+    /\b(fix|implement|refactor|build|create|write|add|update|delete|remove|rename|migrate|install|deploy|commit|push|merge|run|execute|generate|erstelle|baue|implementiere|schreibe|behebe)\b/i;
+const _QUESTION_LEAD_RE =
+    /^(is|are|does|do|did|can|could|should|would|will|which|what|why|how|when|where|who|whose|ist|sind|hat|haben|kann|welche[rs]?|was|warum|wie|wann|wo|wer)\b/i;
+const _CLASSIFY_LEAD_RE = /^(classify|categori[sz]e|klassifiziere)\b/i;
+const _QUESTION_MAX_LEN = 240;
+
+/** A question that names a file/repo object or a concrete path needs TOOLS —
+ *  a blind completion cannot read it, so it is never ask-shaped. */
+const _NEEDS_TOOLS_RE =
+    /\b(this|the|that|my|our)\s+(?:[\w-]+\s+){0,2}?(file|files|codebase|repo|repository|transcript|log|logs|diff|document|branch|pr|route|routes|schema|module|class|function|endpoint|test|tests)\b|[\w.-]+\/[\w.-]+|\b[\w-]+\.(ts|js|py|php|md|json|yaml|yml|sh|go|rs)\b/i;
+
+export function detectBoundedQuestion(taskText: string): { matched: boolean; reason: string } {
+    const text = taskText.trim();
+    if (!text || text.length > _QUESTION_MAX_LEN || text.includes('\n')) {
+        return { matched: false, reason: 'not-bounded' };
+    }
+    if (_NEEDS_TOOLS_RE.test(text)) {
+        return { matched: false, reason: 'references-tool-requiring-objects' };
+    }
+    // Classify-lead first: its PAYLOAD may quote work verbs ("classify this
+    // error: ETIMEDOUT on push") without being a work instruction itself.
+    if (_CLASSIFY_LEAD_RE.test(text)) {
+        return {
+            matched: true,
+            reason: 'bounded-question (classification) — rung-0.5 single completion via ask_transport, no session',
+        };
+    }
+    if (_QUESTION_IMPERATIVE_RE.test(text)) {
+        return { matched: false, reason: 'imperative-work-verb' };
+    }
+    if (_QUESTION_LEAD_RE.test(text) && text.endsWith('?')) {
+        return {
+            matched: true,
+            reason: 'bounded-question — rung-0.5 single completion via ask_transport, no session',
+        };
+    }
+    return { matched: false, reason: 'no-interrogative-shape' };
+}
+
 export function classifyLadder(inp: LadderInputs): LadderResult {
     if (inp.interactiveApprovalRequired === true) {
         return {
@@ -362,6 +422,18 @@ export function classifyLadder(inp: LadderInputs): LadderResult {
     // regex and dispatched a subagent anyway, silently bypassing the floor
     // `classifyTask` had just enforced one line above.
     if (inp.signals.size_estimate <= SIZE_FLOOR) {
+        // Rung 0.5 (token-economy-dispatch 4.2) — a SELF-CONTAINED bounded
+        // question below the floor is the one below-spawn shape with its own
+        // routing verdict: one completion via ask_transport (no session, no
+        // tools, hard-capped). This is an ORCHESTRATOR-facing routing datum —
+        // the delegation-nudge carrier deliberately stays silent on it (a
+        // user's question is answered in-session at zero marginal cost; see
+        // classifyPrompt). Questions referencing files/paths are excluded by
+        // the detector: a completion without tools cannot read them.
+        const question = detectBoundedQuestion(inp.taskText);
+        if (question.matched) {
+            return { rung: 0.5, verdict: 'ask', reason: question.reason };
+        }
         return {
             rung: null,
             verdict: classification.action === 'ask' ? 'ask' : 'in-session',
@@ -380,3 +452,183 @@ export function classifyLadder(inp: LadderInputs): LadderResult {
         reason: classification.reason,
     };
 }
+
+// ── Explanation trail (additive — Phase 4.1, road-to-feedback-9-29) ──────
+//
+// `classifyLadder` short-circuits on the first rung that resolves, so its
+// minimal `{rung, verdict, reason}` return cannot answer "why NOT team /
+// why NOT council / why no spawn". This layer answers exactly that without
+// touching the minimal shape current callers depend on: the result is taken
+// from `classifyLadder` itself (never re-derived, so the two can never
+// disagree on the headline), and the per-rung trail is reconstructed from
+// the SAME exported pure detectors and gate fields the resolver reads, in
+// the same fixed priority order.
+
+export type RungStatus = 'taken' | 'rejected' | 'not-reached';
+
+export interface RungEvaluation {
+    rung: 0 | 0.5 | 1 | 2 | 3 | 4;
+    /** The verdict this rung resolves to when taken. */
+    resolves_to: 'script' | 'ask' | 'subagent' | 'team' | 'council';
+    status: RungStatus;
+    reason: string;
+}
+
+export interface LadderExplanation {
+    /** The authoritative resolution — exactly `classifyLadder(inp)`. */
+    result: LadderResult;
+    /**
+     * Per-rung trail in the resolver's fixed priority order: 0, 4, 3, 2, 0.5, 1.
+     *
+     * 0.5 sits where the resolver checks it — inside the size-floor branch,
+     * after rung 2's verdict and before rung 1 — not where its number would
+     * sort. The order IS the contract, so the trail follows the walk.
+     */
+    trail: RungEvaluation[];
+    /** Present only when `result.rung` is null (∅) — the why-no-spawn reason. */
+    no_spawn_reason?: string;
+}
+
+/**
+ * Explain one ladder resolution: the rung taken, every rung genuinely
+ * evaluated-and-rejected (with the detector's own reason), and rungs the
+ * short-circuit never reached (marked `not-reached`, never given a
+ * fabricated rejection reason — a lower rung's detector might well have
+ * matched had it been consulted).
+ */
+export function explainLadder(inp: LadderInputs): LadderExplanation {
+    const result = classifyLadder(inp);
+    const trail: RungEvaluation[] = [];
+    const approval = inp.interactiveApprovalRequired === true;
+
+    // Rung 0 — evaluated first, exempt from the guards below.
+    if (result.rung === 0) {
+        trail.push({ rung: 0, resolves_to: 'script', status: 'taken', reason: result.reason });
+    } else if (approval) {
+        trail.push({
+            rung: 0,
+            resolves_to: 'script',
+            status: 'not-reached',
+            reason: 'interactive-approval-required resolves before every rung',
+        });
+    } else {
+        const lookup = classifyLookup(inp.taskText);
+        const mechanical = detectMechanicalTransform(inp.taskText);
+        trail.push({ rung: 0, resolves_to: 'script', status: 'rejected', reason: `${lookup.reason}; ${mechanical.reason}` });
+    }
+
+    // A gate that resolved ∅ before rung 4 blocks rungs 4-1 wholesale; a
+    // resolution at rung 0 means they were never consulted either.
+    const gate: string | null = approval
+        ? 'interactive-approval-required — caller-stated, resolves ∅'
+        : result.rung === 0
+          ? 'resolved at rung 0'
+          : inp.insideSubagentSession === true
+            ? 'recursive-dispatch guard — running inside a subagent/teammate session'
+            : inp.activation.halted
+              ? 'emergency.orchestration_halt is set'
+              : !inp.activation.subagent_spawn
+                ? 'host has no subagent_spawn primitive'
+                : null;
+
+    const notReached = (why: string): string => `not evaluated — ${why}`;
+
+    // Rung 4 — council.
+    if (gate !== null) {
+        trail.push({ rung: 4, resolves_to: 'council', status: 'not-reached', reason: notReached(gate) });
+    } else if (result.rung === 4) {
+        trail.push({ rung: 4, resolves_to: 'council', status: 'taken', reason: result.reason });
+    } else {
+        trail.push({ rung: 4, resolves_to: 'council', status: 'rejected', reason: detectContestedJudgment(inp.taskText).reason });
+    }
+
+    // Rung 3 — team.
+    if (gate !== null) {
+        trail.push({ rung: 3, resolves_to: 'team', status: 'not-reached', reason: notReached(gate) });
+    } else if (result.rung === 4) {
+        trail.push({ rung: 3, resolves_to: 'team', status: 'not-reached', reason: notReached('resolved at rung 4') });
+    } else if (result.rung === 3) {
+        trail.push({ rung: 3, resolves_to: 'team', status: 'taken', reason: result.reason });
+    } else {
+        const communication = detectCommunicationNeed(inp.taskText);
+        const reason =
+            communication.matched && result.degraded_from === 3
+                ? `${communication.reason} — but host reports agent_teams: false, degraded (see resolved rung)`
+                : communication.reason;
+        trail.push({ rung: 3, resolves_to: 'team', status: 'rejected', reason });
+    }
+
+    // Rungs 2 and 1 — classifyTask's verdict, then the single-slice check.
+    const resolvedAbove = result.rung === 4 || result.rung === 3;
+    if (gate !== null || resolvedAbove) {
+        const why = gate ?? `resolved at rung ${result.rung}`;
+        trail.push({ rung: 2, resolves_to: 'subagent', status: 'not-reached', reason: notReached(why) });
+        trail.push({ rung: 0.5, resolves_to: 'ask', status: 'not-reached', reason: notReached(why) });
+        trail.push({ rung: 1, resolves_to: 'subagent', status: 'not-reached', reason: notReached(why) });
+    } else {
+        const classification = classifyTask(inp.signals, inp.activation);
+        if (result.rung === 2) {
+            trail.push({ rung: 2, resolves_to: 'subagent', status: 'taken', reason: result.reason });
+            trail.push({ rung: 0.5, resolves_to: 'ask', status: 'not-reached', reason: notReached('resolved at rung 2') });
+            trail.push({ rung: 1, resolves_to: 'subagent', status: 'not-reached', reason: notReached('resolved at rung 2') });
+        } else {
+            trail.push({ rung: 2, resolves_to: 'subagent', status: 'rejected', reason: classification.reason });
+            if (result.rung === 1) {
+                trail.push({
+                    rung: 0.5,
+                    resolves_to: 'ask',
+                    status: 'not-reached',
+                    reason: notReached(`task above the size floor (${inp.signals.size_estimate} > ${SIZE_FLOOR}) — rung 0.5 is reachable only below it`),
+                });
+                trail.push({ rung: 1, resolves_to: 'subagent', status: 'taken', reason: result.reason });
+            } else if (result.degraded_from === 3) {
+                // The communication branch returns from INSIDE rung 3's handling
+                // (its `classifyTask` fallback is the rung-2 attempt), so it exits
+                // before `detectBoundedReadHeavySlice` is ever called. Reporting
+                // rung 1 as `rejected` here quoted that detector's reason — and
+                // when the detector MATCHES, that reason describes a match, so
+                // the trail read "rejected: one lite-tier subagent instead of
+                // session-context burn". A maintainer asking why nothing spawned
+                // was told rung 1 declined, hiding the missing agent_teams
+                // capability that actually ended the walk.
+                const skipped = notReached('the rung-3 communication branch resolved before it was consulted');
+                trail.push({ rung: 0.5, resolves_to: 'ask', status: 'not-reached', reason: skipped });
+                trail.push({ rung: 1, resolves_to: 'subagent', status: 'not-reached', reason: skipped });
+            } else if (inp.signals.size_estimate <= SIZE_FLOOR) {
+                // Rung 0.5 lives INSIDE the resolver's floor branch, between rung
+                // 2 and rung 1, so it is reachable only here. Emitting it in that
+                // position keeps the trail's order the resolver's order; omitting
+                // it (as this trail did before the rung landed) would report a
+                // walk that skipped a rung the resolver actually consulted.
+                if (result.rung === 0.5) {
+                    trail.push({ rung: 0.5, resolves_to: 'ask', status: 'taken', reason: result.reason });
+                } else {
+                    trail.push({
+                        rung: 0.5,
+                        resolves_to: 'ask',
+                        status: 'rejected',
+                        reason: detectBoundedQuestion(inp.taskText).reason,
+                    });
+                }
+                trail.push({
+                    rung: 1,
+                    resolves_to: 'subagent',
+                    status: 'rejected',
+                    reason: `task below size floor (${inp.signals.size_estimate} <= ${SIZE_FLOOR}) — rung 1 never bypasses the floor`,
+                });
+            } else {
+                // Above the floor the resolver never enters the branch rung 0.5
+                // lives in, so it was not consulted — not declined.
+                trail.push({
+                    rung: 0.5,
+                    resolves_to: 'ask',
+                    status: 'not-reached',
+                    reason: notReached(`task above the size floor (${inp.signals.size_estimate} > ${SIZE_FLOOR}) — rung 0.5 is reachable only below it`),
+                });
+                trail.push({ rung: 1, resolves_to: 'subagent', status: 'rejected', reason: detectBoundedReadHeavySlice(inp.taskText).reason });
+            }
+        }
+    }
+
+    return result.rung === null ? { result, trail, no_spawn_reason: result.reason } : { result, trail };
+}

package/src/scripts/_lib/orchestration_record.ts

@@ -19,8 +19,10 @@
 import type { LookupClass } from './auto_dispatch.js';
 
 export type DispatchOutcome = 'DONE' | 'DONE_WITH_CONCERNS' | 'NEEDS_CONTEXT' | 'BLOCKED' | 'killed';
-/** Which route the lookup-class rung took (lean-init L0). */
-export type RouteTaken = 'primitive' | 'subagent';
+/** Which route the rung took: deterministic primitive (lean-init L0),
+ *  single-completion ask (token-economy-dispatch rung 0.5), or a full
+ *  subagent spawn. */
+export type RouteTaken = 'primitive' | 'subagent' | 'ask';
 export type VerifyMode = 'deterministic' | 'judge' | 'none';
 export type Provenance = 'measured' | 'estimated';
 export type TierChosen = 'lite' | 'medium' | 'high';
@@ -98,6 +100,23 @@ export interface RecordInput {
     /** Rules the worker actually applied/cited (count of the envelope's
      *  `rules_applied`-equivalent on the worker side). Counts only. */
     rules_used?: number | null | undefined;
+    // ── dispatch-economy additive fields (road-to-token-economy-dispatch
+    //    Phase 1.1). `init_tokens` above (lean-init) is the spawn-payload
+    //    half; `work_tokens` is the delta from first worker turn to envelope
+    //    close. Both are counts; the pair's provenance rides
+    //    `floor_provenance` exactly like `token_delta_provenance` tags
+    //    `token_delta`. ──
+    /** Tokens the worker consumed AFTER init (delta to envelope close). */
+    work_tokens?: number | null | undefined;
+    /** Chars the dispatch RETURNED into the orchestrator context (serialized
+     *  tool-result length on sync completions) — the Phase 6.3 detector for
+     *  "isolation win refunded through the return channel". A count, never
+     *  content. */
+    return_channel_chars?: number | null | undefined;
+    /** Provenance of the init/work pair: 'measured' (transcript ledger via
+     *  cc_transcript) or 'estimated'. Defaults to 'estimated' when either
+     *  field is present without a tag. */
+    floor_provenance?: Provenance | null | undefined;
     // ── capsule shadow-measurement fields (road-to-worker-generation-recycling
     //    Phase 1.2). SHADOW ONLY: the worker still runs to stop-loss, nothing
     //    reads a capsule. All counts / enums — a capsule's CONTENT never
@@ -138,7 +157,7 @@ const TIER_SOURCES: readonly TierSource[] = ['static', 'inferred', 'inherit'];
 const BANDS: readonly Band[] = ['low', 'medium', 'high'];
 const PHASES: readonly LinePhase[] = ['refine', 'memory', 'analyze', 'plan', 'implement', 'test', 'verify', 'report'];
 const LOOKUP_CLASSES: readonly LookupClass[] = ['definition', 'references', 'string-existence', 'report-run'];
-const ROUTES_TAKEN: readonly RouteTaken[] = ['primitive', 'subagent'];
+const ROUTES_TAKEN: readonly RouteTaken[] = ['primitive', 'subagent', 'ask'];
 const TRIGGER_ARMS: readonly TriggerArm[] = ['watermark', 'saturation', 'tie'];
 /** Hex-only payload hash — a hash can never smuggle content (privacy by construction). */
 const PAYLOAD_HASH_RE = /^[a-f0-9]{8,64}$/i;
@@ -164,13 +183,15 @@ function isInt(n: unknown): n is number {
 export function buildOrchestrationLine(input: RecordInput): BuiltLine {
     const errors: string[] = [];
 
-    // A lookup-class primitive route is the ONE recordable zero-spawn event
-    // (lean-init L0): the routing decision itself is the datum the
-    // cost-reduction claim reads. Everything else with spawn_count 0 stays
-    // unrecordable in-session work.
-    const zeroSpawnPrimitive = input.route_taken === 'primitive' && input.spawn_count === 0;
-    if (!zeroSpawnPrimitive && (!isInt(input.spawn_count) || input.spawn_count < 1)) {
-        errors.push('spawn_count must be an integer ≥ 1 (0 = handled in-session, not a dispatch — do not record; exception: route_taken=primitive lookup routes record with spawn_count 0)');
+    // A lookup-class primitive route (lean-init L0) and a rung-0.5 ask route
+    // (token-economy-dispatch Phase 4) are the TWO recordable zero-spawn
+    // events: the routing decision itself is the datum the cost-reduction
+    // claim reads. Everything else with spawn_count 0 stays unrecordable
+    // in-session work.
+    const zeroSpawnRoute =
+        (input.route_taken === 'primitive' || input.route_taken === 'ask') && input.spawn_count === 0;
+    if (!zeroSpawnRoute && (!isInt(input.spawn_count) || input.spawn_count < 1)) {
+        errors.push('spawn_count must be an integer ≥ 1 (0 = handled in-session, not a dispatch — do not record; exception: route_taken=primitive|ask routes record with spawn_count 0)');
     }
     if (!isInt(input.token_delta)) errors.push('token_delta must be an integer (negative = net saved vs the in-session baseline)');
     if (input.task_size_estimate !== undefined && (!isInt(input.task_size_estimate) || input.task_size_estimate < 0)) {
@@ -239,9 +260,14 @@ export function buildOrchestrationLine(input: RecordInput): BuiltLine {
     for (const [key, v] of [
         ['rules_carried', input.rules_carried],
         ['rules_used', input.rules_used],
+        ['work_tokens', input.work_tokens],
+        ['return_channel_chars', input.return_channel_chars],
     ] as const) {
         if (v != null && (!isInt(v) || v < 0)) errors.push(`${key} must be a non-negative integer count`);
     }
+    if (input.floor_provenance != null && !PROVENANCES.includes(input.floor_provenance)) {
+        errors.push(`floor_provenance must be one of ${PROVENANCES.join(' | ')} (or omitted)`);
+    }
     if (
         input.rules_carried != null &&
         input.rules_used != null &&
@@ -298,6 +324,11 @@ export function buildOrchestrationLine(input: RecordInput): BuiltLine {
         origin: input.origin ?? null,
         rules_carried: input.rules_carried ?? null,
         rules_used: input.rules_used ?? null,
+        // dispatch-economy additive fields — readers ignore unknowns per audit-log-v1
+        work_tokens: input.work_tokens ?? null,
+        return_channel_chars: input.return_channel_chars ?? null,
+        floor_provenance:
+            input.floor_provenance ?? (input.init_tokens != null || input.work_tokens != null ? 'estimated' : null),
         // capsule shadow-measurement — readers ignore unknowns per audit-log-v1
         capsule_emitted: input.capsule_emitted ?? null,
         capsule_entries: input.capsule_entries ?? null,

package/src/scripts/_lib/recycle_envelope_paths.ts

@@ -0,0 +1,35 @@
+/**
+ * Recycle-envelope filesystem contract (road-to-token-economy-recycling
+ * Phase 2.2/2.3) — the ONE place the producer (`session:recycle`) and the
+ * consumer (`handoff_context_hook`) agree on where the envelope lives and
+ * when it is stale. A second copy of any of these values is the drift seam
+ * Risk 6 warns about.
+ */
+import * as path from 'node:path';
+
+/** Where `session:recycle` writes the pending envelope (gitignored runtime state). */
+export const RECYCLE_ENVELOPE_REL = path.join('agents', 'runtime', 'state', 'recycle-envelope.json');
+
+/**
+ * Where the consumer MOVES the envelope on consumption — moved, not copied,
+ * so a consumed or rejected envelope can never leak into a later session,
+ * while the last one stays inspectable for debugging.
+ */
+export const RECYCLE_CONSUMED_REL = path.join(
+    'agents',
+    'runtime',
+    'state',
+    'recycle-envelope.consumed.json',
+);
+
+/** Staleness guard — mirrors the handoff file's 48 h discipline. */
+export const RECYCLE_MAX_AGE_HOURS = 48;
+
+/**
+ * Producer-side size cap on the serialized envelope. The schema's per-field
+ * caps make a transcript-shaped envelope invalid; this cap keeps even a
+ * legal envelope inside the `handoff-context` injection budget
+ * (`src/config/hook-token-budget.json`: 8192 B for the concern) with room
+ * for the wrapper block and a co-pending handoff.
+ */
+export const RECYCLE_ENVELOPE_MAX_BYTES = 6144;