@event4u/agent-config 9.29.0 → 9.30.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/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/_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 "$@" ;;