@aiwg/cli 2026.10.0 → 2026.10.3

package/dist/src/cli/env.js

@@ -25,9 +25,24 @@
  *
  * Handlers MUST call this helper instead of re-deriving the check locally.
  * Divergent isTTY checks scattered across handlers have caused bugs in the
- * past (#918 audit findings).
+ * past (#918 audit findings, and #3062 review item 12: `init` only checked
+ * `CI === 'true'`, `setup project` ignored CI/TERM entirely, and `session`
+ * ignored its own `--non-interactive` flag — each reinventing a narrower
+ * version of this same check instead of using it).
+ *
+ * @param explicitNonInteractive When `true`, short-circuits to `false`
+ *   without inspecting the environment at all. Pass the caller's own
+ *   explicit non-interactive flag here (e.g. `--non-interactive`, or
+ *   `--yes` where it means "don't prompt") so the single interactive
+ *   decision takes the command's explicit flags as input, rather than
+ *   every call site re-deriving its own mix of flag-vs-environment
+ *   precedence. Omit it (or pass `false`) to fall through to the
+ *   environment-only checks below, unchanged from before this parameter
+ *   existed.
  */
-export function isInteractive() {
+export function isInteractive(explicitNonInteractive = false) {
+    if (explicitNonInteractive)
+        return false;
     if (!process.stdin.isTTY)
         return false;
     if (!process.stdout.isTTY)
@@ -40,25 +55,32 @@ export function isInteractive() {
         return false;
     return true;
 }
+/**
+ * Variables that mark a continuous-integration environment. Exported so tests
+ * that need the interactive path can clear exactly what `isCI()` reads.
+ */
+export const CI_ENV_VARS = [
+    'CI',
+    'CONTINUOUS_INTEGRATION',
+    'BUILD_NUMBER',
+    'RUN_ID',
+    'GITHUB_ACTIONS',
+    'GITLAB_CI',
+    'CIRCLECI',
+    'TRAVIS',
+    'BUILDKITE',
+    'JENKINS_URL',
+    'TF_BUILD', // Azure DevOps
+    'TEAMCITY_VERSION',
+];
+/** Other variables `isInteractive()` reads. */
+export const INTERACTIVE_ENV_VARS = ['TERM', 'DEBIAN_FRONTEND'];
 /**
  * Return true iff we're running in a continuous-integration environment.
  * Checks the common CI env vars set by major CI systems.
  */
 export function isCI() {
-    const ciVars = [
-        'CI',
-        'CONTINUOUS_INTEGRATION',
-        'BUILD_NUMBER',
-        'RUN_ID',
-        'GITHUB_ACTIONS',
-        'GITLAB_CI',
-        'CIRCLECI',
-        'TRAVIS',
-        'BUILDKITE',
-        'JENKINS_URL',
-        'TF_BUILD', // Azure DevOps
-        'TEAMCITY_VERSION',
-    ];
+    const ciVars = CI_ENV_VARS;
     for (const v of ciVars) {
         const val = process.env[v];
         if (val && val !== '0' && val.toLowerCase() !== 'false')

package/dist/src/cli/flag-parsing.js

@@ -0,0 +1,236 @@
+/**
+ * Shared strict CLI flag/value parsing (#3062 review item 11, and the
+ * second-round review's finding 4).
+ *
+ * Several handlers (`init`, `setup`, `session`, `setup-run`) each grew
+ * their own small `flagValue(args, name)` helper, and every one of them
+ * treated a flag that is present but missing its value the same as a flag
+ * that was never given at all — `--prompt` as the very last token, or
+ * immediately followed by another flag, silently resolved to `undefined`
+ * instead of erroring. At a terminal that let the handler fall through
+ * into an interactive prompt instead of reporting the mistake; without one
+ * it could proceed on a silently-wrong default.
+ *
+ * The first-round shared parser fixed that but introduced its own gaps,
+ * found by the second review:
+ *
+ *   - It validated only the *first* occurrence of a repeated single-value
+ *     flag, so `--provider claude --provider` (a malformed second
+ *     occurrence) silently passed.
+ *   - It always resolved a repeated flag to its first occurrence, which
+ *     silently changed `aiwg session`'s pre-existing last-occurrence-wins
+ *     precedence for `--provider`/`--profile` to first-wins — a real
+ *     behavior regression, not just a new validation gap.
+ *   - `--flag=value` was never recognized at all.
+ *   - Scanning never stopped at a bare `--` terminator.
+ *   - An empty-string value (`--prompt ''`) was accepted as a valid value
+ *     for flags where that is never meaningful.
+ *
+ * {@link scanFlagOccurrences} is the single-pass tokenizer every other
+ * helper here is built on: it finds *every* occurrence of the named
+ * flag(s), in one scan, validating each one independently, and stops
+ * recognizing flags entirely once it sees a bare `--` token (everything
+ * after that point is positional, per POSIX convention). `--flag value`
+ * and `--flag=value` are both accepted; in the space-separated form a
+ * value that itself looks like another flag (starts with `--`) is treated
+ * as a missing value — pass it via the `=` form instead
+ * (`--flag=--literal`) when a value must start with `--`. A value starting
+ * with a single `-` is always accepted in either form.
+ *
+ * Callers choose `precedence: 'first' | 'last'` to match whatever
+ * precedence the command already had before this module existed — see
+ * each call site's own comment for which one applies and why. Callers
+ * MUST catch {@link MissingFlagValueError} (or let it propagate to a
+ * handler-level catch) and report it before any preflight check, spawn,
+ * or write — never after.
+ */
+/** Thrown when a recognized flag is present but has no usable value following it. */
+export class MissingFlagValueError extends Error {
+    /** The exact flag token that was missing its value (e.g. `--prompt`). */
+    flagName;
+    constructor(flagName) {
+        super(`${flagName} requires a value`);
+        this.name = 'MissingFlagValueError';
+        this.flagName = flagName;
+    }
+}
+function splitEquals(token) {
+    const eq = token.indexOf('=');
+    if (eq === -1)
+        return null;
+    return [token.slice(0, eq), token.slice(eq + 1)];
+}
+/**
+ * Single-pass scan for every occurrence of any of `names` in `args`. See
+ * the module doc comment for the full set of semantics this implements.
+ *
+ * Throws {@link MissingFlagValueError} on the *first* occurrence (in
+ * left-to-right order) that has no usable value or an empty one (when
+ * `options.rejectEmpty`) — every occurrence is checked, not just the
+ * first one found overall, so a malformed *later* occurrence is still an
+ * error even when an earlier one was valid.
+ */
+export function scanFlagOccurrences(args, names, options = {}) {
+    const occurrences = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const token = args[i];
+        if (token === undefined)
+            continue;
+        if (token === '--')
+            break; // bare terminator — stop recognizing flags entirely
+        if (token.startsWith('--')) {
+            const eqSplit = splitEquals(token);
+            if (eqSplit && names.includes(eqSplit[0])) {
+                const [flag, value] = eqSplit;
+                if (options.rejectEmpty && value === '')
+                    throw new MissingFlagValueError(flag);
+                occurrences.push({ index: i, flag, value });
+                continue;
+            }
+        }
+        if (names.includes(token)) {
+            const next = args[i + 1];
+            if (next === undefined || next.startsWith('--')) {
+                throw new MissingFlagValueError(token);
+            }
+            if (options.rejectEmpty && next === '') {
+                throw new MissingFlagValueError(token);
+            }
+            occurrences.push({ index: i, flag: token, value: next });
+            i += 1; // skip the consumed value token
+        }
+    }
+    return occurrences;
+}
+/**
+ * Look up the value of a (possibly repeated) single-value flag.
+ *
+ * - None of `names` appear at all → `undefined` (the flag was never
+ *   given; not an error).
+ * - `names` appear once or more, every occurrence validated → the first
+ *   or last occurrence's value, per `options.precedence` (default
+ *   `'first'`). Pass `'last'` only for a command whose pre-existing
+ *   behavior (before this module existed) already let a later occurrence
+ *   override an earlier one — see the call site's comment.
+ */
+export function requireFlagValue(args, options, ...names) {
+    const occurrences = scanFlagOccurrences(args, names, options);
+    if (occurrences.length === 0)
+        return undefined;
+    return options.precedence === 'last'
+        ? occurrences[occurrences.length - 1].value
+        : occurrences[0].value;
+}
+/**
+ * Same validation contract as {@link requireFlagValue}, but collects the
+ * value of *every* occurrence in left-to-right order — for repeatable
+ * flags such as `--param`/`--script`. Returns `[]` when the flag never
+ * appears.
+ */
+export function collectFlagValues(args, options, ...names) {
+    return scanFlagOccurrences(args, names, options).map((occurrence) => occurrence.value);
+}
+/**
+ * Parse a strict `true`/`false` flag value. `undefined` in means the flag
+ * was not given (not an error, and not a default — callers decide the
+ * default). Anything other than exactly `true`/`false` throws, naming
+ * `flagName` in the message.
+ */
+export function parseBooleanFlagValue(value, flagName) {
+    if (value === undefined)
+        return undefined;
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    throw new Error(`${flagName} must be true or false (got '${value}')`);
+}
+/**
+ * Parse a comma-separated list flag value, trimming whitespace and
+ * dropping empty entries. Returns `undefined` when `raw` is `undefined`
+ * (flag not given); returns `[]` only if every entry was empty.
+ */
+export function parseListFlagValue(raw) {
+    if (raw === undefined)
+        return undefined;
+    return raw.split(',').map((entry) => entry.trim()).filter(Boolean);
+}
+/**
+ * Split one repeatable `<name>=<value>` entry (as used by `--script`,
+ * `--param`) into its parts. Throws, naming `flagName`, when `entry` has
+ * no `=`, an empty name, or an empty value.
+ */
+export function parseKeyValueEntry(entry, flagName) {
+    const eq = entry.indexOf('=');
+    if (eq <= 0 || eq === entry.length - 1) {
+        throw new Error(`${flagName} requires the form <name>=<value> (got '${entry}')`);
+    }
+    return [entry.slice(0, eq).trim(), entry.slice(eq + 1).trim()];
+}
+/**
+ * The index of the first bare `--` terminator in `args`, or `args.length`
+ * when there is none — a loop bounded by this never looks at anything
+ * after the terminator, which per POSIX convention is never a flag or a
+ * command word again (#3062 go/no-go review, blocker 4).
+ */
+export function argsTerminatorIndex(args) {
+    const index = args.indexOf('--');
+    return index === -1 ? args.length : index;
+}
+/**
+ * The set of array indexes in `args` consumed as the *value* of a
+ * `--flag value` (two-token) occurrence of any name in `valueFlagNames`
+ * (#3062 go/no-go review, blocker 4). A `--flag=value` (one-token) form
+ * has no separate value index to report — the value is part of the same
+ * token, so it can never coincidentally equal a bare positional word or a
+ * different flag's own name the way a space-separated value can.
+ *
+ * This does not validate occurrences (a missing/malformed value is the
+ * paired value-flag parser's own job — e.g. {@link requireFlagValue} on
+ * the same `args` and `valueFlagNames`, called separately); it exists
+ * purely so a positional/switch scan knows which indexes are already
+ * spoken for and must not be reinterpreted as something else.
+ */
+export function valueTokenIndexes(args, valueFlagNames) {
+    const consumed = new Set();
+    const limit = args.length;
+    for (let i = 0; i < limit; i += 1) {
+        const token = args[i];
+        if (token === undefined)
+            continue;
+        if (token === '--')
+            break;
+        if (token.startsWith('--') && token.includes('='))
+            continue; // value is part of this same token
+        if (valueFlagNames.includes(token) && i + 1 < limit) {
+            consumed.add(i + 1);
+            i += 1; // the value token itself is spoken for; do not also treat it as a flag name
+        }
+    }
+    return consumed;
+}
+/**
+ * True iff `name` appears as a bare positional token or an exact-match
+ * boolean switch anywhere in `args` *before* the `--` terminator, and is
+ * not itself the already-consumed value of one of `valueFlagNames` (#3062
+ * go/no-go review, blocker 4).
+ *
+ * Use this instead of `args.includes(name)` (or an equivalent hand-rolled
+ * loop) for any boolean switch or positional command word that a value-
+ * taking flag's own value could coincidentally equal — e.g. a free-text
+ * `--prompt` argument that happens to contain the literal word a command
+ * also uses as a switch, or a value that collides with another flag's own
+ * name.
+ */
+export function hasPositionalOrSwitch(args, name, valueFlagNames) {
+    const consumed = valueTokenIndexes(args, valueFlagNames);
+    const limit = argsTerminatorIndex(args);
+    for (let i = 0; i < limit; i += 1) {
+        if (consumed.has(i))
+            continue;
+        if (args[i] === name)
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=flag-parsing.js.map

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

@@ -1,10 +1,11 @@
-import { decisionCapabilities, evaluateRequestPath, listPatterns, livePlan, materializeSyntheticClassificationSetup, runOfflinePattern, showPattern, syntheticClassificationSetup, validateDecisionInput, } from '../../decision/driver.js';
+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';
 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]',
+        '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]',
         '',
         'Commands:',
         '  capabilities|status                 Show offline readiness, primitives, config and feature availability',
@@ -15,6 +16,34 @@ function usage() {
         '  validate <request|definition|ruleset|binding> <path>',
         '  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) [--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]',
+        '',
+        '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) {
@@ -23,11 +52,266 @@ function takeOption(args, name) {
         return undefined;
     return args[index + 1];
 }
+function takeRequiredOption(args, name) {
+    const value = takeOption(args, name);
+    if (!value || value.startsWith('--'))
+        throw new DecisionAskUsageError(`missing-${name.slice(2)}`, `${name} requires a value`);
+    return value;
+}
 function patternId(value) {
     if (!value)
         throw new Error('Pattern id is required');
     return value;
 }
+function flagCount(args, names) {
+    return args.filter(arg => names.includes(arg)).length;
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    return Buffer.concat(chunks).toString('utf8');
+}
+function parseNumber(value, name) {
+    if (value === undefined)
+        throw new DecisionAskUsageError(`missing-${name.slice(2)}`, `${name} requires a value`);
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed))
+        throw new DecisionAskUsageError(`invalid-${name.slice(2)}`, `${name} must be numeric`);
+    return parsed;
+}
+function parseScale(value) {
+    if (!value)
+        throw new DecisionAskUsageError('invalid-scale', '--scale requires a range like 1-5');
+    const match = /^(-?\d+)-(-?\d+)$/.exec(value);
+    if (!match)
+        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({
+        token,
+        region: takeOption(rest, '--region'),
+        endpoint: takeOption(rest, '--endpoint'),
+        verify: rest.includes('--verify'),
+        remove: rest.includes('--remove'),
+    }, { env: process.env });
+    return jsonResult(result);
+}
+async function decisionAsk(ctx) {
+    const args = ctx.args.slice(1);
+    const modeCount = flagCount(args, ['--yes-no']) + (args.includes('--choices') ? 1 : 0) + (args.includes('--scale') ? 1 : 0);
+    if (modeCount !== 1)
+        throw new DecisionAskUsageError('invalid-mode', 'Select exactly one of --yes-no, --choices, or --scale');
+    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('--'))) {
+        throw new DecisionAskUsageError('missing-context', '--context requires text');
+    }
+    if (args.includes('--context-file')) {
+        const filePath = takeRequiredOption(args, '--context-file');
+        context = await readDecisionContextFile(filePath);
+    }
+    if (args.includes('--context-stdin'))
+        context = await readStdin();
+    const choices = args.includes('--choices') ? takeRequiredOption(args, '--choices') : undefined;
+    const scale = args.includes('--scale') ? parseScale(takeOption(args, '--scale')) : null;
+    const input = {
+        question,
+        mode: args.includes('--yes-no') ? { kind: 'yes-no' }
+            : choices !== undefined ? { kind: 'choices', choices: choices.split(',').map(value => value.trim()).filter(Boolean) }
+                : { kind: 'scale', ...scale },
+        ...(context === undefined ? {} : { context }),
+        ...(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, {
+        transport: 'cli',
+        projectRoot: ctx.cwd,
+        env: process.env,
+        explicitProvider: takeOption(args, '--provider'),
+        explicitSessionId,
+        caller: caller ?? null,
+        recordText: args.includes('--record-text'),
+    });
+    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'];
+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, 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})`,
+        `  jev usage: input=${group.jevUsage.inputTokens} output=${group.jevUsage.outputTokens}`,
+        `  estimated LLM tokens avoided=${group.estimatedLlmTokensAvoidedTotal} net savings=${group.netSavingsTokens}`,
+    ]);
+    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 };
@@ -36,6 +320,12 @@ async function executeDecision(ctx) {
             return { exitCode: 0, message: usage(), rawOutput: true };
         if (command === 'capabilities' || command === 'status')
             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());
@@ -70,9 +360,14 @@ async function executeDecision(ctx) {
                 return jsonResult(await materializeSyntheticClassificationSetup(outputDir, {}, options));
             return jsonResult(syntheticClassificationSetup({}, options));
         }
+        if (command === 'setup' && subcommand === 'jev')
+            return await decisionSetupJev(rest);
         return { exitCode: 2, message: usage(), rawOutput: true };
     }
     catch (error) {
+        if (error instanceof DecisionAskUsageError) {
+            return { exitCode: 2, message: JSON.stringify({ schema: 'aiwg-decision-error/v1', reason: error.reason, message: error.message }, null, 2), rawOutput: true };
+        }
         return { exitCode: 1, message: error instanceof Error ? error.message : String(error) };
     }
 }