@aiwg/cli 2026.7.24 → 2026.8.0

package/dist/src/artifacts/cli.js

@@ -937,12 +937,19 @@ async function handleExport(args) {
         console.log('  --out <path>           Write JSON or .shard output to a file');
         console.log('  --repo <name>          Source repository label (default: cwd basename)');
         console.log('  --privacy <level>      private, sanitized, or public (default: private)');
-        console.log('  --schema-version <v>   Export contract version: v1 or v2 (default: v1)');
+        console.log('  --schema-version <v>   Browser: v1|v2; shard: 2.0.0|1.2.0');
+        console.log('  --profile <name>       Shard profile: full-v1 (default) or core-v1');
+        console.log('  --fail-on-loss         Reject a full-v1 conversion that reports any loss');
+        console.log('  --dry-run              Build and report without writing the shard');
+        console.log('  --force                Replace an existing output path');
+        console.log('  --migrate-from <path>  Diagnose a source-less legacy shard (dry-run only)');
+        console.log('  --json                 Emit the machine-readable conversion report');
         console.log('  --generated-at <iso>   Override generated timestamp for deterministic fixtures');
         console.log('');
         console.log('Examples:');
         console.log('  aiwg index export --format fortemi --graph project --out aiwg-fortemi-index.json');
-        console.log('  aiwg index export --format fortemi-shard --graph project --out aiwg-index.shard');
+        console.log('  aiwg index export --format fortemi-shard --graph project --schema-version 2.0.0 --profile full-v1 --fail-on-loss --out aiwg-index.shard');
+        console.log('  aiwg index export --format fortemi-shard --migrate-from legacy.shard --dry-run --json');
         console.log('  aiwg index export --format fortemi --privacy sanitized --generated-at 2026-01-01T00:00:00.000Z');
         return;
     }
@@ -960,29 +967,65 @@ async function handleExport(args) {
         process.exit(1);
     }
     const generatedAt = parseFlagValue(args, '--generated-at', 'Error: --generated-at requires an ISO timestamp value');
