@aiwg/cli 2026.10.1 → 2026.10.4

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

@@ -1,11 +1,11 @@
-import { askDecision, DecisionAskUsageError, decisionCapabilities, evaluateRequestPath, listPatterns, livePlan, materializeSyntheticClassificationSetup, readDecisionContextFile, 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> [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] [--json]',
+        '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] [--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',
@@ -17,7 +17,33 @@ function usage() {
         '  evaluate --request <path> [--host-policy-module <path>]',
         '  setup synthetic-classification [--output-dir <dir>]',
         '  setup jev [--token-stdin] [--region <r>] [--endpoint <url>] [--verify] [--remove]',
-        '  ask --question "<q>" (--yes-no | --choices a,b,c | --scale 1-5)',
+        '  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|passes|escalation] [--json]',
+        '',
+        'Notes:',
+        '  Every COMPLETED `ask` call (CLI and MCP) appends one record to the decision',
+        '  ledger (.aiwg/decision/ledger.jsonl, resolved like `aiwg artifacts path`).',
+        '  Usage errors (bad flags, oversized context) are never recorded. Question',
+        '  and context text are never written unless --record-text is passed, and even',
+        '  then only after redaction and truncation to a documented size cap. Every',
+        '  other persisted field (session, caller, choice ids, answer, model, provider,',
+        '  project root) is also redacted before being written. `questionDigest` and',
+        '  `contextDigest` are plain SHA-256 over the raw text: a short, predictable',
+        '  question can still be matched by hashing candidate guesses, so a digest is',
+        '  not a confidentiality guarantee on its own.',
+        '  `history` and `stats` read that ledger offline — no network, no Jev call.',
+        '  `--since` is strict ISO-8601: a bare date or an offsetless timestamp is',
+        '  interpreted as UTC; invalid calendar dates (e.g. 2026-02-30) are rejected,',
+        '  including when an explicit offset is present.',
+        `  --session and --caller must match ${ATTRIBUTION_FIELD_PATTERN.source} (<= ${MAX_ATTRIBUTION_FIELD_LENGTH} characters).`,
+        '  `history`/`stats` accept `--caller <tag>` (exact), `--caller \'<prefix>*\'` (prefix; the only wildcard), or `--no-caller` (records with no tag; not combinable with `--caller`).',
+        '  `history`/`stats` reject unknown flags and positional arguments with exit 2.',
+        '  The ledger has no built-in retention: it grows without bound and the',
+        '  operator may truncate or delete it at any time; readers tolerate a missing',
+        '  file. The ledger trusts only the local filesystem under the project',
+        '  artifact root, owned by the same user running aiwg — it is not a defense',
+        '  against a hostile process already running as that user.',
     ].join('\n');
 }
 function takeOption(args, name) {
@@ -62,6 +88,16 @@ function parseScale(value) {
         throw new DecisionAskUsageError('invalid-scale', '--scale requires a range like 1-5');
     return { low: Number(match[1]), high: Number(match[2]) };
 }
+/** Shared by --session and --caller (review r1 finding 1): a conservative identifier shape, rejected with exit 2. */
+function takeAttributionOption(args, name, reason) {
+    const value = takeOption(args, name);
+    if (value === undefined)
+        return undefined;
+    if (!ATTRIBUTION_FIELD_PATTERN.test(value)) {
+        throw new DecisionAskUsageError(reason, `${name} must match ${ATTRIBUTION_FIELD_PATTERN.source} (<= ${MAX_ATTRIBUTION_FIELD_LENGTH} characters)`);
+    }
+    return value;
+}
 async function decisionSetupJev(rest) {
     const token = rest.includes('--token-stdin') ? (await readStdin()).trim() : undefined;
     const result = await setupJev({
@@ -81,6 +117,9 @@ async function decisionAsk(ctx) {
     const contextModes = flagCount(args, ['--context', '--context-file', '--context-stdin']);
     if (contextModes > 1)
         throw new DecisionAskUsageError('invalid-context', 'Select at most one context source');
+    // Validated before any Jev call, so a malformed attribution flag never wastes one.
+    const explicitSessionId = takeAttributionOption(args, '--session', 'invalid-session');
+    const caller = takeAttributionOption(args, '--caller', 'invalid-caller');
     const question = args.includes('--question') ? takeRequiredOption(args, '--question') : '';
     let context = takeOption(args, '--context');
     if (args.includes('--context') && (context === undefined || context.startsWith('--'))) {
@@ -100,16 +139,186 @@ 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 });
+    const invocation = await runDecisionOffloadCheckpoint(input, {
+        transport: 'cli',
+        projectRoot: ctx.cwd,
+        env: process.env,
+        explicitProvider: takeOption(args, '--provider'),
+        explicitSessionId,
+        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')
         return { exitCode: 0, message: `FALLBACK to LLM: ${result.reason}`, rawOutput: true };
     return { exitCode: 0, message: `${String(result.answer)} (confidence ${result.confidence?.toFixed(2) ?? 'unknown'}, ${result.model ?? 'unknown-model'})`, rawOutput: true };
 }
+function parseSince(value) {
+    if (value === undefined)
+        return undefined;
+    try {
+        return parseDecisionLedgerSince(value);
+    }
+    catch (error) {
+        if (error instanceof DecisionLedgerSinceError)
+            throw new DecisionAskUsageError('invalid-since', error.message);
+        throw error;
+    }
+}
+const DECISION_LEDGER_KINDS = ['yes-no', 'choices', 'scale'];
+const DECISION_LEDGER_STATUSES = ['answered', 'fallback'];
+const DECISION_LEDGER_GROUP_BYS = ['provider', 'session', 'kind', 'caller', 'passes', 'escalation'];
+function parseKindFilter(value) {
+    if (value === undefined)
+        return undefined;
+    if (!DECISION_LEDGER_KINDS.includes(value)) {
+        throw new DecisionAskUsageError('invalid-kind', `--kind must be one of ${DECISION_LEDGER_KINDS.join(', ')}`);
+    }
+    return value;
+}
+function parseStatusFilter(value) {
+    if (value === undefined)
+        return undefined;
+    if (!DECISION_LEDGER_STATUSES.includes(value)) {
+        throw new DecisionAskUsageError('invalid-status', `--status must be one of ${DECISION_LEDGER_STATUSES.join(', ')}`);
+    }
+    return value;
+}
+function parseGroupBy(value) {
+    if (value === undefined)
+        return undefined;
+    if (!DECISION_LEDGER_GROUP_BYS.includes(value)) {
+        throw new DecisionAskUsageError('invalid-group-by', `--group-by must be one of ${DECISION_LEDGER_GROUP_BYS.join(', ')}`);
+    }
+    return value;
+}
+const HISTORY_VALUE_FLAGS = ['--since', '--provider', '--session', '--kind', '--status', '--caller'];
+const HISTORY_BOOL_FLAGS = ['--json', '--no-caller'];
+const STATS_VALUE_FLAGS = [...HISTORY_VALUE_FLAGS, '--group-by'];
+const STATS_BOOL_FLAGS = HISTORY_BOOL_FLAGS;
+/**
+ * Strict allow-list for `history`/`stats`: unknown `--flags` and positional
+ * arguments are usage errors (exit 2) naming the offending token, instead of
+ * being silently ignored. `ask`/`setup` parsing is intentionally untouched.
+ */
+function assertLedgerArgs(args, valueFlags, boolFlags) {
+    let index = 0;
+    while (index < args.length) {
+        const token = args[index];
+        if (valueFlags.includes(token)) {
+            if (args[index + 1] === undefined)
+                throw new DecisionAskUsageError(`missing-${token.slice(2)}`, `${token} requires a value`);
+            index += 2;
+            continue;
+        }
+        if (boolFlags.includes(token)) {
+            index += 1;
+            continue;
+        }
+        if (token.startsWith('--'))
+            throw new DecisionAskUsageError('unknown-flag', `unknown flag ${token}`);
+        throw new DecisionAskUsageError('unexpected-argument', `unexpected argument ${token}`);
+    }
+}
+/**
+ * Parses `--caller <tag>` for `history`/`stats`: an exact match, except a
+ * single trailing `*` means prefix match (`--caller 'address-issues:*'`).
+ * The tag itself must match the attribution shape; `--no-caller` (records
+ * with no caller tag) is parsed separately and cannot be combined with it.
+ */
+function parseCallerFilter(args) {
+    const raw = takeOption(args, '--caller');
+    const noCaller = args.includes('--no-caller');
+    if (raw !== undefined && noCaller) {
+        throw new DecisionAskUsageError('invalid-caller-filter', '--caller and --no-caller cannot be used together');
+    }
+    if (noCaller)
+        return { noCaller: true };
+    if (raw === undefined)
+        return {};
+    if (raw === '' || raw.startsWith('--')) {
+        throw new DecisionAskUsageError('invalid-caller', '--caller requires a non-empty value');
+    }
+    const prefix = raw.endsWith('*');
+    const tag = prefix ? raw.slice(0, -1) : raw;
+    if (tag === '' || !ATTRIBUTION_FIELD_PATTERN.test(tag)) {
+        throw new DecisionAskUsageError('invalid-caller', `--caller must match ${ATTRIBUTION_FIELD_PATTERN.source} (<= ${MAX_ATTRIBUTION_FIELD_LENGTH} characters), allowing one trailing *`);
+    }
+    return prefix ? { callerPrefix: tag } : { caller: tag };
+}
+/** Shared by `history` and `stats` (review r1 finding 9): the same filters, parsed the same way. */
+function parseLedgerFilters(args) {
+    return {
+        since: parseSince(takeOption(args, '--since')),
+        provider: takeOption(args, '--provider'),
+        sessionId: takeOption(args, '--session'),
+        kind: parseKindFilter(takeOption(args, '--kind')),
+        status: parseStatusFilter(takeOption(args, '--status')),
+        ...parseCallerFilter(args),
+    };
+}
+/** One header line stating the caller filter, shown only when one is set. */
+function callerFilterHeader(filters) {
+    if (filters.noCaller)
+        return 'Caller filter: no caller (records with no caller tag)';
+    if (filters.caller !== undefined)
+        return `Caller filter: ${filters.caller}`;
+    if (filters.callerPrefix !== undefined)
+        return `Caller filter: ${filters.callerPrefix}*`;
+    return null;
+}
+async function decisionHistory(ctx) {
+    const args = ctx.args.slice(1);
+    assertLedgerArgs(args, HISTORY_VALUE_FLAGS, HISTORY_BOOL_FLAGS);
+    const filters = parseLedgerFilters(args);
+    const result = await decisionLedgerHistory(ctx.cwd, filters);
+    if (args.includes('--json'))
+        return jsonResult(result);
+    const header = result.skipped > 0 ? [`(${result.skipped} invalid line(s) skipped)`] : [];
+    const callerHeader = callerFilterHeader(filters);
+    if (callerHeader)
+        header.push(callerHeader);
+    if (result.count === 0)
+        return { exitCode: 0, message: [...header, 'No decision ledger records match the filters.'].join('\n'), rawOutput: true };
+    const lines = result.records.map(record => `${record.timestamp}  ${record.status.padEnd(8)} provider=${record.provider} kind=${record.decisionKind} confidence=${record.confidence ?? '-'} caller=${record.caller ?? '-'} id=${record.id}`);
+    return { exitCode: 0, message: [...header, ...lines].join('\n'), rawOutput: true };
+}
+async function decisionStats(ctx) {
+    const args = ctx.args.slice(1);
+    assertLedgerArgs(args, STATS_VALUE_FLAGS, STATS_BOOL_FLAGS);
+    const filters = { ...parseLedgerFilters(args), groupBy: parseGroupBy(takeOption(args, '--group-by')) };
+    const result = await decisionLedgerStats(ctx.cwd, filters);
+    if (args.includes('--json'))
+        return jsonResult(result);
+    const header = result.skipped > 0 ? [`(${result.skipped} invalid line(s) skipped)`] : [];
+    const callerHeader = callerFilterHeader(filters);
+    if (callerHeader)
+        header.push(callerHeader);
+    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, 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}`,
+        `  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 };
+}
 async function executeDecision(ctx) {
     const [command, subcommand, ...rest] = ctx.args;
     const options = { cwd: ctx.cwd, frameworkRoot: ctx.frameworkRoot, env: process.env };
@@ -120,6 +329,10 @@ async function executeDecision(ctx) {
             return jsonResult(decisionCapabilities(options));
         if (command === 'ask')
             return await decisionAsk(ctx);
+        if (command === 'history')
+            return await decisionHistory(ctx);
+        if (command === 'stats')
+            return await decisionStats(ctx);
         if (command === 'patterns') {
             if (subcommand === 'list')
                 return jsonResult(listPatterns());

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

@@ -26,6 +26,8 @@ import { getLoggerInfo } from '../log.js';
 import { readAiwgConfig, getProjectDir } from '../../config/aiwg-config.js';
 import { getLogger } from '../log.js';
 import { spawnSync } from 'child_process';
+import { boundedSpawnSync } from '../../process/bounded-child-process.mjs';
+import { exitCodeForSpawnResult } from '../child-process-result.js';
 import { readFileSync, writeFileSync, existsSync, statSync, readdirSync, mkdtempSync, rmSync } from 'fs';
 import path from 'path';
 import os from 'os';
@@ -85,9 +87,14 @@ export const diagnoseHandler = {
             }
             // tar it up via system tar. We rely on GNU/BSD tar being present;
             // degrade gracefully if not.
-            const tar = spawnSync('tar', ['-czf', outPath, '-C', stage, '.'], { stdio: 'pipe' });
+            // Packaging a small local diagnostics bundle; quick tier (#3062).
+            const tar = boundedSpawnSync('tar', ['-czf', outPath, '-C', stage, '.'], 'quick', { stdio: 'pipe' });
             if (tar.status !== 0) {
-                ui.error(`tar failed: ${tar.stderr?.toString() ?? '(no stderr)'}`);
+                // #3062 review item 7: already correctly treats a null status
+                // (timeout/signal) as failure; surface the bounded helper's
+                // diagnostic (e.g. the enriched timeout message) ahead of stderr.
+                const detail = exitCodeForSpawnResult(tar).message ?? tar.stderr?.toString() ?? '(no stderr)';
+                ui.error(`tar failed: ${detail}`);
                 ui.info(`Bundle contents staged at: ${stage}`);
                 ui.info(`You can tar it manually: tar -czf ${outName} -C ${stage} .`);
                 return { exitCode: 1, error: new Error('tar failed') };
@@ -200,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 [
@@ -225,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/feedback.js

@@ -19,11 +19,12 @@
  *
  * @issue #885
  */
-import { spawnSync } from 'child_process';
+import { boundedSpawnSync } from '../../process/bounded-child-process.mjs';
 import os from 'os';
 import { readAiwgConfig } from '../../config/aiwg-config.js';
 import { createPromptInterface, askString, askChoice } from '../prompt-utils.js';
 import { debug } from '../log.js';
+import { exitCodeForSpawnResult } from '../child-process-result.js';
 // ── GitHub repo ───────────────────────────────────────────────────────────────
 const GITHUB_REPO = 'jmagly/aiwg';
 const GITHUB_ISSUES_URL = `https://github.com/${GITHUB_REPO}/issues/new`;
@@ -57,7 +58,7 @@ async function collectSystemContext(cwd) {
     // aiwg version from package.json if available
     let aiwgVersion = 'unknown';
     try {
-        const r = spawnSync(process.execPath, [process.argv[1], 'version'], {
+        const r = boundedSpawnSync(process.execPath, [process.argv[1], 'version'], 'quick', {
             encoding: 'utf-8',
             stdio: 'pipe',
         });
@@ -235,7 +236,7 @@ async function promptSelect(question, options, signal) {
 // ── Submission ────────────────────────────────────────────────────────────────
 function hasGhCli() {
     try {
-        const r = spawnSync('gh', ['--version'], { stdio: 'pipe' });
+        const r = boundedSpawnSync('gh', ['--version'], 'quick', { stdio: 'pipe' });
         return r.status === 0;
     }
     catch {
@@ -244,7 +245,14 @@ function hasGhCli() {
 }
 function submitViaGh(title, body, type) {
     const label = type === 'bug' ? 'bug' : type === 'feature' ? 'enhancement' : type === 'doc' ? 'documentation' : 'feedback';
-    const result = spawnSync('gh', ['issue', 'create', '--repo', GITHUB_REPO, '--title', title, '--body', body, '--label', label], { stdio: 'inherit' });
+    // Creates a GitHub issue via the `gh` CLI (network call); network tier (#3062).
+    const result = boundedSpawnSync('gh', ['issue', 'create', '--repo', GITHUB_REPO, '--title', title, '--body', body, '--label', label], 'network', { stdio: 'inherit' });
+    // #3062 review item 7: already correctly treats a null status
+    // (timeout/signal) as failure; surface the bounded helper's diagnostic
+    // under AIWG_DEBUG — the caller falls back to the browser either way.
+    const { message } = exitCodeForSpawnResult(result, 'gh issue create');
+    if (message)
+        debug('cli:feedback:gh', message);
     return result.status === 0;
 }
 function submitViaBrowser(title, body) {
@@ -260,7 +268,8 @@ function submitViaBrowser(title, body) {
             : process.platform === 'win32'
                 ? 'start'
                 : 'xdg-open';
-        spawnSync(openCmd, [urlStr], { stdio: 'ignore' });
+        // Fire-and-forget local browser launch; quick tier (#3062).
+        boundedSpawnSync(openCmd, [urlStr], 'quick', { stdio: 'ignore' });
         console.log(`\n  Opened GitHub in your browser to file the issue.`);
         console.log(`  If the browser did not open, visit:\n  ${urlStr}`);
     }

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,