@aiwg/cli 2026.7.21 → 2026.7.24

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

@@ -1,16 +1,20 @@
-import { mkdirSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-import { CLAUDE_ADAPTER_VERSION, ClaudeSessionAdapter, CODEX_ADAPTER_VERSION, CodexSessionAdapter, COPILOT_ADAPTER_VERSION, CopilotSessionAdapter, CURSOR_ADAPTER_VERSION, CursorSessionAdapter, FACTORY_ADAPTER_VERSION, FactorySessionAdapter, HERMES_ADAPTER_VERSION, HermesSessionAdapter, OPENCODE_ADAPTER_VERSION, OpenCodeSessionAdapter, OPENCLAW_ADAPTER_VERSION, OpenClawSessionAdapter, OPENHUMAN_ADAPTER_VERSION, OpenHumanSessionAdapter, WARP_ADAPTER_VERSION, WarpSessionAdapter, DEVIN_DESKTOP_ADAPTER_VERSION, DevinDesktopSessionAdapter, CandidateExtractionService, GENERIC_ADAPTER_VERSION, GenericSessionInterchangeAdapter, IncrementalSessionImporter, FilesystemMemoryDestination, FilesystemPromotionDispositionCoordinator, MemoryPromotionGateway, SESSION_CONTRACT_VERSION, SESSION_PROVIDER_IDS, SessionContractError, SessionRepository, SessionSourceSchema, StructuralCandidateExtractor, resolveMemoryConsumerManifest, assertSessionProviderId, redactSourceLocator, } from '../../sessions/index.js';
+import { existsSync, mkdirSync, realpathSync, statSync, } from 'node:fs';
+import { dirname, isAbsolute, resolve, } from 'node:path';
+import { CLAUDE_ADAPTER_VERSION, ClaudeSessionAdapter, CODEX_ADAPTER_VERSION, CodexSessionAdapter, COPILOT_ADAPTER_VERSION, CopilotSessionAdapter, CURSOR_ADAPTER_VERSION, CursorSessionAdapter, FACTORY_ADAPTER_VERSION, FactorySessionAdapter, HERMES_ADAPTER_VERSION, HermesSessionAdapter, OPENCODE_ADAPTER_VERSION, OpenCodeSessionAdapter, OPENCLAW_ADAPTER_VERSION, OpenClawSessionAdapter, OPENHUMAN_ADAPTER_VERSION, OpenHumanSessionAdapter, WARP_ADAPTER_VERSION, WarpSessionAdapter, DEVIN_DESKTOP_ADAPTER_VERSION, DevinDesktopSessionAdapter, CandidateExtractionService, GENERIC_ADAPTER_VERSION, GenericSessionInterchangeAdapter, IncrementalSessionImporter, ImportLeaseContentionError, FilesystemMemoryDestination, FilesystemPromotionDispositionCoordinator, MemoryPromotionGateway, SESSION_CONTRACT_VERSION, SESSION_PROVIDER_IDS, SessionContractError, SessionRepository, SessionSourceSchema, StructuralCandidateExtractor, resolveMemoryConsumerManifest, assertSessionProviderId, acquireImportLease, defaultDiscoveryManifestPath, discoverWorkspaceHistories, deriveSessionTimeline, importDiscoveryManifest, previewDiscoveryImport, publicDiscoveryManifest, readDiscoveryManifest, redactSourceLocator, sha256, parseTimelineGap, writeDiscoveryManifest, } from '../../sessions/index.js';
 const JSON_CONTRACT_VERSION = '1.0.0';
 const EXIT = {
     ok: 0, usage: 2, unsupported: 3, unavailable: 4, contract: 5, storage: 6,
+    locked: 7, coverage: 8,
 };
 const HELP = `Usage: aiwg sessions <command> [options]
 
 Commands:
   sources                         Show all canonical provider dispositions
+  discover --workspace <path>     Inventory authorized workspace histories
+  import-discovered --workspace <path>  Import the exact saved manifest
   import <file> --source-id <id>  Import a supported provider JSONL source
   list [--limit N] [--cursor N]   List normalized sessions
+  timeline [--gap 30m]            Report chronological activity segments
   show <session-id>               Show a session with events and tags
   search <query> --workspace <id> Search authorized normalized content
   extract [session-id] --workspace <id> Extract structural candidates
@@ -30,6 +34,13 @@ Options:
   --json          Emit the versioned JSON contract
   --dry-run       Preview a mutation without changing state
   --db <path>     Override .aiwg/sessions/catalog.sqlite
+  --manifest <path>  Override the discovery manifest path
+  --provider-home <path>  Override the provider home root (testing/portable homes)
+  --codex-root <path>  Explicitly authorize a shared Codex sessions/export root
+  --confirm, --yes  Confirm a persistent discovered batch import
+  --lock-wait-ms <n>  Maximum import-lease wait (default 5000)
+  --inactivity-threshold <duration>  Historical inactivity threshold (default 24h)
+  --min-coverage <0..1>  Fail list/report commands below a coverage ratio
   --provider <id> Filter list or select an import adapter
   --consumer <id> Select a named memory consumer for promotion
   --workspace <id>, --tag <tag>, --limit <n>, --cursor <n>
@@ -90,11 +101,15 @@ async function executeCommand(ctx, args) {
     }
     if (command === 'import')
         return importSource(ctx, args);
+    if (command === 'discover')
+        return discoverWorkspace(ctx, args);
+    if (command === 'import-discovered')
+        return importDiscovered(ctx, args);
     const repository = openRepository(ctx, args);
     try {
         switch (command) {
             case 'list': {
-                const { workspaceId } = authorizationContext(args, command);
+                const { workspaceId } = readAuthorizationContext(ctx, args, command, repository);
                 const limit = boundedInteger(args.values.get('--limit'), 50, 1, 500, '--limit');
                 const cursor = args.values.get('--cursor');
                 const providerInput = args.values.get('--provider');
@@ -106,7 +121,8 @@ async function executeCommand(ctx, args) {
                     limit,
                     cursor,
                 });
-                return ok(command, {
+                const coverage = repository.getCoverage(workspaceId);
+                const response = {
                     items: result.items,
                     page: {
                         limit,
@@ -115,11 +131,56 @@ async function executeCommand(ctx, args) {
                         snapshotRowid: result.snapshotRowid,
                         total: result.total,
                     },
-                });
+                    coverage,
+                };
+                const minimum = args.values.has('--min-coverage')
+                    ? boundedNumber(args.values.get('--min-coverage'), 0, 0, 1, '--min-coverage')
+                    : null;
+                if (minimum !== null
+                    && (coverage.coverageRatio === null || coverage.coverageRatio < minimum)) {
+                    return {
+                        envelope: envelope(`sessions.${command}`, 'error', response, {
+                            code: 'COVERAGE_BELOW_THRESHOLD',
+                            message: `session coverage is below the requested threshold ${minimum}`,
+                            details: coverage,
+                        }),
+                        exitCode: EXIT.coverage,
+                    };
+                }
+                return ok(command, response);
+            }
+            case 'timeline': {
+                const { workspaceId } = readAuthorizationContext(ctx, args, command, repository);
+                const gapMs = timelineGap(args.values.get('--gap'));
+                const items = deriveSessionTimeline(repository.listTimelineInputs(workspaceId), gapMs);
+                const coverage = repository.getCoverage(workspaceId);
+                const response = {
+                    schemaVersion: '1.0.0',
+                    workspaceId,
+                    gapMs,
+                    items,
+                    count: items.length,
+                    coverage,
+                };
+                const minimum = args.values.has('--min-coverage')
+                    ? boundedNumber(args.values.get('--min-coverage'), 0, 0, 1, '--min-coverage')
+                    : null;
+                if (minimum !== null
+                    && (coverage.coverageRatio === null || coverage.coverageRatio < minimum)) {
+                    return {
+                        envelope: envelope(`sessions.${command}`, 'error', response, {
+                            code: 'COVERAGE_BELOW_THRESHOLD',
+                            message: `session coverage is below the requested threshold ${minimum}`,
+                            details: coverage,
+                        }),
+                        exitCode: EXIT.coverage,
+                    };
+                }
+                return ok(command, response);
             }
             case 'show': {
                 const id = requiredPositional(args, 0, 'session-id');
-                const { workspaceId } = authorizationContext(args, command);
+                const { workspaceId } = readAuthorizationContext(ctx, args, command, repository);
                 const session = repository.getSession(id, workspaceId);
                 if (!session)
                     throw new CliError('SESSION_NOT_FOUND', `session not found: ${id}`, EXIT.unavailable);
@@ -131,7 +192,7 @@ async function executeCommand(ctx, args) {
             }
             case 'search': {
                 const query = requiredPositional(args, 0, 'query');
-                const { workspaceId } = authorizationContext(args, command);
+                const { workspaceId } = readAuthorizationContext(ctx, args, command, repository);
                 const providerInput = args.values.get('--provider');
                 const provider = providerInput ? assertSessionProviderId(providerInput) : undefined;
                 const result = repository.search({
@@ -148,6 +209,7 @@ async function executeCommand(ctx, args) {
                     entity: args.values.get('--entity'),
                     sensitivity: args.values.get('--sensitivity'),
                     extractionState: args.values.get('--extraction-state'),
+                    controlEvents: controlEventMode(args.values.get('--control-events')),
                     limit: boundedInteger(args.values.get('--limit'), 50, 1, 500, '--limit'),
                     cursor: args.values.get('--cursor'),
                 });
@@ -158,7 +220,7 @@ async function executeCommand(ctx, args) {
                 });
             }
             case 'extract': {
-                const { workspaceId } = authorizationContext(args, command);
+                const { workspaceId } = authorizationContext(ctx, args, command);
                 const sessionId = args.positionals[0];
                 const pageSize = boundedInteger(args.values.get('--page-size'), 250, 1, 500, '--page-size');
                 const maxDocuments = args.values.has('--max-documents')
@@ -217,14 +279,14 @@ async function executeCommand(ctx, args) {
                     : ok(command, { items, count: items.length, durableMemoryWrites: 0, scan });
             }
             case 'candidates': {
-                const { workspaceId } = authorizationContext(args, command);
+                const { workspaceId } = readAuthorizationContext(ctx, args, command, repository);
                 const state = candidateState(args.values.get('--state'));
                 return ok(command, {
                     items: repository.listCandidates(state, workspaceId),
                 });
             }
             case 'review': {
-                const { workspaceId } = authorizationContext(args, command);
+                const { workspaceId } = authorizationContext(ctx, args, command);
                 const candidateId = requiredPositional(args, 0, 'candidate-id');
                 const version = boundedInteger(requiredPositional(args, 1, 'version'), 1, 1, Number.MAX_SAFE_INTEGER, 'version');
                 const toState = candidateState(requiredPositional(args, 2, 'state'));
@@ -249,7 +311,7 @@ async function executeCommand(ctx, args) {
                 }));
             }
             case 'promote': {
-                const { workspaceId } = authorizationContext(args, command);
+                const { workspaceId } = authorizationContext(ctx, args, command);
                 const candidateId = requiredPositional(args, 0, 'candidate-id');
                 const version = boundedInteger(requiredPositional(args, 1, 'version'), 1, 1, Number.MAX_SAFE_INTEGER, 'version');
                 const consumer = requiredValue(args, '--consumer');
@@ -286,7 +348,7 @@ async function executeCommand(ctx, args) {
             }
             case 'tag': {
                 const id = requiredPositional(args, 0, 'session-id');
-                const { workspaceId } = authorizationContext(args, command);
+                const { workspaceId } = authorizationContext(ctx, args, command);
                 const tag = requiredPositional(args, 1, 'tag');
                 if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/.test(tag)) {
                     throw new CliError('INVALID_TAG', 'tag must be 1-64 safe identifier characters', EXIT.usage);
@@ -302,7 +364,7 @@ async function executeCommand(ctx, args) {
             }
             case 'relocate': {
                 const sourceId = requiredPositional(args, 0, 'source-id');
-                const { workspaceId } = authorizationContext(args, command);
+                const { workspaceId } = authorizationContext(ctx, args, command);
                 const locator = requiredPositional(args, 1, 'file');
                 if (!repository.getSource(sourceId, workspaceId)) {
                     throw new CliError('SOURCE_NOT_FOUND', `source not found: ${sourceId}`, EXIT.unavailable);
@@ -314,14 +376,14 @@ async function executeCommand(ctx, args) {
                 return ok(command, { sourceId, redactedLocator });
             }
             case 'reindex': {
-                const { workspaceId } = authorizationContext(args, command);
+                const { workspaceId } = authorizationContext(ctx, args, command);
                 if (isDryRun(ctx, args))
                     return preview(command, { operation: 'reindex' });
                 repository.reindex(workspaceId);
                 return ok(command, { operation: 'reindex' });
             }
             case 'audit': {
-                const { workspaceId } = authorizationContext(args, command);
+                const { workspaceId } = readAuthorizationContext(ctx, args, command, repository);
                 const limit = boundedInteger(args.values.get('--limit'), 100, 1, 500, '--limit');
                 const cursor = args.values.get('--cursor');
                 if (args.flags.has('--otel')) {
@@ -339,7 +401,7 @@ async function executeCommand(ctx, args) {
             }
             case 'delete': {
                 const id = requiredPositional(args, 0, 'session-id');
-                const { workspaceId } = authorizationContext(args, command);
+                const { workspaceId } = authorizationContext(ctx, args, command);
                 const counts = repository.deletionPreview(id, workspaceId);
                 if (counts.sessions === 0) {
                     throw new CliError('SESSION_NOT_FOUND', `session not found: ${id}`, EXIT.unavailable);
@@ -357,7 +419,7 @@ async function executeCommand(ctx, args) {
             }
             case 'restore': {
                 const id = requiredPositional(args, 0, 'session-id');
-                const { workspaceId } = authorizationContext(args, command);
+                const { workspaceId } = authorizationContext(ctx, args, command);
                 if (isDryRun(ctx, args))
                     return preview(command, { sessionId: id, wouldRestore: true });
                 if (!repository.restoreSession(id, workspaceId)) {
@@ -367,7 +429,7 @@ async function executeCommand(ctx, args) {
             }
             case 'purge': {
                 const id = requiredPositional(args, 0, 'session-id');
-                const { workspaceId } = authorizationContext(args, command);
+                const { workspaceId } = authorizationContext(ctx, args, command);
                 const completed = repository.getCompletedPurge(id, workspaceId);
                 if (completed) {
                     return ok(command, {
@@ -455,7 +517,9 @@ async function importSource(ctx, args) {
         throw new CliError('UNSUPPORTED_OPERATION', `session import is not implemented for ${provider}`, EXIT.unsupported);
     }
     const sourceId = requiredValue(args, '--source-id');
-    const workspaceId = args.values.get('--workspace') ?? 'default';
+    const workspaceId = args.values.has('--workspace')
+        ? normalizeWorkspaceId(ctx.cwd, args.values.get('--workspace'))
+        : 'default';
     const isClaude = provider === 'claude';
     const isCodex = provider === 'codex';
     const isCopilot = provider === 'copilot';
@@ -605,22 +669,106 @@ async function importSource(ctx, args) {
     if (isDryRun(ctx, args)) {
         return preview('import', { source, wouldInspect: true, wouldPersist: false });
     }
-    const repository = openRepository(ctx, args);
+    const lease = await acquireImportLease(databasePath(ctx, args), sha256(['single-source-import', sourceId, workspaceId].join('\0')), {
+        waitMs: boundedInteger(args.values.get('--lock-wait-ms'), 5_000, 0, 300_000, '--lock-wait-ms'),
+    });
     try {
-        const receipts = await new IncrementalSessionImporter(repository).import({
-            source, selectedSource, adapter, workspaceId, policyVersion: '1.0.0',
-        });
-        return ok('import', {
-            sourceId,
-            receipts,
-            totals: {
-                sessionsInserted: receipts.reduce((sum, item) => sum + item.sessionsInserted, 0),
-                eventsInserted: receipts.reduce((sum, item) => sum + item.eventsInserted, 0),
-            },
+        const repository = openRepository(ctx, args);
+        try {
+            const receipts = await new IncrementalSessionImporter(repository).import({
+                source, selectedSource, adapter, workspaceId, policyVersion: '1.0.0',
+                inactivityThresholdMs: inactivityThreshold(args.values.get('--inactivity-threshold')),
+            });
+            return ok('import', {
+                sourceId,
+                receipts,
+                totals: {
+                    sessionsInserted: receipts.reduce((sum, item) => sum + item.sessionsInserted, 0),
+                    eventsInserted: receipts.reduce((sum, item) => sum + item.eventsInserted, 0),
+                },
+            });
+        }
+        finally {
+            repository.close();
+        }
+    }
+    finally {
+        await lease.release();
+    }
+}
+async function discoverWorkspace(ctx, args) {
+    const workspace = resolve(ctx.cwd, requiredValue(args, '--workspace'));
+    const manifest = await discoverWorkspaceHistories({
+        workspace,
+        providerHome: args.values.has('--provider-home')
+            ? resolve(ctx.cwd, args.values.get('--provider-home'))
+            : undefined,
+        codexRoot: args.values.has('--codex-root')
+            ? resolve(ctx.cwd, args.values.get('--codex-root'))
+            : undefined,
+    });
+    const manifestPath = resolve(ctx.cwd, args.values.get('--manifest') ?? defaultDiscoveryManifestPath(manifest.workspacePath));
+    const data = {
+        manifest: publicDiscoveryManifest(manifest),
+        manifestPath: redactSourceLocator(manifestPath),
+        exactManifestRequiredForImport: true,
+    };
+    if (isDryRun(ctx, args)) {
+        return preview('discover', { ...data, wouldPersistManifest: false });
+    }
+    await writeDiscoveryManifest(manifestPath, manifest);
+    return ok('discover', { ...data, manifestPersisted: true });
+}
+async function importDiscovered(ctx, args) {
+    const workspace = resolve(ctx.cwd, requiredValue(args, '--workspace'));
+    const canonicalWorkspace = realpathSync(workspace);
+    const manifestPath = resolve(ctx.cwd, args.values.get('--manifest') ?? defaultDiscoveryManifestPath(canonicalWorkspace));
+    const manifest = await readDiscoveryManifest(manifestPath);
+    if (manifest.workspaceId !== canonicalWorkspace) {
+        throw new CliError('MANIFEST_WORKSPACE_MISMATCH', 'discovery manifest does not belong to the explicitly authorized workspace', EXIT.contract);
+    }
+    const confirmed = args.flags.has('--confirm') || args.flags.has('--yes');
+    if (isDryRun(ctx, args) || !confirmed) {
+        let existing = null;
+        try {
+            const repository = openRepository(ctx, args);
+            existing = repository.getBatchImportRunForManifest(manifest.manifestId, manifest.workspaceId);
+            repository.close();
+        }
+        catch {
+            // A preview can still describe the exact manifest before a catalog exists.
+        }
+        return preview('import-discovered', {
+            manifest: publicDiscoveryManifest(manifest),
+            receipt: previewDiscoveryImport(manifest, existing),
+            confirmationRequired: !isDryRun(ctx, args),
+            wouldPersist: false,
         });
     }
+    const lease = await acquireImportLease(databasePath(ctx, args), sha256(['discovered-import', manifest.manifestId, manifest.workspaceId].join('\0')), {
+        waitMs: boundedInteger(args.values.get('--lock-wait-ms'), 5_000, 0, 300_000, '--lock-wait-ms'),
+    });
+    try {
+        const repository = openRepository(ctx, args);
+        try {
+            const receipt = await importDiscoveryManifest({
+                manifest,
+                repository,
+                signal: ctx.signal,
+                inactivityThresholdMs: inactivityThreshold(args.values.get('--inactivity-threshold')),
+            });
+            return ok('import-discovered', {
+                manifestId: manifest.manifestId,
+                receipt,
+                resumable: receipt.run.status !== 'complete',
+            });
+        }
+        finally {
+            repository.close();
+        }
+    }
     finally {
-        repository.close();
+        await lease.release();
     }
 }
 function providerDisposition(provider) {
@@ -669,10 +817,10 @@ function providerDisposition(provider) {
     if (provider === 'cursor') {
         return {
             provider, disposition: 'implemented', operationalState: 'available',
-            supportedOperations: ['inspect', 'stream'],
+            supportedOperations: ['discover', 'inspect', 'stream'],
             acquisitionModes: ['api', 'jsonl', 'manual-export'],
             reasonCode: null,
-            remediation: 'Import Cursor CLI stream-json, captured Cloud Agent v1 events, or an editor Markdown export.',
+            remediation: 'Authorize a workspace agent-transcripts root, or import Cursor CLI/Cloud Agent exports explicitly.',
             evidence: {
                 adapterVersion: CURSOR_ADAPTER_VERSION,
                 verifiedAt: '2026-07-27',
@@ -804,6 +952,8 @@ function cursorLocatorClass(input) {
         return 'cursor-editor-markdown';
     if (input.endsWith('.cloud.jsonl'))
         return 'cursor-cloud-events-jsonl';
+    if (input.split(/[\\/]+/).includes('agent-transcripts'))
+        return 'cursor-agent-transcript-jsonl';
     return 'cursor-cli-stream-json';
 }
 function cursorProviderProfile(locatorClass) {
@@ -811,6 +961,8 @@ function cursorProviderProfile(locatorClass) {
         return 'editor-markdown-lossy';
     if (locatorClass === 'cursor-cloud-events-jsonl')
         return 'cloud-agents-api-v1';
+    if (locatorClass === 'cursor-agent-transcript-jsonl')
+        return 'agent-transcript-jsonl';
     return 'cli-stream-json';
 }
 function openRepository(ctx, args) {
@@ -820,11 +972,17 @@ function openRepository(ctx, args) {
         return new SessionRepository(path);
     }
     catch (error) {
-        throw new CliError('CATALOG_UNAVAILABLE', error instanceof Error ? error.message : String(error), EXIT.storage);
+        const message = error instanceof Error ? error.message : String(error);
+        if (/SQLITE_BUSY|database is locked/i.test(message)) {
+            throw new CliError('IMPORT_LOCKED', 'the session catalog is busy; retry after the active writer finishes', EXIT.locked, { owner: null, waitedMs: 0 });
+        }
+        throw new CliError('CATALOG_UNAVAILABLE', message, EXIT.storage);
     }
 }
 function databasePath(ctx, args) {
-    return resolve(ctx.cwd, args.values.get('--db') ?? '.aiwg/sessions/catalog.sqlite');
+    if (args.values.has('--db'))
+        return resolve(ctx.cwd, args.values.get('--db'));
+    return resolve(projectRootCandidate(ctx.cwd) ?? ctx.cwd, '.aiwg/sessions/catalog.sqlite');
 }
 function parseArgs(argv) {
     const flags = new Set();
@@ -836,6 +994,9 @@ function parseArgs(argv) {
         '--entity', '--sensitivity', '--extraction-state', '--page-size', '--max-documents',
         '--state', '--reviewer', '--reason', '--policy-version', '--min-confidence',
         '--consumer', '--actor-class', '--reason-code', '--dependent-action', '--basis',
+        '--manifest', '--provider-home', '--codex-root', '--lock-wait-ms', '--min-coverage', '--gap',
+        '--inactivity-threshold',
+        '--control-events',
     ]);
     let command;
     for (let index = 0; index < argv.length; index += 1) {
@@ -872,15 +1033,94 @@ function requiredValue(args, flag) {
         throw new CliError('MISSING_ARGUMENT', `missing required ${flag}`, EXIT.usage);
     return value;
 }
-function authorizationContext(args, operation) {
+function authorizationContext(ctx, args, operation) {
     return {
         actorId: 'local-catalog-owner',
-        workspaceId: requiredValue(args, '--workspace'),
+        workspaceId: normalizeWorkspaceId(ctx.cwd, requiredValue(args, '--workspace')),
         operation,
         catalogScope: 'workspace',
         mode: 'local-owner',
     };
 }
+function readAuthorizationContext(ctx, args, operation, repository) {
+    const explicit = args.values.get('--workspace');
+    if (explicit) {
+        return {
+            actorId: 'local-catalog-owner',
+            workspaceId: normalizeWorkspaceId(ctx.cwd, explicit),
+            operation,
+            catalogScope: 'workspace',
+            mode: 'local-owner',
+        };
+    }
+    const project = projectRootCandidate(ctx.cwd);
+    if (project) {
+        return {
+            actorId: 'local-catalog-owner',
+            workspaceId: project,
+            operation,
+            catalogScope: 'workspace',
+            mode: 'local-owner',
+        };
+    }
+    const candidates = repository.listWorkspaceIds();
+    if (candidates.length === 1) {
+        return {
+            actorId: 'local-catalog-owner',
+            workspaceId: candidates[0],
+            operation,
+            catalogScope: 'workspace',
+            mode: 'local-owner',
+        };
+    }
+    if (candidates.length > 1) {
+        throw new CliError('WORKSPACE_AMBIGUOUS', 'current workspace cannot be inferred safely; pass --workspace explicitly', EXIT.usage, {
+            candidates,
+            example: `aiwg sessions ${operation} --workspace ${JSON.stringify(candidates[0])}`,
+        });
+    }
+    throw new CliError('WORKSPACE_REQUIRED', 'current workspace cannot be inferred; pass --workspace explicitly', EXIT.usage, {
+        candidates: [],
+        example: `aiwg sessions ${operation} --workspace <path-or-id>`,
+    });
+}
+function projectRootCandidate(start) {
+    let current;
+    try {
+        const resolved = realpathSync(resolve(start));
+        current = statSync(resolved).isDirectory() ? resolved : dirname(resolved);
+    }
+    catch {
+        current = resolve(start);
+    }
+    let gitRoot = null;
+    while (true) {
+        if (existsSync(resolve(current, '.aiwg', 'aiwg.config')))
+            return current;
+        if (!gitRoot && existsSync(resolve(current, '.git')))
+            gitRoot = current;
+        const parent = dirname(current);
+        if (parent === current)
+            return gitRoot;
+        current = parent;
+    }
+}
+function normalizeWorkspaceId(cwd, value) {
+    const pathLike = isAbsolute(value)
+        || value === '.'
+        || value === '..'
+        || value.startsWith('./')
+        || value.startsWith('../');
+    if (!pathLike)
+        return value;
+    const candidate = resolve(cwd, value);
+    try {
+        return realpathSync(candidate);
+    }
+    catch {
+        return candidate;
+    }
+}
 function boundedInteger(value, fallback, min, max, name) {
     if (value === undefined)
         return fallback;
@@ -901,6 +1141,29 @@ function boundedNumber(value, fallback, min, max, name) {
     }
     return parsed;
 }
+function timelineGap(value) {
+    try {
+        return parseTimelineGap(value);
+    }
+    catch (error) {
+        throw new CliError('INVALID_ARGUMENT', error instanceof Error ? error.message : 'invalid timeline gap', EXIT.usage);
+    }
+}
+function inactivityThreshold(value) {
+    try {
+        return parseTimelineGap(value ?? '24h');
+    }
+    catch (error) {
+        throw new CliError('INVALID_ARGUMENT', error instanceof Error ? error.message : 'invalid inactivity threshold', EXIT.usage);
+    }
+}
+function controlEventMode(value) {
+    if (value === undefined)
+        return 'exclude';
+    if (value === 'exclude' || value === 'include' || value === 'only')
+        return value;
+    throw new CliError('INVALID_ARGUMENT', '--control-events must be exclude, include, or only', EXIT.usage);
+}
 function candidateState(value) {
     if (value === undefined)
         return undefined;
@@ -939,25 +1202,61 @@ function emit(value) {
 function printHuman(value) {
     if (value.status === 'preview')
         console.log('Preview (no changes applied)');
+    if (value.command === 'sessions.timeline' && value.data
+        && typeof value.data === 'object' && 'items' in value.data) {
+        const data = value.data;
+        for (const item of data.items) {
+            console.log([
+                item.startAt ?? '<unknown-time>',
+                item.endAt ?? '<unknown-time>',
+                item.provider,
+                item.sessionId,
+                `segment=${item.segmentIndex}`,
+                `events=${item.eventCount}`,
+                `boundary=${item.boundaryBasis}`,
+                `confidence=${item.confidence}`,
+            ].join(' '));
+        }
+        console.log(`Coverage: ${data.coverage?.status ?? 'unknown'}`);
+        return;
+    }
     console.log(JSON.stringify(value.data, null, 2));
 }
 class CliError extends Error {
     code;
     exitCode;
-    constructor(code, message, exitCode) {
+    details;
+    constructor(code, message, exitCode, details) {
         super(message);
         this.code = code;
         this.exitCode = exitCode;
+        this.details = details;
     }
 }
 function normalizeError(error) {
     if (error instanceof CliError) {
-        return { error: { code: error.code, message: error.message }, exitCode: error.exitCode };
+        return {
+            error: { code: error.code, message: error.message, details: error.details },
+            exitCode: error.exitCode,
+        };
     }
     if (error instanceof SessionContractError) {
         const exitCode = error.code === 'UNSUPPORTED_OPERATION' ? EXIT.unsupported : EXIT.contract;
         return { error: { code: error.code, message: error.message }, exitCode };
     }
+    if (error instanceof ImportLeaseContentionError) {
+        return {
+            error: {
+                code: error.code,
+                message: error.message,
+                details: {
+                    owner: error.owner,
+                    waitedMs: error.waitMs,
+                },
+            },
+            exitCode: EXIT.locked,
+        };
+    }
     return {
         error: { code: 'INTERNAL_ERROR', message: error instanceof Error ? error.message : String(error) },
         exitCode: EXIT.storage,