@cleocode/cleo 2026.4.9 → 2026.4.11

package/dist/cli/commands/self-update.js

@@ -0,0 +1,329 @@
+/**
+ * CLI self-update command - check for and install updates.
+ *
+ * After updating, runs post-update diagnostics:
+ *   - Pre-flight storage migration check
+ *   - Auto-triggers upgrade if JSON data needs SQLite migration
+ *
+ * Designed for LLM agents: structured JSON output, actionable fix commands.
+ *
+ * @task T4699
+ * @epic T4454
+ */
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import * as readline from 'node:readline';
+import { promisify } from 'node:util';
+import { ExitCode } from '@cleocode/contracts';
+import { BUILD_CONFIG, CleoError, checkStorageMigration, formatError, getCleoHome, getRuntimeDiagnostics, runUpgrade, } from '@cleocode/core/internal';
+import { createSelfUpdateProgress } from '../progress.js';
+import { cliOutput } from '../renderers/index.js';
+const execAsync = promisify(execFile);
+const GITHUB_REPO = BUILD_CONFIG.repository.fullName;
+async function getCurrentVersion() {
+    const cleoHome = getCleoHome();
+    try {
+        const content = await readFile(join(cleoHome, 'VERSION'), 'utf-8');
+        return (content.split('\n')[0] ?? 'unknown').trim();
+    }
+    catch {
+        return 'unknown';
+    }
+}
+async function getNpmInstalledVersion() {
+    try {
+        const { stdout } = await execAsync('npm', [
+            'ls',
+            '-g',
+            '@cleocode/cleo',
+            '--depth=0',
+            '--json',
+        ]);
+        const data = JSON.parse(stdout);
+        return data.dependencies?.['@cleocode/cleo']?.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+async function getDistTagVersion(tag) {
+    try {
+        const { stdout } = await execAsync('npm', ['view', `@cleocode/cleo@${tag}`, 'version']);
+        const v = stdout.trim();
+        return v || null;
+    }
+    catch {
+        // Fallback to GitHub latest for stable only
+        if (tag === 'latest') {
+            try {
+                const { stdout } = await execAsync('curl', [
+                    '-sL',
+                    '--max-time',
+                    '10',
+                    `https://api.github.com/repos/${GITHUB_REPO}/releases/latest`,
+                ]);
+                const data = JSON.parse(stdout);
+                return data.tag_name?.replace(/^v/, '') ?? null;
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+}
+async function writeRuntimeVersionMetadata(mode, source, version) {
+    const cleoHome = getCleoHome();
+    const lines = [
+        version,
+        `mode=${mode}`,
+        `source=${source}`,
+        `installed=${new Date().toISOString()}`,
+    ];
+    await import('node:fs/promises').then(({ writeFile, mkdir }) => mkdir(cleoHome, { recursive: true }).then(() => writeFile(join(cleoHome, 'VERSION'), `${lines.join('\n')}\n`, 'utf-8')));
+}
+export function registerSelfUpdateCommand(program) {
+    program
+        .command('self-update')
+        .description('Check for and install CLEO updates, then run post-update diagnostics')
+        .option('--check', 'Only check if update is available')
+        .option('--status', 'Show current vs latest version')
+        .option('--version <ver>', 'Update to specific version')
+        .option('--channel <channel>', 'Update channel: stable|beta')
+        .option('--beta', 'Shortcut for --channel beta')
+        .option('--force', 'Force update even if same version')
+        .option('--post-update', 'Run post-update diagnostics and migration only')
+        .option('--no-auto-upgrade', 'Skip automatic upgrade after update')
+        .option('--auto-migrate', 'Automatically migrate storage without prompting')
+        .action(async (_opts, command) => {
+        const opts = command.optsWithGlobals ? command.optsWithGlobals() : command.opts();
+        const isHuman = opts['human'] === true || (!!process.stdout.isTTY && opts['json'] !== true);
+        const progress = createSelfUpdateProgress(isHuman);
+        try {
+            const noAutoUpgrade = opts['autoUpgrade'] === false; // Commander normalizes --no-auto-upgrade to autoUpgrade=false
+            // --post-update: skip version check, just run diagnostics + upgrade
+            if (opts['postUpdate']) {
+                progress.start();
+                progress.step(4, 'Running post-update diagnostics');
+                await runPostUpdateDiagnostics({
+                    skipUpgrade: noAutoUpgrade,
+                    autoMigrate: !!opts['autoMigrate'] || !!opts['force'],
+                });
+                progress.complete('Post-update diagnostics complete');
+                return;
+            }
+            progress.start();
+            progress.step(0, 'Detecting installation type');
+            const runtime = await getRuntimeDiagnostics();
+            const script = runtime.invocation.script;
+            const fromNodeModules = script.includes('/node_modules/@cleocode/cleo/') ||
+                script.includes('\\node_modules\\@cleocode\\cleo\\');
+            const isDev = runtime.channel === 'dev' && !fromNodeModules;
+            progress.step(1, 'Checking current version');
+            const currentVersion = isDev
+                ? await getCurrentVersion()
+                : ((await getNpmInstalledVersion()) ?? (await getCurrentVersion()));
+            const rawChannel = opts['channel']?.toLowerCase();
+            if (rawChannel && rawChannel !== 'stable' && rawChannel !== 'beta') {
+                throw new CleoError(ExitCode.VALIDATION_ERROR, `Invalid --channel '${rawChannel}'. Expected stable|beta`);
+            }
+            const requestedChannel = opts['beta']
+                ? 'beta'
+                : (rawChannel ??
+                    (runtime.channel === 'beta' ? 'beta' : 'stable'));
+            if (isDev && !opts['force']) {
+                // For dev installs, still run post-update diagnostics
+                progress.step(4, 'Running post-update checks');
+                const preflight = checkStorageMigration();
+                cliOutput({
+                    devMode: true,
+                    channel: runtime.channel,
+                    currentVersion,
+                    message: 'Dev install detected. Use git pull to update.',
+                    storagePreflight: {
+                        migrationNeeded: preflight.migrationNeeded,
+                        summary: preflight.summary,
+                        fix: preflight.fix,
+                    },
+                }, { command: 'self-update' });
+                if (preflight.migrationNeeded) {
+                    progress.error(`Storage migration needed: ${preflight.summary}`);
+                    process.stderr.write(`\n⚠ Storage migration needed: ${preflight.summary}\n` +
+                        `  Fix: ${preflight.fix}\n` +
+                        `  Or run: cleo upgrade\n\n`);
+                }
+                else {
+                    progress.complete('Dev environment check complete');
+                }
+                process.exit(ExitCode.NO_DATA);
+                return;
+            }
+            if (opts['status'] || opts['check']) {
+                progress.step(2, 'Querying npm registry');
+                const latest = await getDistTagVersion(requestedChannel === 'beta' ? 'beta' : 'latest');
+                if (!latest) {
+                    throw new CleoError(ExitCode.DEPENDENCY_ERROR, 'Failed to check latest version from GitHub');
+                }
+                progress.step(3, 'Comparing versions');
+                const updateAvailable = latest !== currentVersion;
+                const preflight = checkStorageMigration();
+                cliOutput({
+                    currentVersion,
+                    latestVersion: latest,
+                    channel: requestedChannel,
+                    updateAvailable,
+                    storagePreflight: {
+                        migrationNeeded: preflight.migrationNeeded,
+                        summary: preflight.summary,
+                        fix: preflight.fix,
+                    },
+                }, { command: 'self-update' });
+                if (opts['check'] && updateAvailable) {
+                    process.exit(1); // exit 1 means update available for scripting
+                }
+                return;
+            }
+            // Actual update - delegated to shell for file system operations
+            progress.step(2, 'Querying npm registry');
+            const latest = opts['version'] ??
+                (await getDistTagVersion(requestedChannel === 'beta' ? 'beta' : 'latest'));
+            if (!latest) {
+                throw new CleoError(ExitCode.DEPENDENCY_ERROR, 'Failed to check latest version from GitHub');
+            }
+            progress.step(3, 'Comparing versions');
+            if (latest === currentVersion && !opts['force']) {
+                // Up to date - still run post-update diagnostics
+                progress.step(4, 'Running post-update checks');
+                await runPostUpdateDiagnostics({
+                    skipUpgrade: noAutoUpgrade,
+                    autoMigrate: !!opts['autoMigrate'] || !!opts['force'],
+                });
+                progress.complete('Already up to date');
+                cliOutput({
+                    currentVersion,
+                    upToDate: true,
+                }, { command: 'self-update', message: 'Already up to date' });
+                return;
+            }
+            const spec = opts['version']
+                ? `@cleocode/cleo@${latest}`
+                : requestedChannel === 'beta'
+                    ? '@cleocode/cleo@beta'
+                    : '@cleocode/cleo@latest';
+            progress.step(4, `Installing ${spec}`);
+            await execAsync('npm', ['install', '-g', spec], { maxBuffer: 10 * 1024 * 1024 });
+            await writeRuntimeVersionMetadata('prod-npm', 'npm', latest);
+            progress.step(5, 'Finalizing');
+            cliOutput({
+                currentVersion,
+                targetVersion: latest,
+                channel: requestedChannel,
+                updated: true,
+                command: `npm install -g ${spec}`,
+            }, { command: 'self-update', message: `Updated to ${latest}` });
+            await runPostUpdateDiagnostics({
+                skipUpgrade: noAutoUpgrade,
+                autoMigrate: !!opts['autoMigrate'] || !!opts['force'],
+            });
+            progress.complete(`Updated to ${latest}`);
+        }
+        catch (err) {
+            if (err instanceof CleoError) {
+                progress.error(err.message);
+                console.error(formatError(err));
+                process.exit(err.code);
+            }
+            progress.error('Unexpected error during update');
+            throw err;
+        }
+    });
+}
+/**
+ * Run post-update diagnostics and auto-upgrade.
+ *
+ * Called after a version update to detect and fix:
+ *   - JSON→SQLite storage migration
+ *   - Schema version mismatches
+ *   - Structural data repairs
+ *
+ * @task T4699
+ */
+async function runPostUpdateDiagnostics(opts) {
+    const preflight = checkStorageMigration();
+    if (preflight.migrationNeeded) {
+        if (opts?.skipUpgrade) {
+            process.stderr.write(`\n⚠ Storage migration detected: ${preflight.summary}\n` +
+                `  Auto-upgrade skipped (--no-auto-upgrade).\n` +
+                `  Run manually: cleo upgrade\n\n`);
+            cliOutput({
+                postUpdate: true,
+                upgradeSkipped: true,
+                storagePreflight: {
+                    migrationNeeded: true,
+                    summary: preflight.summary,
+                    fix: preflight.fix,
+                },
+            }, { command: 'self-update', message: 'Post-update upgrade skipped.' });
+            return;
+        }
+        process.stderr.write(`\n⚠ Storage migration detected: ${preflight.summary}\n`);
+        let shouldMigrate = !!opts?.autoMigrate;
+        if (!shouldMigrate) {
+            const rl = readline.createInterface({
+                input: process.stdin,
+                output: process.stdout,
+            });
+            shouldMigrate = await new Promise((resolve) => {
+                rl.question('  Do you want to run the upgrade now? [Y/n] ', (answer) => {
+                    rl.close();
+                    const clean = answer.trim().toLowerCase();
+                    resolve(clean === '' || clean === 'y' || clean === 'yes');
+                });
+            });
+        }
+        if (!shouldMigrate) {
+            process.stderr.write(`\n  Upgrade skipped. Run manually later: cleo upgrade\n\n`);
+            return;
+        }
+        process.stderr.write(`  Running upgrade...\n\n`);
+        const result = await runUpgrade({ autoMigrate: true });
+        // Show structured output of each action taken
+        if (result.actions.length > 0) {
+            process.stderr.write('Upgrade actions:\n');
+            for (const action of result.actions) {
+                const icon = action.status === 'applied' ? '  ✓' : action.status === 'error' ? '  ✗' : '  -';
+                process.stderr.write(`${icon} ${action.action}: ${action.details}\n`);
+            }
+            process.stderr.write('\n');
+        }
+        cliOutput({
+            postUpdate: true,
+            upgrade: {
+                success: result.success,
+                applied: result.applied,
+                actions: result.actions,
+                storageMigration: result.storageMigration,
+                errors: result.errors.length > 0 ? result.errors : undefined,
+            },
+        }, {
+            command: 'self-update',
+            message: result.success
+                ? 'Post-update upgrade complete.'
+                : 'Post-update upgrade had errors.',
+        });
+        if (!result.success) {
+            process.stderr.write(`\n⚠ Some upgrade steps failed. Manual fix:\n` + `  ${preflight.fix}\n\n`);
+        }
+    }
+    else {
+        cliOutput({
+            postUpdate: true,
+            storagePreflight: {
+                migrationNeeded: false,
+                summary: preflight.summary,
+            },
+        }, { command: 'self-update', message: 'No post-update actions needed.' });
+    }
+}
+//# sourceMappingURL=self-update.js.map

package/dist/cli/commands/self-update.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-update.js","sourceRoot":"","sources":["../../../src/cli/commands/self-update.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/sequence.d.ts

@@ -0,0 +1,8 @@
+/**
+ * CLI sequence command - task ID sequence management.
+ * @task T4538
+ * @epic T4454
+ */
+import type { ShimCommand as Command } from '../commander-shim.js';
+export declare function registerSequenceCommand(program: Command): void;
+//# sourceMappingURL=sequence.d.ts.map

package/dist/cli/commands/sequence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequence.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/sequence.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,WAAW,IAAI,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEnE,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA2C9D"}

package/dist/cli/commands/sequence.js

@@ -0,0 +1,30 @@
+/**
+ * CLI sequence command - task ID sequence management.
+ * @task T4538
+ * @epic T4454
+ */
+import { dispatchFromCli } from '../../dispatch/adapters/cli.js';
+export function registerSequenceCommand(program) {
+    const sequence = program
+        .command('sequence')
+        .description('Inspect and manage task ID sequence (show/check/repair)');
+    sequence
+        .command('show')
+        .description('Display current sequence state')
+        .action(async () => {
+        await dispatchFromCli('query', 'admin', 'sequence', { action: 'show' }, { command: 'sequence' });
+    });
+    sequence
+        .command('check')
+        .description('Verify counter >= max(todo + archive)')
+        .action(async () => {
+        await dispatchFromCli('query', 'admin', 'sequence', { action: 'check' }, { command: 'sequence' });
+    });
+    sequence
+        .command('repair')
+        .description('Reset counter to max + 1 if behind')
+        .action(async () => {
+        await dispatchFromCli('mutate', 'admin', 'config.set', { key: 'sequence', value: 'repair' }, { command: 'sequence' });
+    });
+}
+//# sourceMappingURL=sequence.js.map

package/dist/cli/commands/sequence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequence.js","sourceRoot":"","sources":["../../../src/cli/commands/sequence.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAGjE,MAAM,UAAU,uBAAuB,CAAC,OAAgB;IACtD,MAAM,QAAQ,GAAG,OAAO;SACrB,OAAO,CAAC,UAAU,CAAC;SACnB,WAAW,CAAC,yDAAyD,CAAC,CAAC;IAE1E,QAAQ;SACL,OAAO,CAAC,MAAM,CAAC;SACf,WAAW,CAAC,gCAAgC,CAAC;SAC7C,MAAM,CAAC,KAAK,IAAI,EAAE;QACjB,MAAM,eAAe,CACnB,OAAO,EACP,OAAO,EACP,UAAU,EACV,EAAE,MAAM,EAAE,MAAM,EAAE,EAClB,EAAE,OAAO,EAAE,UAAU,EAAE,CACxB,CAAC;IACJ,CAAC,CAAC,CAAC;IAEL,QAAQ;SACL,OAAO,CAAC,OAAO,CAAC;SAChB,WAAW,CAAC,uCAAuC,CAAC;SACpD,MAAM,CAAC,KAAK,IAAI,EAAE;QACjB,MAAM,eAAe,CACnB,OAAO,EACP,OAAO,EACP,UAAU,EACV,EAAE,MAAM,EAAE,OAAO,EAAE,EACnB,EAAE,OAAO,EAAE,UAAU,EAAE,CACxB,CAAC;IACJ,CAAC,CAAC,CAAC;IAEL,QAAQ;SACL,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CAAC,oCAAoC,CAAC;SACjD,MAAM,CAAC,KAAK,IAAI,EAAE;QACjB,MAAM,eAAe,CACnB,QAAQ,EACR,OAAO,EACP,YAAY,EACZ,EAAE,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE,EACpC,EAAE,OAAO,EAAE,UAAU,EAAE,CACxB,CAAC;IACJ,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/cli/commands/session.d.ts

@@ -0,0 +1,12 @@
+/**
+ * CLI session command group.
+ * @task T4463
+ * @epic T4454
+ */
+import type { ShimCommand as Command } from '../commander-shim.js';
+/**
+ * Register the session command group.
+ * @task T4463
+ */
+export declare function registerSessionCommand(program: Command): void;
+//# sourceMappingURL=session.d.ts.map

package/dist/cli/commands/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/session.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,WAAW,IAAI,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAGnE;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA2O7D"}

package/dist/cli/commands/session.js

@@ -0,0 +1,175 @@
+/**
+ * CLI session command group.
+ * @task T4463
+ * @epic T4454
+ */
+import { ExitCode } from '@cleocode/contracts';
+import { dispatchFromCli, dispatchRaw, handleRawError } from '../../dispatch/adapters/cli.js';
+import { cliOutput } from '../renderers/index.js';
+/**
+ * Register the session command group.
+ * @task T4463
+ */
+export function registerSessionCommand(program) {
+    const session = program.command('session').description('Manage work sessions');
+    session
+        .command('start')
+        .description('Start a new session')
+        .requiredOption('--scope <scope>', 'Session scope (epic:T### or global)')
+        .requiredOption('--name <name>', 'Session name')
+        .option('--auto-start', 'Auto-start on first available task')
+        .option('--auto-focus', 'Auto-focus on first available task (alias for --auto-start)')
+        .option('--focus <taskId>', 'Set initial task to work on')
+        .option('--agent <agent>', 'Agent identifier')
+        .option('--grade', 'Enable full query+mutation audit logging for behavioral grading')
+        .action(async (opts) => {
+        await dispatchFromCli('mutate', 'session', 'start', {
+            scope: opts['scope'],
+            name: opts['name'],
+            autoStart: (opts['autoStart'] || opts['autoFocus']),
+            focus: opts['focus'],
+            grade: opts['grade'],
+        }, { command: 'session', operation: 'session.start' });
+    });
+    session
+        .command('stop')
+        .alias('end')
+        .description('Stop the current session')
+        .option('--session <id>', 'Specific session ID to stop')
+        .option('--note <note>', 'Stop note')
+        .option('--next-action <action>', 'Suggested next action')
+        .action(async (opts) => {
+        await dispatchFromCli('mutate', 'session', 'end', {
+            note: opts['note'],
+            nextAction: opts['nextAction'],
+        }, { command: 'session', operation: 'session.end' });
+    });
+    session
+        .command('handoff')
+        .description('Show handoff data from the most recent ended session')
+        .option('--scope <scope>', 'Filter by scope (epic:T### or global)')
+        .action(async (opts) => {
+        const scope = opts['scope'];
+        const response = await dispatchRaw('query', 'session', 'handoff.show', {
+            scope,
+        });
+        if (!response.success) {
+            handleRawError(response, { command: 'session handoff', operation: 'session.handoff.show' });
+        }
+        const data = response.data;
+        if (!data || !data.handoff) {
+            cliOutput({ handoff: null }, {
+                command: 'session handoff',
+                message: 'No handoff data available',
+                operation: 'session.handoff.show',
+            });
+            process.exit(ExitCode.NO_DATA);
+            return;
+        }
+        const { sessionId, handoff } = data;
+        // Format the handoff data for display
+        const formattedHandoff = {
+            sessionId,
+            lastTask: handoff.lastTask ?? 'None',
+            tasksCompleted: handoff.tasksCompleted ?? [],
+            tasksCreated: handoff.tasksCreated ?? [],
+            decisionsRecorded: handoff.decisionsRecorded ?? 0,
+            nextSuggested: handoff.nextSuggested ?? [],
+            openBlockers: handoff.openBlockers ?? [],
+            openBugs: handoff.openBugs ?? [],
+            ...(handoff.note ? { note: handoff.note } : {}),
+            ...(handoff.nextAction ? { nextAction: handoff.nextAction } : {}),
+        };
+        cliOutput({ handoff: formattedHandoff }, { command: 'session handoff', operation: 'session.handoff.show' });
+    });
+    session
+        .command('status')
+        .description('Show current session status')
+        .action(async () => {
+        const response = await dispatchRaw('query', 'session', 'status');
+        if (!response.success) {
+            handleRawError(response, { command: 'session', operation: 'session.status' });
+        }
+        const data = response.data;
+        if (!data || data['session'] === null || (data['session'] === undefined && !data['id'])) {
+            cliOutput({ session: null }, { command: 'session', message: 'No active session', operation: 'session.status' });
+            process.exit(ExitCode.NO_DATA);
+            return;
+        }
+        cliOutput({ session: data }, { command: 'session', operation: 'session.status' });
+    });
+    session
+        .command('resume <sessionId>')
+        .description('Resume an existing session')
+        .action(async (sessionId) => {
+        await dispatchFromCli('mutate', 'session', 'resume', {
+            sessionId,
+        }, { command: 'session', operation: 'session.resume' });
+    });
+    session
+        .command('find')
+        .description('Find sessions (lightweight discovery — minimal fields, low context cost)')
+        .option('--status <status>', 'Filter by status (active|ended|orphaned)')
+        .option('--scope <scope>', 'Filter by scope (e.g. "epic:T001" or "global")')
+        .option('--query <query>', 'Fuzzy match on session name or ID')
+        .option('--limit <n>', 'Max results', parseInt)
+        .action(async (opts) => {
+        await dispatchFromCli('query', 'session', 'find', {
+            status: opts['status'],
+            scope: opts['scope'],
+            query: opts['query'],
+            limit: opts['limit'],
+        }, { command: 'session', operation: 'session.find' });
+    });
+    session
+        .command('list')
+        .description('List sessions')
+        .option('--status <status>', 'Filter by status (active|ended|orphaned)')
+        .option('--limit <n>', 'Max results', parseInt)
+        .option('--offset <n>', 'Skip first n results', parseInt)
+        .action(async (opts) => {
+        await dispatchFromCli('query', 'session', 'list', {
+            status: opts['status'],
+            limit: opts['limit'],
+            offset: opts['offset'],
+        }, { command: 'session', operation: 'session.list' });
+    });
+    session
+        .command('gc')
+        .description('Garbage collect old sessions')
+        .option('--max-age <days>', 'Max age in days for active sessions', parseInt)
+        .action(async (opts) => {
+        await dispatchFromCli('mutate', 'session', 'gc', {
+            maxAgeDays: opts['maxAge'],
+        }, { command: 'session', operation: 'session.gc' });
+    });
+    session
+        .command('record-decision')
+        .description('Record a decision made during the current session')
+        .requiredOption('--session-id <sessionId>', 'Session ID')
+        .requiredOption('--task-id <taskId>', 'Task ID the decision relates to')
+        .requiredOption('--decision <decision>', 'Decision text')
+        .requiredOption('--rationale <rationale>', 'Rationale for the decision')
+        .option('--alternatives <alternatives>', 'Alternatives considered')
+        .action(async (opts) => {
+        await dispatchFromCli('mutate', 'session', 'record.decision', {
+            sessionId: opts['sessionId'],
+            taskId: opts['taskId'],
+            decision: opts['decision'],
+            rationale: opts['rationale'],
+            alternatives: opts['alternatives'],
+        }, { command: 'session', operation: 'session.record.decision' });
+    });
+    session
+        .command('decision-log')
+        .description('Show decisions recorded in a session')
+        .option('--session-id <sessionId>', 'Session ID to filter by')
+        .option('--task-id <taskId>', 'Task ID to filter by')
+        .action(async (opts) => {
+        await dispatchFromCli('query', 'session', 'decision.log', {
+            sessionId: opts['sessionId'],
+            taskId: opts['taskId'],
+        }, { command: 'session', operation: 'session.decision.log' });
+    });
+}
+//# sourceMappingURL=session.js.map

package/dist/cli/commands/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../../src/cli/commands/session.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/show.d.ts

@@ -0,0 +1,13 @@
+/**
+ * CLI show command.
+ * @task T4460
+ * @epic T4454
+ */
+import type { ShimCommand as Command } from '../commander-shim.js';
+/**
+ * Register the show command.
+ * @task T4460
+ * @task T4666
+ */
+export declare function registerShowCommand(program: Command): void;
+//# sourceMappingURL=show.d.ts.map

package/dist/cli/commands/show.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"show.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/show.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,WAAW,IAAI,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEnE;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAO1D"}

package/dist/cli/commands/show.js

@@ -0,0 +1,20 @@
+/**
+ * CLI show command.
+ * @task T4460
+ * @epic T4454
+ */
+import { dispatchFromCli } from '../../dispatch/adapters/cli.js';
+/**
+ * Register the show command.
+ * @task T4460
+ * @task T4666
+ */
+export function registerShowCommand(program) {
+    program
+        .command('show <taskId>')
+        .description('Show full task details by ID')
+        .action(async (taskId) => {
+        await dispatchFromCli('query', 'tasks', 'show', { taskId }, { command: 'show' });
+    });
+}
+//# sourceMappingURL=show.js.map

package/dist/cli/commands/show.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"show.js","sourceRoot":"","sources":["../../../src/cli/commands/show.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAGjE;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAgB;IAClD,OAAO;SACJ,OAAO,CAAC,eAAe,CAAC;SACxB,WAAW,CAAC,8BAA8B,CAAC;SAC3C,MAAM,CAAC,KAAK,EAAE,MAAc,EAAE,EAAE;QAC/B,MAAM,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IACnF,CAAC,CAAC,CAAC;AACP,CAAC"}