@event4u/agent-config 9.29.0 → 9.31.0

package/src/config/hook-token-budget.json

@@ -0,0 +1,91 @@
+{
+    "_comment": "Pre-registered hook-INJECTION byte budget (road-to-token-economy-cache Phase 3) — the latency file's twin: same discipline, different unit. Committed BEFORE any trimming lands; the budget is the acceptance bar, not a post-hoc fit. Bytes, not tokens, as the deterministic CI unit (no tokenizer dependency — roadmap non-goal 7.6); token-exact numbers appear only in ledger-based telemetry. Consumed by scripts/bench_hook_injection and its CI gate: a concern whose measured emission (reason + additional_context + context bytes) exceeds its row fails the build, and an EMITTING concern with no row fails the build — a new injector cannot ship without a budget row.",
+    "schema_version": 1,
+    "registered_at": "2026-08-10",
+    "owner": "maintainer",
+    "review_by": "2026-11-10",
+    "unit": "bytes of concern stdout payload fields (reason + additional_context + context) per fire",
+    "default_cap_bytes": 1024,
+    "per_concern_caps_bytes": {
+        "_comment": "Named exceptions above the default, each with its reason. Absent concern = default_cap_bytes.",
+        "hot-context": 4096,
+        "hot-context_reason": "400-word working-memory restore, session_start only — one-shot, not per-turn",
+        "handoff-context": 8192,
+        "handoff-context_reason": "consume-once handoff injection, deleted after delivery — the one legitimately large one-shot",
+        "session-canary": 2048,
+        "session-canary_reason": "full canary contract once at session_start; the per-turn beat is one line",
+        "language-mirror": 2048,
+        "language-mirror_reason": "the measured 626-wrong-turn failure class justifies a full-paragraph pin per turn",
+        "council-availability": 1536,
+        "council-availability_reason": "session_start availability block incl. resolved path + member list",
+        "session-register": 2048,
+        "session-register_reason": "collision listing scales with live sessions; capped, not unbounded",
+        "chat-history": 4096,
+        "chat-history_reason": "session_start restore block",
+        "edit-shape": 1024,
+        "edit-shape_reason": "one advisory line naming the cheaper edit primitive (roadmap 5.2: budget row from day one - the economy nudge must not itself become an economy problem)",
+        "reread-guard": 1024,
+        "reread-guard_reason": "one advisory line naming the earlier read / ranged alternative (roadmap 6.1)",
+        "session-eol": 1024,
+        "session-eol_reason": "one recycle-advisory line, once per session past the committed threshold (road-to-token-economy-recycling 3.2); recording itself emits nothing"
+    },
+    "per_slot_sum_caps_bytes": {
+        "_comment": "Cross-concern per-fire sum per slot (roadmap 3.1). session_start is one-time and may carry the restore payloads; per-turn slots stay tight.",
+        "session_start": 16384,
+        "user_prompt_submit": 4096,
+        "pre_tool_use": 2048,
+        "post_tool_use": 2048,
+        "stop": 2048,
+        "session_end": 1024,
+        "pre_compact": 2048,
+        "agent_error": 1024
+    },
+    "injection_load_metric": {
+        "definition": "Roadmap 3.4: total injected bytes per session and per turn, hook-carried. The census mode of bench_hook_injection (--record) appends counts-only lines to agents/runtime/state/injection-census.jsonl; the caps above are the thresholds; breach trend at review date decides tighten vs relax — by evidence, in a PR. The census is also the repeat-injection-census blocker's instrument (one instrumented week ranks the repeaters for the 3.3 idempotency gate).",
+        "privacy": "census lines carry {ts, slot, concern, bytes} — counts and ids only, never content"
+    },
+    "honest_null_consequence": "If real-session census data shows the caps are systematically wrong (either direction), the caps move by evidence in a PR at review date — never silently. A budget nobody benches is the fossilization failure this file's latency twin avoided via its CI harness; bench_hook_injection is wired into the same pipeline in the same phase.",
+    "advisory_adoption_metrics": {
+        "_comment": "Roadmap 5.3 + 6.4 registrations. These are BEHAVIOUR metrics (advisory adoption), not injection bytes - registered here because this file already carries the owner/review discipline for the same concerns.",
+        "owner": "maintainer",
+        "review_by": "2026-11-10",
+        "full_rewrite_small_diff_rate": {
+            "definition": "edit-shape fires / Write calls per session (the full-rewrite-with-small-diff rate). Kill criterion per the shipped nudge standard: a nudge whose verdicts are measurably ignored (adoption near zero over the review window, from conformance audits) gets its trigger tightened or the injected line removed.",
+            "instrument": "rule-trips.json warn counters (the dispatcher already counts every warn per concern) + conformance audits for adoption"
+        },
+        "duplicate_read_rate": {
+            "definition": "reread-guard fires / Read calls per session; re-read advisory adoption via conformance audits. Same kill standard.",
+            "instrument": "rule-trips.json warn counters per concern"
+        },
+        "unbounded_output_advisory_rate": {
+            "definition": "Roadmap 4.3 + 4.4 registration (advisory-degraded per the resolved pretooluse-rewrite-semantics blocker: no updatedInput in the v1 contract, so nothing caps and nothing can be bypassed - the demand signal is the fire count itself). rtk-wrap cap-advisory fires per session from the OUTPUT_CAP_TABLE branch; adoption (did the next run use a bounded form) via conformance audits. HONEST GAP: bytes-into-context from tool RESULTS is not instrumented anywhere (the census covers hook payloads only) - the pre/post bytes half of roadmap 4.4 is registered as unmeasurable until a tool-result byte counter exists.",
+            "instrument": "rule-trips.json warn counters for the rtk-wrap concern + conformance audits",
+            "threshold": "none committed before data - baseline first, threshold at review date"
+        },
+        "turns_per_task": {
+            "definition": "user_prompt_submit count keyed to the task envelope - the invisible multiplier (every turn re-pays the accumulated context at read rates).",
+            "instrument": "session-register / chat-history turn counters; HONEST GAP: no task-envelope key exists yet in those counters - the number is per-SESSION until a task key ships; registered with that stated limitation rather than silently redefined",
+            "threshold": "none committed before data - baseline first, threshold at review date"
+        },
+        "recycle_advisory_adoption": {
+            "definition": "road-to-token-economy-recycling 3.4: of the sessions where the session-eol recycle advisory fired, the share that actually recycled (a recycle-envelope.consumed.json produced by a successor session start). Kill standard as for the sibling nudges: adoption near zero over the review window means the advisory line is dead weight - tighten the trigger or remove the line.",
+            "instrument": "rule-trips.json warn counters for the session-eol concern (fires) + presence/turnover of agents/runtime/state/recycle-envelope.consumed.json and session-eol per-session state (recycles); conformance audits for the denominator detail",
+            "threshold": "none committed before data - baseline first, threshold at review date (2026-11-10)"
+        },
+        "auto_compact_incidence": {
+            "definition": "road-to-token-economy-recycling 3.4: sessions with >=1 auto compact_boundary event / all sessions, from the session-eol per-session counters (baseline: 11.2%, 23/205 sessions - agents/evidence/analysis/token-economy-recycling-phase1.md). TARGET DIRECTION: trends toward zero as recycle adoption rises; a flat or rising incidence with rising adoption falsifies the mechanism.",
+            "instrument": "session-eol state files (compactions[] counters) aggregated by session_eol_report; the marker-drift alarm in the same report guards the detector against silent host shape changes",
+            "threshold": "baseline 11.2%; direction-only target (down) until the review date"
+        },
+        "envelope_resume_success": {
+            "definition": "road-to-token-economy-recycling 3.4: successor sessions that completed the recycled task WITHOUT re-asking for state the envelope should have carried - i.e. the 2.1 not_carried_forward list staying honest (everything else was carried; the successor re-derived only what the list named).",
+            "instrument": "conformance audits over successor-session transcripts (the consumed envelope names the task; the audit checks the successor's first turns for state re-asks); HONEST GAP: no deterministic counter exists for 'had to re-ask' - this is audit-carried and registered as such",
+            "threshold": "none committed before data - baseline first, threshold at review date"
+        },
+        "post_recycle_verify_fail_vs_baseline": {
+            "definition": "road-to-token-economy-recycling 3.4, the falsifiable core: verify-fail rate of recycled successor sessions vs the long-session baseline. PUBLISH-IF-WORSE COMMITMENT, pre-registered before data exists: if recycled sessions verify WORSE, the result is published and the threshold (recycle-threshold-budget.json) or the envelope schema revises in a PR citing the numbers - the claim never survives on vibes.",
+            "instrument": "session-eol per-session state (recycled or not) joined with verify outcomes from conformance audits / review_skipped telemetry; HONEST GAP: transcripts carry no verify-outcome field, so the join is audit-carried until a verify-outcome counter ships",
+            "threshold": "comparison metric - no absolute threshold; verdict recorded at review date whichever way it went"
+        }
+    }
+}

