@aiwg/cli 2026.9.12 → 2026.9.15

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

@@ -1,7 +1,8 @@
-import { existsSync, mkdirSync, realpathSync, statSync, } from 'node:fs';
-import { dirname, isAbsolute, resolve, } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync, } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { dirname, isAbsolute, join, resolve, } from 'node:path';
 import { pathToFileURL } from 'node:url';
-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, PI_ADAPTER_VERSION, PiSessionAdapter, DEEPSEEK_HARNESS_ADAPTER_VERSION, DeepSeekHarnessSessionAdapter, OmpSessionAdapter, OMP_ADAPTER_VERSION, 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';
+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, PI_ADAPTER_VERSION, PiSessionAdapter, DEEPSEEK_HARNESS_ADAPTER_VERSION, DeepSeekHarnessSessionAdapter, OmpSessionAdapter, OMP_ADAPTER_VERSION, 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, buildSessionExportPlan, reverifySessionExportPlan, buildSessionAiwgFortemiIndexExport, recoverAiwgFortemiIndexFromFullV1Shard, SESSION_EXPORT_PLAN_SCHEMA_VERSION, } from '../../sessions/index.js';
 const JSON_CONTRACT_VERSION = '1.0.0';
 async function createLineMemoryPromotionDestination(projectRoot, manifestPath) {
     const modulePath = resolve(dirname(manifestPath), 'commands', 'line-memory.mjs');
@@ -33,6 +34,10 @@ Commands:
   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
+  export plan --workspace <id> --out <file> <session-id...>  Select sessions into a reviewable plan
+  export build --plan <file> --out <dir>  Build a Fortemi Knowledge Shard from a plan
+  export verify --input <shard>   Validate a shard and its receipt
+  export unpack --input <shard> --out <dir>  Recover a shard's records to disk
   candidates [--state <state>]    List the candidate review queue
   review <id> <version> <state>   Record an explicit review transition
   promote <id> <version>          Preview promotion; use --confirm to write
@@ -409,6 +414,7 @@ async function executeCommand(ctx, args) {
                     ? preview(command, { items, count: items.length, durableMemoryWrites: 0, scan })
                     : ok(command, { items, count: items.length, durableMemoryWrites: 0, scan });
             }
+            case 'export': return exportCommand(ctx, args, repository);
             case 'candidates': {
                 const { workspaceId } = readAuthorizationContext(ctx, args, command, repository);
                 const state = candidateState(args.values.get('--state'));
@@ -694,7 +700,7 @@ async function importSource(ctx, args) {
                                                     ? new DevinDesktopSessionAdapter()
                                                     : new GenericSessionInterchangeAdapter();
     const locatorClass = isDsh ? 'deepseek-harness-session-v2-jsonl' : isOmp ? 'omp-session-v3-jsonl' : isClaude
-        ? (input.endsWith('.hooks.jsonl') ? 'claude-hook-jsonl' : 'claude-transcript-jsonl')
+        ? claudeLocatorClass(input)
         : isCodex
             ? (input.endsWith('.app-server.jsonl') ? 'codex-app-server-jsonl' : 'codex-rollout-jsonl')
             : isCopilot
@@ -726,7 +732,7 @@ async function importSource(ctx, args) {
     const source = SessionSourceSchema.parse({
         contractVersion: SESSION_CONTRACT_VERSION, sourceId, provider,
         providerProfile: isDsh ? 'native-session-v2-jsonl' : isOmp ? 'native-title-slot-v3' : isClaude
-            ? 'documented-local-jsonl'
+            ? claudeProviderProfile(locatorClass)
             : isCodex
                 ? 'app-server-v2-rollout-fallback'
                 : isCopilot
@@ -837,6 +843,178 @@ async function importSource(ctx, args) {
         await lease.release();
     }
 }
+/**
+ * `aiwg sessions export {plan,build,verify,unpack}` (#2564). Sub-verb after
+ * `export`, matching the issue's proposed shape:
+ *   export plan --workspace ID --out selection.json SESSION_ID...
+ *   export build --plan selection.json --out DIRECTORY
+ *   export verify --input evidence.shard
+ *   export unpack --input evidence.shard --out DIRECTORY
+ */
+async function exportCommand(ctx, args, repository) {
+    const subVerb = requiredPositional(args, 0, 'export sub-command (plan|build|verify|unpack)');
+    const command = `export.${subVerb}`;
+    if (subVerb === 'plan')
+        return exportPlan(ctx, args, repository, command);
+    if (subVerb === 'build')
+        return exportBuild(ctx, args, repository, command);
+    if (subVerb === 'verify')
+        return exportVerify(ctx, args, command);
+    if (subVerb === 'unpack')
+        return exportUnpack(ctx, args, command);
+    throw new CliError('UNKNOWN_COMMAND', `unknown export sub-command: ${subVerb}`, EXIT.usage);
+}
+function exportPlan(ctx, args, repository, command) {
+    const workspaceId = normalizeWorkspaceId(ctx.cwd, requiredValue(args, '--workspace'));
+    const out = resolve(ctx.cwd, requiredValue(args, '--out'));
+    const flagSelection = args.values.get('--session')?.split(',').map((value) => value.trim()).filter(Boolean) ?? [];
+    const sessionIds = [...new Set([...flagSelection, ...args.positionals.slice(1)])];
+    const { plan } = buildSessionExportPlan(repository, { workspaceId, sessionIds, projectRoot: ctx.cwd });
+    mkdirSync(dirname(out), { recursive: true, mode: 0o700 });
+    writeFileSync(out, `${JSON.stringify(plan, null, 2)}\n`, { mode: 0o600 });
+    return ok(command, {
+        plan: out,
+        totals: plan.totals,
+        sessions: plan.sessions.map((entry) => entry.sessionId),
+        outputs: plan.outputs.length,
+    });
+}
+async function exportBuild(ctx, args, repository, command) {
+    const planPath = resolve(ctx.cwd, requiredValue(args, '--plan'));
+    const outDirectory = resolve(ctx.cwd, requiredValue(args, '--out'));
+    const shardName = args.values.get('--shard-name') ?? 'evidence.shard';
+    let plan;
+    try {
+        plan = JSON.parse(readFileSync(planPath, 'utf8'));
+    }
+    catch {
+        throw new CliError('MALFORMED_SOURCE', `plan file is not readable JSON: ${planPath}`, EXIT.usage);
+    }
+    if (plan.schemaVersion !== SESSION_EXPORT_PLAN_SCHEMA_VERSION) {
+        throw new CliError('UNKNOWN_SCHEMA_MAJOR', `plan schemaVersion ${plan.schemaVersion} is not supported by this build (expected ${SESSION_EXPORT_PLAN_SCHEMA_VERSION})`, EXIT.contract);
+    }
+    // Recheck source changes before writing (#2564 acceptance criteria):
+    // re-select from the live repository and reject on any digest drift.
+    const { sessions, eventsBySessionId } = reverifySessionExportPlan(repository, plan);
+    const index = buildSessionAiwgFortemiIndexExport(plan.workspaceId, sessions, eventsBySessionId, plan.outputs);
+    // aiwgFortemiIndexToKnowledgeShardWithReport targets the declared
+    // full-v1/2.0.0 archive contract and validates losslessness -- unlike the
+    // plain aiwgFortemiIndexToKnowledgeShard (core-v1), which silently embeds
+    // the whole input record as opaque note metadata regardless of whether it
+    // maps to any native component. The mapping in fortemi-export-mapping.ts
+    // was built specifically so every AIWG-specific field lands in a real
+    // full-v1 component (tags, provenance_events) rather than being smuggled
+    // through as an unmapped blob.
+    const { aiwgFortemiIndexToKnowledgeShardWithReport } = await import('@fortemi/core');
+    const result = await aiwgFortemiIndexToKnowledgeShardWithReport(index);
+    if (!result.success || !result.archive) {
+        throw new CliError('MALFORMED_SOURCE', `full-v1 shard conversion failed: ${JSON.stringify(result.losses)}`, EXIT.contract);
+    }
+    const bytes = result.archive;
+    mkdirSync(outDirectory, { recursive: true, mode: 0o700 });
+    const finalPath = join(outDirectory, shardName);
+    // Interrupted writes must never be mistaken for a completed export: write
+    // to a sibling temp file, then rename (atomic on the same filesystem), and
+    // only then write the receipt -- the receipt's existence is the completion
+    // signal, not the shard file's.
+    const tempPath = join(outDirectory, `.${shardName}.${randomUUID()}.tmp`);
+    writeFileSync(tempPath, bytes, { mode: 0o600 });
+    renameSync(tempPath, finalPath);
+    const readBack = readFileSync(finalPath);
+    const shardDigest = sha256(readBack);
+    if (readBack.length !== bytes.length) {
+        throw new CliError('IMPORT_INTERRUPTED', 'shard readback size did not match the written archive', EXIT.storage);
+    }
+    const receipt = {
+        schemaVersion: '1.0.0',
+        generatedAt: new Date().toISOString(),
+        workspaceId: plan.workspaceId,
+        planGeneratedAt: plan.generatedAt,
+        sessionIds: plan.sessions.map((entry) => entry.sessionId),
+        totals: plan.totals,
+        indexSchemaVersion: index.schema_version,
+        archiveProfile: result.profile,
+        archiveSchemaVersion: result.schema_version,
+        lossless: result.lossless,
+        losses: result.losses,
+        fortemiReceipt: result.receipt,
+        shardFile: shardName,
+        shardDigest,
+        shardBytes: readBack.length,
+    };
+    writeFileSync(`${finalPath}.receipt.json`, `${JSON.stringify(receipt, null, 2)}\n`, { mode: 0o600 });
+    return ok(command, { shard: finalPath, receipt: `${finalPath}.receipt.json`, ...receipt });
+}
+async function exportVerify(ctx, args, command) {
+    const input = resolve(ctx.cwd, requiredValue(args, '--input'));
+    let bytes;
+    try {
+        bytes = readFileSync(input);
+    }
+    catch {
+        throw new CliError('SOURCE_NOT_AUTHORIZED', `shard file is not readable: ${input}`, EXIT.usage);
+    }
+    let recovered;
+    try {
+        recovered = recoverAiwgFortemiIndexFromFullV1Shard(bytes);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new CliError('MALFORMED_SOURCE', `shard failed validation: ${message}`, EXIT.contract);
+    }
+    const shardDigest = sha256(bytes);
+    const receiptPath = `${input}.receipt.json`;
+    let receiptMatches = null;
+    if (existsSync(receiptPath)) {
+        try {
+            const receipt = JSON.parse(readFileSync(receiptPath, 'utf8'));
+            receiptMatches = receipt.shardDigest === shardDigest && receipt.shardBytes === bytes.length;
+        }
+        catch {
+            receiptMatches = false;
+        }
+    }
+    return ok(command, {
+        valid: true,
+        schemaVersion: recovered.schema_version,
+        itemCount: recovered.items.length,
+        shardDigest,
+        shardBytes: bytes.length,
+        receiptChecked: existsSync(receiptPath),
+        receiptMatches,
+    });
+}
+async function exportUnpack(ctx, args, command) {
+    const input = resolve(ctx.cwd, requiredValue(args, '--input'));
+    const outDirectory = resolve(ctx.cwd, requiredValue(args, '--out'));
+    let bytes;
+    try {
+        bytes = readFileSync(input);
+    }
+    catch {
+        throw new CliError('SOURCE_NOT_AUTHORIZED', `shard file is not readable: ${input}`, EXIT.usage);
+    }
+    let recovered;
+    try {
+        recovered = recoverAiwgFortemiIndexFromFullV1Shard(bytes);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new CliError('MALFORMED_SOURCE', `shard failed validation: ${message}`, EXIT.contract);
+    }
+    mkdirSync(outDirectory, { recursive: true, mode: 0o700 });
+    const finalPath = join(outDirectory, 'index.json');
+    const tempPath = join(outDirectory, `.index.json.${randomUUID()}.tmp`);
+    writeFileSync(tempPath, `${JSON.stringify(recovered, null, 2)}\n`, { mode: 0o600 });
+    renameSync(tempPath, finalPath);
+    return ok(command, {
+        index: finalPath,
+        schemaVersion: recovered.schema_version,
+        itemCount: recovered.items.length,
+        sessionRecordCount: recovered.items.filter((item) => item.type === 'aiwg.session').length,
+        eventRecordCount: recovered.items.filter((item) => item.type === 'aiwg.session-event').length,
+    });
+}
 async function discoverWorkspace(ctx, args) {
     const workspace = resolve(ctx.cwd, requiredValue(args, '--workspace'));
     const manifest = await discoverWorkspaceHistories({
@@ -935,12 +1113,13 @@ function providerDisposition(provider) {
         return {
             provider, disposition: 'implemented', operationalState: 'available',
             supportedOperations: ['discover', 'inspect', 'stream'],
-            acquisitionModes: ['jsonl', 'hook'],
+            acquisitionModes: ['jsonl', 'hook', 'manual-export'],
             reasonCode: null,
-            remediation: 'Authorize a Claude projects or hook root, then import an explicit JSONL file.',
+            remediation: 'Authorize a Claude projects or hook root and import a JSONL file, '
+                + 'or import an explicitly selected Claude web/account conversations.json export.',
             evidence: {
                 adapterVersion: CLAUDE_ADAPTER_VERSION,
-                verifiedAt: '2026-07-27',
+                verifiedAt: '2026-09-15',
                 documentation: 'https://code.claude.com/docs/en/sessions',
             },
         };
@@ -1131,6 +1310,18 @@ function providerDisposition(provider) {
         evidence: { adapterVersion: null, verifiedAt: '2026-07-26' },
     };
 }
+function claudeLocatorClass(input) {
+    if (input.endsWith('.hooks.jsonl') || input.endsWith('.hook.jsonl'))
+        return 'claude-hook-jsonl';
+    if (input.endsWith('.json'))
+        return 'claude-web-export-json';
+    return 'claude-transcript-jsonl';
+}
+function claudeProviderProfile(locatorClass) {
+    if (locatorClass === 'claude-web-export-json')
+        return 'web-account-export-conversations-json';
+    return 'documented-local-jsonl';
+}
 function cursorLocatorClass(input) {
     if (input.endsWith('.md') || input.endsWith('.markdown'))
         return 'cursor-editor-markdown';
@@ -1182,6 +1373,7 @@ function parseArgs(argv) {
         '--inactivity-threshold',
         '--control-events',
         '--session', '--status', '--actor', '--group-by',
+        '--out', '--plan', '--input', '--shard-name',
     ]);
     let command;
     for (let index = 0; index < argv.length; index += 1) {

package/dist/src/sessions/adapters/claude.js

@@ -3,9 +3,12 @@ import { basename, extname, resolve } from 'node:path';
 import { z } from 'zod';
 import { SessionContractError, assertSupportedSchemaMajor, sha256, } from '../contracts.js';
 import { redactSourceLocator } from '../discovery.js';
-import { readBoundedJsonLines, streamBoundedJsonLines, } from '../readers.js';
-export const CLAUDE_ADAPTER_VERSION = '1.0.0';
+import { readBoundedJson, readBoundedJsonLines, streamBoundedJsonLines, } from '../readers.js';
+export const CLAUDE_ADAPTER_VERSION = '1.1.0';
 export const CLAUDE_TRANSCRIPT_SCHEMA_VERSION = '1.0.0';
+/** AIWG's own understanding of the layout it supports; Claude web/account
+ *  exports carry no in-band schema version to read instead. */
+export const CLAUDE_WEB_EXPORT_SCHEMA_VERSION = '1.0.0';
 const ClaudeRecordSchema = z.object({
     type: z.string().min(1),
     subtype: z.string().optional(),
@@ -40,6 +43,43 @@ const ClaudeHookSchema = z.object({
     schemaVersion: z.string().optional(),
     timestamp: z.string().datetime({ offset: true }).optional(),
 }).passthrough();
+/**
+ * Claude.ai web/account data export (`conversations.json`): a JSON array of
+ * conversations, each carrying its own `chat_messages`. This is a distinct
+ * source format from local JSONL transcripts/hooks -- renaming the file does
+ * not make it one (#2565). Unrecognized fields are captured via unknownFields
+ * rather than dropped, and content the export marks as an attachment/file is
+ * recorded as a reference (bytes are not embedded in this export format).
+ */
+const ClaudeWebExportAttachmentSchema = z.object({
+    file_name: z.string().optional(),
+    file_type: z.string().optional(),
+    file_size: z.number().optional(),
+    extracted_content: z.string().optional(),
+}).passthrough();
+const ClaudeWebExportContentBlockSchema = z.object({
+    type: z.string().optional(),
+    text: z.string().optional(),
+}).passthrough();
+const ClaudeWebExportMessageSchema = z.object({
+    uuid: z.string().min(1),
+    text: z.string().optional(),
+    sender: z.enum(['human', 'assistant']),
+    created_at: z.string().optional(),
+    updated_at: z.string().optional(),
+    content: z.array(ClaudeWebExportContentBlockSchema).optional(),
+    attachments: z.array(ClaudeWebExportAttachmentSchema).optional(),
+    files: z.array(ClaudeWebExportAttachmentSchema).optional(),
+}).passthrough();
+const ClaudeWebExportConversationSchema = z.object({
+    uuid: z.string().min(1),
+    name: z.string().optional(),
+    created_at: z.string().optional(),
+    updated_at: z.string().optional(),
+    account: z.object({ uuid: z.string().optional() }).passthrough().optional(),
+    chat_messages: z.array(ClaudeWebExportMessageSchema),
+}).passthrough();
+const ClaudeWebExportSchema = z.array(ClaudeWebExportConversationSchema);
 export class ClaudeSessionAdapter {
     limits;
     discoveryLimits;
@@ -47,7 +87,7 @@ export class ClaudeSessionAdapter {
     adapterVersion = CLAUDE_ADAPTER_VERSION;
     disposition = 'implemented';
     supportedOperations = ['discover', 'inspect', 'stream'];
-    acquisitionModes = ['jsonl', 'hook'];
+    acquisitionModes = ['jsonl', 'hook', 'manual-export'];
     constructor(limits, discoveryLimits = { maxDepth: 8, maxFiles: 10_000 }) {
         this.limits = limits;
         this.discoveryLimits = discoveryLimits;
@@ -80,6 +120,13 @@ export class ClaudeSessionAdapter {
         };
     }
     async *stream(source, cursor) {
+        if (source.locatorClass === 'claude-web-export-json') {
+            const parsed = await this.readWebExportSource(source);
+            const start = parseRecordCursor(cursor?.value);
+            for (const record of parsed.records.slice(start))
+                yield record;
+            return;
+        }
         const start = parseRecordCursor(cursor?.value);
         const input = await streamBoundedJsonLines({
             selectedPath: source.locator,
@@ -112,6 +159,9 @@ export class ClaudeSessionAdapter {
         }
     }
     async readSource(source) {
+        if (source.locatorClass === 'claude-web-export-json') {
+            return this.readWebExportSource(source);
+        }
         const result = await readBoundedJsonLines({
             selectedPath: source.locator,
             allowedRoots: source.authorizedScope.allowedRoots,
@@ -132,7 +182,81 @@ export class ClaudeSessionAdapter {
             consistency: normalized.complete ? 'complete' : 'provisional',
         };
     }
+    async readWebExportSource(source) {
+        const { value } = await readBoundedJson({ selectedPath: source.locator, allowedRoots: source.authorizedScope.allowedRoots }, this.limits);
+        const parsed = ClaudeWebExportSchema.safeParse(value);
+        if (!parsed.success) {
+            throw new SessionContractError('MALFORMED_SOURCE', 'Claude web/account export is not a recognized conversations.json layout');
+        }
+        if (parsed.data.length === 0) {
+            throw new SessionContractError('MALFORMED_SOURCE', 'Claude web/account export is empty');
+        }
+        return {
+            records: normalizeWebExport(parsed.data),
+            schemaVersion: CLAUDE_WEB_EXPORT_SCHEMA_VERSION,
+            // The export is a completed snapshot at request time, not a live tail.
+            consistency: 'complete',
+        };
+    }
 }
+function normalizeWebExport(conversations) {
+    const output = [];
+    const seenConversationIds = new Set();
+    for (const conversation of conversations) {
+        if (seenConversationIds.has(conversation.uuid)) {
+            throw new SessionContractError('DUPLICATE_NATIVE_ID', `Claude web export declares the same conversation uuid twice: ${conversation.uuid}`);
+        }
+        seenConversationIds.add(conversation.uuid);
+        const seenMessageIds = new Set();
+        for (const [index, message] of conversation.chat_messages.entries()) {
+            if (seenMessageIds.has(message.uuid)) {
+                throw new SessionContractError('DUPLICATE_NATIVE_ID', `Claude web export conversation ${conversation.uuid} declares the same message uuid twice: ${message.uuid}`);
+            }
+            seenMessageIds.add(message.uuid);
+            output.push(webExportProviderRecord(conversation, message, index));
+        }
+    }
+    return output;
+}
+function webExportProviderRecord(conversation, message, sequence) {
+    const text = message.text && message.text.length > 0
+        ? message.text
+        : (message.content ?? []).map((block) => block.text ?? '').filter(Boolean).join('\n');
+    const attachments = [...(message.attachments ?? []), ...(message.files ?? [])];
+    return {
+        nativeSessionId: conversation.uuid,
+        nativeEventId: message.uuid,
+        sequence,
+        kind: 'message',
+        role: message.sender,
+        participant: message.sender,
+        occurredAt: message.created_at,
+        text,
+        rawReference: { locatorClass: 'claude-web-export-json', sequence },
+        extensions: {
+            conversationName: conversation.name,
+            conversationCreatedAt: conversation.created_at,
+            conversationUpdatedAt: conversation.updated_at,
+            provenance: { acquisition: 'claude-web-export-json', schema: CLAUDE_WEB_EXPORT_SCHEMA_VERSION },
+            // Web/account exports reference attachments/files by metadata only; the
+            // export format does not embed original bytes, so this is a coverage
+            // note (#2565 acceptance criteria), not a loss AIWG introduced.
+            ...(attachments.length > 0 ? {
+                attachmentReferences: attachments.map((attachment) => ({
+                    fileName: attachment.file_name,
+                    fileType: attachment.file_type,
+                    fileSize: attachment.file_size,
+                    extractedContentAvailable: typeof attachment.extracted_content === 'string',
+                })),
+                metadataLoss: ['attachment bytes unavailable in web/account export format'],
+            } : {}),
+            unknownFields: unknownFields(message, WEB_EXPORT_MESSAGE_KEYS),
+        },
+    };
+}
+const WEB_EXPORT_MESSAGE_KEYS = new Set([
+    'uuid', 'text', 'sender', 'created_at', 'updated_at', 'content', 'attachments', 'files',
+]);
 function normalizeTranscript(records, locator) {
     const filenameSessionId = basename(locator, extname(locator));
     const output = [];

package/dist/src/sessions/export-plan.js

@@ -0,0 +1,117 @@
+/**
+ * Builds and re-verifies a session export selection plan (#2564). A plan
+ * binds a reviewable, human-inspectable selection to the exact session ids
+ * and source/event digests seen at plan time, so `sessions export build`
+ * can detect a stale plan (source changed since planning) rather than
+ * silently exporting drifted data.
+ */
+import { createHash } from 'node:crypto';
+import { SessionContractError } from './contracts.js';
+import { buildSessionAiwgFortemiIndexExport, SESSION_EXPORT_INDEX_SCHEMA_VERSION, } from './fortemi-export-mapping.js';
+import { discoverSessionOutputCandidates } from './output-lineage.js';
+import { FilesystemDerivedOutputIndex } from './output-registration.js';
+export const SESSION_EXPORT_PLAN_SCHEMA_VERSION = '1.0.0';
+function eventDigestSummary(events) {
+    const hash = createHash('sha256');
+    for (const event of events)
+        hash.update(event.digest);
+    return `sha256:${hash.digest('hex')}`;
+}
+/**
+ * Selects the requested sessions from the repository and builds a plan.
+ * Rejects an empty or duplicate selection, and any session id the
+ * repository cannot authorize for the given workspace -- an unauthorized
+ * or unknown id is a planning error, not something to silently skip.
+ */
+export function buildSessionExportPlan(repository, options) {
+    const requested = [...new Set(options.sessionIds)];
+    if (requested.length === 0) {
+        throw new SessionContractError('INVALID_ARGUMENT', 'session export plan requires at least one session id');
+    }
+    if (requested.length !== options.sessionIds.length) {
+        throw new SessionContractError('INVALID_ARGUMENT', 'session export plan selection contains duplicate session ids');
+    }
+    const sessions = [];
+    const eventsBySessionId = new Map();
+    const entries = [];
+    for (const sessionId of requested) {
+        const session = repository.getSession(sessionId, options.workspaceId);
+        if (!session) {
+            throw new SessionContractError('SOURCE_NOT_AUTHORIZED', `session is unknown or not authorized for this workspace: ${sessionId}`);
+        }
+        const events = repository.listEvents(sessionId, options.workspaceId);
+        sessions.push(session);
+        eventsBySessionId.set(sessionId, events);
+        entries.push({
+            sessionId: session.sessionId,
+            nativeSessionId: session.nativeSessionId,
+            provider: session.provider,
+            sourceId: session.sourceId,
+            sourceDigest: session.sourceDigest,
+            eventCount: events.length,
+            eventDigestSummary: eventDigestSummary(events),
+        });
+    }
+    const sampleSize = options.previewSampleSize ?? 5;
+    const outputCandidates = options.projectRoot
+        ? discoverSessionOutputCandidates(new FilesystemDerivedOutputIndex(options.projectRoot).registrations(), sessions)
+        : [];
+    const outputs = outputCandidates.map((candidate) => ({
+        sessionId: candidate.sessionId,
+        registrationId: candidate.registration.registrationId,
+        outputLocator: candidate.registration.output.locator,
+        outputDigest: candidate.registration.output.digest,
+        mediaType: candidate.registration.output.mediaType,
+        lineage: candidate.lineage,
+        matchReason: candidate.matchReason,
+    }));
+    const index = buildSessionAiwgFortemiIndexExport(options.workspaceId, sessions, eventsBySessionId, outputs);
+    const plan = {
+        schemaVersion: SESSION_EXPORT_PLAN_SCHEMA_VERSION,
+        indexSchemaVersion: SESSION_EXPORT_INDEX_SCHEMA_VERSION,
+        generatedAt: new Date().toISOString(),
+        workspaceId: options.workspaceId,
+        sessions: entries,
+        outputs,
+        totals: {
+            sessionCount: sessions.length,
+            eventCount: entries.reduce((sum, entry) => sum + entry.eventCount, 0),
+            outputCount: outputs.length,
+            recordCount: index.items.length,
+        },
+        preview: {
+            recordCount: index.items.length,
+            sampleRecordIds: index.items.slice(0, sampleSize).map((item) => item.id),
+        },
+    };
+    return { plan, sessions, eventsBySessionId };
+}
+/**
+ * Re-selects the plan's sessions from the repository and compares digests
+ * against what the plan recorded. Any drift -- a changed source, a
+ * changed/reimported event set, or a session/id that has since disappeared
+ * -- fails closed rather than exporting silently-stale data (#2564
+ * acceptance criteria: "Plans reject stale sources ... changed analysis
+ * bytes").
+ */
+export function reverifySessionExportPlan(repository, plan) {
+    const sessions = [];
+    const eventsBySessionId = new Map();
+    for (const entry of plan.sessions) {
+        const session = repository.getSession(entry.sessionId, plan.workspaceId);
+        if (!session) {
+            throw new SessionContractError('SOURCE_NOT_AUTHORIZED', `planned session no longer exists or is not authorized: ${entry.sessionId}`);
+        }
+        if (session.sourceDigest !== entry.sourceDigest) {
+            throw new SessionContractError('SCHEMA_DRIFT', `session source changed since the plan was generated: ${entry.sessionId}`);
+        }
+        const events = repository.listEvents(entry.sessionId, plan.workspaceId);
+        if (events.length !== entry.eventCount || eventDigestSummary(events) !== entry.eventDigestSummary) {
+            throw new SessionContractError('SCHEMA_DRIFT', `session events changed since the plan was generated: ${entry.sessionId}`);
+        }
+        sessions.push(session);
+        eventsBySessionId.set(entry.sessionId, events);
+    }
+    return { sessions, eventsBySessionId };
+}
+//# sourceMappingURL=export-plan.js.map

package/dist/src/sessions/fortemi-export-mapping.js

@@ -0,0 +1,296 @@
+/**
+ * `record.v1`/`export.v1` forbid exactly the fields this mapping needs
+ * (`source.origin`/`generated`/`checksum`/`updated_at`, relationship
+ * `direction`/`confidence`/`privacy`) -- verified empirically against
+ * @fortemi/core's bundled AJV schema, since the type declarations alone
+ * don't encode this v1/v2 split. Use v2 throughout.
+ */
+export const SESSION_EXPORT_RECORD_SCHEMA_VERSION = 'aiwg.fortemi.index.record.v2';
+export const SESSION_EXPORT_INDEX_SCHEMA_VERSION = 'aiwg.fortemi.index.export.v2';
+const INDEX_GRAPH_ID = 'aiwg-sessions';
+function tag(key, value) {
+    return `${key}:${value}`;
+}
+export function sessionRecordLocator(session) {
+    return `aiwg-session://${session.provider}/${session.sessionId}`;
+}
+export function sessionEventRecordLocator(session, event) {
+    return `${sessionRecordLocator(session)}/event/${event.eventId}`;
+}
+export function sessionToAiwgFortemiRecord(session) {
+    const locator = sessionRecordLocator(session);
+    const updatedAt = session.updatedAt ?? session.startedAt ?? new Date(0).toISOString();
+    return {
+        schema_version: SESSION_EXPORT_RECORD_SCHEMA_VERSION,
+        id: session.sessionId,
+        type: 'aiwg.session',
+        source: {
+            path: locator,
+            repo_relative_path: locator,
+            locator,
+            origin: 'aiwg-session-catalog',
+            generated: true,
+            checksum: session.sourceDigest,
+            updated_at: updatedAt,
+        },
+        // `title`/`text` are required by @fortemi/core's runtime schema even
+        // though the published type marks them optional -- always emit a
+        // deterministic fallback rather than an empty/undefined value.
+        title: session.intent.title ?? `${session.provider} session ${session.nativeSessionId}`,
+        text: session.intent.summary ?? `AIWG session ${session.sessionId} (${session.provider}, ${session.lifecycle})`,
+        facets: {},
+        tags: [tag('provider', session.provider), tag('lifecycle', session.lifecycle)],
+        concepts: [],
+        relationships: [],
+        provenance: [{
+                field: 'source',
+                source: 'aiwg-session-catalog',
+                path: locator,
+                confidence: 'source',
+                privacy: 'private',
+            }],
+        // Structural identifiers this export exists to preserve, carried as a
+        // native provenance_events attribute bag rather than an unmapped
+        // `compatibility` field the full-v1 converter would refuse to archive.
+        provenance_events: [{
+                activity: 'aiwg.session',
+                agent: session.provider,
+                started_at: session.startedAt ?? updatedAt,
+                source: 'aiwg-session-catalog',
+                path: locator,
+                confidence: 'source',
+                privacy: 'private',
+                attributes: {
+                    nativeSessionId: session.nativeSessionId,
+                    sourceId: session.sourceId,
+                    workspaceId: session.workspaceId,
+                    consistency: session.consistency,
+                },
+            }],
+        privacy: { classification: 'public', pii: false },
+        updated_at: updatedAt,
+    };
+}
+export function sessionEventToAiwgFortemiRecord(session, event) {
+    const locator = sessionEventRecordLocator(session, event);
+    const parentLocator = sessionRecordLocator(session);
+    const updatedAt = event.occurredAt ?? new Date(0).toISOString();
+    const relationships = [{
+            type: 'parent-session',
+            target_id: session.sessionId,
+            target_path: parentLocator,
+            direction: 'upstream',
+            // This edge is a structural fact from the session catalog, not a
+            // probabilistic inference -- maximum confidence, not a default.
+            confidence: 1,
+            privacy: event.sensitivity.classification === 'sensitive' ? 'private' : 'public',
+        }];
+    const provenance = [{
+            field: 'text',
+            source: 'aiwg-session-catalog',
+            path: locator,
+            confidence: 'source',
+            privacy: event.sensitivity.classification === 'sensitive' ? 'private' : 'public',
+        }];
+    const provenanceEvents = [{
+            activity: `aiwg.session-event.${event.kind}`,
+            agent: event.model ?? session.provider,
+            started_at: event.occurredAt ?? updatedAt,
+            source: 'aiwg-session-catalog',
+            path: locator,
+            confidence: 'source',
+            privacy: event.sensitivity.classification === 'sensitive' ? 'private' : 'public',
+            attributes: {
+                sessionId: event.sessionId,
+                sourceId: event.sourceId,
+                nativeId: event.nativeId,
+                sequence: event.sequence,
+                toolCallId: event.toolCallId,
+            },
+        }];
+    const tags = [
+        tag('kind', event.kind),
+        ...(event.role ? [tag('role', event.role)] : []),
+        ...(event.toolName ? [tag('tool', event.toolName)] : []),
+        ...(event.entities ?? []).map((entity) => tag('entity', entity)),
+    ];
+    return {
+        schema_version: SESSION_EXPORT_RECORD_SCHEMA_VERSION,
+        id: event.eventId,
+        type: 'aiwg.session-event',
+        source: {
+            path: locator,
+            repo_relative_path: locator,
+            locator,
+            origin: 'aiwg-session-catalog',
+            generated: true,
+            checksum: event.digest,
+            updated_at: updatedAt,
+        },
+        title: `${event.kind}${event.role ? ` (${event.role})` : ''} -- ${session.sessionId}`,
+        text: event.searchableText.length > 0 ? event.searchableText : `[${event.kind}: no text content]`,
+        facets: {},
+        tags,
+        // Entities are AIWG-extracted strings, not real SKOS taxonomy concepts
+        // with definitions -- represented as `entity:` tags above, not as
+        // `concepts` (which the full-v1 converter treats as SKOS references and
+        // refuses to archive without SKOS metadata backing them).
+        concepts: [],
+        relationships,
+        provenance,
+        provenance_events: provenanceEvents,
+        privacy: {
+            classification: event.sensitivity.classification === 'sensitive' ? 'private' : 'public',
+            pii: event.sensitivity.classes.length > 0,
+        },
+        updated_at: updatedAt,
+    };
+}
+/**
+ * A registered analysis output associated with a session (#2566), mapped as
+ * a reference record. Like session-event attachments (#2565), this does not
+ * embed the output's original bytes -- only its registration metadata and
+ * digest, which is enough for a consumer to locate and verify the output
+ * against the original registration, not to recover it from the shard
+ * alone. Full byte embedding needs a blob-store integration that neither
+ * #2564 nor #2566 has landed yet; that limitation is shared and explicit,
+ * not silently dropped.
+ */
+export function sessionOutputToAiwgFortemiRecord(session, output) {
+    const locator = `${sessionRecordLocator(session)}/output/${output.registrationId}`;
+    const now = new Date().toISOString();
+    return {
+        schema_version: SESSION_EXPORT_RECORD_SCHEMA_VERSION,
+        id: `output_${output.registrationId}`,
+        type: 'aiwg.session-output',
+        source: {
+            path: locator,
+            repo_relative_path: output.outputLocator,
+            locator,
+            origin: 'aiwg-output-registration',
+            generated: true,
+            checksum: output.outputDigest,
+            updated_at: now,
+        },
+        title: `registered output for ${session.sessionId}`,
+        text: `${output.mediaType} output registered at ${output.outputLocator} (${output.matchReason}); `
+            + 'bytes not embedded -- reference and digest only.',
+        facets: {},
+        tags: [tag('mediaType', output.mediaType), tag('lineage', 'registered')],
+        concepts: [],
+        relationships: [{
+                type: 'parent-session',
+                target_id: session.sessionId,
+                target_path: sessionRecordLocator(session),
+                direction: 'upstream',
+                confidence: 1,
+                privacy: 'private',
+            }],
+        provenance: [{
+                field: 'source',
+                source: 'aiwg-output-registration',
+                path: locator,
+                confidence: 'source',
+                privacy: 'private',
+            }],
+        provenance_events: [{
+                activity: 'aiwg.session-output',
+                agent: 'aiwg-output-registration',
+                started_at: now,
+                source: 'aiwg-output-registration',
+                path: locator,
+                confidence: 'source',
+                privacy: 'private',
+                attributes: {
+                    sessionId: output.sessionId,
+                    registrationId: output.registrationId,
+                    outputLocator: output.outputLocator,
+                    matchReason: output.matchReason,
+                    bytesEmbedded: false,
+                },
+            }],
+        privacy: { classification: 'private', pii: false },
+        updated_at: now,
+    };
+}
+/**
+ * A full-v1 archive has no per-archive metadata sidecar -- only the
+ * `aiwg_source` embedded on each individual note. Without this record, the
+ * index-level wrapper (`source.repo`/`privacy`/`graph`, `generated_at`)
+ * would be a real, disclosed recovery gap. Representing it as one more
+ * ordinary record closes that gap using the exact mechanism already built
+ * for every other field (`provenance_events[0].attributes`), rather than
+ * inventing a second, parallel embedding path.
+ *
+ * The id is prefixed to sort after every `event_`/`output_`/`session_` id
+ * (deterministic regardless of content), and the type is namespaced so
+ * recovery can find and exclude it from the recovered `items` unambiguously.
+ */
+export const EXPORT_MANIFEST_RECORD_TYPE = 'aiwg.session-catalog-export-manifest';
+export const EXPORT_MANIFEST_RECORD_ID = 'zzz-aiwg-session-catalog-export-manifest';
+function exportManifestRecord(repoRef, generatedAt) {
+    const locator = `aiwg-session-catalog://export-manifest/${repoRef}`;
+    return {
+        schema_version: SESSION_EXPORT_RECORD_SCHEMA_VERSION,
+        id: EXPORT_MANIFEST_RECORD_ID,
+        type: EXPORT_MANIFEST_RECORD_TYPE,
+        source: {
+            path: locator,
+            repo_relative_path: locator,
+            locator,
+            origin: 'aiwg-session-catalog',
+            generated: true,
+            updated_at: generatedAt,
+        },
+        title: 'AIWG session export manifest',
+        text: `Index-level metadata for this session export (${repoRef}). Not a session, event, or output record.`,
+        facets: {},
+        tags: [tag('graph', INDEX_GRAPH_ID)],
+        concepts: [],
+        relationships: [],
+        provenance: [{
+                field: 'source', source: 'aiwg-session-catalog', path: locator, confidence: 'source', privacy: 'private',
+            }],
+        provenance_events: [{
+                activity: EXPORT_MANIFEST_RECORD_TYPE,
+                agent: 'aiwg-session-catalog',
+                started_at: generatedAt,
+                source: 'aiwg-session-catalog',
+                path: locator,
+                confidence: 'source',
+                privacy: 'private',
+                attributes: { repo: repoRef, privacy: 'private', graph: INDEX_GRAPH_ID, generatedAt },
+            }],
+        privacy: { classification: 'private', pii: false },
+        updated_at: generatedAt,
+    };
+}
+/**
+ * Builds the full record graph for a selected set of sessions. `repoRef` is
+ * a caller-supplied identity for `AiwgFortemiIndexExport.source.repo` (the
+ * session catalog's workspace id, not a git repo -- the field is repurposed
+ * honestly rather than left to imply something untrue).
+ */
+export function buildSessionAiwgFortemiIndexExport(repoRef, sessions, eventsBySessionId, outputs = []) {
+    const generatedAt = new Date().toISOString();
+    const items = [exportManifestRecord(repoRef, generatedAt)];
+    for (const session of sessions) {
+        items.push(sessionToAiwgFortemiRecord(session));
+        for (const event of eventsBySessionId.get(session.sessionId) ?? []) {
+            items.push(sessionEventToAiwgFortemiRecord(session, event));
+        }
+        for (const output of outputs.filter((entry) => entry.sessionId === session.sessionId)) {
+            items.push(sessionOutputToAiwgFortemiRecord(session, output));
+        }
+    }
+    // Deterministic ordering: reproducible archives, easier diffing.
+    items.sort((left, right) => left.id.localeCompare(right.id));
+    return {
+        schema_version: SESSION_EXPORT_INDEX_SCHEMA_VERSION,
+        generated_at: generatedAt,
+        source: { repo: repoRef, privacy: 'private', graph: INDEX_GRAPH_ID },
+        compatibility: { previous_schema_version: 'aiwg.fortemi.index.export.v1', strategy: 'supported' },
+        items,
+    };
+}
+//# sourceMappingURL=fortemi-export-mapping.js.map

package/dist/src/sessions/fortemi-shard-recovery.js

@@ -0,0 +1,151 @@
+/**
+ * Recovers an `AiwgFortemiIndexExport`-shaped record graph from a real
+ * `full-v1`/`2.0.0` Knowledge Shard archive built by
+ * `aiwgFortemiIndexToKnowledgeShardWithReport` (#2564).
+ *
+ * `@fortemi/core`'s own `aiwgFortemiIndexFromKnowledgeShard` only recovers
+ * archives built by the plain `aiwgFortemiIndexToKnowledgeShard` (`core-v1`):
+ * that function embeds the entire original record verbatim as opaque note
+ * metadata (`metadata.aiwg_fortemi_index`), which is what its reader looks
+ * for. The strict `full-v1` converter deliberately does not do this -- the
+ * point of `full-v1` is a genuinely native note/tag/link/provenance
+ * representation any Fortemi consumer can read, not an AIWG-only escape
+ * hatch. Verified empirically: `aiwgFortemiIndexFromKnowledgeShard` throws
+ * "has no AIWG index metadata" against a `full-v1` archive, and even AIWG's
+ * own artifact-index shard export test only round-trips through it using
+ * `profile: "core-v1"`.
+ *
+ * So recovering a `full-v1` archive means reading the native shard files
+ * directly and inverting this module's own mapping:
+ *   - id/type/source/privacy  <- note.metadata.aiwg_source
+ *   - title/text              <- note.title / note.original_content
+ *   - tags                    <- note.tags
+ *   - relationships           <- links.jsonl (from_note_id/to_note_id/kind/score)
+ *   - provenance/provenance_events <- provenance_activities.jsonl, split by
+ *     the `source:<field>` activity_type convention this module uses to
+ *     distinguish `provenance` entries from `provenance_events` entries
+ *
+ * The index-level wrapper (`AiwgFortemiIndexExport.source`/`compatibility`)
+ * is genuinely not preserved anywhere in a full-v1 archive -- there is no
+ * per-archive metadata sidecar for it, only per-note. Recovery reports this
+ * honestly with a fixed placeholder rather than inventing a value.
+ */
+import { unpackTarGz } from '@fortemi/core';
+import { EXPORT_MANIFEST_RECORD_TYPE, SESSION_EXPORT_INDEX_SCHEMA_VERSION, SESSION_EXPORT_RECORD_SCHEMA_VERSION, } from './fortemi-export-mapping.js';
+const SOURCE_PROVENANCE_PREFIX = 'source:';
+function decodeJsonLines(bytes) {
+    if (!bytes)
+        return [];
+    const text = new TextDecoder().decode(bytes);
+    return text.split('\n').filter((line) => line.trim().length > 0).map((line) => JSON.parse(line));
+}
+function isAiwgSourceSidecar(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const candidate = value;
+    return typeof candidate.record_id === 'string' && typeof candidate.record_type === 'string';
+}
+export class FortemiShardRecoveryError extends Error {
+}
+/**
+ * Recovers the record graph from a `full-v1` archive. Throws
+ * `FortemiShardRecoveryError` if the archive has no notes, or any note is
+ * missing the `aiwg_source` sidecar this module's own mapping always writes
+ * (meaning the shard wasn't produced by this mapping and can't be recovered
+ * this way).
+ */
+export function recoverAiwgFortemiIndexFromFullV1Shard(bytes) {
+    const files = unpackTarGz(bytes);
+    const notes = decodeJsonLines(files.get('notes.jsonl'));
+    if (notes.length === 0) {
+        throw new FortemiShardRecoveryError('Knowledge Shard contains no notes to recover');
+    }
+    const links = decodeJsonLines(files.get('links.jsonl'));
+    const activities = decodeJsonLines(files.get('provenance_activities.jsonl'));
+    const noteIdToRecordId = new Map();
+    for (const note of notes) {
+        const sidecar = note.metadata?.aiwg_source;
+        if (!isAiwgSourceSidecar(sidecar)) {
+            throw new FortemiShardRecoveryError(`Knowledge Shard note ${note.id} has no aiwg_source metadata -- `
+                + 'this archive was not produced by the AIWG session export mapping');
+        }
+        noteIdToRecordId.set(note.id, sidecar.record_id);
+    }
+    const items = notes.map((note) => {
+        const sidecar = note.metadata.aiwg_source;
+        const relationships = links
+            .filter((link) => link.from_note_id === note.id)
+            .map((link) => ({
+            type: link.kind,
+            target_id: link.to_note_id ? (noteIdToRecordId.get(link.to_note_id) ?? link.to_note_id) : '',
+            confidence: link.score ?? undefined,
+        }));
+        const noteActivities = activities.filter((activity) => activity.note_id === note.id);
+        const provenance = [];
+        const provenanceEvents = [];
+        for (const activity of noteActivities) {
+            const metadata = activity.metadata ?? {};
+            if (activity.activity_type.startsWith(SOURCE_PROVENANCE_PREFIX)) {
+                provenance.push({
+                    field: activity.activity_type.slice(SOURCE_PROVENANCE_PREFIX.length),
+                    source: metadata.source ?? activity.model_name ?? '',
+                    path: metadata.path ?? '',
+                    confidence: metadata.confidence ?? 'source',
+                    privacy: metadata.privacy ?? 'private',
+                });
+            }
+            else {
+                provenanceEvents.push({
+                    activity: activity.activity_type,
+                    agent: activity.model_name ?? undefined,
+                    started_at: activity.started_at ?? undefined,
+                    ended_at: activity.ended_at ?? undefined,
+                    source: metadata.source ?? undefined,
+                    path: metadata.path ?? undefined,
+                    confidence: metadata.confidence ?? undefined,
+                    privacy: metadata.privacy ?? undefined,
+                    attributes: metadata.attributes ?? undefined,
+                });
+            }
+        }
+        return {
+            schema_version: SESSION_EXPORT_RECORD_SCHEMA_VERSION,
+            id: sidecar.record_id,
+            type: sidecar.record_type,
+            source: sidecar.source,
+            title: note.title,
+            text: note.original_content,
+            facets: {},
+            tags: note.tags,
+            concepts: [],
+            relationships,
+            provenance,
+            provenance_events: provenanceEvents,
+            privacy: sidecar.privacy,
+            updated_at: sidecar.source.updated_at ?? new Date(0).toISOString(),
+        };
+    });
+    items.sort((left, right) => left.id.localeCompare(right.id));
+    // The export-manifest record (see fortemi-export-mapping.ts) carries the
+    // index-level wrapper fields through the same provenance_events mechanism
+    // as everything else. Extract it and exclude it from the recovered items
+    // -- it isn't a session, event, or output record.
+    const manifestIndex = items.findIndex((item) => item.type === EXPORT_MANIFEST_RECORD_TYPE);
+    const manifestAttributes = manifestIndex >= 0
+        ? items[manifestIndex].provenance_events?.[0]?.attributes
+        : undefined;
+    const recoveredItems = manifestIndex >= 0
+        ? items.filter((_, index) => index !== manifestIndex)
+        : items;
+    return {
+        schema_version: SESSION_EXPORT_INDEX_SCHEMA_VERSION,
+        generated_at: manifestAttributes?.generatedAt ?? new Date(0).toISOString(),
+        source: manifestAttributes
+            ? { repo: manifestAttributes.repo ?? 'unknown', privacy: manifestAttributes.privacy ?? 'private' }
+            // No manifest record present (e.g. an archive built before this record
+            // existed) -- labeled honestly rather than invented.
+            : { repo: 'recovered-from-full-v1-shard', privacy: 'private' },
+        items: recoveredItems,
+    };
+}
+//# sourceMappingURL=fortemi-shard-recovery.js.map

package/dist/src/sessions/index.js

@@ -7,6 +7,10 @@ export * from './repository.js';
 export * from './ports.js';
 export * from './optional-backends.js';
 export * from './knowledge-shard.js';
+export * from './fortemi-export-mapping.js';
+export * from './fortemi-shard-recovery.js';
+export * from './output-lineage.js';
+export * from './export-plan.js';
 export * from './candidates.js';
 export * from './promotion.js';
 export * from './output-registration.js';

package/dist/src/sessions/output-lineage.js

@@ -0,0 +1,43 @@
+import { sessionRecordLocator } from './fortemi-export-mapping.js';
+/** Known, exact conventions a `kind: 'session'` source ref may use to name a session. Order is the preference used to report `matchReason`. */
+function sessionRefCandidates(session) {
+    return [
+        { ref: session.sessionId, reason: 'ref equals the stable session id' },
+        { ref: `session:${session.sessionId}`, reason: "ref equals 'session:<stable session id>'" },
+        { ref: sessionRecordLocator(session), reason: 'ref equals the aiwg-session:// export locator' },
+        { ref: session.nativeSessionId, reason: 'ref equals the native session id' },
+        { ref: `session:${session.nativeSessionId}`, reason: "ref equals 'session:<native session id>'" },
+    ];
+}
+function matchSource(source, session) {
+    if (source.kind !== 'session')
+        return null;
+    for (const candidate of sessionRefCandidates(session)) {
+        if (source.ref === candidate.ref)
+            return candidate.reason;
+    }
+    return null;
+}
+/**
+ * Registrations are scanned once and matched against every selected session
+ * -- bounded by the selection, not an unbounded corpus walk, satisfying
+ * "bound any file discovery to an explicit workspace/source scope."
+ */
+export function discoverSessionOutputCandidates(registrations, sessions) {
+    const candidates = [];
+    for (const registration of registrations) {
+        for (const session of sessions) {
+            for (const source of registration.contextPack.sources) {
+                const reason = matchSource(source, session);
+                if (reason) {
+                    candidates.push({
+                        registration, sessionId: session.sessionId, lineage: 'registered', matchReason: reason,
+                    });
+                    break;
+                }
+            }
+        }
+    }
+    return candidates;
+}
+//# sourceMappingURL=output-lineage.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwg/cli",
-  "version": "2026.9.12",
+  "version": "2026.9.15",
   "description": "Lightweight AIWG CLI for signed, versioned web-backed resources.",
   "type": "module",
   "license": "MIT",