-    const schemaVersion = parseFlagValue(args, '--schema-version', 'Error: --schema-version must be v1 or v2');
-    if (schemaVersion && !['v1', 'v2'].includes(schemaVersion)) {
-        console.error('Error: --schema-version must be v1 or v2');
+    const schemaVersion = parseFlagValue(args, '--schema-version', 'Error: --schema-version requires a value');
+    const profile = parseFlagValue(args, '--profile', 'Error: --profile requires a value');
+    const migrateFrom = parseFlagValue(args, '--migrate-from', 'Error: --migrate-from requires a shard path');
+    const dryRun = args.includes('--dry-run');
+    const json = args.includes('--json');
+    if (format === 'fortemi' && schemaVersion && !['v1', 'v2'].includes(schemaVersion)) {
+        console.error('Error: browser export --schema-version must be v1 or v2');
+        process.exit(1);
+    }
+    if (format === 'fortemi-shard' && schemaVersion && !['1.2.0', '2.0.0'].includes(schemaVersion)) {
+        console.error('Error: shard --schema-version must be 2.0.0 or 1.2.0');
         process.exit(1);
     }
-    if (format === 'fortemi-shard' && schemaVersion && schemaVersion !== 'v2') {
-        console.error('Error: --format fortemi-shard requires --schema-version v2');
+    if (format === 'fortemi-shard' && profile && !['full-v1', 'core-v1'].includes(profile)) {
+        console.error('Error: shard --profile must be full-v1 or core-v1');
         process.exit(1);
     }
-    if (format === 'fortemi-shard' && !out) {
+    if (format === 'fortemi-shard' && !out && !migrateFrom) {
         console.error('Error: --format fortemi-shard requires --out <path>');
         process.exit(1);
     }
     try {
         if (format === 'fortemi-shard') {
-            const { writeAiwgFortemiKnowledgeShard } = await import('./fortemi-shard-export.js');
+            const { diagnoseAiwgFortemiShardMigration, writeAiwgFortemiKnowledgeShard, } = await import('./fortemi-shard-export.js');
+            if (migrateFrom) {
+                if (!dryRun) {
+                    throw new Error('--migrate-from is diagnostic-only and requires --dry-run; '
+                        + 'source-less core-v1 artifacts cannot be promoted losslessly.');
+                }
+                const diagnosis = diagnoseAiwgFortemiShardMigration(process.cwd(), migrateFrom);
+                if (json)
+                    console.log(JSON.stringify(diagnosis, null, 2));
+                else {
+                    console.log(`Migration supported: no`);
+                    console.log(`Diagnostic: ${diagnosis.diagnostic}`);
+                    console.log(`Action: ${diagnosis.action}`);
+                }
+                return;
+            }
             const result = await writeAiwgFortemiKnowledgeShard(process.cwd(), out, {
                 graph,
                 repo,
                 privacy: privacy,
                 generatedAt,
+                schemaVersion: schemaVersion,
+                profile: profile,
+                failOnLoss: args.includes('--fail-on-loss'),
+                dryRun,
+                overwrite: args.includes('--force'),
             });
-            console.log(`Exported ${result.items} AIWG records to ${result.outPath} (${result.bytes} bytes)`);
+            if (json)
+                console.log(JSON.stringify(result, null, 2));
+            else {
+                const action = result.written ? 'Exported' : 'Would export';
+                console.log(`${action} ${result.items} AIWG records as `
+                    + `${result.conversion.schemaVersion}/${result.conversion.profile} `
+                    + `to ${result.outPath} (${result.bytes} bytes; `
+                    + `${result.conversion.losses.length} losses)`);
+            }
             return;
         }
         const { buildAiwgFortemiIndexExport, writeAiwgFortemiIndexExport } = await import('./browser-export.js');

package/dist/src/artifacts/fortemi-shard-export.js

@@ -1,7 +1,20 @@
 import fs from "fs";
 import path from "path";
 import { buildAiwgFortemiIndexExport, } from "./browser-export.js";
-async function loadFortemiShardConverter() {
+const SUPPORTED_SHARD_TUPLES = new Set([
+    "1.2.0/core-v1",
+    "2.0.0/full-v1",
+]);
+export function resolveAiwgFortemiShardTuple(options) {
+    const schemaVersion = options.schemaVersion ?? "2.0.0";
+    const profile = options.profile ?? "full-v1";
+    if (!SUPPORTED_SHARD_TUPLES.has(`${schemaVersion}/${profile}`)) {
+        throw new Error(`Unsupported Fortemi Knowledge Shard tuple ${schemaVersion}/${profile}; `
+            + "supported tuples are 2.0.0/full-v1 and 1.2.0/core-v1.");
+    }
+    return { schemaVersion, profile };
+}
+async function loadFortemiShardConverters() {
     let core;
     try {
         core = (await import(
@@ -10,35 +23,111 @@ async function loadFortemiShardConverter() {
     catch {
         throw new Error("Portable Fortemi shard export requires @fortemi/core with aiwgFortemiIndexToKnowledgeShard.");
     }
-    if (!core.aiwgFortemiIndexToKnowledgeShard) {
-        throw new Error("Installed @fortemi/core does not support portable AIWG shards; upgrade to the release containing aiwgFortemiIndexToKnowledgeShard.");
+    if (!core.aiwgFortemiIndexToKnowledgeShard
+        || !core.aiwgFortemiIndexToKnowledgeShardWithReport) {
+        throw new Error("Installed @fortemi/core does not support both public AIWG shard converters; "
+            + "upgrade to a compatible published release.");
     }
-    return core.aiwgFortemiIndexToKnowledgeShard;
+    return core;
 }
-export async function buildAiwgFortemiKnowledgeShard(cwd, options = {}, converter) {
+export async function buildAiwgFortemiKnowledgeShardWithReport(cwd, options = {}, converter, reportConverter) {
     const exported = buildAiwgFortemiIndexExport(cwd, {
         ...options,
         schemaVersion: "v2",
     });
-    const convert = converter ?? (await loadFortemiShardConverter());
-    return convert(exported, {
-        createdAt: options.generatedAt,
-        matricVersion: "aiwg",
-    });
+    const tuple = resolveAiwgFortemiShardTuple(options);
+    const needsCore = tuple.profile === "core-v1" ? !converter : !reportConverter;
+    const core = needsCore ? await loadFortemiShardConverters() : null;
+    if (tuple.profile === "core-v1") {
+        const archive = await (converter ?? core.aiwgFortemiIndexToKnowledgeShard)(exported, { createdAt: options.generatedAt, matricVersion: "aiwg" });
+        return {
+            ...tuple,
+            success: true,
+            lossless: true,
+            losses: [],
+            receipt: null,
+            archive,
+        };
+    }
+    const result = await (reportConverter ?? core.aiwgFortemiIndexToKnowledgeShardWithReport)(exported, { createdAt: options.generatedAt, matricVersion: "aiwg" });
+    if (!result.success || !result.archive) {
+        throw new Error("Fortemi full-v1 conversion failed without producing an archive; losses="
+            + JSON.stringify(result.losses));
+    }
+    if (options.failOnLoss && (!result.lossless || result.losses.length > 0)) {
+        throw new Error(`Fortemi full-v1 conversion reported ${result.losses.length} loss(es); `
+            + "archive was not written because --fail-on-loss was set.");
+    }
+    return {
+        ...tuple,
+        success: result.success,
+        lossless: result.lossless,
+        losses: result.losses,
+        receipt: result.receipt,
+        archive: result.archive,
+    };
+}
+export async function buildAiwgFortemiKnowledgeShard(cwd, options = {}, converter, reportConverter) {
+    return (await buildAiwgFortemiKnowledgeShardWithReport(cwd, options, converter, reportConverter)).archive;
 }
-export async function writeAiwgFortemiKnowledgeShard(cwd, outPath, options = {}, converter) {
+export async function writeAiwgFortemiKnowledgeShard(cwd, outPath, options = {}, converter, reportConverter) {
     const exported = buildAiwgFortemiIndexExport(cwd, {
         ...options,
         schemaVersion: "v2",
     });
-    const convert = converter ?? (await loadFortemiShardConverter());
-    const shard = await convert(exported, {
-        createdAt: options.generatedAt,
-        matricVersion: "aiwg",
-    });
+    const conversion = await buildAiwgFortemiKnowledgeShardWithReport(cwd, options, converter, reportConverter);
     const resolved = path.resolve(cwd, outPath);
+    const report = {
+        bytes: conversion.archive.byteLength,
+        items: exported.items.length,
+        outPath: resolved,
+        written: !options.dryRun,
+        conversion: {
+            schemaVersion: conversion.schemaVersion,
+            profile: conversion.profile,
+            success: conversion.success,
+            lossless: conversion.lossless,
+            losses: conversion.losses,
+            receipt: conversion.receipt,
+        },
+    };
+    if (options.dryRun)
+        return report;
+    if (fs.existsSync(resolved) && !options.overwrite) {
+        throw new Error(`Refusing to overwrite existing shard ${resolved}; choose a new path or pass --force.`);
+    }
     fs.mkdirSync(path.dirname(resolved), { recursive: true });
-    fs.writeFileSync(resolved, shard);
-    return { bytes: shard.byteLength, items: exported.items.length, outPath: resolved };
+    const temporary = `${resolved}.tmp-${process.pid}`;
+    try {
+        fs.writeFileSync(temporary, conversion.archive, { flag: "wx" });
+        if (options.overwrite) {
+            fs.renameSync(temporary, resolved);
+        }
+        else {
+            fs.linkSync(temporary, resolved);
+            fs.unlinkSync(temporary);
+        }
+    }
+    catch (error) {
+        if (fs.existsSync(temporary))
+            fs.unlinkSync(temporary);
+        throw error;
+    }
+    return report;
+}
+export function diagnoseAiwgFortemiShardMigration(cwd, inputPath) {
+    const resolved = path.resolve(cwd, inputPath);
+    if (!fs.existsSync(resolved) || !fs.statSync(resolved).isFile()) {
+        throw new Error(`Legacy shard input does not exist or is not a regular file: ${resolved}`);
+    }
+    return {
+        supported: false,
+        inputPath: resolved,
+        mutationPlanned: false,
+        diagnostic: "Source-less core-v1 to full-v1 conversion is unsupported because omitted rich "
+            + "components cannot be reconstructed without loss.",
+        action: "Regenerate from the source-backed AIWG index with "
+            + "--schema-version 2.0.0 --profile full-v1; retain the legacy shard for rollback.",
+    };
 }
 //# sourceMappingURL=fortemi-shard-export.js.map

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

@@ -57,12 +57,13 @@ import { commandLogHandler } from './command-log.js';
 import { skillUsageHandler } from './skill-usage.js';
 import { modelsHandler } from './models.js';
 import { versionsHandler } from './resource-versions.js';
+import { jobHandler } from './job.js';
 // Re-export individual handlers
 export { 
 // Maintenance
 helpHandler, versionHandler, doctorHandler, updateHandler, refreshHandler, regenerateHandler, workspaceContextHandler, 
 // Framework management
-useHandler, listHandler, removeHandler, promoteHandler, installHandler, packagesHandler, marketplaceHandler, initHandler, setupHandler, setupGenerateHandler, setupRunHandler, setupValidateHandler, issueHandler, issueAuditHandler, runHandler, 
+useHandler, listHandler, removeHandler, promoteHandler, installHandler, packagesHandler, marketplaceHandler, initHandler, setupHandler, setupGenerateHandler, setupRunHandler, setupValidateHandler, issueHandler, issueAuditHandler, runHandler, jobHandler, 
 // Project
 newBundleHandler, quickrefHandler, newProjectHandler, sessionHandler, sessionsHandler, 
 // Workspace
@@ -139,6 +140,7 @@ export const allHandlers = [
     issueHandler,
     issueAuditHandler,
     runHandler,
+    jobHandler,
     // Workspace management
     ...workspaceHandlers,
     // Subcommand handlers (MCP, catalog, index, skills)

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

@@ -0,0 +1,97 @@
+import { constants, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { CodexJobExecutor } from '../../jobs/executor.js';
+import { loadJobFlow, resolveWorkspaceFile } from '../../jobs/flow.js';
+import { GiteaWorkItemClient } from '../../jobs/gitea.js';
+import { renderExternalTrigger } from '../../jobs/render.js';
+import { runExternalJob } from '../../jobs/runner.js';
+import { AiwgError, EXIT_CODES, handlerResultFromError } from '../errors.js';
+function option(args, name) {
+    const index = args.indexOf(name);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+function usage(message) {
+    throw new AiwgError({ code: 'ERR_USAGE_JOB', message, exitCode: EXIT_CODES.USAGE, hint: 'Run `aiwg job help` for usage.' });
+}
+function help() {
+    console.log(`AIWG external-trigger jobs
+
+Usage:
+  aiwg job validate <flow>
+  aiwg job render-cron <flow> [--format cron|systemd|gitea-actions]
+  aiwg job run <flow> --once [--state-dir <absolute-path>] [--json]
+
+The operating system or CI owns time. AIWG validates and executes one reviewed job.`);
+}
+async function validateFiles(flow) {
+    const workspace = await fs.realpath(flow.spec.executor.workspace);
+    if (workspace !== flow.spec.executor.workspace) {
+        throw new Error('executor.workspace must be canonical (no symlink or relative segments)');
+    }
+    const prompt = resolveWorkspaceFile(flow, flow.spec.executor.prompt);
+    const schema = resolveWorkspaceFile(flow, flow.spec.executor.resultSchema);
+    const [promptStat, schemaSource] = await Promise.all([fs.stat(prompt), fs.readFile(schema, 'utf8'), fs.access(flow.spec.executor.binary, constants.X_OK)]);
+    if (!promptStat.isFile())
+        throw new Error('executor.prompt must resolve to a regular file');
+    JSON.parse(schemaSource);
+    for (const root of flow.spec.security.approvedAttachmentRoots) {
+        const [canonical, stat] = await Promise.all([fs.realpath(root), fs.stat(root)]);
+        if (canonical !== root || !stat.isDirectory())
+            throw new Error('approvedAttachmentRoots must contain canonical directories');
+    }
+}
+async function execute(ctx) {
+    try {
+        const [subcommand = 'help', flowArg] = ctx.args;
+        if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h') {
+            help();
+            return { exitCode: 0 };
+        }
+        if (!['validate', 'render-cron', 'run'].includes(subcommand))
+            usage(`Unknown job subcommand: ${subcommand}`);
+        if (!flowArg || flowArg.startsWith('-'))
+            usage(`job ${subcommand} requires a flow file`);
+        const loaded = await loadJobFlow(flowArg, ctx.cwd);
+        await validateFiles(loaded.flow);
+        if (subcommand === 'validate') {
+            console.log(JSON.stringify({ valid: true, apiVersion: loaded.flow.apiVersion, kind: loaded.flow.kind, name: loaded.flow.metadata.name }));
+            return { exitCode: 0 };
+        }
+        if (subcommand === 'render-cron') {
+            const format = (option(ctx.args.slice(2), '--format') ?? 'cron');
+            if (!['cron', 'systemd', 'gitea-actions'].includes(format))
+                usage(`Unsupported scheduler format: ${format}`);
+            console.log(renderExternalTrigger(loaded.flow, loaded.file, format));
+            return { exitCode: 0 };
+        }
+        if (!ctx.args.includes('--once'))
+            usage('job run requires --once; AIWG does not own a resident scheduler');
+        const stateRoot = option(ctx.args.slice(2), '--state-dir');
+        if (stateRoot && !stateRoot.startsWith('/'))
+            usage('--state-dir must be absolute');
+        if (stateRoot && path.resolve(stateRoot) === path.parse(path.resolve(stateRoot)).root)
+            usage('--state-dir must not be a filesystem root');
+        const client = await GiteaWorkItemClient.create(loaded.flow);
+        const result = await runExternalJob({
+            flow: loaded.flow,
+            client,
+            executor: new CodexJobExecutor(),
+            ...(stateRoot ? { stateRoot } : {}),
+            signal: ctx.signal,
+        });
+        console.log(JSON.stringify(result, null, ctx.args.includes('--json') ? 2 : 0));
+        return { exitCode: result.status === 'failed-verification' ? EXIT_CODES.GENERAL : EXIT_CODES.OK };
+    }
+    catch (error) {
+        return handlerResultFromError(error);
+    }
+}
+export const jobHandler = {
+    id: 'job',
+    name: 'External Job',
+    description: 'Validate, render, or run one externally triggered provider job',
+    category: 'orchestration',
+    aliases: ['job'],
+    execute,
+};
+//# sourceMappingURL=job.js.map

package/dist/src/cli/handlers/runtime-info.js

@@ -258,7 +258,7 @@ async function handleRuntimeInfo(args, cwd = process.cwd()) {
             console.log(`Catalog: ${summary.catalogPath}`);
             // Scheduler backend detection
             const { execSync } = await import('child_process');
-            let schedulerBackend = 'aiwg-cli (daemon)';
+            let schedulerBackend = 'external trigger required (system cron/systemd/CI)';
             let chronyInstalled = false;
             try {
                 execSync('which chronyc 2>/dev/null || which chronyd 2>/dev/null', { stdio: 'pipe' });
@@ -273,7 +273,7 @@ async function handleRuntimeInfo(args, cwd = process.cwd()) {
             const isClaudeCodeContext = process.env.CLAUDE_CODE_VERSION !== undefined ||
                 process.env.ANTHROPIC_API_KEY !== undefined;
             if (isClaudeCodeContext) {
-                schedulerBackend = 'native-cron (CronCreate) / aiwg-cli fallback';
+                schedulerBackend = 'native-cron (CronCreate); external trigger outside agent sessions';
             }
             console.log(`\nScheduler:`);
             console.log(`  Backend:  ${schedulerBackend}`);

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

@@ -64,7 +64,7 @@ function parseServeArgs(args) {
 // ============================================================
 // WebSocket routing (#851)
 //
-// @hono/node-server v1.x does not export createNodeWebSocket.
+// @hono/node-server does not export createNodeWebSocket.
 // We wire WebSocket routes directly via the Node.js HTTP server's
 // 'upgrade' event and the `ws` npm package instead.
 // ============================================================
@@ -550,7 +550,7 @@ export async function startServer(opts) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const app = new Hono();
     // WebSocket routes are handled via Node.js upgrade event below (see setupWebSockets).
-    // @hono/node-server v1.x does not export createNodeWebSocket.
+    // @hono/node-server does not export createNodeWebSocket.
     // Health check
     app.get('/api/health', (c) => c.json({ status: 'ok', readOnly: opts.readOnly }));
     // Connection status — server health, PTY sessions, sandboxes, subsystem status (#887)

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

@@ -28,6 +28,8 @@ Commands:
   restore <session-id>            Restore a reversible catalog tombstone
   purge <session-id>              Preview terminal AIWG-copy purge
   audit --workspace <id>          Read content-free mutation events
+  analytics <view> --workspace <id>  Summary, tool-calls, escalations, or HITL
+  forensics <view> --workspace <id>  Authorized timeline, indicators, or evidence
   doctor                          Check catalog availability and integrity
 
 Options:
@@ -219,6 +221,95 @@ async function executeCommand(ctx, args) {
                         nextCursor: result.nextCursor },
                 });
             }
+            case 'analytics': {
+                const view = requiredPositional(args, 0, 'analytics view');
+                const { workspaceId } = readAuthorizationContext(ctx, args, command, repository);
+                const query = analyticsQuery(args, workspaceId);
+                if (view === 'summary') {
+                    return ok(command, {
+                        view,
+                        summary: repository.analyticsSummary(query),
+                    });
+                }
+                const categories = analyticsCategories(view);
+                const items = repository.listAnalyticsFacts({ ...query, categories });
+                return ok(command, {
+                    analyticsVersion: '1.0.0',
+                    view,
+                    items,
+                    count: items.length,
+                    groupBy: analyticsGrouping(items, args.values.get('--group-by')),
+                });
+            }
+            case 'forensics': {
+                if (!args.flags.has('--authorize-forensics')) {
+                    throw new CliError('OPERATION_NOT_AUTHORIZED', 'forensic extraction requires --authorize-forensics for this invocation', EXIT.usage);
+                }
+                const view = requiredPositional(args, 0, 'forensics view');
+                const { workspaceId } = authorizationContext(ctx, args, command);
+                const query = analyticsQuery(args, workspaceId);
+                if (view === 'indicators') {
+                    const items = repository.listAnalyticsFacts({
+                        ...query,
+                        categories: ['indicator'],
+                    });
+                    return ok(command, forensicOutput(view, items, args));
+                }
+                if (view === 'timeline') {
+                    const target = requiredPositional(args, 1, 'session-id or query');
+                    const direct = repository.getSession(target, workspaceId);
+                    const sessionIds = direct
+                        ? [target]
+                        : [...new Set(repository.search({
+                                query: target,
+                                workspaceId,
+                                limit: boundedInteger(args.values.get('--limit'), 50, 1, 500, '--limit'),
+                            }).items.map((item) => item.sessionId))];
+                    const items = sessionIds.flatMap((sessionId) => repository.listAnalyticsFacts({ ...query, sessionId }));
+                    return ok(command, forensicOutput(view, items, args));
+                }
+                if (view === 'evidence') {
+                    const id = requiredPositional(args, 1, 'event-id, fact-id, or candidate-id');
+                    const evidence = repository.getAnalyticsEvidence(id, workspaceId);
+                    if (evidence.fact && evidence.event) {
+                        return ok(command, {
+                            analyticsVersion: '1.0.0',
+                            view,
+                            fact: evidence.fact,
+                            event: {
+                                eventId: evidence.event.eventId,
+                                sessionId: evidence.event.sessionId,
+                                sourceId: evidence.event.sourceId,
+                                importRunId: evidence.event.importRunId,
+                                sequence: evidence.event.sequence,
+                                kind: evidence.event.kind,
+                                occurredAt: evidence.event.occurredAt,
+                                sensitivity: evidence.event.sensitivity,
+                                rawReference: evidence.event.rawReference,
+                                digest: evidence.event.digest,
+                            },
+                        });
+                    }
+                    const candidate = repository.getCandidate(id, undefined, workspaceId);
+                    if (!candidate) {
+                        throw new CliError('EVIDENCE_NOT_FOUND', `authorized analytics evidence not found: ${id}`, EXIT.unavailable);
+                    }
+                    return ok(command, {
+                        analyticsVersion: '1.0.0',
+                        view,
+                        candidate: {
+                            candidateId: candidate.candidateId,
+                            version: candidate.version,
+                            type: candidate.type,
+                            evidence: candidate.evidence.map(({ quote: _quote, ...citation }) => citation),
+                            sensitivity: candidate.sensitivity,
+                            security: candidate.security,
+                            reviewState: candidate.reviewState,
+                        },
+                    });
+                }
+                throw new CliError('INVALID_ARGUMENT', `unknown forensics view: ${view}`, EXIT.usage);
+            }
             case 'extract': {
                 const { workspaceId } = authorizationContext(ctx, args, command);
                 const sessionId = args.positionals[0];
@@ -997,6 +1088,7 @@ function parseArgs(argv) {
         '--manifest', '--provider-home', '--codex-root', '--lock-wait-ms', '--min-coverage', '--gap',
         '--inactivity-threshold',
         '--control-events',
+        '--session', '--status', '--actor', '--group-by',
     ]);
     let command;
     for (let index = 0; index < argv.length; index += 1) {
@@ -1184,6 +1276,96 @@ function dependentAction(value) {
     }
     return value;
 }
+function analyticsQuery(args, workspaceId) {
+    const providerInput = args.values.get('--provider');
+    const statusInput = args.values.get('--status');
+    return {
+        workspaceId,
+        provider: providerInput ? assertSessionProviderId(providerInput) : undefined,
+        sessionId: args.values.get('--session'),
+        dateFrom: args.values.get('--date-from'),
+        dateTo: args.values.get('--date-to'),
+        tool: args.values.get('--tool'),
+        status: statusInput ? analyticsStatus(statusInput) : undefined,
+        actor: args.values.get('--actor') ?? args.values.get('--participant'),
+        tag: args.values.get('--tag'),
+        sensitivity: args.values.get('--sensitivity'),
+        extractionState: args.values.get('--extraction-state'),
+        limit: boundedInteger(args.values.get('--limit'), 500, 1, 5_000, '--limit'),
+    };
+}
+function analyticsStatus(value) {
+    const allowed = new Set([
+        'requested', 'running', 'succeeded', 'failed', 'granted', 'denied',
+        'timed-out', 'unsupported', 'provider-unknown', 'observed',
+    ]);
+    if (!allowed.has(value)) {
+        throw new CliError('INVALID_ARGUMENT', `invalid analytics status: ${value}`, EXIT.usage);
+    }
+    return value;
+}
+function analyticsCategories(view) {
+    if (view === 'tool-calls')
+        return ['tool-call', 'tool-result'];
+    if (view === 'escalations')
+        return ['escalation'];
+    if (view === 'hitl')
+        return ['hitl'];
+    throw new CliError('INVALID_ARGUMENT', `unknown analytics view: ${view}`, EXIT.usage);
+}
+function analyticsGrouping(items, groupBy) {
+    if (!groupBy)
+        return null;
+    if (!['tool', 'session', 'provider'].includes(groupBy)) {
+        throw new CliError('INVALID_ARGUMENT', `invalid --group-by value: ${groupBy}`, EXIT.usage);
+    }
+    const counts = {};
+    for (const item of items) {
+        const value = groupBy === 'tool'
+            ? item.toolName
+            : groupBy === 'session'
+                ? item.sessionId
+                : item.provider;
+        const key = typeof value === 'string' && value ? value : '<unknown>';
+        counts[key] = (counts[key] ?? 0) + 1;
+    }
+    return Object.fromEntries(Object.entries(counts).sort(([left], [right]) => left.localeCompare(right)));
+}
+function forensicOutput(view, items, args) {
+    const output = {
+        analyticsVersion: '1.0.0',
+        view,
+        items,
+        count: items.length,
+        authorization: {
+            explicit: true,
+            providerLogsModified: false,
+            historicalContentExecuted: false,
+        },
+    };
+    if (args.flags.has('--markdown')) {
+        output.markdown = [
+            `# Session Forensics ${view}`,
+            '',
+            `Facts: ${items.length}`,
+            '',
+            '| Time | Provider | Session | Category | Status | Evidence |',
+            '|---|---|---|---|---|---|',
+            ...items.map((item) => {
+                const citation = item.sourceCitation;
+                return [
+                    item.occurredAt ?? '<unknown>',
+                    item.provider ?? '<unknown>',
+                    item.sessionId ?? '<unknown>',
+                    item.category ?? '<unknown>',
+                    item.status ?? '<unknown>',
+                    citation?.eventId ?? item.eventId ?? '<unknown>',
+                ].map((value) => String(value).replaceAll('|', '\\|')).join(' | ');
+            }).map((row) => `| ${row} |`),
+        ].join('\n');
+    }
+    return output;
+}
 function isDryRun(ctx, args) {
     return Boolean(ctx.dryRun || args.flags.has('--dry-run'));
 }
@@ -1202,6 +1384,12 @@ function emit(value) {
 function printHuman(value) {
     if (value.status === 'preview')
         console.log('Preview (no changes applied)');
+    if (value.command === 'sessions.forensics' && value.data
+        && typeof value.data === 'object' && 'markdown' in value.data
+        && typeof value.data.markdown === 'string') {
+        console.log(value.data.markdown);
+        return;
+    }
     if (value.command === 'sessions.timeline' && value.data
         && typeof value.data === 'object' && 'items' in value.data) {
         const data = value.data;