package/src/config/pack-size-budget.json

@@ -7,9 +7,10 @@
     "measurement_conditions": "npm pack --dry-run --json --ignore-scripts, run at the repo root on a clean checkout. `--ignore-scripts` means NO build runs, so dist/cli, dist/ui, dist/mcp and dist/hooks are absent and the figure covers only the TRACKED payload (src/scripts/, dist/agent-src/, dist/install/, docs/guidelines/, templates). That is deliberate: this gate is always-on for every PR, and the tracked content tree is exactly the surface that grows by accretion. The built artifact is ~5.4 MB larger and is gated separately, at release time, by evaluator-budgets.unpacked_size_mb.",
     "budgets": {
         "packed_size_mb": {
-            "max": 6.9,
-            "last_measured": 6.398,
+            "max": 7.8,
+            "last_measured": 7.238,
             "method": "npm pack --dry-run --json --ignore-scripts → dist.size / 1e6 (the compressed tarball a consumer actually downloads)",
+            "baseline_note_2026_08_10": "6.9 → 7.8 re-baselined 2026-08-10. WHICH OF THE TWO THIS IS, stated because the guard asks: a RATCHET RESET, not the config bent around a failing check — and the discriminator is that the payload is real and needed rather than that the check was inconvenient. The 44 KB is two source files a shipped instruction depends on, the cheaper alternative was examined and rejected on that ground (below), the new cap carries ~8% headroom over the higher of two disagreeing measurements rather than clearing by a hair, and the raise was put to the maintainer as a decision instead of applied to make a red go away. A reader who disagrees has everything needed to reverse it: the measurement, its method, the trip cause, and the rejected option. Maintainer-decided in the PR that tripped it, surfaced rather than smuggled — the same standing this file's `owner: maintainer` requires. MEASURED TWICE, and the two do not agree: CI reported 6.907 on this exact commit, a local run under the documented conditions reports 7.238. The 331 KB gap is UNEXPLAINED — the tree matches the pushed commit and only this file differs — so the cap is set over the HIGHER figure rather than the convenient one, and the discrepancy is recorded here as an open question instead of resolved by assumption. A third party reproducing this should expect either number and should not treat the lower one as authoritative. Separately, and this part IS understood: `npm pack --dry-run --ignore-scripts` in a worktree that has been BUILT reads 8.45, because the flag assumes dist/cli, dist/ui, dist/mcp and dist/hooks are absent and a built tree has them. That figure is not comparable to this budget and must never be written here — recorded because it is a trap the documented method invites. Trip cause: road-to-conformance-round5 Phase 3 added src/scripts/hooks/turn_end_gate_hook.ts (32 KB) and src/scripts/measure_turn_end_gate.ts (12 KB) in packed paths plus schema/template/contract growth, landing 7 KB over a 6.9 cap. Max set to 7.8 (~8% headroom over 7.238, and ~13% over CI's 6.907) for the reason the 2026-08-05 note already gives: a cap pinned just above the measurement reds on the next commit and teaches the reader to raise it again. ALTERNATIVE EXAMINED AND REJECTED, so it is not re-proposed: dropping measure_turn_end_gate.ts from the pack would have cleared the cap with room, but the settings description added in the same change instructs CONSUMERS to run that script against their own transcript store before arming the gate — excluding it would break a shipped instruction.",
             "baseline_note": "5.903 → 6.398 re-baselined 2026-08-05. This is a RE-BASELINE, not a carve-out for the change that tripped it: measured on the tracked tree, `origin/main` alone was already at 6.372 of a 6.4 cap, so 28 KB of headroom remained after months of accretion and the next legitimate addition of any size was going to cross it. The addition here is 26 KB — docs/contracts/settings-classes.md (the A/B/C fence, read at RUNTIME by the settings writer, so it must ship) plus src/server/io/yamlIO.ts (imported by that writer to preserve the user's comments). CI measures ~4 KB above the local figure because it regenerates dist/agent-src first. Max set to 6.9 rather than to a number that merely clears: a cap pinned 2 KB above the measurement reds on the next commit and teaches the reader to raise it again, which is how a budget becomes a formality. That restores the ~8% headroom the 5.903/6.4 pair originally carried. The `owner: maintainer` on this file stands — this raise is surfaced in the PR for that decision, not smuggled."
         }
     },

