@event4u/agent-config 9.28.0 → 9.30.0

package/src/scripts/_cli/cmd_conformance.ts

@@ -10,7 +10,9 @@
  *   (b) router-pointers      — dist/router.json ids + routes_to resolve on disk
  *   (c) hook-dispatcher      — dispatcher answers synthetic session_start/stop
  *   (d) lean-projection      — lean_projection.mode matches projected artifacts
- *   (e) host-manifest        — subagents.host_capabilities parses strictly
+ *   (e) host-manifest        — a leftover subagents.host_capabilities override
+ *                              is deprecated + ignored (always-on orchestration
+ *                              resolves capability from a probe/registry only)
  *
  * All checks are deterministic — no LLM, no network. Exit contract:
  *   0 = every check ok/skipped (warns allowed) and doctor --ci green
@@ -39,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,
@@ -421,14 +424,6 @@ export function _check_lean_projection(
 // Check (e) — host-capability manifest parses strictly + matches detection.
 // ---------------------------------------------------------------------------
 
-const HOST_MANIFEST_KEYS = new Set([
-    'schema_version',
-    'subagent_spawn',
-    'parallel_spawn',
-    'status_polling',
-    'separate_quota_pool',
-]);
-
 export function _check_host_manifest(projectRoot: string): Dict {
     const detected = Object.entries(detectToolPresence(projectRoot))
         .filter(([, v]) => v === true)
@@ -441,7 +436,7 @@ export function _check_host_manifest(projectRoot: string): Dict {
         return {
             id: 'host-manifest',
             status: 'ok',
-            message: `no .agent-settings.yml — safe-default manifest applies (${detectedNote})`,
+            message: `no .agent-settings.yml — host capability is always probe/registry-resolved (${detectedNote})`,
             remedy: '',
         };
     }
@@ -462,44 +457,22 @@ export function _check_host_manifest(projectRoot: string): Dict {
         return {
             id: 'host-manifest',
             status: 'ok',
-            message: `no host_capabilities override — safe-default manifest applies (${detectedNote})`,
+            message: `no host_capabilities override — host capability is always probe/registry-resolved (${detectedNote})`,
             remedy: '',
         };
     }
-    if (typeof manifest !== 'object' || Array.isArray(manifest)) {
-        return {
-            id: 'host-manifest',
-            status: 'fail',
-            message: 'subagents.host_capabilities is not a mapping',
-            remedy: 'use the four boolean fields from the host-capability manifest contract',
-        };
-    }
-    const problems: string[] = [];
-    for (const [key, value] of Object.entries(manifest as Dict)) {
-        if (!HOST_MANIFEST_KEYS.has(key)) {
-            problems.push(`unknown key '${key}'`);
-            continue;
-        }
-        if (key === 'schema_version') {
-            if (value !== 1) problems.push(`schema_version must be 1 (got ${JSON.stringify(value)})`);
-            continue;
-        }
-        if (typeof value !== 'boolean') {
-            problems.push(`'${key}' must be boolean (got ${JSON.stringify(value)})`);
-        }
-    }
-    if (problems.length > 0) {
-        return {
-            id: 'host-manifest',
-            status: 'fail',
-            message: `host_capabilities malformed: ${problems.slice(0, 4).join('; ')}`,
-            remedy: 'only schema_version:1 + four boolean capability fields are valid',
-        };
-    }
+    // Always-on orchestration (road-to-always-on-orchestration Phase 1)
+    // deleted `subagents.host_capabilities` as a live override — capability
+    // now resolves ONLY from the host probe/registry. A leftover key is
+    // therefore inert: its shape no longer matters, so this no longer fails
+    // on an unknown key or a non-boolean value — there is nothing left for a
+    // malformed override to break.
     return {
         id: 'host-manifest',
         status: 'ok',
-        message: `host_capabilities override parses strictly (${detectedNote})`,
+        message:
+            `subagents.host_capabilities is deprecated and ignored — host capability is ` +
+            `always probe/registry-resolved (${detectedNote})`,
         remedy: '',
     };
 }
@@ -560,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;
@@ -579,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=')) {
@@ -606,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_doctor.ts

@@ -1050,7 +1050,7 @@ function _check_lockfile_freshness(manifest: Dict): Dict {
 }
 
 /** `shutil.which(name)` — first PATH hit (with PATHEXT on win32). */
-function shutilWhich(name: string): string | null {
+export function shutilWhich(name: string): string | null {
     if (path.dirname(name) !== '.' && (name.includes('/') || name.includes('\\'))) {
         // Has a path component: check directly.
         return isExecutableFile(name) ? name : null;
@@ -2065,6 +2065,31 @@ function osErrorStr(exc: unknown): string {
 const _CLI_PROVIDER_META: Readonly<Record<string, readonly [string, boolean]>> =
     PROVIDER_CLI_META;
 
+/**
+ * m5 fix (independent-review finding) — `MemberConfig.mode` is the RAW
+ * per-member override only (`config.ts::_build_member` never writes the
+ * `defaults.mode`-resolved value back onto it); a member that never sets
+ * `mode:` locally has `member.mode === null` regardless of what the
+ * council's global default is. `defaults.mode` shipped `'auto'` as its own
+ * default (road-to-always-on-orchestration Phase 3.1), so the common,
+ * unconfigured case for every member is `null` here — and `auto` may
+ * legitimately resolve to the `cli` rung, exactly the case
+ * `config.ts::_build_member`'s own binary-override validation already
+ * accounts for ("`auto` may resolve to the cli rung, so a binary override
+ * is legitimate there too"). A check gated on the literal `mode === 'cli'`
+ * misses every `auto`/unset member, honouring neither its binary override
+ * nor its quota — silently, for the majority default shape.
+ */
+function _effectiveMemberMode(member: ai_council_config.MemberConfig, cfg: ai_council_config.CouncilConfig): string {
+    return member.mode ?? cfg.defaults.mode;
+}
+
+/** True when `member` might run over CLI transport — `cli` pinned, or `auto` (which may resolve to it). */
+function _mayRunOverCli(member: ai_council_config.MemberConfig, cfg: ai_council_config.CouncilConfig): boolean {
+    const mode = _effectiveMemberMode(member, cfg);
+    return mode === 'cli' || mode === 'auto';
+}
+
 function _check_council_cli(project_root: string): Dict {
     // Python wraps the council-module import in a try/except ImportError so a
     // broken council install degrades to a `warn` instead of crashing doctor.
@@ -2097,7 +2122,7 @@ function _check_council_cli(project_root: string): Dict {
     }
     const cli_members: Array<[string, ai_council_config.MemberConfig]> = [];
     for (const [name, m] of cfg.members.entries()) {
-        if (m.enabled && m.mode === 'cli' && name in _CLI_PROVIDER_META) {
+        if (m.enabled && _mayRunOverCli(m, cfg) && name in _CLI_PROVIDER_META) {
             cli_members.push([name, m]);
         }
     }
@@ -2216,11 +2241,12 @@ function _codex_home(): string {
 
 /**
  * Codex binary name for the team check — REUSES the council probe's binary
- * discovery: when a council config exists and declares an enabled cli-mode
- * `openai` member with a `binary` override, honour it; else the provider
- * default from `_CLI_PROVIDER_META` (`codex`). Never throws — an unreadable
- * or invalid council config falls back to the default binary (the council-cli
- * check owns reporting that problem).
+ * discovery: when a council config exists and declares an enabled `openai`
+ * member whose effective mode is `cli` (pinned) OR `auto` (may resolve to
+ * `cli` — see `_mayRunOverCli`) with a `binary` override, honour it; else
+ * the provider default from `_CLI_PROVIDER_META` (`codex`). Never throws —
+ * an unreadable or invalid council config falls back to the default binary
+ * (the council-cli check owns reporting that problem).
  */
 function _team_codex_binary_name(project_root: string): string {
     const default_bin = (_CLI_PROVIDER_META['openai'] as [string, boolean])[0];
@@ -2236,21 +2262,12 @@ function _team_codex_binary_name(project_root: string): string {
         return default_bin;
     }
     const member = cfg.members.get('openai');
-    if (member && member.enabled && member.mode === 'cli' && member.binary) {
+    if (member && member.enabled && _mayRunOverCli(member, cfg) && member.binary) {
         return member.binary;
     }
     return default_bin;
 }
 
-/** Settings-flag coercion shared with the tier-usage check (bool or string). */
-function _settings_flag(val: unknown): boolean {
-    if (typeof val === 'boolean') return val;
-    if (typeof val === 'string') {
-        return ['true', 'yes', 'on', '1'].includes(val.trim().toLowerCase());
-    }
-    return false;
-}
-
 /**
  * Decode a JWT payload's `exp` claim (epoch seconds) — base64 decode only,
  * NO signature verification, no network. Non-JWT / undecodable → null.
@@ -2364,9 +2381,16 @@ function _read_ai_team_block(project_root: string): Dict {
  *     loop bound (`max_consecutive_blocks`, Phase 4 — unbuilt) is absent
  *     → WARN.
  *
- * Absent feature ≠ broken feature: with `ai_team` absent or disabled the
- * check reports ok ("team mode not configured (default-off)"); WARN fires
- * only on failing sub-signals or inconsistent half-configured states.
+ * Availability, not a setting (road-to-always-on-orchestration Phase 1,
+ * Step 1.3): `ai_team.enabled` was DELETED — `/team`'s on/off state is the
+ * codex binary + auth facts (a) computes below, mirroring
+ * `checkCodexAvailability()` (`src/scripts/ai_team/availability.ts`).
+ * Absent feature ≠ broken feature: with BOTH the binary and auth absent the
+ * check reports ok ("team unavailable (default) — codex CLI not
+ * installed") — a normal starting state, not a misconfiguration; WARN
+ * fires only when something was set up PARTWAY (binary without auth, a
+ * managed Review-Gate with an invalid bound, …) or a real sub-signal
+ * fails.
  */
 // ---------------------------------------------------------------------------
 // detection check (road-to-zero-ceremony-detection Phases 3 + 4)
@@ -2526,36 +2550,11 @@ function _check_detection(project_root: string): Dict {
 
 function _check_team(project_root: string): Dict {
     const ai_team = _read_ai_team_block(project_root);
-    const enabled = _settings_flag(ai_team['enabled']);
     const gateRaw = ai_team['review_gate'];
     const gate =
         typeof gateRaw === 'object' && gateRaw !== null && !Array.isArray(gateRaw)
             ? (gateRaw as Dict)
             : {};
-    const gate_managed = _settings_flag(gate['managed']);
-
-    if (!enabled) {
-        if (gate_managed) {
-            return {
-                id: 'team',
-                status: 'warn',
-                message:
-                    'half-configured: ai_team.review_gate.managed is on but ' +
-                    'ai_team.enabled is false — the gate never runs',
-                remedy:
-                    'set `ai_team.enabled: true` in .agent-settings.yml, or ' +
-                    'remove `ai_team.review_gate.managed`',
-            };
-        }
-        return {
-            id: 'team',
-            status: 'ok',
-            message: 'team mode not configured (default-off)',
-            remedy:
-                'opt in via `ai_team.enabled: true` in .agent-settings.yml, ' +
-                'then re-run `agent-config doctor --check team`',
-        };
-    }
 
     const remedies: string[] = [];
 
@@ -2563,7 +2562,8 @@ function _check_team(project_root: string): Dict {
     const binary_name = _team_codex_binary_name(project_root);
     const binary_resolved = shutilWhich(binary_name);
     const binary_glyph = binary_resolved !== null ? '✅' : '❌';
-    if (binary_resolved === null) {
+    const binary_missing = binary_resolved === null;
+    if (binary_missing) {
         remedies.push('install the codex CLI: `npm install -g @openai/codex`');
     }
 
@@ -2613,7 +2613,8 @@ function _check_team(project_root: string): Dict {
     // (c) Review-Gate governance (Phase 4) — logic lives in
     // src/scripts/ai_team/review_gate.ts (upstream gate probe + WARN
     // states, incl. plugin-gate-on-while-unmanaged with the quoted
-    // upstream cost warning).
+    // upstream cost warning). Independent of /team's own availability —
+    // `managed` governs the codex PLUGIN's own Stop-hook loop.
     const gate_signal = review_gate_doctor_signal(project_root, gate);
     const gate_str = gate_signal.gate_str;
     remedies.push(...gate_signal.remedies);
@@ -2621,6 +2622,21 @@ function _check_team(project_root: string): Dict {
     const detail =
         `codex binary ${binary_glyph} (${binary_name}) · ` +
         `${auth_str} · ${plugin_str} · ${gate_str}`;
+
+    if (binary_missing && !authed) {
+        // Neither the binary nor auth is present — /team simply is not set
+        // up on this machine yet. CLI-first doctrine (road-to-always-on-
+        // orchestration Phase 1, Step 1.3): this is a normal starting
+        // state, not a misconfiguration — still surface the full detail
+        // (e.g. a `review_gate.managed` left on) so nothing is hidden.
+        return {
+            id: 'team',
+            status: 'ok',
+            message: `team unavailable (default) — codex CLI not installed · ${detail}`,
+            remedy: remedies.join('; '),
+        };
+    }
+
     if (remedies.length > 0) {
         return {
             id: 'team',
@@ -2632,7 +2648,7 @@ function _check_team(project_root: string): Dict {
     return {
         id: 'team',
         status: 'ok',
-        message: `team mode enabled · ${detail}`,
+        message: `team available · ${detail}`,
         remedy: '',
     };
 }
@@ -3556,6 +3572,7 @@ export {
     _foreign_records,
     _check_scope,
     _check_manifest_integrity,
+    _team_codex_binary_name,
     _check_lockfile_freshness,
     _check_global_binary,
     _check_claude_plugin,

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 "$@" ;;