@aiwg/cli 2026.10.10 → 2026.10.12

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

@@ -3,13 +3,14 @@ function jsonResult(value, exitCode = 0) {
 }
 function usage() {
     return [
-        'Usage: aiwg gates <validate|evaluate|show|list> [options]',
+        'Usage: aiwg gates <validate|evaluate|show|list|coverage> [options]',
         '',
         'Commands:',
         '  validate <pack|binding|report> <path> [--pack-dir <dir>] [--aiwg-root <dir>]',
         '  evaluate --binding <file> --metrics <file> --holdout <file> [--upstream <file>] --now <iso> --trusted-binding-digest <sha256> [--pack-dir <dir>] [--aiwg-root <dir>]',
         '  show <id> [--pack-dir <dir>] [--aiwg-root <dir>]',
         '  list [--namespace <ns>] [--rule [<rule-id>]] [--pack-dir <dir>] [--aiwg-root <dir>]',
+        '  coverage [--rule <rule-id>] [--json] [--pack-dir <dir>] [--aiwg-root <dir>]',
         '',
         'Packs live in <bundle>/gate-packs/*.gatepack.yaml|json and register as',
         'aiwg:<bundle>/<name> (shipped).',
@@ -77,7 +78,7 @@ async function executeGates(ctx) {
     try {
         if (!command || command === '--help' || command === '-h')
             return { exitCode: 0, message: usage(), rawOutput: true };
-        const { validateGateFile, evaluateGatesFromFiles, showGatePack, listGatePacks, packsReferencedByRule, } = await import('../../gates/driver.js');
+        const { validateGateFile, evaluateGatesFromFiles, showGatePack, listGatePacks, } = await import('../../gates/driver.js');
         const options = driverOptions(ctx);
         if (command === 'validate') {
             const args = positionals(ctx.args, 'validate');
@@ -115,27 +116,27 @@ async function executeGates(ctx) {
                 return { exitCode: 2, message: `gates show requires <id>\n\n${usage()}`, rawOutput: true };
             return jsonResult(showGatePack(id, options), 0);
         }
-        if (command === 'list') {
+        if (command === 'coverage' || command === 'list' && ctx.args.includes('--rule')) {
+            const { listRuleGateCoverage, formatRuleGateCoverage } = await import('../../rules/gate-coverage.js');
+            const value = takeOption(ctx.args, '--rule');
+            const rule = value && !value.startsWith('-') ? value : undefined;
+            const rules = listRuleGateCoverage(options, rule);
+            if (command === 'coverage') {
+                return ctx.args.includes('--json') ? jsonResult({ schema: 'aiwg-gates-coverage/v1', rules })
+                    : { exitCode: 0, message: formatRuleGateCoverage(rules), rawOutput: true };
+            }
             const namespace = takeOption(ctx.args, '--namespace');
-            const ruleIndex = ctx.args.indexOf('--rule');
-            const ruleValue = ruleIndex >= 0 ? ctx.args[ruleIndex + 1] : undefined;
-            const rule = ruleIndex >= 0 ? (ruleValue && !ruleValue.startsWith('-') ? ruleValue : null) : undefined;
             const packs = listGatePacks({ ...options, ...(namespace ? { namespace } : {}) });
-            if (rule === undefined)
-                return jsonResult({ schema: 'aiwg-gates-list/v1', packs }, 0);
-            if (rule === null) {
-                return jsonResult({
-                    schema: 'aiwg-gates-list/v1', packs,
-                    enforcedBy: { status: 'stub', note: 'Rule enforcedBy coverage is tracked in #2839; rules without enforcedBy remain guidance.' },
-                }, 0);
-            }
-            const referenced = new Set(await packsReferencedByRule(rule, options));
+            const referenced = new Set(rules.flatMap(item => item.enforcedBy.map(reference => reference.split('#')[0])));
             return jsonResult({
-                schema: 'aiwg-gates-list/v1', rule,
-                packs: packs.filter(pack => referenced.has(pack.id)),
-                enforcedBy: { status: 'stub', note: 'Rule enforcedBy coverage is tracked in #2839.' },
+                schema: 'aiwg-gates-list/v1', ...(rule ? { rule } : {}), rules,
+                packs: rule ? packs.filter(pack => referenced.has(pack.id)) : packs,
             }, 0);
         }
+        if (command === 'list') {
+            const namespace = takeOption(ctx.args, '--namespace');
+            return jsonResult({ schema: 'aiwg-gates-list/v1', packs: listGatePacks({ ...options, ...(namespace ? { namespace } : {}) }) });
+        }
         return { exitCode: 2, message: usage(), rawOutput: true };
     }
     catch (error) {

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

@@ -27,7 +27,7 @@ Artifact selectors and options:
   --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
+  TIER: economy | standard | premium | flagship (alias: max-quality)
 
 Direct worker resolution (plans an invocation; does not launch it):
   aiwg models resolve --role <role> --task <class> --group <group>
@@ -43,6 +43,12 @@ Direct worker resolution (plans an invocation; does not launch it):
   --transport                  Must match group execution transport (default: shell)
   --format                     JSON plan or POSIX shell command (default: json)
   --json                       Alias for --format json
+  --max-attempts <count>        Tighten total attempts, including the initial attempt
+  --timeout-ms <ms>             Tighten the hard stop; positive multiple of 1000 (whole seconds)
+  --max-output-tokens <count>   Tighten the existing task token budget (tokens)
+  --max-usd <amount>            Tighten the task cost ceiling (costUsd)
+                               Limits may only tighten resolved policy; larger values fail
+                               JSON includes ceilings and their origins
   --authorize-premium          Authorize premium for this resolution only
                                Agents require explicit human confirmation of escalation
 

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

@@ -144,7 +144,7 @@ async function resolveDirect(ctx, services) {
         return { exitCode: 2 };
     }
 }
-const TIERS = new Set(['economy', 'standard', 'premium', 'max-quality']);
+const TIERS = new Set(['economy', 'standard', 'premium', 'flagship', 'max-quality']);
 const PROVIDERS = new Set(Object.keys(loadProviderModelCapabilities().providers));
 function parseArgs(args) {
     const [subcommand = 'help', ...rest] = args;
@@ -241,7 +241,7 @@ function select(artifacts, parsed, useTierSelector = true) {
         && (!framework || item.framework === framework)));
 }
 function normalizedTier(tier) {
-    return tier === 'max-quality' ? 'premium' : tier ?? 'standard';
+    return tier === 'max-quality' ? 'flagship' : tier ?? 'standard';
 }
 function resolved(item, provider, catalog) {
     const policy = {
@@ -331,7 +331,7 @@ async function execute(ctx, services = { load: loadWorkerInputs }) {
         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|authorize-premium)(?:=|$)/.test(arg))) {
+    if (ctx.args[0] === 'resolve' && ctx.args.slice(1).some(arg => /^--(?:task|group|brief|workdir|final-output|transport|format|authorize-premium|max-attempts|timeout-ms|max-output-tokens|max-usd)(?:=|$)/.test(arg))) {
         return resolveDirect(ctx, services);
     }
     if (await handleWorkerAdoptionArgs(ctx.args, ctx.cwd, 'models', ctx.signal, ctx.dryRun))

package/dist/src/cli/handlers/script-runner.js

@@ -120,11 +120,13 @@ export class DefaultScriptRunner {
                     clearTimeout(timeoutId);
                 if (killEscalationId)
                     clearTimeout(killEscalationId);
-                // On failure in capture mode, surface the captured stderr
-                if (options.capture && code !== 0 && capturedStderrBytes > 0) {
+                // On failure in capture mode, surface the captured stderr. Every
+                // failure carries a message so callers never print an empty ERROR.
+                if (options.capture && code !== 0) {
+                    const stderr = Buffer.concat(capturedStderr).toString().trim();
                     resolve({
                         exitCode: code ?? 1,
-                        message: Buffer.concat(capturedStderr).toString().trim(),
+                        message: stderr || `Script exited with code ${code ?? 1}: ${path.basename(fullPath)}`,
                     });
                 }
                 else {
@@ -183,8 +185,9 @@ export class DefaultScriptRunner {
             // the runner still supports arbitrary scripts via its subprocess path.
             const deployer = await import(pathToFileURL(fullPath).href);
             const exitCode = (await deployer.main(args, { capture: options.capture === true })) ?? 0;
-            const message = Buffer.concat(diagnostics).toString().trim();
-            return exitCode && message ? { exitCode, message } : { exitCode };
+            const message = Buffer.concat(diagnostics).toString().trim()
+                || (exitCode ? `Deployment script exited with code ${exitCode}: ${path.basename(fullPath)}` : '');
+            return exitCode || message ? { exitCode, message } : { exitCode };
         }
         catch (error) {
             const message = Buffer.concat(diagnostics).toString().trim()

package/dist/src/cli/handlers/sessions-intake.js

@@ -0,0 +1,104 @@
+// `aiwg sessions import --from-dir`: idempotent intake-directory batch import (#3168).
+import { join } from 'node:path';
+import { fingerprintSourceFile, intakeSourceId, isRecognisedIntakeFile, listIntakeDirFiles, summarizeIntakeReceipts, INTAKE_DIR_SCHEMA_VERSION, } from '../../sessions/index.js';
+export async function importFromDir(ctx, args, dir, deps) {
+    const { assertSupportedImportProvider, normalizeWorkspaceId, isDryRun, preview, ok, openRepository, adapterVersionFor, importSource, importFailureReason, } = deps;
+    const provider = assertSupportedImportProvider(args.values.get('--provider') ?? 'generic');
+    const workspaceId = args.values.has('--workspace')
+        ? normalizeWorkspaceId(ctx.cwd, args.values.get('--workspace'))
+        : 'default';
+    const prefix = args.values.get('--source-id');
+    const files = await listIntakeDirFiles(dir);
+    if (isDryRun(ctx, args)) {
+        return preview('import', {
+            fromDir: dir,
+            provider,
+            workspaceId,
+            sourceIdPrefix: prefix ?? null,
+            files: files.map((file) => {
+                const recognition = isRecognisedIntakeFile(provider, file);
+                return {
+                    file,
+                    sourceId: recognition.recognised ? intakeSourceId(prefix, file) : null,
+                    recognised: recognition.recognised,
+                    reason: recognition.reason ?? null,
+                };
+            }),
+            wouldPersist: false,
+        });
+    }
+    const repository = openRepository(ctx, args);
+    try {
+        const interrupted = new Map();
+        const receipts = [];
+        for (const file of files) {
+            const recognition = isRecognisedIntakeFile(provider, file);
+            const input = join(dir, file);
+            if (!recognition.recognised) {
+                receipts.push({
+                    file, sourceId: null, digest: null, status: 'skipped',
+                    reason: recognition.reason ?? 'unrecognised file', sessionsInserted: 0, eventsInserted: 0,
+                });
+                continue;
+            }
+            const sourceId = intakeSourceId(prefix, file);
+            let digest = null;
+            try {
+                const fingerprint = await fingerprintSourceFile({ selectedPath: input, allowedRoots: [dir] });
+                digest = fingerprint.digest;
+                const checkpoint = repository.getCheckpoint(sourceId, adapterVersionFor(provider));
+                if (checkpoint?.prefixDigest === digest && checkpoint.sourceSize === fingerprint.size) {
+                    receipts.push({
+                        file, sourceId, digest, status: 'already-imported',
+                        reason: 'content digest already imported', sessionsInserted: 0, eventsInserted: 0,
+                    });
+                    continue;
+                }
+            }
+            catch (error) {
+                receipts.push({
+                    file, sourceId, digest, status: 'rejected',
+                    reason: importFailureReason(error), sessionsInserted: 0, eventsInserted: 0,
+                });
+                continue;
+            }
+            const fileValues = new Map(args.values);
+            fileValues.delete('--from-dir');
+            fileValues.set('--source-id', sourceId);
+            try {
+                const result = await importSource(ctx, {
+                    command: 'import', positionals: [input], flags: new Set(args.flags),
+                    values: fileValues, codexRoots: args.codexRoots, exclude: args.exclude,
+                });
+                const data = result.envelope.data;
+                for (const run of data.interruptedRuns ?? [])
+                    interrupted.set(run.runId, run);
+                receipts.push({
+                    file, sourceId, digest, status: 'imported', reason: null,
+                    sessionsInserted: data.totals?.sessionsInserted ?? 0,
+                    eventsInserted: data.totals?.eventsInserted ?? 0,
+                });
+            }
+            catch (error) {
+                receipts.push({
+                    file, sourceId, digest, status: 'rejected',
+                    reason: importFailureReason(error), sessionsInserted: 0, eventsInserted: 0,
+                });
+            }
+        }
+        return ok('import', {
+            fromDir: dir,
+            provider,
+            workspaceId,
+            sourceIdPrefix: prefix ?? null,
+            schemaVersion: INTAKE_DIR_SCHEMA_VERSION,
+            files: receipts,
+            summary: summarizeIntakeReceipts(receipts),
+            interruptedRuns: [...interrupted.values()],
+        });
+    }
+    finally {
+        repository.close();
+    }
+}
+//# sourceMappingURL=sessions-intake.js.map

package/dist/src/cli/handlers/sessions-tail.js

@@ -0,0 +1,172 @@
+// Resolve catalog identities and authorized native paths for the sessions tail verb.
+import { existsSync } from 'node:fs';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { readAiwgConfig } from '../../config/aiwg-config.js';
+import { createSessionAdapterRegistry } from '../../sessions/adapter-registry.js';
+import { assertSessionProviderId, SessionContractError } from '../../sessions/contracts.js';
+import { redactSessionValue } from '../../sessions/policy.js';
+import { resolveImportLimits } from '../../sessions/import-limits.js';
+import { acquireImportLease } from '../../sessions/import-lease.js';
+import { SessionRepository } from '../../sessions/repository.js';
+import { assertTailSupported, tailSession } from '../../sessions/tail.js';
+import { defaultDiscoveryManifestPath, readDiscoveryManifest } from '../../sessions/workspace-discovery.js';
+export async function executeSessionsTail(ctx, args, helpers) {
+    const json = args.flags.has('--json');
+    let repository;
+    let lease;
+    const controller = new AbortController();
+    const stop = () => controller.abort();
+    const signal = ctx.signal ? AbortSignal.any([ctx.signal, controller.signal]) : controller.signal;
+    process.on('SIGINT', stop);
+    try {
+        const latest = args.flags.has('--latest');
+        const reference = args.positionals[0];
+        const providerInput = args.values.get('--provider');
+        if (args.positionals.length > 1 || (latest ? !providerInput || !!reference : !reference)) {
+            throw new SessionContractError('INVALID_ARGUMENT', 'tail requires <session-id> or --provider <p> --latest');
+        }
+        if (args.flags.has('--import') && (ctx.dryRun || args.flags.has('--dry-run'))) {
+            throw new SessionContractError('INVALID_ARGUMENT', 'tail --import cannot be combined with --dry-run');
+        }
+        const provider = providerInput ? assertSessionProviderId(providerInput) : undefined;
+        if (provider)
+            assertTailSupported(createSessionAdapterRegistry().get(provider));
+        let database = helpers.databasePath(ctx, args);
+        repository = new SessionRepository(database, { readonly: true });
+        const workspace = args.values.has('--workspace') || latest
+            ? helpers.readAuthorizationContext(ctx, args, 'tail', repository).workspaceId : undefined;
+        let matches = latest
+            ? repository.listSessions({ provider, workspaceId: workspace, limit: 1 }).items
+            : repository.findSessionsByReference(reference, workspace);
+        if (provider)
+            matches = matches.filter(session => session.provider === provider);
+        // Account-scoped providers live in the referenced host catalog (#3232).
+        const references = repository.listHostSessionReferences().filter(item => !provider || item.provider === provider);
+        const hosts = new Set(references.map(item => item.hostCatalog));
+        const candidates = matches.map(session => ({ session, database }));
+        for (const hostPath of hosts) {
+            if (!existsSync(hostPath))
+                continue;
+            const host = new SessionRepository(hostPath, { readonly: true });
+            try {
+                const allowed = new Set(references.filter(item => item.hostCatalog === hostPath)
+                    .map(item => item.sessionId));
+                const sessions = latest
+                    ? references.filter(item => item.hostCatalog === hostPath)
+                        .flatMap(item => host.getSession(item.sessionId) ?? [])
+                    : host.findSessionsByReference(reference);
+                candidates.push(...sessions.filter(session => allowed.has(session.sessionId))
+                    .map(session => ({ session, database: hostPath })));
+            }
+            finally {
+                host.close();
+            }
+        }
+        const selected = latest
+            ? candidates.sort((a, b) => (b.session.updatedAt ?? '').localeCompare(a.session.updatedAt ?? '')
+                || b.session.sessionId.localeCompare(a.session.sessionId)).slice(0, 1)
+            : candidates;
+        if (selected.length !== 1) {
+            throw new SessionContractError('INVALID_ARGUMENT', selected.length
+                ? 'session reference is ambiguous; select --workspace or an internal session ID'
+                : 'session not found in the selected catalog and workspace');
+        }
+        const session = selected[0].session;
+        if (selected[0].database !== database) {
+            repository.close();
+            database = selected[0].database;
+            repository = new SessionRepository(database, { readonly: true });
+        }
+        const source = repository.getSource(session.sourceId);
+        if (!source)
+            throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'catalog source is unavailable');
+        const config = await readAiwgConfig(isAbsolute(session.workspaceId) ? session.workspaceId : ctx.cwd);
+        const limits = resolveImportLimits(config?.sessions?.import, {
+            maxRecordBytes: args.values.get('--max-record-bytes'),
+            maxSourceBytes: args.values.get('--max-source-bytes'),
+        });
+        const adapter = createSessionAdapterRegistry(limits).get(session.provider);
+        assertTailSupported(adapter);
+        const selectedSource = await resolveTailSource(ctx, args, session, source.locatorClass, config?.sessions?.discovery_manifests ?? [], resolve(dirname(helpers.databasePath(ctx, args)), 'discovery-manifest.json'));
+        const importing = args.flags.has('--import');
+        if (importing) {
+            repository.close();
+            repository = undefined;
+            lease = await acquireImportLease(database, `sessions-tail-${process.pid}`);
+            repository = new SessionRepository(database);
+        }
+        const checkpoint = repository.getCheckpoint(source.sourceId, adapter.adapterVersion);
+        await tailSession({
+            source, selectedSource, adapter, repository, sessionId: session.sessionId,
+            workspaceId: session.workspaceId, policyVersion: checkpoint?.policyVersion ?? '1.0.0',
+            limits, signal, follow: args.flags.has('--follow'), import: importing,
+            onEvent: event => {
+                if (json)
+                    console.log(JSON.stringify({ contractVersion: '1.0.0', command: 'sessions.tail',
+                        status: 'ok', data: { event }, error: null }));
+                else
+                    console.log(`${event.occurredAt ?? '-'} ${session.provider} ${event.kind}: ${event.searchableText}`);
+            },
+            onPoll: flushStdout,
+        });
+        await flushStdout();
+        return { exitCode: 0 };
+    }
+    catch (error) {
+        if (signal.aborted)
+            return { exitCode: 0 };
+        const cliError = error instanceof Error && 'code' in error && 'exitCode' in error
+            ? error : undefined;
+        const code = error instanceof SessionContractError ? error.code
+            : cliError ? cliError.code
+                : 'code' in Object(error) && error.code === 'IMPORT_LOCKED'
+                    ? 'IMPORT_LOCKED' : 'CATALOG_UNAVAILABLE';
+        const message = redactSessionValue(error instanceof Error ? error.message : 'session tail failed').value;
+        if (json) {
+            console.log(JSON.stringify({ contractVersion: '1.0.0', command: 'sessions.tail', status: 'error',
+                data: null, error: { code, message } }));
+            await flushStdout();
+        }
+        else
+            console.error(`${code}: ${message}`);
+        return { exitCode: cliError?.exitCode ?? (code === 'UNSUPPORTED_PROVIDER' ? 3 : code === 'INVALID_ARGUMENT' ? 2
+                : code === 'IMPORT_LOCKED' ? 7 : code === 'CATALOG_UNAVAILABLE' ? 6 : 5), message };
+    }
+    finally {
+        process.removeListener('SIGINT', stop);
+        repository?.close();
+        await lease?.release();
+    }
+}
+async function resolveTailSource(ctx, args, session, locatorClass, configured, catalogManifest) {
+    const workspace = isAbsolute(session.workspaceId) ? session.workspaceId : ctx.cwd;
+    // Existing explicit input option also supports older direct imports, whose
+    // catalog intentionally never retained the unredacted native pathname.
+    const input = args.values.get('--input');
+    if (input) {
+        const locator = resolve(ctx.cwd, input);
+        return { provider: session.provider, sourceId: session.sourceId, nativeSessionId: session.nativeSessionId, locatorClass, locator,
+            authorizedScope: { workspaceId: session.workspaceId, allowedRoots: [dirname(locator)] } };
+    }
+    const paths = args.values.has('--manifest') ? [resolve(ctx.cwd, args.values.get('--manifest'))] : [
+        defaultDiscoveryManifestPath(workspace), defaultDiscoveryManifestPath(ctx.cwd), catalogManifest,
+        ...configured.map(path => resolve(workspace, path)),
+    ];
+    for (const path of new Set(paths)) {
+        if (!existsSync(path))
+            continue;
+        const manifest = await readDiscoveryManifest(path);
+        const source = manifest.sources.find(item => item.sourceId === session.sourceId
+            && item.provider === session.provider && item.locatorClass === locatorClass && item.status !== 'excluded');
+        if (source)
+            return { provider: session.provider, sourceId: session.sourceId, nativeSessionId: session.nativeSessionId, locatorClass,
+                locator: source.locator, authorizedScope: {
+                    workspaceId: session.workspaceId, allowedRoots: [source.authorizedRoot],
+                } };
+    }
+    throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'native source location is unavailable; pass its saved --manifest or explicitly authorize --input <native-source>');
+}
+function flushStdout() {
+    return new Promise((resolve, reject) => process.stdout.write('', error => error ? reject(error) : resolve()));
+}
+//# sourceMappingURL=sessions-tail.js.map