package/src/config/recycle-threshold-budget.json

@@ -0,0 +1,12 @@
+{
+    "_comment": "Committed recycle threshold (road-to-token-economy-recycling Phase 3.1). ONE threshold, ONE constant: statically imported into the session-eol Stop-slot concern (esbuild folds it into the hook bundle, so consumers carry the same value — no runtime file resolution). Changing it is a PR citing evidence, never a drive-by edit; AGENT_RECYCLE_THRESHOLD_TOKENS overrides per-process (tests + emergency off via 0).",
+    "schema_version": 1,
+    "registered_at": "2026-08-10",
+    "owner": "maintainer",
+    "review_by": "2026-11-10",
+    "unit": "parsed transcript tokens — billable input (input + cache_read + cache_creation) of the last main-chain assistant record, per cc_transcript.ts",
+    "recycle_threshold_tokens": 800000,
+    "derivation": "agents/evidence/analysis/token-economy-recycling-phase1.md — ~p90 of 201 measured session-final sizes (807,937), 54% above the median healthy session (519,349), 15% below the minimum observed auto-compact trigger (941,636). Every one of the 23 sessions that auto-compacted in the baseline would have been advised first.",
+    "known_limitation": "All observed auto-compactions were 1M-window sessions (190 of 201 sessions run on the 1M window on this store). A <=200k-window session auto-compacts near ~160-206k and is never served by this threshold — revisit at review_by; a window-aware threshold needs a window signal the transcript does not carry explicitly.",
+    "honest_null_consequence": "If adoption stays near zero or recycled sessions verify WORSE than the long-session baseline (the registered post_recycle_verify_fail_vs_baseline metric), the result is published and this threshold or the envelope schema revises by evidence in a PR — the claim never survives on vibes."
+}

