@aiwg/cli 2026.10.3 → 2026.10.5

package/dist/src/cli/handlers/decision.js

@@ -1,11 +1,11 @@
-import { ATTRIBUTION_FIELD_PATTERN, askDecision, DecisionAskUsageError, decisionCapabilities, DecisionLedgerSinceError, decisionLedgerHistory, decisionLedgerStats, evaluateRequestPath, listPatterns, livePlan, MAX_ATTRIBUTION_FIELD_LENGTH, materializeSyntheticClassificationSetup, parseDecisionLedgerSince, readDecisionContextFile, recordDecisionAsk, runOfflinePattern, setupJev, showPattern, syntheticClassificationSetup, validateDecisionInput, } from '../../decision/driver.js';
+import { ATTRIBUTION_FIELD_PATTERN, DecisionAskUsageError, decisionCapabilities, DecisionLedgerSinceError, decisionLedgerHistory, decisionLedgerStats, evaluateRequestPath, listPatterns, livePlan, MAX_ATTRIBUTION_FIELD_LENGTH, materializeSyntheticClassificationSetup, parseDecisionLedgerSince, readDecisionContextFile, runDecisionOffloadCheckpoint, runOfflinePattern, setupJev, showPattern, syntheticClassificationSetup, validateDecisionInput, } from '../../decision/driver.js';
 function jsonResult(value, exitCode = 0) {
     return { exitCode, message: JSON.stringify(value, null, 2), rawOutput: true };
 }
 function usage() {
     return [
         'Usage: aiwg decision <capabilities|status|patterns|validate|evaluate|setup|history|stats> [options]',
-        '       aiwg decision ask --question "<q>" (--yes-no | --choices a,b,c | --scale 1-5) [--context <text> | --context-file <path> | --context-stdin] [--threshold 0.8] [--timeout-ms 15000] [--provider <id>] [--session <id>] [--caller <tag>] [--record-text] [--json]',
+        '       aiwg decision ask --question "<q>" (--yes-no | --choices a,b,c | --scale 1-5) [--context <text> | --context-file <path> | --context-stdin] [--threshold 0.8] [--timeout-ms 15000] [--passes N] [--escalation-passes N] [--provider <id>] [--session <id>] [--caller <tag>] [--record-text] [--json]',
         '',
         'Commands:',
         '  capabilities|status                 Show offline readiness, primitives, config and feature availability',
@@ -19,7 +19,7 @@ function usage() {
         '  setup jev [--token-stdin] [--region <r>] [--endpoint <url>] [--verify] [--remove]',
         '  ask --question "<q>" (--yes-no | --choices a,b,c | --scale 1-5) [--provider <id>] [--session <id>] [--caller <tag>] [--record-text]',
         '  history [--since <date>] [--provider <id>] [--session <id>] [--kind yes-no|choices|scale] [--status answered|fallback] [--caller <tag>|<prefix>* | --no-caller] [--json]',
-        '  stats [--since <date>] [--provider <id>] [--session <id>] [--kind yes-no|choices|scale] [--status answered|fallback] [--caller <tag>|<prefix>* | --no-caller] [--group-by provider|session|kind|caller] [--json]',
+        '  stats [--since <date>] [--provider <id>] [--session <id>] [--kind yes-no|choices|scale] [--status answered|fallback] [--caller <tag>|<prefix>* | --no-caller] [--group-by provider|session|kind|caller|passes|escalation] [--json]',
         '',
         'Notes:',
         '  Every COMPLETED `ask` call (CLI and MCP) appends one record to the decision',
@@ -139,22 +139,25 @@ async function decisionAsk(ctx) {
             : choices !== undefined ? { kind: 'choices', choices: choices.split(',').map(value => value.trim()).filter(Boolean) }
                 : { kind: 'scale', ...scale },
         ...(context === undefined ? {} : { context }),
+        ...(args.includes('--passes') ? { passes: parseNumber(takeRequiredOption(args, '--passes'), '--passes') } : {}),
+        ...(args.includes('--escalation-passes') ? { escalationPasses: parseNumber(takeRequiredOption(args, '--escalation-passes'), '--escalation-passes') } : {}),
         ...(args.includes('--threshold') ? { threshold: parseNumber(takeOption(args, '--threshold'), '--threshold') } : {}),
         ...(args.includes('--timeout-ms') ? { timeoutMs: parseNumber(takeOption(args, '--timeout-ms'), '--timeout-ms') } : {}),
     };
-    const result = await askDecision(input, { env: process.env });
-    // Best-effort and bounded (recordDecisionAsk never throws and never hangs past its own
-    // deadline): a ledger failure, timeout, or attribution-detection error can never change
-    // `result` or the exit code decided below (review r1 findings 3 and 4).
-    await recordDecisionAsk(input, result, {
+    const invocation = await runDecisionOffloadCheckpoint(input, {
         transport: 'cli',
         projectRoot: ctx.cwd,
         env: process.env,
         explicitProvider: takeOption(args, '--provider'),
         explicitSessionId,
-        caller: caller ?? null,
+        caller: caller ?? 'decision-cli:ask',
+        ledgerCaller: caller ?? null,
+        category: caller ? undefined : 'unattributed',
         recordText: args.includes('--record-text'),
     });
+    if (!invocation.result)
+        throw invocation.outcome === 'unknown' ? invocation.error : new Error('Decision ask was skipped');
+    const result = invocation.result;
     if (args.includes('--json'))
         return jsonResult(result);
     if (result.status === 'fallback')
@@ -175,7 +178,7 @@ function parseSince(value) {
 }
 const DECISION_LEDGER_KINDS = ['yes-no', 'choices', 'scale'];
 const DECISION_LEDGER_STATUSES = ['answered', 'fallback'];
-const DECISION_LEDGER_GROUP_BYS = ['provider', 'session', 'kind', 'caller'];
+const DECISION_LEDGER_GROUP_BYS = ['provider', 'session', 'kind', 'caller', 'passes', 'escalation'];
 function parseKindFilter(value) {
     if (value === undefined)
         return undefined;
@@ -305,10 +308,14 @@ async function decisionStats(ctx) {
     if (result.groups.length === 0)
         return { exitCode: 0, message: [...header, 'No decision ledger records match the filters.'].join('\n'), rawOutput: true };
     const lines = result.groups.flatMap(group => [
-        `${result.groupBy ?? 'all'}=${group.key ?? 'null'}: ${group.totalCalls} calls (${group.answered} answered, ${group.fallback} fallback, rate=${group.fallbackRate.toFixed(2)})`,
+        `${result.groupBy ?? 'all'}=${group.key ?? 'null'}: ${group.totalCalls} calls (${group.answered} answered, ${group.fallback} fallback, hit rate=${group.hitRate.toFixed(2)}, fallback rate=${group.fallbackRate.toFixed(2)})`,
         `  confidence: mean=${group.confidence.mean?.toFixed(2) ?? '-'} min=${group.confidence.min?.toFixed(2) ?? '-'} max=${group.confidence.max?.toFixed(2) ?? '-'} (n=${group.confidence.count})`,
+        `  agreement: mean=${group.agreement.mean?.toFixed(2) ?? '-'} escalated=${group.escalatedCalls} passes run=${group.passesRun}`,
         `  jev usage: input=${group.jevUsage.inputTokens} output=${group.jevUsage.outputTokens}`,
-        `  estimated LLM tokens avoided=${group.estimatedLlmTokensAvoidedTotal} net savings=${group.netSavingsTokens}`,
+        `  tokens per answered decision=${group.tokensPerAnsweredDecision?.toFixed(2) ?? '-'}`,
+        `  llm_tokens_avoided=${group.llm_tokens_avoided} jev_tokens=${group.jev_tokens} cost_weighted_net_usd=${group.cost_weighted_net_usd.toFixed(6)}`,
+        `  v1 comparison only: estimated LLM tokens avoided=${group.estimatedLlmTokensAvoidedTotal} net savings=${group.netSavingsTokens}`,
+        ...(group.legacyReestimatedCalls ? [`  v1 records re-estimated=${group.legacyReestimatedCalls} weights=${JSON.stringify(result.legacyEstimationWeights)}`] : []),
     ]);
     return { exitCode: 0, message: [...header, ...lines].join('\n'), rawOutput: true };
 }

package/dist/src/cli/handlers/diagnose.js

@@ -207,9 +207,9 @@ function redactSecretsInObject(obj) {
 }
 function collectGitInfo(cwd) {
     try {
-        const branch = spawnSync('git', ['-C', cwd, 'rev-parse', '--abbrev-ref', 'HEAD'], { stdio: 'pipe', timeout: 5000 });
-        const log = spawnSync('git', ['-C', cwd, 'log', '-10', '--oneline'], { stdio: 'pipe', timeout: 5000 });
-        const remote = spawnSync('git', ['-C', cwd, 'remote', '-v'], { stdio: 'pipe', timeout: 5000 });
+        const branch = spawnSync('git', ['-C', cwd, 'rev-parse', '--abbrev-ref', 'HEAD'], { stdio: 'pipe', timeout: 5000, killSignal: 'SIGKILL' });
+        const log = spawnSync('git', ['-C', cwd, 'log', '-10', '--oneline'], { stdio: 'pipe', timeout: 5000, killSignal: 'SIGKILL' });
+        const remote = spawnSync('git', ['-C', cwd, 'remote', '-v'], { stdio: 'pipe', timeout: 5000, killSignal: 'SIGKILL' });
         if (branch.status !== 0)
             return null;
         return [
@@ -232,6 +232,7 @@ function collectDoctorOutput() {
             stdio: 'pipe',
             timeout: 30_000,
             env: { ...process.env, AIWG_LOG_DISABLE: '1', NO_COLOR: '1' },
+            killSignal: 'SIGKILL',
         });
         const out = r.stdout?.toString() ?? '';
         const err = r.stderr?.toString() ?? '';

package/dist/src/cli/handlers/effect.js

@@ -243,7 +243,7 @@ function openLedger(session, registry) {
  * `kinds`, `record`, `reconcile` and `probe` all use it, so `kinds` lists
  * exactly what the registry contains. Tracker authority is resolved lazily at
  * verification time, so a project without tracker configuration still lists
- * the tracker kinds and answers `unknown` / `tracker-blocked`.
+ * the tracker kinds and answers `unknown` with a tracker precondition reason.
  */
 export function buildCliVerifierRegistry(projectRoot, extensions = [], tracker = { config: null, remoteUrls: {} }) {
     const injected = new Set(extensions.map(verifier => verifier.kind));
@@ -425,7 +425,9 @@ function expectationsFrom(parsed) {
     return { expected, ...(timeoutMs !== undefined ? { timeoutMs } : {}), ...(verifierVersion ? { verifierVersion } : {}) };
 }
 function emit(rendered, format) {
-    const message = format === 'text' ? rendered.text : effectOutputJson(rendered.output);
+    const evidence = rendered.output.evidence;
+    const hint = typeof evidence?.hint === 'string' ? `\n${evidence.hint}` : '';
+    const message = format === 'text' ? rendered.text + hint : effectOutputJson(rendered.output);
     return { exitCode: rendered.output.exitCode, message, rawOutput: true };
 }
 function errorOutput(error) {

package/dist/src/cli/handlers/evidence.js

@@ -28,6 +28,9 @@ function usage() {
 }
 export const evidenceHandler = {
     id: 'evidence', name: 'Evidence', description: 'Export and verify portable evaluation evidence bundles', category: 'utility', aliases: [],
+    async help() {
+        return { exitCode: 0, message: usage(), rawOutput: true };
+    },
     async execute(ctx) {
         const [subcommand] = ctx.args;
         if (!subcommand || subcommand === '--help' || subcommand === '-h')

package/dist/src/cli/handlers/help.js

@@ -92,6 +92,7 @@ function displayHelp() {
         ['show <type> <name>', 'Stream the body of an indexed artifact'],
         ['versions <list|resolve|show>', 'Browse and resolve signed AIWG web resource releases'],
         ['auth <login|status|logout>', 'Authenticate for paid AIWG web resources'],
+        ['corpus <subcommand>', 'Research corpus tools (snapshot, radar, profiles, curator)'],
         ['index <subcommand>', 'Manage the artifact index (build/query/discover/deps/stats)'],
         ['artifacts move --to <path>', 'Move/rename the project AIWG artifact root and reindex'],
     ]);

package/dist/src/cli/handlers/index.js

@@ -73,6 +73,7 @@ import { installationHandler } from './installation.js';
 import { uhpHandler } from './uhp.js';
 import { schemaHandler } from './schema.js';
 import { datasetHandler } from './dataset.js';
+import { rulesHandler } from './rules.js';
 import { decisionHandler } from './decision.js';
 import { gatesHandler } from './gates.js';
 // Re-export individual handlers
@@ -80,7 +81,7 @@ export {
 // Maintenance
 helpHandler, versionHandler, authHandler, doctorHandler, contextFirewallHandler, updateHandler, refreshHandler, regenerateHandler, workspaceContextHandler, 
 // Framework management
-useHandler, listHandler, removeHandler, promoteHandler, installHandler, packagesHandler, marketplaceHandler, initHandler, setupHandler, setupGenerateHandler, setupRunHandler, setupValidateHandler, issueHandler, issueAuditHandler, runHandler, jobHandler, costReportHandler, evidenceHandler, artifactVerifyHandler, outputModeHandler, writerProfileHandler, botHandoffHandler, buildVerifyHandler, writingHandler, schemaHandler, datasetHandler, decisionHandler, gatesHandler, installationHandler, 
+useHandler, listHandler, removeHandler, promoteHandler, installHandler, packagesHandler, marketplaceHandler, initHandler, setupHandler, setupGenerateHandler, setupRunHandler, setupValidateHandler, issueHandler, issueAuditHandler, runHandler, jobHandler, costReportHandler, evidenceHandler, artifactVerifyHandler, outputModeHandler, writerProfileHandler, botHandoffHandler, buildVerifyHandler, writingHandler, schemaHandler, datasetHandler, decisionHandler, rulesHandler, gatesHandler, installationHandler, 
 // Project
 newBundleHandler, quickrefHandler, newProjectHandler, sessionHandler, sessionsHandler, 
 // Workspace
@@ -172,6 +173,7 @@ export const allHandlers = [
     schemaHandler,
     datasetHandler,
     decisionHandler,
+    rulesHandler,
     gatesHandler,
     // Workspace management
     ...workspaceHandlers,

package/dist/src/cli/handlers/init.js

@@ -245,7 +245,7 @@ export const initHandler = {
                 }
                 else if (workerDispatchArg === 'enable') {
                     await writeAiwgConfig(projectDir, { ...existing, parallelism: { ...existing.parallelism, worker_dispatch: true } });
-                    ui.success('  Enabled parallelism.worker_dispatch.');
+                    ui.success('  Enabled parallelism.worker_dispatch. Next: aiwg doctor --probe-workers --qualify.');
                 }
                 else {
                     await writeAiwgConfig(projectDir, { ...existing, setup: { ...existing.setup, worker_dispatch_offer: 'declined' } });
@@ -261,6 +261,7 @@ export const initHandler = {
                     const decision = await askWorkerDispatchOffer(rl, existing.parallelism, existing.setup, ctx.signal);
                     if (decision?.kind === 'enable') {
                         await writeAiwgConfig(projectDir, { ...existing, parallelism: { ...existing.parallelism, worker_dispatch: true } });
+                        ui.info('Next: aiwg doctor --probe-workers --qualify.');
                     }
                     else if (decision?.kind === 'decline') {
                         await writeAiwgConfig(projectDir, { ...existing, setup: { ...existing.setup, worker_dispatch_offer: 'declined' } });
@@ -379,6 +380,8 @@ export const initHandler = {
         config = await populateDeployedTo(config, projectDir);
         // Write
         await writeAiwgConfig(projectDir, config);
+        if (workerDispatchDecision?.kind === 'enable')
+            ui.info('Next: aiwg doctor --probe-workers --qualify.');
         const normalizedAiwgMdPath = await writeNormalizedAiwgMd(projectDir);
         const workspace = await ensureWorkspaceContext(projectDir);
         ui.blank();

package/dist/src/cli/handlers/lint.js

@@ -25,6 +25,11 @@ export const lintHandler = {
     description: 'Lint AIWG artifacts against declarative rule sets',
     category: 'utility',
     aliases: ['-lint', '--lint'],
+    async help() {
+        const { main } = await import('../../lint/cli.js');
+        await main(['--help']);
+        return { exitCode: 0 };
+    },
     async execute(ctx) {
         try {
             const { main } = await import('../../lint/cli.js');

package/dist/src/cli/handlers/models.js

@@ -4,6 +4,7 @@
  */
 import { promises as fs } from 'node:fs';
 import os from 'node:os';
+import { isDeepStrictEqual } from 'node:util';
 import path from 'node:path';
 import { glob } from 'glob';
 import { load as loadYaml } from 'js-yaml';
@@ -11,8 +12,16 @@ import { compileModelPolicy, validateCanonicalModelPolicy, validateUserProjectMo
 import { resolveGrokBuildRoleModel } from '../../models/grok-build-models.js';
 import { readAiwgConfig, emptyConfig } from '../../config/aiwg-config.js';
 import { ConfigLoader } from '../../models/config-loader.js';
-import { loadRecordedWorkerInstallations } from '../../models/worker-installation.mjs';
+import { loadRecordedWorkerInstallations, normalizeWorkerVersionBanner } from '../../models/worker-installation.mjs';
 import { parseWorkerCommandArgs, resolveWorkerInvocation, workerInvocationDiagnostic } from '../../serve/worker-invocation.js';
+/** Compare selection facts without observation times or approval/provenance metadata. */
+function approvalFacts(row) {
+    if (!row.worker)
+        return null;
+    const { observedAt, verifiedAt, firstObservedAt, fetchedAt, retiredAt, evidenceDigest, provenance, qualification, ...facts } = row.worker;
+    return { id: row.id, apiModelId: row.apiModelId, llmProvider: row.llmProvider,
+        hidden: row.hidden, reasoningEfforts: row.reasoningEfforts, facts };
+}
 /**
  * #2892: exported so the MCP worker-invoke bridge can resolve a direct worker
  * plan in-process (same snapshot/driver construction as `aiwg models resolve`),
@@ -30,9 +39,48 @@ export async function loadWorkerInputs(ctx) {
         return { snapshot: { config, models, modelDigests: loader.getInputDigests(), catalog,
                 registry, installations: {} }, drivers: {} };
     }
-    const { registry: qualifiedRegistry, installations, drivers } = await loadRecordedWorkerInstallations({
-        registry, cwd: ctx.cwd, policy: models.defaults.workerSelection,
+    const { registry: qualifiedRegistry, installations, drivers, observations } = await loadRecordedWorkerInstallations({
+        registry, cwd: ctx.cwd, policy: models.defaults.workerSelection, parallelism: config.parallelism,
     });
+    catalog.discovery ??= { source: 'static', fetchedAt: new Date().toISOString(), providers: {} };
+    catalog.discovery.instances = { ...catalog.discovery.instances };
+    for (const [cli, approved] of Object.entries(observations)) {
+        const cached = catalog.discovery.instances[cli] ?? catalog.discovery.providers[approved.provider];
+        // Discovery stores the CLI banner; qualification stores its parsed version.
+        const invocation = drivers[cli]?.qualification.adapter.invocation;
+        const versionPattern = invocation?.kind === 'process' ? invocation.versionPattern : undefined;
+        const version = (value) => {
+            if (value === undefined)
+                return value;
+            try {
+                return normalizeWorkerVersionBanner(value, versionPattern);
+            }
+            catch {
+                return value;
+            } // A changed or invalid banner must still fail closed.
+        };
+        const current = cached ? { ...cached, runtimeVersion: version(cached.runtimeVersion),
+            accountBinding: cached.accountBinding ?? cached.accountScope,
+            models: cached.models.map(row => row.worker ? { ...row,
+                worker: { ...row.worker, runtimeVersion: version(row.worker.runtimeVersion) } } : row) } : undefined;
+        // Stale discovery must not replace a newer approved observation.
+        if (!current || Date.parse(approved.observedAt) > Date.parse(current.observedAt)) {
+            catalog.discovery.instances[cli] = approved;
+            continue;
+        }
+        catalog.discovery.instances[cli] = { ...current, models: current.models.map(row => {
+                const prior = approved.models.find(model => model.id === row.id);
+                if (!row.worker || !prior?.worker)
+                    return row;
+                if (Date.parse(prior.worker.observedAt) > Date.parse(row.worker.observedAt))
+                    return prior;
+                // New retirement/conflict/visibility evidence always requires requalification.
+                const safe = !row.hidden && row.worker.visibility !== 'hidden'
+                    && row.worker.lifecycle !== 'retired' && !row.worker.conflicts?.length;
+                return safe && isDeepStrictEqual(approvalFacts(row), approvalFacts(prior))
+                    ? { ...row, worker: { ...row.worker, qualification: prior.worker.qualification } } : row;
+            }) };
+    }
     return { snapshot: { config, models, modelDigests: loader.getInputDigests(), catalog,
             registry: qualifiedRegistry, installations }, drivers };
 }
@@ -272,9 +320,60 @@ function replaceFrontmatter(raw, item, tier) {
     }
     return `---\n${frontmatter}\n---\n${match[2]}`;
 }
+const MODELS_HELP = `Usage: aiwg models <subcommand> [options]
+
+Subcommands:
+  list                         List discovered agent and skill model policies
+  audit                        Compile selected policies and report diagnostics
+  resolve                      Resolve artifact policies, or a direct worker invocation
+  validate                     Validate selected artifact policies (not worker configuration)
+  sources                      Show the effective model catalog without network refresh
+  refresh                      Refresh model discovery (may access the network)
+  set-default <TIER>           Write defaults.tier to models.json
+  set --tier <TIER>            Update selected agent/skill frontmatter; requires a selector or --all
+  migrate                      Add canonical role/tier hints to legacy skills
+
+Artifact selectors and options:
+  --agent <name>  --skill <name>  --glob <pattern>  --role <role>
+  --tier <tier>  --framework <name>  --all
+  --provider <provider>         Provider for artifact compilation (default: claude)
+  --model <id>                  Explicit Grok Build model for artifact resolve
+  --target <directory>         Artifact/project root (default: current directory)
+  --scope project|user         set-default destination (default: project)
+  --dry-run                    Preview mutations without writing
+  --json                       Emit JSON
+  --drift                      Include catalog drift for sources/refresh
+  --url <url>                  Remote catalog URL for refresh
+  --help, -h                   Show this reference
+  TIER: economy | standard | premium | max-quality
+
+Direct worker resolution (plans an invocation; does not launch it):
+  aiwg models resolve --role <role> --task <class> --group <group>
+    --brief <file> --workdir <tree> --final-output <file>
+    [--transport shell|mcp] [--format json|shell] [--authorize-premium]
+  --role                       efficiency | coding | reasoning
+  --task                       Task class from defaults.workerSelection.taskClasses
+                               Built-ins: inventory, implementation, architecture, review
+  --group                      Group from parallelism.groups and the role's guidance
+  --brief                      Absolute path to the task brief
+  --workdir                    Absolute path to the worker tree
+  --final-output               Absolute path for the final result
+  --transport                  Must match group execution transport (default: shell)
+  --format                     JSON plan or POSIX shell command (default: json)
+  --json                       Alias for --format json
+  --authorize-premium          Authorize premium for this resolution only
+                               Agents require explicit human confirmation of escalation
+
+Worker groups live in .aiwg/aiwg.config; role guidance lives in project-root models.json.
+Configure both, then run aiwg doctor --probe-workers --qualify.
+See docs/getting-started/worker-dispatch.md for a complete example.`;
 async function execute(ctx, services = { load: loadWorkerInputs }) {
+    if (ctx.args.length === 0 || ctx.args[0] === 'help' || ctx.args.includes('--help') || ctx.args.includes('-h')) {
+        print(MODELS_HELP, false);
+        return { exitCode: 0 };
+    }
     // Preserve artifact/native resolve when direct-only flags are absent.
-    if (ctx.args[0] === 'resolve' && ctx.args.slice(1).some(arg => /^--(?:task|group|brief|workdir|final-output|transport|format)(?:=|$)/.test(arg))) {
+    if (ctx.args[0] === 'resolve' && ctx.args.slice(1).some(arg => /^--(?:task|group|brief|workdir|final-output|transport|format|authorize-premium)(?:=|$)/.test(arg))) {
         return resolveDirect(ctx, services);
     }
     const parsed = parseArgs(ctx.args);
@@ -290,10 +389,6 @@ async function execute(ctx, services = { load: loadWorkerInputs }) {
     const provider = flagString(parsed, 'provider') ?? 'claude';
     if (!PROVIDERS.has(provider))
         return { exitCode: 2, message: `Unknown provider: ${provider}` };
-    if (parsed.subcommand === 'help' || parsed.flags.has('help')) {
-        print('Usage: aiwg models <audit|list|resolve|sources|refresh|set-default|set|validate|migrate> [selectors] [--provider P] [--dry-run] [--json]', json);
-        return { exitCode: 0 };
-    }
     if (parsed.subcommand === 'sources' || parsed.subcommand === 'refresh') {
         const { diffModelCatalog } = await import('../../models/model-discovery.js');
         const catalog = await effectiveCatalog(ctx, target, parsed.subcommand === 'refresh', parsed, provider);
@@ -438,6 +533,7 @@ export const modelsHandler = {
     description: 'Audit, resolve, validate, and safely update model policy',
     category: 'catalog',
     aliases: [],
+    help: async () => ({ exitCode: 0, message: MODELS_HELP, rawOutput: true }),
     execute,
 };
 export function createModelsHandler(services) {

package/dist/src/cli/handlers/ralph-launcher.js

@@ -296,6 +296,8 @@ export function saveLauncherRegistry(projectRoot, registry) {
  * Check if a process is still running
  */
 export function isProcessAlive(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
     try {
         process.kill(pid, 0);
         return true;

package/dist/src/cli/handlers/refresh.js

@@ -572,6 +572,7 @@ export const refreshHandler = {
                         // #2507: give operators a reclaim path for artifacts an older
                         // AIWG left behind without a managed marker.
                         ...(forceDeploy ? ['--force'] : []),
+                        ...(hasFlag(ctx.args, '--allow-over-budget') ? ['--allow-over-budget'] : []),
                         ...modelDeployArgs,
                     ],
                     rawArgs: ['use', fw],
@@ -596,6 +597,17 @@ export const refreshHandler = {
                 }
             }
         }
+        // Runtime updates can change the corpus even when there are no recorded
+        // deployments. Refresh both discovery representations, independently of use.
+        if (!dryRun) {
+            try {
+                const { refreshFrameworkCapabilities } = await import('../../artifacts/framework-capabilities.js');
+                await refreshFrameworkCapabilities(frameworkRoot, true, { force: true });
+            }
+            catch (error) {
+                ui.warn(`Capability index refresh failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
         // Step 4.25: Report planned project-local deploys (#1035).
         // The active use handler performs the actual project-local deploy during
         // framework refresh; this block surfaces dry-run and completion details.

package/dist/src/cli/handlers/resource-versions.js

@@ -159,6 +159,9 @@ export const versionsHandler = {
     description: "Browse and resolve signed AIWG web resource releases",
     category: "index",
     aliases: [],
+    async help() {
+        return { exitCode: 0, message: usage(), rawOutput: true };
+    },
     async execute(ctx) {
         if (ctx.args[0] === "help" || ctx.args[0] === "--help" || ctx.args[0] === "-h") {
             console.log(usage());

package/dist/src/cli/handlers/rules.js

@@ -0,0 +1,195 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { loadRulePinConfigs, selectorKey, validateRulePinCapabilities } from '../../rules/pins.mjs';
+const usage = `Usage: aiwg rules pin|unpin [rule...] [--tier critical,high] [--capability id,... | --group name] [--all-tiers] [--all]
+       aiwg rules pinned [--capability id] [--json]
+       aiwg rules inventory|list [--scope workspace|user|installation|catalog] [--capability id,...] [--activation mode,...] [--tier level,...] [--provider name] [--bodies] [--json]
+       aiwg rules group set <name> <capability>... | group list
+Flags: --project (default), --user, --dry-run, --no-deploy, --json, --allow-over-budget
+Pins and group changes validate every input without prompting. --dry-run prints effective rules and per-provider startup bytes.`;
+const valueFlags = new Set(['--tier', '--capability', '--group', '--scope', '--activation', '--provider']);
+const boolFlags = new Set(['--all-tiers', '--all', '--dry-run', '--no-deploy', '--json', '--allow-over-budget', '--user', '--project', '--help', '-h', '--bodies']);
+function parse(args) {
+    const values = new Map();
+    const flags = new Set();
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (valueFlags.has(arg)) {
+            if (!args[i + 1] || args[i + 1].startsWith('-') || values.has(arg))
+                throw new Error(`${arg} requires one value`);
+            values.set(arg, args[++i]);
+        }
+        else if (boolFlags.has(arg))
+            flags.add(arg);
+        else if (arg.startsWith('-'))
+            throw new Error(`Unknown flag: ${arg}`);
+        else
+            positional.push(arg);
+    }
+    if (flags.has('--user') && flags.has('--project'))
+        throw new Error('Choose --project or --user');
+    const list = (flag) => values.get(flag)?.split(',').map(id => id.trim());
+    return { values, flags, positional, list };
+}
+// Provider helpers log progress while assembling staged output. Keep the command's
+// stdout a single JSON document (and keep temporary staging paths out of text output).
+async function quietDeployment(deploy, options) {
+    const log = console.log;
+    const warn = console.warn;
+    try {
+        console.log = () => { };
+        console.warn = () => { };
+        return await deploy(options);
+    }
+    finally {
+        console.log = log;
+        console.warn = warn;
+    }
+}
+export const rulesHandler = {
+    id: 'rules', name: 'Rule pins', category: 'config', aliases: [],
+    description: 'Pin rules to every request, inspect pins, and manage capability groups',
+    async help() { return { exitCode: 0, message: usage, rawOutput: true }; },
+    async execute(ctx) {
+        const json = ctx.args.includes('--json');
+        try {
+            const { values, flags, positional, list } = parse(ctx.args);
+            if (flags.has('--help') || flags.has('-h') || !positional.length)
+                return { exitCode: 0, message: usage, rawOutput: true };
+            const { rulePinState } = await import('../../rules/pin-state.js');
+            const { setRuleConfigKey } = await import('../../config/cli.js');
+            const [command, ...ids] = positional;
+            if (command === 'inventory' || command === 'list') {
+                if (ids.length || values.has('--group') || [...flags].some(flag => !['--json', '--bodies'].includes(flag)))
+                    throw new Error('inventory accepts only inventory filters and output flags');
+                const scope = values.get('--scope') ?? 'workspace';
+                if (!['workspace', 'user', 'installation', 'catalog'].includes(scope))
+                    throw new Error('Invalid inventory scope');
+                const activation = list('--activation');
+                const tier = list('--tier');
+                if (activation?.some(value => !['kernel', 'summary', 'bound', 'paths', 'on-demand'].includes(value)))
+                    throw new Error('Invalid activation filter');
+                if (tier?.some(value => !['critical', 'high', 'medium', 'low'].includes(value)))
+                    throw new Error('Invalid tier filter');
+                if (list('--capability')?.some(value => !value))
+                    throw new Error('Invalid capability filter');
+                const { ruleInventory } = await import('../../rules/inventory.js');
+                const report = await ruleInventory(ctx.cwd, ctx.frameworkRoot, { scope: scope, capability: list('--capability'), activation, enforcement: tier, provider: values.get('--provider'), bodies: flags.has('--bodies') });
+                return { exitCode: 0, rawOutput: true, message: json ? JSON.stringify(report, null, 2) :
+                        [`Scope: ${report.scope} (${report.scope_description})`, 'Per-rule delivery and session loading: unknown.', ...report.rules.map(rule => `${rule.capability}/${rule.name} [${rule.effective_activation ?? 'unconfigured'}, ${rule.enforcement ?? 'unknown'}]: ${rule.summary ?? '(no summary)'}; ${rule.fetch_command ?? 'fetch ID unknown'}${rule.content ? `\n${rule.content}` : ''}`), ...report.warnings, ...(!report.rules.length ? ['No matching rules.'] : [])].join('\n') };
+            }
+            if (values.has('--scope') || values.has('--activation') || values.has('--provider') || flags.has('--bodies'))
+                throw new Error('Inventory filters are only valid for rules inventory');
+            const source = flags.has('--user') ? 'user' : 'project';
+            const configs = loadRulePinConfigs(ctx.cwd);
+            const before = rulePinState(ctx.cwd, ctx.frameworkRoot, configs, true);
+            if (command === 'pinned') {
+                if (ids.length || [...values.keys()].some(key => key !== '--capability'))
+                    throw new Error('pinned accepts only --capability and output/scope flags');
+                const filter = list('--capability');
+                if (filter?.some(id => !before.installed.includes(id)))
+                    throw new Error(`Unknown capability. Installed ids: ${before.installed.join(', ')}`);
+                const rules = before.rules.filter(rule => !filter || filter.includes(rule.capability?.replace(/^(framework|addon|extension|plugin):/, '') || ''));
+                return { exitCode: 0, message: json ? JSON.stringify({ rules, warnings: before.warnings }, null, 2)
+                        : [...rules.map(rule => `${rule.name}: pinned kernel (canonical ${rule.canonical_activation}) ${rule.matches.map(match => `${match.source}: ${JSON.stringify(match.selector)}`).join('; ')}`), ...before.warnings, ...(!rules.length ? ['No effective rule pins.'] : [])].join('\n'), rawOutput: true };
+            }
+            if (command === 'group' && ids[0] === 'list') {
+                if (ids.length !== 1 || values.size)
+                    throw new Error('Usage: aiwg rules group list');
+                const groups = { user: configs.user.rules?.pin_groups || {}, project: configs.project.rules?.pin_groups || {} };
+                return { exitCode: 0, message: JSON.stringify(groups, null, 2), rawOutput: true };
+            }
+            const selected = configs[source];
+            selected.rules = { ...selected.rules };
+            if (command === 'group') {
+                const [action, name, ...capabilities] = ids;
+                if (action !== 'set' || !name || !capabilities.length || values.size)
+                    throw new Error('Usage: aiwg rules group set <name> <capability>...');
+                selected.rules.pin_groups = { ...selected.rules.pin_groups, [name]: [...new Set(capabilities.flatMap(id => id.split(',')))].sort() };
+            }
+            else if (command === 'pin' || command === 'unpin') {
+                if (flags.has('--all-tiers') && values.has('--tier'))
+                    throw new Error('--all-tiers and --tier are mutually exclusive');
+                const selector = {};
+                if (ids.length)
+                    selector.rules = [...new Set(ids)].sort();
+                if (values.has('--tier'))
+                    selector.enforcement = list('--tier');
+                if (values.has('--capability'))
+                    selector.capabilities = list('--capability');
+                if (values.has('--group'))
+                    selector.group = values.get('--group');
+                if (flags.has('--all'))
+                    selector.all = true;
+                if (!Object.keys(selector).length)
+                    throw new Error('Supply rule ids, --tier, --capability, --group, or --all');
+                if (flags.has('--all-tiers') && !selector.capabilities && !selector.group && !selector.all)
+                    throw new Error('--all-tiers requires --capability, --group or --all');
+                const existing = selected.rules.always_load || [];
+                const key = selectorKey(selector);
+                if (command === 'pin') {
+                    const unknown = ids.filter(id => !before.inventory.some(rule => [rule.name, rule.id, rule.path].includes(id)));
+                    if (unknown.length)
+                        throw new Error(`Unknown installed rule ids: ${unknown.join(', ')}`);
+                    selected.rules.always_load = existing.some(item => selectorKey(item) === key) ? existing : [...existing, selector];
+                }
+                else
+                    selected.rules.always_load = existing.filter(item => selectorKey(item) !== key);
+            }
+            else
+                throw new Error(usage);
+            // Only the edited scope is strict: stale pins in another scope remain visible warnings.
+            const errors = validateRulePinCapabilities(selected.rules, before.installed, { ...configs.user.rules?.pin_groups, ...configs.project.rules?.pin_groups });
+            if (errors.length)
+                throw new Error(errors.join('\n'));
+            const after = rulePinState(ctx.cwd, ctx.frameworkRoot, configs, true);
+            const providers = [...new Set([...(configs.project.providers || []), ...Object.values(configs.project.installed || {}).flatMap(entry => Object.keys(entry.deployedTo || {}))])];
+            const reports = [];
+            const failures = [];
+            const plans = [];
+            // Use precisely the installed rule inventory, including local bundles; do not select new capabilities.
+            for (const provider of providers) {
+                if (!['claude', 'codex', 'cursor', 'hermes', 'warp', 'openclaw'].includes(provider)) {
+                    failures.push(`Rule pin projection is unavailable for provider '${provider}'`);
+                    continue;
+                }
+                const module = await import(pathToFileURL(path.join(ctx.frameworkRoot, 'tools/agents/providers', `${provider}.mjs`)).href);
+                const options = { srcRoot: path.join(ctx.frameworkRoot, 'agentic/code'), target: ctx.cwd, mode: 'all',
+                    ruleSources: after.inventory.map(rule => rule.path), config: configs.project, pinConfigs: configs,
+                    rulesOnly: true, deployRules: true, deploySkills: false, deployCommands: false,
+                    force: true, quiet: true, allowOverBudget: flags.has('--allow-over-budget') };
+                try {
+                    const report = await quietDeployment(module.deploy, { ...options, dryRun: true, previewReport: true });
+                    reports.push(report);
+                    plans.push({ deploy: module.deploy, options });
+                }
+                catch (error) {
+                    failures.push(`${provider}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            if (failures.length)
+                throw new Error(failures.join('\n'));
+            const dryRun = flags.has('--dry-run') || ctx.dryRun;
+            if (!dryRun) {
+                await setRuleConfigKey(ctx.cwd, source, 'rules', JSON.stringify(selected.rules));
+                if (!flags.has('--no-deploy'))
+                    for (const plan of plans)
+                        await quietDeployment(plan.deploy, plan.options);
+            }
+            const redeploy = 'aiwg refresh --skip-update --force' + (flags.has('--allow-over-budget') ? ' --allow-over-budget' : '');
+            const needsRedeploy = flags.has('--no-deploy') || plans.length === 0;
+            const output = { dry_run: !!dryRun, source, rules: after.rules, warnings: after.warnings, providers: reports,
+                deployed: !dryRun && !needsRedeploy, ...(needsRedeploy ? { redeploy } : {}) };
+            return { exitCode: 0, message: json ? JSON.stringify(output, null, 2)
+                    : [dryRun ? 'Rule pin preview (config unchanged)' : 'Rule pins updated', ...after.rules.map(rule => `${rule.name}: kernel (canonical ${rule.canonical_activation})`),
+                        ...reports.map(report => { const r = report; return `${r.provider}: ${r.selected_bytes} startup bytes${report.exceeded ? ' (over budget; explicitly allowed)' : ''}`; }),
+                        ...after.warnings, ...(needsRedeploy ? [`Redeploy: ${redeploy}`] : [])].join('\n'), rawOutput: true };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { exitCode: 1, message: json ? JSON.stringify({ error: message }) : message, rawOutput: json };
+        }
+    },
+};
+//# sourceMappingURL=rules.js.map

package/dist/src/cli/handlers/run.js

@@ -62,6 +62,10 @@ export const runHandler = {
     description: 'Run a user-defined script from aiwg.config',
     category: 'utility',
     aliases: [],
+    async help() {
+        printRunUsage();
+        return { exitCode: 0 };
+    },
     async execute(ctx) {
         let parsed;
         try {