evolcore 0.0.5 → 0.0.6

package/dist/core/data-migration.js

@@ -0,0 +1,1434 @@
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import { formatChannelSessionKey, scanLegacyChatDirs, scanMetaFiles, scanNestedAgentChatDirs, scanNonCanonicalAgentChatDirs, } from './session/session-fs-store.js';
+import { rewriteLegacyTriggerSessionPaths } from '../trigger/legacy-session-history.js';
+const SESSION_SEEN_FILE = 'seen-messages.jsonl';
+const CHANNEL_TYPES = new Set(['aun', 'feishu', 'wechat', 'dingtalk', 'qqbot', 'wecom']);
+const DATA_MIGRATION_PLAN_VERSION = 3;
+function encodeSegment(value) {
+    return value.replace(/[<>:"/\\|?*\x00-\x1F%]/g, ch => '%' + ch.charCodeAt(0).toString(16).toUpperCase().padStart(2, '0'));
+}
+function migrationDir(root) {
+    return path.join(root, 'data', 'daemon', 'migrations');
+}
+function manifestPath(root, id) {
+    return path.join(migrationDir(root), `${id}.json`);
+}
+function migrationStagingDir(root, id) {
+    return path.join(migrationDir(root), `${id}.staging`);
+}
+function migrationPlanSignature(operations) {
+    const topology = operations.map(operation => ({
+        kind: operation.kind,
+        source: operation.source,
+        sources: [...(operation.sources ?? [])].sort(),
+        destination: operation.destination,
+        destinations: [...(operation.destinations ?? [])].sort(),
+        exclude: [...(operation.exclude ?? [])].sort(),
+        transform: operation.transform,
+        sessionChannelKey: operation.sessionChannelKey,
+    }));
+    return crypto.createHash('sha256')
+        .update(JSON.stringify({ version: DATA_MIGRATION_PLAN_VERSION, topology }), 'utf8')
+        .digest('hex');
+}
+function operationTopologyKey(operation) {
+    return JSON.stringify({
+        kind: operation.kind,
+        source: operation.source,
+        sources: [...(operation.sources ?? [])].sort(),
+        destination: operation.destination,
+        destinations: [...(operation.destinations ?? [])].sort(),
+        exclude: [...(operation.exclude ?? [])].sort(),
+        transform: operation.transform,
+        sessionChannelKey: operation.sessionChannelKey,
+    });
+}
+function sessionDestination(root, aid, channelKey, channelId) {
+    const channelType = channelKey === 'daemon' ? 'daemon' : channelKey.split('#', 1)[0]?.trim();
+    if (!channelType)
+        throw new Error(`Cannot derive session channel type from key: ${channelKey}`);
+    return path.join(root, 'agents', aid, 'sessions', formatChannelSessionKey(channelType, channelId, channelKey));
+}
+function channelStateDestination(root, channelKey, ...parts) {
+    return path.join(root, 'data', 'channel-state', encodeURIComponent(channelKey), ...parts);
+}
+function triggerDestination(root, aid, ...parts) {
+    return path.join(root, 'agents', aid, 'triggers', ...parts);
+}
+function readJson(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * A plan extension must not replay an already verified legacy copy: the
+ * destination is now the live runtime data and may legitimately have grown.
+ * Reuse only a completed proof with an identical source hash and topology.
+ */
+function acknowledgeCompletedCopies(root, operations) {
+    const proofs = new Map();
+    const currentPlanSignature = migrationPlanSignature(operations);
+    try {
+        const manifests = fs.readdirSync(migrationDir(root), { withFileTypes: true })
+            .filter(entry => entry.isFile() && entry.name.endsWith('.json'))
+            .map(entry => ({
+            path: path.join(migrationDir(root), entry.name),
+            mtime: fs.statSync(path.join(migrationDir(root), entry.name)).mtimeMs,
+        }))
+            .sort((left, right) => right.mtime - left.mtime);
+        for (const candidate of manifests) {
+            const manifest = readJson(candidate.path);
+            if (manifest?.state !== 'completed')
+                continue;
+            // An unchanged plan is a normal re-run and must retain its conflict
+            // checks. Acknowledgement is only for extending a prior plan.
+            if (manifest.planSignature === currentPlanSignature)
+                return;
+            for (const operation of manifest.operations ?? []) {
+                if (operation.kind !== 'copy' || (operation.status !== 'committed' && operation.status !== 'skipped') || !operation.sourceHash)
+                    continue;
+                const key = operationTopologyKey(operation);
+                if (!proofs.has(key))
+                    proofs.set(key, { migrationId: manifest.id, sourceHash: operation.sourceHash });
+            }
+        }
+    }
+    catch { }
+    for (const operation of operations) {
+        if (operation.kind !== 'copy' || !operation.destination || !fs.existsSync(operation.destination))
+            continue;
+        const proof = proofs.get(operationTopologyKey(operation));
+        if (!proof)
+            continue;
+        try {
+            if (treeHash(operation.source, operation.exclude) !== proof.sourceHash)
+                continue;
+            operation.status = 'acknowledged';
+            operation.acknowledgedBy = proof.migrationId;
+        }
+        catch { }
+    }
+}
+function readLatestSession(chatDir) {
+    const candidates = [path.join(chatDir, 'active.json')];
+    for (const name of scanMetaFiles(chatDir))
+        candidates.push(path.join(chatDir, name));
+    for (const name of scanMetaFiles(path.join(chatDir, '_threads')))
+        candidates.push(path.join(chatDir, '_threads', name));
+    for (const candidate of candidates) {
+        try {
+            const lines = fs.readFileSync(candidate, 'utf8').trim().split('\n').filter(Boolean);
+            const value = candidate.endsWith('.json') ? JSON.parse(lines.join('\n')) : JSON.parse(lines.at(-1));
+            if (value && typeof value === 'object')
+                return value;
+        }
+        catch { }
+    }
+    return undefined;
+}
+function normalizeLegacyChannelKey(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const [first, second, third, ...rest] = value.split('#');
+    if (rest.length > 0 || !first || !second || !third)
+        return undefined;
+    return CHANNEL_TYPES.has(second) && first.includes('.') ? `${second}#${first}#${third}` : value;
+}
+function parseChannelKey(value) {
+    const normalized = normalizeLegacyChannelKey(value);
+    if (!normalized)
+        return undefined;
+    const parts = normalized.split('#');
+    if (parts.length !== 3 || !CHANNEL_TYPES.has(parts[0]) || !parts[1])
+        return undefined;
+    return { type: parts[0], aid: parts[1], key: normalized };
+}
+function listChannelInstances(root) {
+    const results = [];
+    const agentsDir = path.join(root, 'agents');
+    let entries;
+    try {
+        entries = fs.readdirSync(agentsDir, { withFileTypes: true });
+    }
+    catch {
+        return results;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const config = readJson(path.join(agentsDir, entry.name, 'config.json'));
+        if (!config)
+            continue;
+        for (const channel of Array.isArray(config.channels) ? config.channels : []) {
+            if (!channel || typeof channel.type !== 'string' || typeof channel.name !== 'string')
+                continue;
+            results.push({
+                aid: entry.name,
+                type: channel.type,
+                rawName: channel.name,
+                key: `${channel.type}#${entry.name}#${channel.name}`,
+            });
+        }
+    }
+    return results;
+}
+function configuredAids(root) {
+    return new Set(listChannelInstances(root).map(instance => instance.aid).concat((() => {
+        try {
+            return fs.readdirSync(path.join(root, 'agents'), { withFileTypes: true })
+                .filter(entry => entry.isDirectory() && fs.existsSync(path.join(root, 'agents', entry.name, 'config.json')))
+                .map(entry => entry.name);
+        }
+        catch {
+            return [];
+        }
+    })()));
+}
+function controlIdentity(root) {
+    const config = readJson(path.join(root, 'daemon.json'));
+    const aid = typeof config?.aid === 'string' && config.aid.trim() && config.aid !== '_unknown'
+        ? config.aid.trim()
+        : undefined;
+    const owners = new Set();
+    if (Array.isArray(config?.owners)) {
+        for (const owner of config.owners) {
+            if (typeof owner === 'string' && owner.trim())
+                owners.add(owner);
+        }
+    }
+    return { aids: new Set(aid ? [aid] : []), owners };
+}
+function inferUnknownAunOwner(chat, control) {
+    if (chat.channelType !== 'aun' || chat.selfAID !== '_unknown' || control.aids.size !== 1)
+        return undefined;
+    // Old message-only AUN directories use `_unknown` for the local identity.
+    // The control identity is recoverable only when the peer is one of its
+    // configured owners; arbitrary unknown directories remain untouched.
+    if (!control.owners.has(chat.channelId))
+        return undefined;
+    return control.aids.values().next().value;
+}
+function isOwnedTriggerDefinition(definition, aid, triggerId) {
+    return !!definition
+        && typeof definition === 'object'
+        && definition.id === triggerId
+        && definition.agentAid === aid;
+}
+function listTriggerStorageRoots(root, layout) {
+    const roots = [];
+    if (layout === 'legacy') {
+        const legacyRoot = path.join(root, 'data', 'triggers');
+        try {
+            for (const entry of fs.readdirSync(legacyRoot, { withFileTypes: true })) {
+                if (entry.isDirectory())
+                    roots.push({ aid: entry.name, directory: path.join(legacyRoot, entry.name) });
+            }
+        }
+        catch { }
+        return roots;
+    }
+    const agentsRoot = path.join(root, 'agents');
+    try {
+        for (const entry of fs.readdirSync(agentsRoot, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const directory = path.join(agentsRoot, entry.name, 'triggers');
+            if (fs.existsSync(directory))
+                roots.push({ aid: entry.name, directory });
+        }
+    }
+    catch { }
+    return roots;
+}
+/**
+ * Trigger definitions are the authority for daemon-session ownership. Search
+ * both layouts while a completed migration retains the immutable legacy copy.
+ */
+function listTriggerOwners(root) {
+    const ownerAids = new Map();
+    for (const layout of ['legacy', 'agent']) {
+        for (const { aid, directory } of listTriggerStorageRoots(root, layout)) {
+            let triggerEntries;
+            try {
+                triggerEntries = fs.readdirSync(directory, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const triggerEntry of triggerEntries) {
+                if (!triggerEntry.isDirectory())
+                    continue;
+                const definition = readJson(path.join(directory, triggerEntry.name, 'trigger.json'));
+                if (!isOwnedTriggerDefinition(definition, aid, triggerEntry.name))
+                    continue;
+                const owners = ownerAids.get(triggerEntry.name) ?? new Set();
+                owners.add(aid);
+                ownerAids.set(triggerEntry.name, owners);
+            }
+        }
+    }
+    return new Map([...ownerAids].map(([triggerId, aids]) => [
+        triggerId,
+        [...aids].sort().map(aid => ({ aid })),
+    ]));
+}
+function resolveDaemonTriggerOwner(chat, record, triggerOwners) {
+    if (chat.channelType !== 'daemon') {
+        return { warning: `Non-Trigger daemon session retained: ${chat.channelId}` };
+    }
+    const triggerIds = new Set();
+    if (chat.channelId.startsWith('trigger:'))
+        triggerIds.add(chat.channelId.slice('trigger:'.length));
+    for (const value of [record?.metadata?.peerId, record?.metadata?.triggerId, record?.triggerId]) {
+        if (typeof value === 'string' && value.startsWith('trigger:'))
+            triggerIds.add(value.slice('trigger:'.length));
+    }
+    triggerIds.delete('');
+    if (triggerIds.size === 0)
+        return { warning: `Non-Trigger daemon session retained: ${chat.channelId}` };
+    if (triggerIds.size > 1) {
+        return { warning: `Daemon session references multiple Trigger IDs and was retained: ${chat.channelId}` };
+    }
+    const triggerId = [...triggerIds][0];
+    const candidates = triggerOwners.get(triggerId) ?? [];
+    const declaredOwner = typeof record?.selfAID === 'string' && record.selfAID !== '_unknown'
+        ? record.selfAID
+        : undefined;
+    const ownedCandidates = declaredOwner
+        ? candidates.filter(candidate => candidate.aid === declaredOwner)
+        : candidates;
+    if (ownedCandidates.length === 1)
+        return { aid: ownedCandidates[0].aid };
+    if (declaredOwner && candidates.length > 0) {
+        return { warning: `Daemon Trigger session owner conflicts with its definition and was retained: ${chat.channelId}` };
+    }
+    if (candidates.length === 0) {
+        return { warning: `Daemon Trigger session has no matching definition and was retained: ${chat.channelId}` };
+    }
+    return { warning: `Daemon Trigger session has ambiguous ownership and was retained: ${chat.channelId}` };
+}
+function matchingChannel(instances, type, legacyName) {
+    const matches = instances.filter(instance => instance.type === type && (instance.key === legacyName || instance.rawName === legacyName));
+    return matches.length === 1 ? matches[0].key : undefined;
+}
+function matchingAgentChannel(instances, type, aid, legacyName) {
+    if (typeof legacyName !== 'string')
+        return undefined;
+    const matches = instances.filter(instance => instance.aid === aid && instance.type === type && (instance.key === legacyName
+        || instance.rawName === legacyName
+        || `${type}_${instance.rawName}` === legacyName));
+    return matches.length === 1 ? matches[0].key : undefined;
+}
+/**
+ * A stored full channel key may name an instance removed from the current
+ * Agent configuration. Rebind only when the current same-type instance is
+ * unique; with multiple candidates, preserving the old route is safer.
+ */
+function configuredChannelKey(instances, type, aid, ...storedKeys) {
+    if (type === 'aun')
+        return `aun#${aid}#main`;
+    const candidates = instances.filter(instance => instance.type === type && instance.aid === aid);
+    for (const storedKey of storedKeys) {
+        const parsed = parseChannelKey(storedKey);
+        if (!parsed || parsed.type !== type || parsed.aid !== aid)
+            continue;
+        if (candidates.some(candidate => candidate.key === parsed.key))
+            return parsed.key;
+        if (candidates.length === 1)
+            return candidates[0].key;
+    }
+    for (const storedKey of storedKeys) {
+        const matched = matchingAgentChannel(instances, type, aid, storedKey);
+        if (matched)
+            return matched;
+    }
+    return candidates.length === 1 ? candidates[0].key : undefined;
+}
+/**
+ * Existing Agent-owned session directories already have an authoritative
+ * parent AID. Prefer the currently configured route when it is unambiguous;
+ * otherwise retain a valid stored key so flattening never discards history.
+ */
+function channelKeyForNestedAgentSession(chat, record, instances) {
+    if (chat.channelType === 'daemon')
+        return 'daemon';
+    const storedKeys = [record?.channel, record?.metadata?.channelKey, chat.channelKey];
+    const configured = configuredChannelKey(instances, chat.channelType, chat.selfAID, ...storedKeys);
+    if (configured)
+        return configured;
+    for (const storedKey of storedKeys) {
+        const parsed = parseChannelKey(storedKey);
+        if (parsed?.type === chat.channelType && parsed.aid === chat.selfAID)
+            return parsed.key;
+    }
+    return undefined;
+}
+function nestedSessionSourcePriority(chat, record, destinationChannelKey) {
+    if (!destinationChannelKey)
+        return 2;
+    for (const value of [record?.channel, record?.metadata?.channelKey, chat.channelKey]) {
+        if (parseChannelKey(value)?.key === destinationChannelKey)
+            return 0;
+    }
+    return 1;
+}
+function addCopy(operations, id, source, destination, staging, exclude, transform, sessionChannelKey) {
+    if (!fs.existsSync(source))
+        return;
+    operations.push({ id, kind: 'copy', source, destination, staging, exclude, transform, sessionChannelKey, status: 'planned' });
+}
+/**
+ * Historic AUN data can contain an early `_unknown` transcript and a later
+ * identified transcript for the same peer. They are one logical session, so
+ * retain both instead of allowing the second copy to collide with the first.
+ */
+function addSessionCopy(operations, id, source, destination, staging, exclude, transform, sessionChannelKey) {
+    if (!fs.existsSync(source))
+        return;
+    const existing = operations.find(operation => operation.destination === destination
+        && (operation.kind === 'copy' || operation.kind === 'merge-copy'));
+    if (existing) {
+        existing.kind = 'merge-copy';
+        existing.sources = [...new Set([...(existing.sources ?? []), source])];
+        return;
+    }
+    operations.push({ id, kind: 'copy', source, destination, staging, exclude, transform, sessionChannelKey, status: 'planned' });
+}
+/** A rebinding can meet existing migrated state; merge it conservatively. */
+function addMergeCopy(operations, id, source, destination, staging, exclude, transform, sessionChannelKey) {
+    if (!fs.existsSync(source))
+        return;
+    const existing = operations.find(operation => operation.destination === destination
+        && (operation.kind === 'copy' || operation.kind === 'merge-copy'));
+    if (existing) {
+        existing.kind = 'merge-copy';
+        existing.sources = [...new Set([...(existing.sources ?? []), source])];
+        return;
+    }
+    operations.push({ id, kind: 'merge-copy', source, destination, staging, exclude, transform, sessionChannelKey, status: 'planned' });
+}
+/** Build a read-only plan for the explicit, copy-based user-data migration. */
+export function planDataMigration(root) {
+    const operations = [];
+    const warnings = [];
+    const id = `data-${Date.now().toString(36)}-${crypto.randomBytes(3).toString('hex')}`;
+    const stagingDir = migrationStagingDir(root, id);
+    const instances = listChannelInstances(root);
+    const aids = configuredAids(root);
+    const control = controlIdentity(root);
+    const triggerOwners = listTriggerOwners(root);
+    const legacySessions = path.join(root, 'data', 'sessions');
+    const legacyFeishuChats = new Map();
+    let sequence = 0;
+    const nextId = (prefix) => `${prefix}-${String(++sequence).padStart(5, '0')}`;
+    const stageFor = (operationId) => path.join(stagingDir, operationId, 'payload');
+    const liveSessionDestinations = new Set();
+    const nestedSessionDestinations = new Set();
+    const rememberFeishuChat = (channelKey, channelId) => {
+        const chats = legacyFeishuChats.get(channelKey) ?? new Set();
+        chats.add(channelId);
+        legacyFeishuChats.set(channelKey, chats);
+    };
+    const addFeishuSeen = (source, channelKey, channelId, prefix) => {
+        if (!fs.existsSync(source))
+            return;
+        const destination = channelStateDestination(root, channelKey, 'dedup', 'feishu', `${encodeURIComponent(channelId)}.jsonl`);
+        const operationId = nextId(prefix);
+        if (operations.some(operation => operation.destination === destination)) {
+            addMergeCopy(operations, operationId, source, destination, stageFor(operationId));
+        }
+        else {
+            addCopy(operations, operationId, source, destination, stageFor(operationId));
+        }
+    };
+    // Trigger data is Agent-owned. Migrate each valid Trigger independently so
+    // one malformed legacy definition does not block unrelated Agent data.
+    for (const { aid, directory } of listTriggerStorageRoots(root, 'legacy')) {
+        let entries;
+        try {
+            entries = fs.readdirSync(directory, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const source = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name.startsWith('.')) {
+                    const operationId = nextId('trigger-metadata');
+                    addCopy(operations, operationId, source, triggerDestination(root, aid, entry.name), stageFor(operationId));
+                    continue;
+                }
+                const definition = readJson(path.join(source, 'trigger.json'));
+                if (!isOwnedTriggerDefinition(definition, aid, entry.name)) {
+                    warnings.push(`Invalid Trigger definition retained: ${source}`);
+                    continue;
+                }
+                const operationId = nextId('trigger');
+                addCopy(operations, operationId, source, triggerDestination(root, aid, entry.name), stageFor(operationId), undefined, 'rewrite-trigger-session-paths');
+                continue;
+            }
+            if (entry.isFile() && (entry.name === 'history.jsonl' || /^triggers\.legacy\.migrated\.\d+\.json$/.test(entry.name))) {
+                const operationId = nextId(entry.name === 'history.jsonl' ? 'trigger-history' : 'trigger-legacy-stats');
+                addCopy(operations, operationId, source, triggerDestination(root, aid, entry.name), stageFor(operationId));
+                continue;
+            }
+            warnings.push(`Unrecognized Trigger data retained: ${source}`);
+        }
+    }
+    // Canonicalize single-level keys written by an earlier v3 build. These are
+    // live Agent-owned copies and therefore take precedence over retained source
+    // layouts when both resolve to the same destination.
+    for (const chat of scanNonCanonicalAgentChatDirs(path.join(root, 'agents'))) {
+        const record = readLatestSession(chat.dirPath);
+        const channelKey = channelKeyForNestedAgentSession(chat, record, instances);
+        if (!channelKey) {
+            warnings.push(`Unresolved non-canonical Agent session retained: ${chat.dirPath}`);
+            continue;
+        }
+        let destination;
+        try {
+            destination = sessionDestination(root, chat.selfAID, channelKey, chat.channelId);
+        }
+        catch (error) {
+            warnings.push(`Unmigratable Agent session retained: ${chat.dirPath}: ${error instanceof Error ? error.message : String(error)}`);
+            continue;
+        }
+        liveSessionDestinations.add(destination);
+        const sessionId = nextId('canonical-session');
+        addSessionCopy(operations, sessionId, chat.dirPath, destination, stageFor(sessionId), chat.channelType === 'feishu' ? [SESSION_SEEN_FILE] : undefined, channelKey === 'daemon' ? undefined : 'normalize-session-channel-key', channelKey === 'daemon' ? undefined : channelKey);
+        if (chat.channelType === 'feishu') {
+            rememberFeishuChat(channelKey, chat.channelId);
+            addFeishuSeen(path.join(chat.dirPath, SESSION_SEEN_FILE), channelKey, chat.channelId, 'canonical-feishu-seen');
+        }
+    }
+    // Version 3 flattens the previous Agent-owned two-level session layout.
+    // These directories are the most recent runtime copies, so when they and a
+    // retained data/sessions source resolve to the same destination, this copy
+    // takes precedence and avoids replaying an older transcript.
+    const nestedChats = scanNestedAgentChatDirs(path.join(root, 'agents'))
+        .map(chat => {
+        const record = readLatestSession(chat.dirPath);
+        const channelKey = channelKeyForNestedAgentSession(chat, record, instances);
+        return { chat, record, channelKey };
+    })
+        .sort((left, right) => {
+        const priority = nestedSessionSourcePriority(left.chat, left.record, left.channelKey)
+            - nestedSessionSourcePriority(right.chat, right.record, right.channelKey);
+        if (priority)
+            return priority;
+        return left.chat.dirPath < right.chat.dirPath ? -1 : left.chat.dirPath > right.chat.dirPath ? 1 : 0;
+    });
+    for (const { chat, channelKey } of nestedChats) {
+        if (!channelKey) {
+            warnings.push(`Unresolved Agent session channel retained: ${chat.dirPath}`);
+            continue;
+        }
+        let destination;
+        try {
+            destination = sessionDestination(root, chat.selfAID, channelKey, chat.channelId);
+        }
+        catch (error) {
+            warnings.push(`Unmigratable Agent session retained: ${chat.dirPath}: ${error instanceof Error ? error.message : String(error)}`);
+            continue;
+        }
+        if (liveSessionDestinations.has(destination))
+            continue;
+        nestedSessionDestinations.add(destination);
+        const sessionId = nextId('flatten-session');
+        addSessionCopy(operations, sessionId, chat.dirPath, destination, stageFor(sessionId), chat.channelType === 'feishu' ? [SESSION_SEEN_FILE] : undefined, channelKey === 'daemon' ? undefined : 'normalize-session-channel-key', channelKey === 'daemon' ? undefined : channelKey);
+        if (chat.channelType === 'feishu') {
+            rememberFeishuChat(channelKey, chat.channelId);
+            addFeishuSeen(path.join(chat.dirPath, SESSION_SEEN_FILE), channelKey, chat.channelId, 'flatten-feishu-seen');
+        }
+    }
+    for (const chat of scanLegacyChatDirs(legacySessions)) {
+        const record = readLatestSession(chat.dirPath);
+        if (chat.channelType === 'daemon') {
+            const triggerOwner = resolveDaemonTriggerOwner(chat, record, triggerOwners);
+            if (!triggerOwner.aid) {
+                warnings.push(`${triggerOwner.warning ?? 'Unresolved daemon session retained'}: ${chat.dirPath}`);
+                continue;
+            }
+            let destination;
+            try {
+                destination = sessionDestination(root, triggerOwner.aid, 'daemon', chat.channelId);
+            }
+            catch (error) {
+                warnings.push(`Unmigratable daemon session retained: ${chat.dirPath}: ${error instanceof Error ? error.message : String(error)}`);
+                continue;
+            }
+            if (!liveSessionDestinations.has(destination) && !nestedSessionDestinations.has(destination)) {
+                const sessionId = nextId('trigger-session');
+                addSessionCopy(operations, sessionId, chat.dirPath, destination, stageFor(sessionId));
+            }
+            continue;
+        }
+        const fromChannel = parseChannelKey(record?.channel ?? record?.metadata?.channelKey);
+        const aid = chat.selfAID && chat.selfAID !== '_unknown'
+            ? chat.selfAID
+            : (typeof record?.selfAID === 'string' && record.selfAID !== '_unknown'
+                ? record.selfAID
+                : fromChannel?.aid ?? inferUnknownAunOwner(chat, control));
+        if (!aid || aid === '_unknown') {
+            warnings.push(`Unresolved session owner retained: ${chat.dirPath}`);
+            continue;
+        }
+        if (!aids.has(aid) && !control.aids.has(aid)) {
+            warnings.push(`Session owner has no Agent config and was retained: ${chat.dirPath}`);
+            continue;
+        }
+        const channelKey = configuredChannelKey(instances, chat.channelType, aid, record?.channel, record?.metadata?.channelKey, chat.channelKey);
+        if (!channelKey) {
+            warnings.push(`Unresolved session channel retained: ${chat.dirPath}`);
+            continue;
+        }
+        let destination;
+        try {
+            destination = sessionDestination(root, aid, channelKey, chat.channelId);
+        }
+        catch (error) {
+            warnings.push(`Unmigratable session retained: ${chat.dirPath}: ${error instanceof Error ? error.message : String(error)}`);
+            continue;
+        }
+        if (!liveSessionDestinations.has(destination) && !nestedSessionDestinations.has(destination)) {
+            const sessionId = nextId('session');
+            addSessionCopy(operations, sessionId, chat.dirPath, destination, stageFor(sessionId), [SESSION_SEEN_FILE], 'normalize-session-channel-key', channelKey);
+        }
+        if (chat.channelType === 'feishu') {
+            rememberFeishuChat(channelKey, chat.channelId);
+            addFeishuSeen(path.join(chat.dirPath, SESSION_SEEN_FILE), channelKey, chat.channelId, 'feishu-seen');
+        }
+    }
+    // Rebind connector state written under a removed unique channel instance.
+    // The source stays intact; a merge-copy handles an already-created target.
+    try {
+        for (const entry of fs.readdirSync(path.join(root, 'data', 'channel-state'), { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            let oldChannelKey;
+            try {
+                oldChannelKey = decodeURIComponent(entry.name);
+            }
+            catch {
+                warnings.push(`Unreadable channel-state key retained: ${entry.name}`);
+                continue;
+            }
+            const parsed = parseChannelKey(oldChannelKey);
+            if (!parsed || parsed.type === 'aun' || parsed.type === 'daemon')
+                continue;
+            const channelKey = configuredChannelKey(instances, parsed.type, parsed.aid, parsed.key);
+            if (!channelKey || channelKey === parsed.key)
+                continue;
+            const operationId = nextId('rebound-channel-state');
+            addMergeCopy(operations, operationId, path.join(root, 'data', 'channel-state', entry.name), channelStateDestination(root, channelKey), stageFor(operationId));
+        }
+    }
+    catch { }
+    const legacyHandoff = path.join(root, 'data', 'handoff');
+    try {
+        for (const entry of fs.readdirSync(legacyHandoff, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            if (!aids.has(entry.name)) {
+                warnings.push(`Unresolved handoff owner retained: ${entry.name}`);
+                continue;
+            }
+            const operationId = nextId('handoff');
+            addCopy(operations, operationId, path.join(legacyHandoff, entry.name), path.join(root, 'agents', entry.name, 'data', 'handoff'), stageFor(operationId));
+        }
+    }
+    catch { }
+    const legacyOutbox = path.join(root, 'data', 'outbox');
+    try {
+        for (const entry of fs.readdirSync(legacyOutbox, { withFileTypes: true })) {
+            if (!entry.isFile() || !entry.name.endsWith('.jsonl'))
+                continue;
+            const aid = entry.name.slice(0, -'.jsonl'.length);
+            if (!aids.has(aid)) {
+                warnings.push(`Unresolved outbox owner retained: ${entry.name}`);
+                continue;
+            }
+            const operationId = nextId('outbox');
+            addCopy(operations, operationId, path.join(legacyOutbox, entry.name), path.join(root, 'agents', aid, 'data', 'outbox.jsonl'), stageFor(operationId));
+        }
+    }
+    catch { }
+    const contactAudit = path.join(root, 'data', 'contact-book-audit.jsonl');
+    if (fs.existsSync(contactAudit)) {
+        const operationId = nextId('contact-audit');
+        operations.push({ id: operationId, kind: 'contact-audit-partition', source: contactAudit, staging: path.join(stagingDir, operationId), status: 'planned' });
+    }
+    for (const [prefix, source, destination] of [
+        ['queue', path.join(root, 'data', 'message-queue.json'), path.join(root, 'data', 'daemon', 'message-queue.json')],
+        ['restart-pending', path.join(root, 'data', 'restart-pending.json'), path.join(root, 'data', 'daemon', 'control', 'restart-pending.json')],
+    ]) {
+        const operationId = nextId(prefix);
+        addCopy(operations, operationId, source, destination, stageFor(operationId));
+    }
+    try {
+        for (const entry of fs.readdirSync(path.join(root, 'data'), { withFileTypes: true })) {
+            if (entry.isFile() && /^restart-confirm-.*\.json$/.test(entry.name)) {
+                const operationId = nextId('restart-confirm');
+                addCopy(operations, operationId, path.join(root, 'data', entry.name), path.join(root, 'data', 'daemon', 'control', entry.name), stageFor(operationId));
+            }
+        }
+    }
+    catch { }
+    // Connector state whose filename embeds a full effective channel key.
+    try {
+        for (const entry of fs.readdirSync(path.join(root, 'data'), { withFileTypes: true })) {
+            const welcome = entry.name.match(/^([a-z0-9_-]+)-greeted-(.+)\.jsonl$/i);
+            if (entry.isFile() && welcome) {
+                const channelKey = matchingChannel(instances, welcome[1], welcome[2]);
+                if (channelKey) {
+                    const operationId = nextId('welcome');
+                    addCopy(operations, operationId, path.join(root, 'data', entry.name), channelStateDestination(root, channelKey, 'welcome.jsonl'), stageFor(operationId));
+                }
+                else
+                    warnings.push(`Unresolved welcome state retained: ${entry.name}`);
+            }
+            const globalFeishuSeen = entry.name.match(/^feishu-seen-(.+)\.jsonl$/);
+            if (entry.isFile() && globalFeishuSeen) {
+                const channelKey = matchingChannel(instances, 'feishu', globalFeishuSeen[1]);
+                const chatIds = channelKey ? [...(legacyFeishuChats.get(channelKey) ?? [])] : [];
+                if (!channelKey) {
+                    warnings.push(`Unresolved Feishu instance dedup retained: ${entry.name}`);
+                }
+                else if (chatIds.length === 0) {
+                    warnings.push(`Feishu instance dedup retained because no legacy chat maps to ${channelKey}: ${entry.name}`);
+                }
+                else {
+                    for (const chatId of chatIds) {
+                        const operationId = nextId('feishu-global-seen');
+                        addCopy(operations, operationId, path.join(root, 'data', entry.name), channelStateDestination(root, channelKey, 'dedup', 'feishu', `${encodeURIComponent(chatId)}.jsonl`), stageFor(operationId));
+                    }
+                }
+            }
+        }
+    }
+    catch { }
+    // Legacy WeCom state includes its full channel key in the parent path and file.
+    for (const instance of instances.filter(item => item.type === 'wecom')) {
+        const oldDir = path.join(root, 'agents', instance.aid, 'data', 'channels', encodeURIComponent(instance.key));
+        for (const [prefix, file, target] of [
+            ['wecom-dedup', 'wecom-message-dedup.json', 'dedup.json'],
+            ['wecom-cards', 'wecom-cards.json', 'cards.json'],
+        ]) {
+            const operationId = nextId(prefix);
+            addCopy(operations, operationId, path.join(oldDir, file), channelStateDestination(root, instance.key, target), stageFor(operationId));
+        }
+    }
+    const wechatInstances = instances.filter(item => item.type === 'wechat');
+    if (wechatInstances.length === 1) {
+        const channelKey = wechatInstances[0].key;
+        for (const [prefix, source, target] of [
+            ['wechat-context', path.join(root, 'data', 'wechat-context-tokens.json'), 'context-tokens.json'],
+            ['wechat-cursor', path.join(root, 'data', 'wechat-sync-buf.txt'), 'sync-buffer.txt'],
+        ]) {
+            const operationId = nextId(prefix);
+            addCopy(operations, operationId, source, channelStateDestination(root, channelKey, target), stageFor(operationId));
+        }
+    }
+    else if (fs.existsSync(path.join(root, 'data', 'wechat-context-tokens.json')) || fs.existsSync(path.join(root, 'data', 'wechat-sync-buf.txt'))) {
+        warnings.push('Wechat global state retained because it does not map to exactly one configured instance.');
+    }
+    const dingtalkByHash = new Map();
+    for (const instance of instances.filter(item => item.type === 'dingtalk')) {
+        const hash = crypto.createHash('sha256').update(`${instance.aid}:${instance.key}`).digest('hex').slice(0, 16);
+        dingtalkByHash.set(hash, instance);
+    }
+    try {
+        for (const entry of fs.readdirSync(path.join(root, 'data'), { withFileTypes: true })) {
+            if (!entry.isFile())
+                continue;
+            const match = entry.name.match(/^dingtalk-(seen|routes)-([0-9a-f]{16})\.(jsonl|json)$/);
+            if (!match)
+                continue;
+            const instance = dingtalkByHash.get(match[2]);
+            if (!instance) {
+                warnings.push(`Unresolved DingTalk state retained: ${entry.name}`);
+                continue;
+            }
+            const targetName = match[1] === 'seen' ? 'dingtalk-seen.jsonl' : 'routes.json';
+            const operationId = nextId('dingtalk');
+            addCopy(operations, operationId, path.join(root, 'data', entry.name), channelStateDestination(root, instance.key, targetName), stageFor(operationId));
+        }
+    }
+    catch { }
+    acknowledgeCompletedCopies(root, operations);
+    const now = new Date().toISOString();
+    return {
+        schemaVersion: 1,
+        id,
+        root,
+        createdAt: now,
+        updatedAt: now,
+        state: 'planned',
+        operations,
+        warnings,
+        planSignature: migrationPlanSignature(operations),
+    };
+}
+function strictJsonValidation(filePath) {
+    if (filePath.endsWith('.json')) {
+        JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        return;
+    }
+    if (!filePath.endsWith('.jsonl'))
+        return;
+    const lines = fs.readFileSync(filePath, 'utf8').split('\n');
+    for (const [index, line] of lines.entries()) {
+        if (line.trim())
+            JSON.parse(line);
+        if (index > Number.MAX_SAFE_INTEGER)
+            throw new Error('unreachable');
+    }
+}
+function validateTree(filePath) {
+    const stat = fs.statSync(filePath);
+    if (stat.isFile())
+        return strictJsonValidation(filePath);
+    for (const entry of fs.readdirSync(filePath, { withFileTypes: true })) {
+        const child = path.join(filePath, entry.name);
+        if (entry.isDirectory())
+            validateTree(child);
+        else if (entry.isFile())
+            strictJsonValidation(child);
+    }
+}
+function verifyRequiredTriggerPayload(source, destination, relative = '') {
+    const sourceStat = fs.statSync(source);
+    let destinationStat;
+    try {
+        destinationStat = fs.statSync(destination);
+    }
+    catch {
+        throw new Error(`destination conflict: missing Trigger payload ${relative || '.'}`);
+    }
+    if (sourceStat.isFile()) {
+        if (!destinationStat.isFile())
+            throw new Error(`destination conflict: incompatible Trigger payload ${relative}`);
+        if (relative === 'active.json') {
+            strictJsonValidation(destination);
+            return;
+        }
+        if (relative === 'trigger.json') {
+            strictJsonValidation(destination);
+            return;
+        }
+        if (!fs.readFileSync(source).equals(fs.readFileSync(destination))) {
+            throw new Error(`destination conflict: changed Trigger payload ${relative}`);
+        }
+        return;
+    }
+    if (!destinationStat.isDirectory())
+        throw new Error(`destination conflict: incompatible Trigger directory ${relative || '.'}`);
+    for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+        if (!entry.isDirectory() && !entry.isFile())
+            continue;
+        const childRelative = relative ? path.join(relative, entry.name) : entry.name;
+        verifyRequiredTriggerPayload(path.join(source, entry.name), path.join(destination, entry.name), childRelative);
+    }
+}
+function verifyLiveTriggerDestination(operation) {
+    if (operation.transform !== 'rewrite-trigger-session-paths' || !operation.destination) {
+        throw new Error('operation is not a Trigger live-state reconciliation');
+    }
+    verifyRequiredTriggerPayload(operation.source, operation.destination);
+    const sourceDefinition = readJson(path.join(operation.source, 'trigger.json'));
+    const targetPath = path.join(operation.destination, 'trigger.json');
+    const targetDefinition = readJson(targetPath);
+    const aid = typeof sourceDefinition?.agentAid === 'string' ? sourceDefinition.agentAid : undefined;
+    const id = typeof sourceDefinition?.id === 'string' ? sourceDefinition.id : undefined;
+    if (!aid || !id || !isOwnedTriggerDefinition(targetDefinition, aid, id)) {
+        throw new Error('destination conflict: Trigger definition owner or id changed');
+    }
+    const content = fs.readFileSync(targetPath, 'utf8');
+    const transformed = transformedFileContent(targetPath, 'trigger.json', content, operation.transform, operation.sessionChannelKey);
+    if (transformed !== content)
+        throw new Error('destination conflict: Trigger definition still has legacy session paths');
+    validateTree(operation.destination);
+}
+function reconcileLiveTriggerDestination(operation) {
+    if (!operation.destination)
+        throw new Error('Trigger live-state reconciliation has no destination');
+    verifyRequiredTriggerPayload(operation.source, operation.destination);
+    const targetPath = path.join(operation.destination, 'trigger.json');
+    const content = fs.readFileSync(targetPath, 'utf8');
+    const transformed = transformedFileContent(targetPath, 'trigger.json', content, operation.transform, operation.sessionChannelKey);
+    if (transformed !== content)
+        atomicWriteText(targetPath, transformed);
+    verifyLiveTriggerDestination(operation);
+}
+function normalizeSessionRecordChannelKeys(record, channelKey, forceCurrentRoute = false) {
+    if (!record || typeof record !== 'object')
+        return false;
+    if (!channelKey)
+        throw new Error('session channel-key transform has no canonical target');
+    let changed = false;
+    const normalize = (value) => {
+        if (typeof value !== 'string')
+            return undefined;
+        const parsed = parseChannelKey(value);
+        // A single archived chat may span prior Agent/channel assignments. The
+        // destination path is authoritative for the current route; historical
+        // metadata must stay readable rather than making the entire copy fail.
+        // Only rewrite the unambiguous legacy key ordering for this same route.
+        if (!parsed)
+            return undefined;
+        if (forceCurrentRoute)
+            return value === channelKey ? undefined : channelKey;
+        return parsed.key === channelKey && parsed.key !== value ? channelKey : undefined;
+    };
+    const channel = normalize(record.channel);
+    if (channel && channel !== record.channel) {
+        record.channel = channel;
+        changed = true;
+    }
+    const metadataChannel = normalize(record.metadata?.channelKey);
+    if (metadataChannel && metadataChannel !== record.metadata.channelKey) {
+        record.metadata.channelKey = metadataChannel;
+        changed = true;
+    }
+    return changed;
+}
+function transformedFileContent(filePath, relative, content, transform, sessionChannelKey) {
+    if (transform === 'rewrite-trigger-session-paths') {
+        if (path.basename(filePath) !== 'trigger.json')
+            return content;
+        const definition = JSON.parse(content);
+        const prompt = definition?.execution?.prompt;
+        if (typeof prompt !== 'string')
+            return content;
+        const rewritten = rewriteLegacyTriggerSessionPaths(prompt, definition.agentAid);
+        return rewritten === prompt ? content : JSON.stringify({ ...definition, execution: { ...definition.execution, prompt: rewritten } }, null, 2) + '\n';
+    }
+    if (transform !== 'normalize-session-channel-key')
+        return content;
+    const baseName = path.basename(filePath);
+    if (relative === 'active.json') {
+        const record = JSON.parse(content);
+        return normalizeSessionRecordChannelKeys(record, sessionChannelKey, true) ? JSON.stringify(record, null, 2) + '\n' : content;
+    }
+    if (!/^meta_.*\.jsonl$/.test(baseName))
+        return content;
+    const lines = content.split('\n');
+    let changed = false;
+    for (let index = 0; index < lines.length; index++) {
+        const line = lines[index];
+        if (!line.trim())
+            continue;
+        const record = JSON.parse(line);
+        if (normalizeSessionRecordChannelKeys(record, sessionChannelKey)) {
+            lines[index] = JSON.stringify(record);
+            changed = true;
+        }
+    }
+    return changed ? lines.join('\n') : content;
+}
+function transformTree(filePath, transform, sessionChannelKey, relative = '') {
+    if (!transform)
+        return;
+    const stat = fs.statSync(filePath);
+    if (stat.isFile()) {
+        const content = fs.readFileSync(filePath, 'utf8');
+        const transformed = transformedFileContent(filePath, relative, content, transform, sessionChannelKey);
+        if (transformed !== content)
+            fs.writeFileSync(filePath, transformed);
+        return;
+    }
+    for (const entry of fs.readdirSync(filePath, { withFileTypes: true })) {
+        const childRelative = relative ? path.join(relative, entry.name) : entry.name;
+        if (entry.isDirectory() || entry.isFile())
+            transformTree(path.join(filePath, entry.name), transform, sessionChannelKey, childRelative);
+    }
+}
+function treeHash(filePath, exclude = [], relative = '', transform, sessionChannelKey) {
+    const hash = crypto.createHash('sha256');
+    const visit = (current, rel) => {
+        const stat = fs.statSync(current);
+        if (stat.isFile()) {
+            if (exclude.includes(rel))
+                return;
+            hash.update(`F\0${rel}\0`);
+            const raw = fs.readFileSync(current);
+            if (!transform) {
+                hash.update(raw);
+            }
+            else {
+                const rawText = raw.toString('utf8');
+                const transformed = transformedFileContent(current, rel, rawText, transform, sessionChannelKey);
+                hash.update(transformed === rawText ? raw : transformed);
+            }
+            return;
+        }
+        hash.update(`D\0${rel}\0`);
+        for (const entry of fs.readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            visit(path.join(current, entry.name), rel ? path.join(rel, entry.name) : entry.name);
+        }
+    };
+    visit(filePath, relative);
+    return hash.digest('hex');
+}
+function writeManifest(manifest) {
+    fs.mkdirSync(migrationDir(manifest.root), { recursive: true });
+    manifest.updatedAt = new Date().toISOString();
+    const target = manifestPath(manifest.root, manifest.id);
+    const temporary = `${target}.tmp`;
+    fs.writeFileSync(temporary, JSON.stringify(manifest, null, 2) + '\n');
+    fs.renameSync(temporary, target);
+}
+function atomicWriteText(target, content) {
+    const temporary = `${target}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`;
+    fs.writeFileSync(temporary, content);
+    fs.renameSync(temporary, target);
+}
+function hashContent(content) {
+    return crypto.createHash('sha256').update(content, 'utf8').digest('hex');
+}
+function appendIssue(operation, issue) {
+    const issues = operation.issues ?? [];
+    if (!issues.includes(issue))
+        issues.push(issue);
+    operation.issues = issues;
+}
+function executeContactAudit(manifest, operation, checkpoint) {
+    const groups = new Map();
+    const sourceHash = treeHash(operation.source);
+    if (operation.sourceHash && operation.sourceHash !== sourceHash) {
+        throw new Error(`source changed since migration began: ${operation.source}`);
+    }
+    operation.sourceHash = sourceHash;
+    operation.destinations = [];
+    operation.destinationHashes = {};
+    operation.issues = [];
+    for (const [index, line] of fs.readFileSync(operation.source, 'utf8').split('\n').entries()) {
+        if (!line.trim())
+            continue;
+        let record;
+        try {
+            record = JSON.parse(line);
+        }
+        catch {
+            appendIssue(operation, `contact audit line ${index + 1} is not valid JSON`);
+            continue;
+        }
+        if (typeof record.selfAid !== 'string' || !fs.existsSync(path.join(manifest.root, 'agents', record.selfAid, 'config.json'))) {
+            appendIssue(operation, `contact audit line ${index + 1} has no configured selfAid`);
+            continue;
+        }
+        const records = groups.get(record.selfAid) ?? [];
+        records.push(line);
+        groups.set(record.selfAid, records);
+    }
+    for (const [aid, lines] of groups) {
+        const destination = path.join(manifest.root, 'agents', aid, 'data', 'contact-audit.jsonl');
+        const content = lines.join('\n') + '\n';
+        const expectedHash = hashContent(content);
+        operation.destinations.push(destination);
+        operation.destinationHashes[destination] = expectedHash;
+        if (fs.existsSync(destination)) {
+            const existing = fs.readFileSync(destination, 'utf8');
+            if (hashContent(existing) !== expectedHash) {
+                // Audit logs are append-only. An exact existing prefix is a partial
+                // prior copy, so replacing it with the verified complete partition is
+                // lossless; every other mismatch remains a manual conflict.
+                if (!content.startsWith(existing)) {
+                    appendIssue(operation, `destination conflict: ${destination}`);
+                    continue;
+                }
+                atomicWriteText(destination, content);
+            }
+            continue;
+        }
+        if (!operation.staging)
+            throw new Error('contact audit operation has no staging path');
+        const stage = path.join(operation.staging, `${encodeSegment(aid)}.jsonl`);
+        if (!fs.existsSync(stage)) {
+            fs.mkdirSync(path.dirname(stage), { recursive: true });
+            const temporary = `${stage}.tmp`;
+            fs.writeFileSync(temporary, content);
+            fs.renameSync(temporary, stage);
+            operation.status = 'staged';
+            checkpoint();
+        }
+        strictJsonValidation(stage);
+        if (hashContent(fs.readFileSync(stage, 'utf8')) !== expectedHash) {
+            appendIssue(operation, `staging content mismatch: ${stage}`);
+            continue;
+        }
+        operation.status = 'verified';
+        checkpoint();
+        fs.mkdirSync(path.dirname(destination), { recursive: true });
+        fs.renameSync(stage, destination);
+        checkpoint();
+    }
+    if (operation.issues.length > 0) {
+        operation.status = 'error';
+        operation.error = operation.issues.join('; ');
+    }
+    else {
+        operation.status = operation.destinations.length > 0 ? 'committed' : 'skipped';
+        operation.error = undefined;
+    }
+}
+function executeCopy(operation, checkpoint) {
+    if (!operation.destination)
+        throw new Error('copy operation has no destination');
+    const sourceHash = treeHash(operation.source, operation.exclude);
+    if (operation.sourceHash && operation.sourceHash !== sourceHash) {
+        throw new Error(`source changed since migration began: ${operation.source}`);
+    }
+    operation.sourceHash = sourceHash;
+    const expectedHash = treeHash(operation.source, operation.exclude, '', operation.transform, operation.sessionChannelKey);
+    if (operation.expectedHash && operation.expectedHash !== expectedHash) {
+        throw new Error(`expected output changed since migration began: ${operation.source}`);
+    }
+    operation.expectedHash = expectedHash;
+    if (fs.existsSync(operation.destination)) {
+        operation.destinationHash = treeHash(operation.destination);
+        if (operation.destinationHash === expectedHash) {
+            operation.status = 'skipped';
+            operation.error = undefined;
+            operation.verificationError = undefined;
+            return;
+        }
+        if (operation.transform === 'rewrite-trigger-session-paths') {
+            reconcileLiveTriggerDestination(operation);
+            operation.preservedLiveTrigger = true;
+            operation.destinationHash = treeHash(operation.destination);
+            operation.status = 'committed';
+            operation.error = undefined;
+            operation.verificationError = undefined;
+            checkpoint();
+            return;
+        }
+        throw new Error(`destination conflict: ${operation.destination}`);
+    }
+    if (!operation.staging)
+        throw new Error('copy operation has no staging path');
+    if (!fs.existsSync(operation.staging)) {
+        fs.mkdirSync(path.dirname(operation.staging), { recursive: true });
+        fs.cpSync(operation.source, operation.staging, {
+            recursive: true,
+            filter: source => !operation.exclude?.includes(path.relative(operation.source, source)),
+        });
+    }
+    transformTree(operation.staging, operation.transform, operation.sessionChannelKey);
+    operation.status = 'staged';
+    operation.stagedHash = treeHash(operation.staging);
+    checkpoint();
+    validateTree(operation.staging);
+    operation.stagedHash = treeHash(operation.staging);
+    if (operation.stagedHash !== expectedHash)
+        throw new Error(`staging hash mismatch: ${operation.staging}`);
+    operation.status = 'verified';
+    checkpoint();
+    fs.mkdirSync(path.dirname(operation.destination), { recursive: true });
+    fs.renameSync(operation.staging, operation.destination);
+    operation.destinationHash = treeHash(operation.destination);
+    if (operation.destinationHash !== expectedHash)
+        throw new Error('content hash mismatch after commit');
+    operation.status = 'committed';
+    operation.error = undefined;
+    operation.verificationError = undefined;
+}
+function operationSources(operation) {
+    return [...new Set([operation.source, ...(operation.sources ?? [])])];
+}
+function trackMergeSources(operation) {
+    const sources = operationSources(operation);
+    const hashes = {};
+    for (const source of sources) {
+        const sourceHash = treeHash(source, operation.exclude);
+        if (operation.sourceHashes?.[source] && operation.sourceHashes[source] !== sourceHash) {
+            throw new Error(`source changed since migration began: ${source}`);
+        }
+        hashes[source] = sourceHash;
+    }
+    operation.sourceHashes = hashes;
+    operation.sourceHash = hashes[operation.source];
+    return sources;
+}
+function mergeJsonl(target, source) {
+    const lines = new Set(fs.readFileSync(target, 'utf8').split('\n').filter(line => line.trim()));
+    const merged = [...lines];
+    for (const line of fs.readFileSync(source, 'utf8').split('\n')) {
+        if (!line.trim() || lines.has(line))
+            continue;
+        lines.add(line);
+        merged.push(line);
+    }
+    fs.writeFileSync(target, merged.length ? `${merged.join('\n')}\n` : '');
+}
+function copyTree(source, destination) {
+    const stat = fs.statSync(source);
+    if (stat.isFile()) {
+        fs.mkdirSync(path.dirname(destination), { recursive: true });
+        fs.copyFileSync(source, destination);
+        return;
+    }
+    fs.mkdirSync(destination, { recursive: true });
+    for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+        if (entry.isDirectory() || entry.isFile())
+            copyTree(path.join(source, entry.name), path.join(destination, entry.name));
+    }
+}
+function mergeTree(source, destination, stagingRoot, relative = '') {
+    const stat = fs.statSync(source);
+    if (stat.isFile()) {
+        if (!fs.existsSync(destination)) {
+            copyTree(source, destination);
+            return;
+        }
+        const sourceContent = fs.readFileSync(source);
+        const destinationContent = fs.readFileSync(destination);
+        if (sourceContent.equals(destinationContent))
+            return;
+        if (source.endsWith('.jsonl')) {
+            mergeJsonl(destination, source);
+            return;
+        }
+        // Both payloads remain recoverable even when a singleton session file has
+        // incompatible historic versions. The canonical first copy stays in place.
+        const version = crypto.createHash('sha256').update(sourceContent).digest('hex').slice(0, 16);
+        copyTree(source, path.join(stagingRoot, '_legacy-conflicts', version, relative));
+        return;
+    }
+    fs.mkdirSync(destination, { recursive: true });
+    for (const entry of fs.readdirSync(source, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+        if (!entry.isDirectory() && !entry.isFile())
+            continue;
+        const childRelative = relative ? path.join(relative, entry.name) : entry.name;
+        mergeTree(path.join(source, entry.name), path.join(destination, entry.name), stagingRoot, childRelative);
+    }
+}
+function executeMergeCopy(operation, checkpoint) {
+    if (!operation.destination || !operation.staging)
+        throw new Error('merge-copy operation is incomplete');
+    const sources = trackMergeSources(operation);
+    const sourceOutputHashes = sources.map(source => treeHash(source, operation.exclude, '', operation.transform, operation.sessionChannelKey));
+    // The legacy copies remain authoritative, so a partially built stage may
+    // always be recreated safely. No destination is touched before validation.
+    if (fs.existsSync(operation.staging))
+        fs.rmSync(operation.staging, { recursive: true, force: true });
+    for (const source of sources)
+        mergeTree(source, operation.staging, operation.staging);
+    transformTree(operation.staging, operation.transform, operation.sessionChannelKey);
+    operation.status = 'staged';
+    operation.stagedHash = treeHash(operation.staging);
+    checkpoint();
+    validateTree(operation.staging);
+    const expectedHash = treeHash(operation.staging);
+    if (operation.expectedHash && operation.expectedHash !== expectedHash) {
+        throw new Error(`expected output changed since migration began: ${operation.source}`);
+    }
+    operation.expectedHash = expectedHash;
+    operation.status = 'verified';
+    checkpoint();
+    if (fs.existsSync(operation.destination)) {
+        const destinationHash = treeHash(operation.destination);
+        if (destinationHash !== expectedHash && !sourceOutputHashes.includes(destinationHash)) {
+            throw new Error(`destination conflict: ${operation.destination}`);
+        }
+        if (destinationHash !== expectedHash)
+            copyTree(operation.staging, operation.destination);
+    }
+    else {
+        fs.mkdirSync(path.dirname(operation.destination), { recursive: true });
+        fs.renameSync(operation.staging, operation.destination);
+    }
+    operation.destinationHash = treeHash(operation.destination);
+    if (operation.destinationHash !== expectedHash)
+        throw new Error('content hash mismatch after commit');
+    operation.status = 'committed';
+    operation.error = undefined;
+    operation.verificationError = undefined;
+}
+/**
+ * Copy each planned item independently. Failed items remain in the manifest;
+ * later items still run and a subsequent `--resume` only retries failures.
+ */
+export function applyDataMigration(manifest) {
+    manifest.state = 'running';
+    writeManifest(manifest);
+    for (const operation of manifest.operations) {
+        if (operation.status === 'committed' || operation.status === 'skipped' || operation.status === 'acknowledged')
+            continue;
+        try {
+            const checkpoint = () => writeManifest(manifest);
+            if (operation.kind === 'copy')
+                executeCopy(operation, checkpoint);
+            else if (operation.kind === 'merge-copy')
+                executeMergeCopy(operation, checkpoint);
+            else
+                executeContactAudit(manifest, operation, checkpoint);
+        }
+        catch (error) {
+            operation.status = 'error';
+            operation.error = error instanceof Error ? error.message : String(error);
+            operation.verificationError = undefined;
+        }
+        writeManifest(manifest);
+    }
+    manifest.state = manifest.operations.some(operation => operation.status === 'error' || operation.issues?.length)
+        ? 'completed_with_errors'
+        : 'completed';
+    writeManifest(manifest);
+    return manifest;
+}
+export function readDataMigration(root, id) {
+    const manifest = readJson(manifestPath(root, id));
+    if (!manifest || manifest.schemaVersion !== 1)
+        throw new Error(`migration manifest not found: ${id}`);
+    return manifest;
+}
+/**
+ * Startup gate for the explicit migration workflow. Legacy source files are
+ * deliberately retained after success, so their mere presence is not enough
+ * to block startup; only a changed or unacknowledged plan requires action.
+ */
+export function inspectDataMigrationRequirement(root) {
+    const plan = planDataMigration(root);
+    const planSignature = plan.planSignature ?? migrationPlanSignature(plan.operations);
+    if (plan.operations.length === 0) {
+        return { required: false, operationCount: 0, planSignature };
+    }
+    let completedMigrationId;
+    try {
+        const manifests = fs.readdirSync(migrationDir(root), { withFileTypes: true });
+        for (const entry of manifests) {
+            if (!entry.isFile() || !entry.name.endsWith('.json'))
+                continue;
+            const manifest = readJson(path.join(migrationDir(root), entry.name));
+            if (manifest?.state !== 'completed' || manifest.planSignature !== planSignature)
+                continue;
+            completedMigrationId = manifest.id;
+            break;
+        }
+    }
+    catch { }
+    return {
+        required: !completedMigrationId,
+        operationCount: plan.operations.length,
+        planSignature,
+        completedMigrationId,
+    };
+}
+export function verifyDataMigration(manifest, { strictTargetContent = true } = {}) {
+    for (const operation of manifest.operations) {
+        if (operation.status === 'acknowledged')
+            continue;
+        if (operation.preservedLiveTrigger) {
+            try {
+                verifyLiveTriggerDestination(operation);
+                operation.destinationHash = treeHash(operation.destination);
+                operation.status = 'committed';
+                operation.error = undefined;
+                operation.verificationError = undefined;
+            }
+            catch (error) {
+                operation.status = 'error';
+                operation.verificationError = error instanceof Error ? error.message : String(error);
+                operation.error ??= operation.verificationError;
+            }
+            continue;
+        }
+        if (operation.kind === 'contact-audit-partition') {
+            try {
+                const sourceHash = treeHash(operation.source);
+                if (operation.sourceHash && operation.sourceHash !== sourceHash)
+                    throw new Error('source changed since migration began');
+                operation.sourceHash = sourceHash;
+                for (const destination of operation.destinations ?? []) {
+                    if (!fs.existsSync(destination))
+                        throw new Error(`destination missing: ${destination}`);
+                    strictJsonValidation(destination);
+                    const expectedHash = operation.destinationHashes?.[destination];
+                    if (strictTargetContent && expectedHash && hashContent(fs.readFileSync(destination, 'utf8')) !== expectedHash) {
+                        throw new Error(`content hash mismatch: ${destination}`);
+                    }
+                }
+                if (operation.issues?.length)
+                    throw new Error(operation.issues.join('; '));
+                operation.status = operation.destinations?.length ? 'committed' : 'skipped';
+                operation.error = undefined;
+            }
+            catch (error) {
+                operation.status = 'error';
+                operation.verificationError = error instanceof Error ? error.message : String(error);
+                operation.error ??= operation.verificationError;
+            }
+            continue;
+        }
+        if (operation.kind === 'merge-copy') {
+            try {
+                if (!operation.destination || !fs.existsSync(operation.destination))
+                    throw new Error('destination missing');
+                trackMergeSources(operation);
+                validateTree(operation.destination);
+                const destinationHash = treeHash(operation.destination);
+                operation.destinationHash = destinationHash;
+                if (!operation.expectedHash)
+                    throw new Error('expected output hash missing');
+                if (strictTargetContent && operation.expectedHash !== destinationHash)
+                    throw new Error('content hash mismatch');
+                operation.status = 'committed';
+                operation.error = undefined;
+                operation.verificationError = undefined;
+            }
+            catch (error) {
+                operation.status = 'error';
+                operation.verificationError = error instanceof Error ? error.message : String(error);
+                operation.error ??= operation.verificationError;
+            }
+            continue;
+        }
+        if (!operation.destination || !fs.existsSync(operation.destination)) {
+            operation.status = 'error';
+            operation.verificationError = 'destination missing';
+            operation.error ??= operation.verificationError;
+            continue;
+        }
+        try {
+            validateTree(operation.destination);
+            const sourceHash = treeHash(operation.source, operation.exclude);
+            if (operation.sourceHash && operation.sourceHash !== sourceHash) {
+                throw new Error('source changed since migration began');
+            }
+            const expectedHash = treeHash(operation.source, operation.exclude, '', operation.transform, operation.sessionChannelKey);
+            if (operation.expectedHash && operation.expectedHash !== expectedHash) {
+                throw new Error('expected output changed since migration began');
+            }
+            const destinationHash = treeHash(operation.destination);
+            operation.sourceHash = sourceHash;
+            operation.expectedHash = expectedHash;
+            operation.destinationHash = destinationHash;
+            if (!strictTargetContent && operation.status === 'error' && operation.error?.startsWith('destination conflict') && expectedHash !== destinationHash) {
+                throw new Error(operation.error ?? 'content hash mismatch');
+            }
+            if (strictTargetContent && expectedHash !== destinationHash)
+                throw new Error('content hash mismatch');
+            if (operation.status !== 'skipped')
+                operation.status = 'committed';
+            operation.error = undefined;
+            operation.verificationError = undefined;
+        }
+        catch (error) {
+            operation.status = 'error';
+            operation.verificationError = error instanceof Error ? error.message : String(error);
+            operation.error ??= operation.verificationError;
+        }
+    }
+    manifest.state = manifest.operations.some(operation => operation.status === 'error' || operation.issues?.length)
+        ? 'completed_with_errors'
+        : 'completed';
+    writeManifest(manifest);
+    return manifest;
+}