package/src/config/rule-enforcement-baseline.json

@@ -0,0 +1,86 @@
+[
+  "active-remediation.md",
+  "agent-authority.md",
+  "analysis-skill-routing.md",
+  "architecture.md",
+  "artifact-drafting-protocol.md",
+  "artifact-engagement-recording.md",
+  "ask-when-uncertain.md",
+  "augment-edit-discipline.md",
+  "autonomous-execution.md",
+  "brand-consistency.md",
+  "brand-source-of-truth.md",
+  "broken-access-control.md",
+  "cli-output-handling.md",
+  "code-comment-discipline.md",
+  "command-suggestion-policy.md",
+  "commit-conventions.md",
+  "commit-policy.md",
+  "communication-through-line.md",
+  "content-quoting-floor.md",
+  "copilot-routing.md",
+  "cross-source-consistency.md",
+  "decision-revisit-gate.md",
+  "delegation-policy.md",
+  "design-fidelity.md",
+  "devcontainer-routing.md",
+  "direct-answers.md",
+  "doc-screenshot-hygiene.md",
+  "docker-commands.md",
+  "domain-adoption-policy.md",
+  "domain-safety-disclaimer.md",
+  "domain-safety-pii.md",
+  "domain-safety-retention.md",
+  "downstream-changes.md",
+  "engineering-safety-floor.md",
+  "external-code-graph-interop.md",
+  "external-reference-deep-dive.md",
+  "fast-path-marker-visibility.md",
+  "finance-safety-floor.md",
+  "guidelines.md",
+  "history-discipline.md",
+  "icon-consistency.md",
+  "image-likeness-and-rights.md",
+  "improve-before-implement.md",
+  "invite-challenge.md",
+  "laravel-routing.md",
+  "laravel-translations.md",
+  "legal-safety-floor.md",
+  "linked-projects-onboarding-gate.md",
+  "low-impact-corpus-privacy-floor.md",
+  "markdown-safe-codeblocks.md",
+  "media-sync-ground-truth.md",
+  "missing-tool-handling.md",
+  "model-recommendation.md",
+  "no-attribution-footers.md",
+  "no-cheap-questions.md",
+  "no-decorative-emojis-in-git-surfaces.md",
+  "no-pr-progress-comments.md",
+  "notes-first-reasoning.md",
+  "package-ci-checks.md",
+  "php-coding.md",
+  "prefer-enums-over-literals.md",
+  "provider-lifecycle-discipline.md",
+  "question-not-instruction.md",
+  "reviewer-awareness.md",
+  "roadmap-ci-steps-policy.md",
+  "role-mode-adherence.md",
+  "rule-type-governance.md",
+  "runtime-safety.md",
+  "scale-discipline.md",
+  "scope-control.md",
+  "senior-engineering-discipline.md",
+  "size-enforcement.md",
+  "skill-improvement-trigger.md",
+  "slash-command-routing-policy.md",
+  "source-discovery-gate.md",
+  "spreadsheet-source-quality.md",
+  "strategy-safety-floor.md",
+  "symfony-routing.md",
+  "think-before-action.md",
+  "token-budget-discipline.md",
+  "token-efficiency.md",
+  "upstream-proposal.md",
+  "user-interaction.md",
+  "user-interrupt-priority.md"
+]

package/src/scripts/_cli/cmd_conformance.ts

@@ -41,6 +41,7 @@ import { readRecentEntries } from '../../install/txlog.js';
 import { detectToolPresence } from '../../install/detect.js';
 import { resolvePackageRoot } from '../_lib/package_root.js';
 import { routeTargetPathsPosix } from '../router_target_paths.mjs';
+import { buildFunnel, render as renderFunnel } from '../report_conformance_funnel.js';
 import {
     _classify,
     _collect_manifest_entries,
@@ -532,16 +533,17 @@ export function appendConformanceReport(
 
 const USAGE =
     'usage: agent-config conformance [-h] [--project PROJECT] [--json]\n' +
-    '                                [--skip-dispatcher]\n';
+    '                                [--skip-dispatcher] [--funnel]\n';
 
 interface Options {
     project: string | null;
     json: boolean;
     skip_dispatcher: boolean;
+    funnel: boolean;
 }
 
 function _parse(argv: string[]): Options {
-    const opts: Options = { project: null, json: false, skip_dispatcher: false };
+    const opts: Options = { project: null, json: false, skip_dispatcher: false, funnel: false };
     let i = 0;
     while (i < argv.length) {
         const a = argv[i] as string;
@@ -551,6 +553,8 @@ function _parse(argv: string[]): Options {
         }
         if (a === '--json') {
             opts.json = true;
+        } else if (a === '--funnel') {
+            opts.funnel = true;
         } else if (a === '--skip-dispatcher') {
             opts.skip_dispatcher = true;
         } else if (a === '--project' || a.startsWith('--project=')) {
@@ -578,6 +582,17 @@ function _parse(argv: string[]): Options {
 function main(argv: string[] | null = null): number {
     const opts = _parse(argv !== null ? Array.from(argv) : process.argv.slice(2));
 
+    // `--funnel` — the delivery → activation → compliance report join
+    // (road-to-feedback-9-29 Phase 4.2). A REPORT, not a gate: it hangs off
+    // this verb so no new top-level verb enters the dispatcher registry, it
+    // skips the doctor/conformance legs entirely, and it always exits 0. It
+    // must never be wired into CI without a measured false-positive rate
+    // first — see the header of `report_conformance_funnel.ts`.
+    if (opts.funnel) {
+        print(renderFunnel(buildFunnel()));
+        return 0;
+    }
+
     let project_root: string;
     try {
         [project_root] = _resolve_project_root(opts.project);

package/src/scripts/_cli/cmd_session_recycle.ts

@@ -0,0 +1,226 @@
+/**
+ * `agent-config session:recycle` — write the main-session recycle envelope
+ * (road-to-token-economy-recycling Phase 2.2).
+ *
+ * The producer half of the deliberate session recycle: the model composes
+ * the envelope content it already knows (state, never a transcript
+ * summary), this command VALIDATES it against the main_session CHECKPOINT
+ * variant (`_lib/subagent_capsule.validateRecycleEnvelope`) and writes it
+ * atomically to `agents/runtime/state/recycle-envelope.json`, then prints
+ * the exact resume instruction. Deterministic — no model step in the write
+ * path; the only values this command fills are provenance it can resolve
+ * itself (`written_at` = now, `workspace` = project root,
+ * `capsule_version`/`variant` = the constants).
+ *
+ * Hooks cannot inject `/clear` (host limitation, roadmap Context) — the
+ * clear is the USER's action; the successor session's `handoff_context_hook`
+ * consumes the envelope at session_start (moved, not copied).
+ *
+ * Usage:
+ *   agent-config session:recycle --file <envelope.json>   # read from file
+ *   agent-config session:recycle < envelope.json          # read from stdin
+ *   agent-config session:recycle --template               # print a skeleton
+ *
+ * Exit codes: 0 written (or template printed) · 1 invalid / refused · 2 usage.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { resolve_project_root } from '../_lib/agent_settings.js';
+import {
+    RECYCLE_ENVELOPE_MAX_BYTES,
+    RECYCLE_ENVELOPE_REL,
+} from '../_lib/recycle_envelope_paths.js';
+import {
+    CAPSULE_SCHEMA_VERSION,
+    validateRecycleEnvelope,
+} from '../_lib/subagent_capsule.js';
+import { atomic_write_json } from '../hooks/state_io.js';
+
+export interface RecycleResult {
+    code: 0 | 1 | 2;
+    out: string[];
+    err: string[];
+}
+
+/** Skeleton the model fills — every list ships empty, nothing is invented. */
+export function templateEnvelope(): Record<string, unknown> {
+    return {
+        capsule_version: CAPSULE_SCHEMA_VERSION,
+        variant: 'main_session',
+        summary: '<one- or two-sentence outcome so far>',
+        task: '<the active task, one line>',
+        acceptance_criteria: ['<what done means, one line each>'],
+        remaining: ['<open work, one line each>'],
+        not_carried_forward: ['<what the successor must re-derive from source>'],
+        decisions: ['<decision — one-line rationale>'],
+        constraints: ['<binding constraint>'],
+        open_worker_envelopes: [],
+        artifact_paths: ['<path to a deliverable / note / evidence file>'],
+        assumptions: [],
+    };
+}
+
+interface ParsedArgv {
+    ok: boolean;
+    message?: string;
+    file?: string;
+    template?: boolean;
+}
+
+export function parseArgv(argv: readonly string[]): ParsedArgv {
+    const parsed: ParsedArgv = { ok: true };
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i] as string;
+        if (a === '--template') {
+            parsed.template = true;
+        } else if (a === '--file') {
+            const value = argv[i + 1];
+            if (!value) return { ok: false, message: '--file requires a path' };
+            parsed.file = value;
+            i += 1;
+        } else if (a === '-h' || a === '--help') {
+            return { ok: false, message: 'usage' };
+        } else {
+            return { ok: false, message: `unknown argument: ${a}` };
+        }
+    }
+    return parsed;
+}
+
+/**
+ * Validate + write. `input` is the raw JSON text the model composed;
+ * provenance fields this command can resolve itself are filled when absent,
+ * then the STRICT validator decides.
+ */
+export function runSessionRecycle(
+    input: string,
+    opts: { cwd: string; now?: Date },
+): RecycleResult {
+    const out: string[] = [];
+    const err: string[] = [];
+    const [projectRoot] = resolve_project_root(null, { cwd: opts.cwd });
+
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(input);
+    } catch (exc) {
+        return { code: 1, out, err: [`envelope is not valid JSON: ${String(exc)}`] };
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return { code: 1, out, err: ['envelope must be a JSON object'] };
+    }
+    const envelope = parsed as Record<string, unknown>;
+
+    // Deterministic provenance — filled only when the composer left them out.
+    if (envelope['capsule_version'] === undefined) envelope['capsule_version'] = CAPSULE_SCHEMA_VERSION;
+    if (envelope['variant'] === undefined) envelope['variant'] = 'main_session';
+    if (envelope['written_at'] === undefined) {
+        envelope['written_at'] = (opts.now ?? new Date()).toISOString();
+    }
+    if (envelope['workspace'] === undefined) envelope['workspace'] = projectRoot;
+
+    const violations = validateRecycleEnvelope(envelope);
+    if (violations.length > 0) {
+        return {
+            code: 1,
+            out,
+            err: ['recycle envelope refused — schema violations:', ...violations.map((v) => `  - ${v}`)],
+        };
+    }
+
+    const serialized = JSON.stringify(envelope, null, 2);
+    const bytes = Buffer.byteLength(serialized, 'utf-8');
+    if (bytes > RECYCLE_ENVELOPE_MAX_BYTES) {
+        return {
+            code: 1,
+            out,
+            err: [
+                `recycle envelope refused — ${bytes} bytes > ${RECYCLE_ENVELOPE_MAX_BYTES} byte cap.`,
+                'An envelope is selection and pointers, not a dump: move detail into artifact',
+                'files and reference them via artifact_paths.',
+            ],
+        };
+    }
+
+    const target = path.join(projectRoot, RECYCLE_ENVELOPE_REL);
+    try {
+        atomic_write_json(target, envelope);
+    } catch (exc) {
+        return { code: 1, out, err: [`could not write ${target}: ${String(exc)}`] };
+    }
+
+    out.push(`recycle envelope written — ${RECYCLE_ENVELOPE_REL} (${bytes} bytes)`);
+    out.push('');
+    out.push('Resume instruction:');
+    out.push('  1. End this session now: run /clear (or start a fresh session in this workspace).');
+    out.push('  2. The successor session receives the envelope automatically at session_start');
+    out.push('     (injected once as DATA, then consumed — moved, not copied).');
+    out.push('  3. The successor re-derives everything on the not_carried_forward list from');
+    out.push('     source before trusting it.');
+    return { code: 0, out, err };
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    const parsed = parseArgv(argv);
+    if (!parsed.ok) {
+        const usage = [
+            'usage: agent-config session:recycle [--file <envelope.json>] [--template]',
+            '  --file <path>   read the envelope JSON from a file (default: stdin)',
+            '  --template      print a skeleton envelope and exit',
+        ].join('\n');
+        if (parsed.message === 'usage') {
+            process.stdout.write(`${usage}\n`);
+            return 0;
+        }
+        process.stderr.write(`${parsed.message}\n${usage}\n`);
+        return 2;
+    }
+
+    if (parsed.template) {
+        process.stdout.write(`${JSON.stringify(templateEnvelope(), null, 2)}\n`);
+        return 0;
+    }
+
+    let input: string;
+    try {
+        if (parsed.file) {
+            input = fs.readFileSync(parsed.file, 'utf-8');
+        } else if (process.stdin.isTTY) {
+            process.stderr.write('no envelope on stdin and no --file given (see --help)\n');
+            return 2;
+        } else {
+            input = fs.readFileSync(0, 'utf-8');
+        }
+    } catch (exc) {
+        process.stderr.write(`could not read envelope input: ${String(exc)}\n`);
+        return 2;
+    }
+
+    const result = runSessionRecycle(input, { cwd: process.cwd() });
+    for (const line of result.out) process.stdout.write(`${line}\n`);
+    for (const line of result.err) process.stderr.write(`${line}\n`);
+    return result.code;
+}
+
+// Bundle-safety: never auto-run when inlined into an esbuild bundle.
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) return false;
+    if (process.argv[1] === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
+    try {
+        return (
+            fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]))
+        );
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/_cli/explain_last/inputs.ts

@@ -132,6 +132,19 @@ export function build(project_root: string): Record<string, unknown> | null {
         rule_loading_tier = null;
     }
     let rule_loading_tier_source = _pyTruthy(rule_loading_tier) ? 'user' : 'default';
+    // The one read-site divergence from the template that is NOT a
+    // `settingsCarveOut` row, so it is explained here instead
+    // (`road-to-scripts-settings-defaults` Phase 1, § 2 of the Evidence Report).
+    // The template ships `rule_loading_tier: __RULE_LOADING_TIER__` — an
+    // installer placeholder, not a value — so the template-defaults layer in
+    // `load_agent_settings` deliberately does not inject it and an absent key
+    // arrives here as `undefined`. `balanced` is therefore this reader's own
+    // default, matching what the installer substitutes.
+    // The second arm is the deliberate part: a settings file that still
+    // literally contains the placeholder is a BROKEN install, and this reports
+    // it as `source: default` — i.e. the trace looks healthy. Surfacing it
+    // instead would be a reporting change beyond this roadmap's scope; it is
+    // recorded rather than silently kept.
     if (!_pyTruthy(rule_loading_tier) || rule_loading_tier === '__RULE_LOADING_TIER__') {
         rule_loading_tier = _DEFAULT_RULE_LOADING_TIER;
         rule_loading_tier_source = 'default';

package/src/scripts/_dispatch.bash

@@ -197,10 +197,17 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
                              session register). Flags: --json
   sessions:claim             Claim a roadmap for this session so other sessions skip
                              it; --release clears the claim
+  session:recycle            Validate + write the main-session recycle envelope
+                             (deliberate recycle instead of auto-compact). Flags:
+                             --file <json> | --template; default reads stdin
   roadmap:progress           Regenerate agents/roadmaps-progress.md from open roadmaps
   roadmap:progress-check     Fail if agents/roadmaps-progress.md is stale (for CI)
   roadmap:archive            Archive completed roadmaps (branch-touched by default;
                              --all for every complete one; --dry-run to preview)
+  gates                      Open decisions that need you, rendered as actions —
+                             roadmap blockers filtered by owner, most-unblocking
+                             first. Flags: --all (include maintainer/external),
+                             --json
   capabilities:index         Regenerate CAPABILITIES.yaml — the package coverage index
                              (capability area → coverage → backing skills/commands → gaps).
                              Pass --check to fail if stale (for CI). Reads src/ (package repo).
@@ -614,6 +621,14 @@ cmd_sessions_claim() {
   exec_ts "$PACKAGE_ROOT/src/scripts/sessions_cli.ts" claim "$@"
 }
 
+# Main-session recycle envelope producer (road-to-token-economy-recycling
+# Phase 2.2). PACKAGE_ROOT: imports src/scripts/_lib/ (capsule schema) and
+# src/scripts/hooks/state_io.ts, which are never projected into
+# dist/agent-src/scripts/.
+cmd_session_recycle() {
+  exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_session_recycle.ts" "$@"
+}
+
 # Capability probes (road-to-capability-answerability). All three resolve from
 # PACKAGE_ROOT rather than the consumer projection: each imports package-internal
 # libraries under src/scripts/_lib/ or src/shared/, which are never projected into
@@ -654,6 +669,12 @@ cmd_roadmap_archive() {
   exec_ts "$script" "$@"
 }
 
+cmd_gates() {
+  local script
+  script="$(resolve_script "dist/agent-src/scripts/roadmap_gates.ts" ".augment/scripts/roadmap_gates.ts")"
+  exec_ts "$script" "$@"
+}
+
 cmd_capabilities_index() {
   local script
   script="$(resolve_script "src/scripts/generate_capabilities_index.ts")"
@@ -1320,6 +1341,7 @@ main() {
     conformance:behavior)    cmd_conformance_behavior "$@" ;;
     sessions:list)           cmd_sessions_list "$@" ;;
     sessions:claim)          cmd_sessions_claim "$@" ;;
+    session:recycle)         cmd_session_recycle "$@" ;;
     packs:active)            cmd_packs_active "$@" ;;
     settings:get)            cmd_settings_get "$@" ;;
     mcp:available)           cmd_mcp_available "$@" ;;
@@ -1327,6 +1349,7 @@ main() {
     roadmap:progress)        cmd_roadmap_progress "$@" ;;
     roadmap:progress-check)  cmd_roadmap_progress_check "$@" ;;
     roadmap:archive)         cmd_roadmap_archive "$@" ;;
+    gates)                   cmd_gates "$@" ;;
     capabilities:index)      cmd_capabilities_index "$@" ;;
     hooks:install)           cmd_hooks_install "$@" ;;
     keys:install-anthropic)  cmd_keys_install_anthropic "$@" ;;