@evomap/evolver-core 2.0.0-beta.19 → 2.0.0-beta.22

package/dist/bootstrap/lifecycleBootstrap.js

@@ -0,0 +1,433 @@
+import { posix, win32 } from 'node:path';
+import { parseFileLockProcessStartIdentity, sameFileLockProcessStartIdentity, } from '../util/fileLock.js';
+export const LIFECYCLE_BOOTSTRAP_MARKER_SCHEMA = 'evolver.lifecycle-bootstrap.v1';
+export const LIFECYCLE_BOOTSTRAP_LEGACY_BINDING = 'legacy-v907';
+export const LIFECYCLE_BOOTSTRAP_LEGACY_ENV_FILE_STATE_ROOT_PROOF = 'legacy-v907-env-file';
+export const LIFECYCLE_BOOTSTRAP_DEADLINE_ENV = 'EVOLVER_INTERNAL_BOOTSTRAP_DEADLINE_MS';
+export const LIFECYCLE_BOOTSTRAP_TRANSACTION_ENV = 'EVOLVER_INTERNAL_BOOTSTRAP_TRANSACTION_ID';
+export const LIFECYCLE_BOOTSTRAP_SUCCESS_FILE = 'bootstrap.json';
+export const LIFECYCLE_BOOTSTRAP_JOURNAL_FILE = 'bootstrap-transaction.json';
+export const LIFECYCLE_BOOTSTRAP_OWNER_LOCK_FILE = 'bootstrap-owner.lock';
+export const LIFECYCLE_BOOTSTRAP_READINESS_FILE = 'bootstrap-readiness.json';
+export const LIFECYCLE_BOOTSTRAP_READINESS_LOCK_FILE = 'bootstrap-readiness.lock';
+export const LIFECYCLE_BOOTSTRAP_READINESS_SCHEMA = 'evolver.lifecycle-bootstrap-readiness.v1';
+export const LIFECYCLE_BOOTSTRAP_MANUAL_TRANSITION_FILE = 'bootstrap-manual-transition.json';
+export const LIFECYCLE_BOOTSTRAP_MANUAL_TRANSITION_SCHEMA = 'evolver.lifecycle-bootstrap-manual-transition.v1';
+export const MAX_LIFECYCLE_BOOTSTRAP_MANUAL_TRANSITION_BYTES = 4 * 1024;
+export const LIFECYCLE_BOOTSTRAP_REGISTRATION_INTENT_FILE = 'bootstrap-registration.intent.json';
+export const LIFECYCLE_BOOTSTRAP_REGISTRATION_INTENT_TERMINAL_FILE = 'bootstrap-registration.intent.terminal';
+export const LIFECYCLE_BOOTSTRAP_REGISTRATION_INTENT_CLEARING_FILE = 'bootstrap-registration.intent.clearing';
+export const LIFECYCLE_BOOTSTRAP_REGISTRATION_INTENT_SCHEMA = 'evolver.bootstrap-registration-intent.v1';
+export const LIFECYCLE_BOOTSTRAP_REGISTRATION_TOKEN_ENV = 'EVOLVER_INTERNAL_BOOTSTRAP_REGISTRATION_TOKEN';
+export const MAX_LIFECYCLE_BOOTSTRAP_REGISTRATION_INTENT_BYTES = 4 * 1024;
+const TARGETS = new Set(['launchd', 'systemd', 'windows']);
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const SHA256_RE = /^[0-9a-f]{64}$/;
+function canonicalBootstrapPath(path, target) {
+    return target === 'windows'
+        ? win32.isAbsolute(path) && win32.normalize(path) === path
+        : posix.isAbsolute(path) && posix.normalize(path) === path;
+}
+function bootstrapPathKey(path, target) {
+    return target === 'windows' ? win32.normalize(path).toLowerCase() : path;
+}
+function boundedText(value, maxLength) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > maxLength)
+        return false;
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code <= 0x1f || code === 0x7f)
+            return false;
+    }
+    return true;
+}
+function exactRecordKeys(record, expected) {
+    const actual = Object.keys(record).sort();
+    const sortedExpected = [...expected].sort();
+    return actual.length === sortedExpected.length
+        && actual.every((key, index) => key === sortedExpected[index]);
+}
+function exactIsoTimestamp(value) {
+    if (typeof value !== 'string')
+        return false;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) && new Date(parsed).toISOString() === value;
+}
+export function parseLifecycleBootstrapRegistrationToken(value) {
+    return typeof value === 'string' && UUID_RE.test(value) ? value : undefined;
+}
+function exactProcessStartIdentityKeys(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const record = value;
+    if (record['source'] === 'linux-proc') {
+        return exactRecordKeys(record, ['source', 'bootId', 'startTicks']);
+    }
+    if (record['source'] === 'windows-powershell') {
+        return exactRecordKeys(record, ['source', 'startTimeTicks']);
+    }
+    if (record['source'] === 'darwin-ps') {
+        return exactRecordKeys(record, ['source', 'startTime']);
+    }
+    return false;
+}
+export function parseLifecycleBootstrapManualTransition(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const record = value;
+    if (!exactRecordKeys(record, ['schema', 'transitionId', 'removedTransactionId', 'target', 'service', 'createdAt'])
+        || record['schema'] !== LIFECYCLE_BOOTSTRAP_MANUAL_TRANSITION_SCHEMA
+        || typeof record['transitionId'] !== 'string' || !UUID_RE.test(record['transitionId'])
+        || typeof record['removedTransactionId'] !== 'string'
+        || !UUID_RE.test(record['removedTransactionId'])
+        || typeof record['target'] !== 'string'
+        || !TARGETS.has(record['target'])
+        || !boundedText(record['service'], 128)
+        || !exactIsoTimestamp(record['createdAt'])) {
+        return undefined;
+    }
+    return {
+        schema: LIFECYCLE_BOOTSTRAP_MANUAL_TRANSITION_SCHEMA,
+        transitionId: record['transitionId'],
+        removedTransactionId: record['removedTransactionId'],
+        target: record['target'],
+        service: record['service'],
+        createdAt: record['createdAt'],
+    };
+}
+export function parseLifecycleBootstrapManualTransitionJson(raw) {
+    try {
+        return parseLifecycleBootstrapManualTransition(JSON.parse(raw));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function parseLifecycleBootstrapRegistrationIntent(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const record = value;
+    const ownerValue = record['owner'];
+    if (record['schema'] !== LIFECYCLE_BOOTSTRAP_REGISTRATION_INTENT_SCHEMA
+        || !ownerValue || typeof ownerValue !== 'object' || Array.isArray(ownerValue)
+        || !exactRecordKeys(ownerValue, ['pid', 'token', 'processStartIdentity'])
+        || !Number.isSafeInteger(ownerValue['pid'])
+        || ownerValue['pid'] <= 0
+        || !parseLifecycleBootstrapRegistrationToken(ownerValue['token'])
+        || !exactProcessStartIdentityKeys(ownerValue['processStartIdentity'])
+        || !exactIsoTimestamp(record['createdAt'])) {
+        return undefined;
+    }
+    const processStartIdentity = parseFileLockProcessStartIdentity(ownerValue['processStartIdentity']);
+    if (!processStartIdentity)
+        return undefined;
+    const owner = {
+        pid: ownerValue['pid'],
+        token: ownerValue['token'],
+        processStartIdentity,
+    };
+    const base = {
+        schema: LIFECYCLE_BOOTSTRAP_REGISTRATION_INTENT_SCHEMA,
+        owner,
+        createdAt: record['createdAt'],
+    };
+    if (record['state'] === 'registering') {
+        if (!exactRecordKeys(record, ['schema', 'state', 'owner', 'createdAt']))
+            return undefined;
+        return { ...base, state: 'registering' };
+    }
+    const terminalOutcomes = new Set([
+        'committed',
+        'rolled_back',
+        'no_child',
+        'cancelled',
+    ]);
+    if (record['state'] !== 'terminal'
+        || typeof record['outcome'] !== 'string'
+        || !terminalOutcomes.has(record['outcome'])
+        || !exactIsoTimestamp(record['terminalAt'])) {
+        return undefined;
+    }
+    const outcome = record['outcome'];
+    if (outcome === 'committed') {
+        if (!exactRecordKeys(record, ['schema', 'state', 'owner', 'createdAt', 'outcome', 'terminalAt', 'transactionId'])
+            || typeof record['transactionId'] !== 'string'
+            || !UUID_RE.test(record['transactionId'])) {
+            return undefined;
+        }
+        return {
+            ...base,
+            state: 'terminal',
+            outcome,
+            terminalAt: record['terminalAt'],
+            transactionId: record['transactionId'],
+        };
+    }
+    if (!exactRecordKeys(record, ['schema', 'state', 'owner', 'createdAt', 'outcome', 'terminalAt'])
+        || record['transactionId'] !== undefined) {
+        return undefined;
+    }
+    return { ...base, state: 'terminal', outcome, terminalAt: record['terminalAt'] };
+}
+export function parseLifecycleBootstrapRegistrationIntentJson(raw) {
+    try {
+        return parseLifecycleBootstrapRegistrationIntent(JSON.parse(raw));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function parseLifecycleBootstrapMarker(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const record = value;
+    if (record['schema'] !== LIFECYCLE_BOOTSTRAP_MARKER_SCHEMA)
+        return undefined;
+    const markerKeys = [
+        'schema',
+        'transactionId',
+        'bootstrappedAt',
+        'target',
+        'service',
+        'files',
+        'managerArtifactPath',
+        'artifacts',
+        ...(record['managerBindingKind'] === undefined ? [] : ['managerBindingKind']),
+        ...(record['preservedArtifacts'] === undefined ? [] : ['preservedArtifacts']),
+        ...(record['legacyStateRootProof'] === undefined ? [] : ['legacyStateRootProof']),
+    ];
+    if (!exactRecordKeys(record, markerKeys))
+        return undefined;
+    if (typeof record['transactionId'] !== 'string' || !UUID_RE.test(record['transactionId']))
+        return undefined;
+    if (typeof record['bootstrappedAt'] !== 'string' || Number.isNaN(Date.parse(record['bootstrappedAt'])))
+        return undefined;
+    if (typeof record['target'] !== 'string' || !TARGETS.has(record['target']))
+        return undefined;
+    if (!boundedText(record['service'], 128))
+        return undefined;
+    if (!Array.isArray(record['files']) || record['files'].length === 0 || record['files'].length > 32)
+        return undefined;
+    if (!record['files'].every((file) => boundedText(file, 4_096)))
+        return undefined;
+    const files = record['files'];
+    const target = record['target'];
+    if (files.some((file) => !canonicalBootstrapPath(file, target)))
+        return undefined;
+    const pathKeys = files.map((file) => bootstrapPathKey(file, target));
+    if (new Set(pathKeys).size !== pathKeys.length)
+        return undefined;
+    if (!boundedText(record['managerArtifactPath'], 4_096)
+        || !canonicalBootstrapPath(record['managerArtifactPath'], target)
+        || !pathKeys.includes(bootstrapPathKey(record['managerArtifactPath'], target)))
+        return undefined;
+    const managerBindingKind = record['managerBindingKind'];
+    if (managerBindingKind !== undefined
+        && managerBindingKind !== 'transaction'
+        && managerBindingKind !== LIFECYCLE_BOOTSTRAP_LEGACY_BINDING)
+        return undefined;
+    if (!Array.isArray(record['artifacts']))
+        return undefined;
+    const parseArtifact = (artifact) => {
+        if (!artifact || typeof artifact !== 'object' || Array.isArray(artifact))
+            return undefined;
+        const value = artifact;
+        if (!exactRecordKeys(value, ['path', 'size', 'sha256', 'device', 'inode']))
+            return undefined;
+        if (!boundedText(value['path'], 4_096) || !canonicalBootstrapPath(value['path'], target)
+            || !Number.isSafeInteger(value['size']) || value['size'] < 0
+            || typeof value['sha256'] !== 'string' || !SHA256_RE.test(value['sha256']))
+            return undefined;
+        if (typeof value['device'] !== 'string' || !/^[0-9]+$/.test(value['device'])
+            || BigInt(value['device']) <= 0n
+            || typeof value['inode'] !== 'string' || !/^[0-9]+$/.test(value['inode'])
+            || BigInt(value['inode']) <= 0n)
+            return undefined;
+        return {
+            path: value['path'],
+            size: value['size'],
+            sha256: value['sha256'],
+            device: value['device'],
+            inode: value['inode'],
+        };
+    };
+    const artifacts = record['artifacts'].map(parseArtifact);
+    const preservedArtifacts = record['preservedArtifacts'] === undefined
+        ? []
+        : Array.isArray(record['preservedArtifacts'])
+            ? record['preservedArtifacts'].map(parseArtifact)
+            : [undefined];
+    if (record['preservedArtifacts'] !== undefined
+        && (managerBindingKind !== LIFECYCLE_BOOTSTRAP_LEGACY_BINDING
+            || preservedArtifacts.length === 0))
+        return undefined;
+    const legacyStateRootProofValue = record['legacyStateRootProof'];
+    let legacyStateRootProof;
+    if (legacyStateRootProofValue !== undefined) {
+        if (managerBindingKind !== LIFECYCLE_BOOTSTRAP_LEGACY_BINDING
+            || !legacyStateRootProofValue
+            || typeof legacyStateRootProofValue !== 'object'
+            || Array.isArray(legacyStateRootProofValue))
+            return undefined;
+        const proof = legacyStateRootProofValue;
+        if (!exactRecordKeys(proof, ['kind', 'envFilePath', 'stateDir'])
+            || proof['kind'] !== LIFECYCLE_BOOTSTRAP_LEGACY_ENV_FILE_STATE_ROOT_PROOF
+            || !boundedText(proof['envFilePath'], 4_096)
+            || !canonicalBootstrapPath(proof['envFilePath'], target)
+            || !boundedText(proof['stateDir'], 4_096)
+            || !canonicalBootstrapPath(proof['stateDir'], target))
+            return undefined;
+        legacyStateRootProof = {
+            kind: LIFECYCLE_BOOTSTRAP_LEGACY_ENV_FILE_STATE_ROOT_PROOF,
+            envFilePath: proof['envFilePath'],
+            stateDir: proof['stateDir'],
+        };
+    }
+    if (managerBindingKind !== LIFECYCLE_BOOTSTRAP_LEGACY_BINDING
+        && artifacts.length !== files.length)
+        return undefined;
+    const receipts = [...artifacts, ...preservedArtifacts];
+    if (receipts.length !== files.length
+        || receipts.some((artifact) => artifact === undefined)
+        || receipts.some((artifact, index) => bootstrapPathKey(artifact.path, target) !== pathKeys[index]))
+        return undefined;
+    const ownedKeys = new Set(artifacts.map((artifact) => bootstrapPathKey(artifact.path, target)));
+    if (!ownedKeys.has(bootstrapPathKey(record['managerArtifactPath'], target)))
+        return undefined;
+    if (legacyStateRootProof) {
+        const proofKey = bootstrapPathKey(legacyStateRootProof.envFilePath, target);
+        const preservedKeys = new Set(preservedArtifacts.map((artifact) => bootstrapPathKey(artifact.path, target)));
+        if (!preservedKeys.has(proofKey) || ownedKeys.has(proofKey))
+            return undefined;
+    }
+    return {
+        schema: LIFECYCLE_BOOTSTRAP_MARKER_SCHEMA,
+        transactionId: record['transactionId'],
+        bootstrappedAt: record['bootstrappedAt'],
+        target,
+        service: record['service'],
+        files: [...files],
+        managerArtifactPath: record['managerArtifactPath'],
+        ...(managerBindingKind === undefined ? {} : {
+            managerBindingKind: managerBindingKind,
+        }),
+        artifacts: artifacts,
+        ...(preservedArtifacts.length === 0 ? {} : {
+            preservedArtifacts: preservedArtifacts,
+        }),
+        ...(legacyStateRootProof ? { legacyStateRootProof } : {}),
+    };
+}
+export function parseLegacyLifecycleBootstrapMarker(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const record = value;
+    if (!exactRecordKeys(record, ['bootstrappedAt', 'target', 'service', 'files'])
+        || !exactIsoTimestamp(record['bootstrappedAt'])
+        || typeof record['target'] !== 'string'
+        || !TARGETS.has(record['target'])
+        || !boundedText(record['service'], 128)
+        || !Array.isArray(record['files'])
+        || record['files'].length === 0
+        || record['files'].length > 32
+        || !record['files'].every((file) => boundedText(file, 4_096)))
+        return undefined;
+    const target = record['target'];
+    const service = record['service'];
+    const expectedService = target === 'systemd'
+        ? 'systemd-user'
+        : target === 'launchd'
+            ? 'launchd'
+            : 'windows-scheduled-task';
+    const files = record['files'];
+    if (service !== expectedService
+        || files.some((file) => !canonicalBootstrapPath(file, target)))
+        return undefined;
+    const pathKeys = files.map((file) => bootstrapPathKey(file, target));
+    if (new Set(pathKeys).size !== pathKeys.length)
+        return undefined;
+    return {
+        bootstrappedAt: record['bootstrappedAt'],
+        target,
+        service,
+        files: [...files],
+    };
+}
+export function parseLegacyLifecycleBootstrapMarkerJson(raw) {
+    try {
+        return parseLegacyLifecycleBootstrapMarker(JSON.parse(raw));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function parseLifecycleBootstrapMarkerJson(raw) {
+    try {
+        return parseLifecycleBootstrapMarker(JSON.parse(raw));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function parseLifecycleBootstrapReadiness(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const record = value;
+    if (!exactRecordKeys(record, [
+        'schema',
+        'transactionId',
+        'pid',
+        'pidProcessStartIdentity',
+        'supervisorPid',
+        'supervisorProcessStartIdentity',
+        'startedAt',
+        'ipcUrl',
+    ])
+        || record['schema'] !== LIFECYCLE_BOOTSTRAP_READINESS_SCHEMA
+        || typeof record['transactionId'] !== 'string' || !UUID_RE.test(record['transactionId'])
+        || !Number.isSafeInteger(record['pid']) || record['pid'] <= 0
+        || !Number.isSafeInteger(record['supervisorPid']) || record['supervisorPid'] <= 0
+        || !exactProcessStartIdentityKeys(record['pidProcessStartIdentity'])
+        || !exactProcessStartIdentityKeys(record['supervisorProcessStartIdentity'])
+        || !exactIsoTimestamp(record['startedAt'])
+        || !boundedText(record['ipcUrl'], 2_048))
+        return undefined;
+    const pidProcessStartIdentity = parseFileLockProcessStartIdentity(record['pidProcessStartIdentity']);
+    const supervisorProcessStartIdentity = parseFileLockProcessStartIdentity(record['supervisorProcessStartIdentity']);
+    if (!pidProcessStartIdentity || !supervisorProcessStartIdentity)
+        return undefined;
+    if (record['pid'] === record['supervisorPid']
+        && !sameFileLockProcessStartIdentity(pidProcessStartIdentity, supervisorProcessStartIdentity))
+        return undefined;
+    try {
+        const url = new URL(record['ipcUrl']);
+        const port = Number(url.port);
+        if (url.protocol !== 'http:' || !['127.0.0.1', '[::1]'].includes(url.hostname.toLowerCase())
+            || !Number.isSafeInteger(port) || port <= 0 || port > 65_535
+            || url.username !== '' || url.password !== '' || url.pathname !== '/'
+            || url.search !== '' || url.hash !== '') {
+            return undefined;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return {
+        schema: LIFECYCLE_BOOTSTRAP_READINESS_SCHEMA,
+        transactionId: record['transactionId'],
+        pid: record['pid'],
+        pidProcessStartIdentity,
+        supervisorPid: record['supervisorPid'],
+        supervisorProcessStartIdentity,
+        startedAt: record['startedAt'],
+        ipcUrl: record['ipcUrl'],
+    };
+}
+export function parseLifecycleBootstrapReadinessJson(raw) {
+    try {
+        return parseLifecycleBootstrapReadiness(JSON.parse(raw));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/bootstrap/v1EnvCompat.d.ts

@@ -14,6 +14,8 @@
  * | `OPENCLAW_WORKSPACE` | *(manual)* | Partial V2 support does not preserve V1 workspace and bridge semantics |
  * | `EVOLVER_NO_PARENT_GIT` | *(none)* | V2 uses `EVOLVER_REPO_ROOT` or nearest Git root |
  * | `EVOLVER_VERBOSE` | *(none)* | V2 has no global switch; opt in to feature-specific diagnostics manually |
+ * | `EVOLVER_OPENAI_COMPATIBLE_BASE_URLS` | *(manual)* | Defensive compatibility spelling; canonical V1 used the EVOMAP-prefixed key |
+ * | `EVOMAP_OPENAI_COMPATIBLE_BASE_URLS` | *(manual)* | Canonical V1 compatible-origin allowlist; selected base and credential were separate |
  * | `EVOLVER_AUTO_ISSUE` | *(none)* | V2 creates local drafts; submit requires explicit approval-gated flow |
  * | `EVOLVER_ROLLBACK_MODE` | *(none)* | V2 uses worktree/snapshot/recovery policy |
  * | `WORKER_ENABLED` | *(none)* | No merchant-worker resolver in V2 |
@@ -98,6 +100,7 @@ export interface V1EnvTranslationReport {
     readonly manualCount: number;
     readonly removableCount: number;
     readonly githubTokenPresent: boolean;
+    readonly caveats?: readonly string[];
 }
 /**
  * Build an offline V1→V2 env translation report.

package/dist/bootstrap/v1EnvCompat.js

@@ -14,6 +14,8 @@
  * | `OPENCLAW_WORKSPACE` | *(manual)* | Partial V2 support does not preserve V1 workspace and bridge semantics |
  * | `EVOLVER_NO_PARENT_GIT` | *(none)* | V2 uses `EVOLVER_REPO_ROOT` or nearest Git root |
  * | `EVOLVER_VERBOSE` | *(none)* | V2 has no global switch; opt in to feature-specific diagnostics manually |
+ * | `EVOLVER_OPENAI_COMPATIBLE_BASE_URLS` | *(manual)* | Defensive compatibility spelling; canonical V1 used the EVOMAP-prefixed key |
+ * | `EVOMAP_OPENAI_COMPATIBLE_BASE_URLS` | *(manual)* | Canonical V1 compatible-origin allowlist; selected base and credential were separate |
  * | `EVOLVER_AUTO_ISSUE` | *(none)* | V2 creates local drafts; submit requires explicit approval-gated flow |
  * | `EVOLVER_ROLLBACK_MODE` | *(none)* | V2 uses worktree/snapshot/recovery policy |
  * | `WORKER_ENABLED` | *(none)* | No merchant-worker resolver in V2 |
@@ -56,6 +58,27 @@ export const V1_DEPRECATION_TABLE = [
         guidance: 'V2 has no global verbose switch. Remove this variable and opt in to a ' +
             'feature-specific flag such as EVOLVER_HOOK_VERBOSE=1 only when hook diagnostics are needed.',
     },
+    {
+        v1Name: 'EVOLVER_OPENAI_COMPATIBLE_BASE_URLS',
+        v2Equivalent: null,
+        migrationAction: 'manual',
+        guidance: 'This compatibility spelling was not resolved by the canonical V1 runtime, but it is tracked defensively. ' +
+            'V2 has no multi-base or arbitrary OpenAI-compatible resolver. Review the workload before cutover. ' +
+            'While either legacy list key remains set, configure the exact canonical pair EVOLVER_LLM_OPENAI_BASE_URL ' +
+            'and EVOLVER_LLM_OPENAI_API_KEY for one official https://*.api.openai.com/v1 endpoint. ' +
+            'LiteLLM, OpenRouter, Azure OpenAI, MiniMax, DeepSeek, Moonshot, and custom endpoints are not drop-in routes; ' +
+            'do not copy their credentials into the V2 OpenAI route.',
+    },
+    {
+        v1Name: 'EVOMAP_OPENAI_COMPATIBLE_BASE_URLS',
+        v2Equivalent: null,
+        migrationAction: 'manual',
+        guidance: 'Canonical V1 treated this comma-separated value as an allowed-origin list; EVOMAP_OPENAI_BASE_URL still selected one ' +
+            'endpoint and EVOMAP_OPENAI_API_KEY or OPENAI_API_KEY supplied its credential. V2 requires a workload-by-workload review ' +
+            'and has no automatic mapping. While the legacy list remains set, only the exact canonical pair ' +
+            'EVOLVER_LLM_OPENAI_BASE_URL and EVOLVER_LLM_OPENAI_API_KEY acknowledges migration; otherwise keep the incompatible ' +
+            'workload outside the V2 OpenAI route.',
+    },
     {
         v1Name: 'EVOLVER_AUTO_ISSUE',
         v2Equivalent: null,
@@ -109,6 +132,23 @@ export const V1_DEPRECATION_TABLE = [
         guidance: 'V2 LocalMemoryGraph retains three archives by default and prunes older archives automatically. ' +
             'There is no environment override; remove this variable.',
     },
+    {
+        v1Name: 'EVOLVER_ATP',
+        v2Equivalent: null,
+        migrationAction: 'manual',
+        guidance: 'V1 auto/on/off controlled merchant/provider lifecycle, which has no one-to-one V2 resolver. '
+            + 'Review the missing merchant workflow before removing this key. Do not map it to `evolver atp enable` '
+            + 'or EVOLVER_ATP_AUTOBUY; those controls authorize autonomous buyer spending. If V1 off meant no '
+            + 'provider or delivery activity, set EVOLVER_ATP_AUTODELIVER=off explicitly as hardening, not as an equivalent mapping.',
+    },
+    {
+        v1Name: 'EVOLVER_SESSION_SOURCE',
+        v2Equivalent: null,
+        migrationAction: 'manual',
+        guidance: 'V1 auto/cursor/openclaw/merge selected session collectors, which has no one-to-one V2 resolver. '
+            + 'Review the workload before removing this key. Supported trajectory export requires explicit runtime '
+            + 'discovery or transcript-directory controls; setting another aggregate key does not restore OpenClaw collection.',
+    },
 ];
 /**
  * Scan the provided environment for deprecated V1 env vars and return
@@ -173,6 +213,10 @@ export function checkV1EnvCompat(env = typeof process !== 'undefined' ? process.
     }
     return result;
 }
+const V1_IMPLICIT_DEFAULT_CAVEATS = [
+    'V1 treated unset EVOLVER_ATP and EVOLVER_SESSION_SOURCE as auto. A clean key scan therefore does not prove '
+        + 'merchant/provider or session-collection workflow parity; audit both before cutover.',
+];
 /**
  * Build an offline V1→V2 env translation report.
  * Does not write files; callers decide how to present or apply suggestions.
@@ -224,6 +268,7 @@ export function translateV1Env(env = typeof process !== 'undefined' ? process.en
         manualCount: suggestions.filter((s) => s.action === 'manual').length,
         removableCount: suggestions.filter((s) => s.action === 'remove').length,
         githubTokenPresent,
+        caveats: V1_IMPLICIT_DEFAULT_CAVEATS,
     };
 }
 /** Human-readable report (never prints secret-looking values; only key names + actions). */
@@ -232,8 +277,10 @@ export function formatV1EnvTranslationReport(report) {
         'V1 → V2 env translation (offline, no writes):',
         `  detected_deprecated=${report.detectedCount} map=${report.mappableCount} manual=${report.manualCount} remove=${report.removableCount} github_token=${report.githubTokenPresent ? 'present' : 'absent'}`,
     ];
+    for (const caveat of report.caveats ?? [])
+        lines.push(`  caveat: ${caveat}`);
     if (report.suggestions.length === 0) {
-        lines.push('  (no V1-only knobs detected)');
+        lines.push('  (no explicit V1-only knobs detected)');
         return `${lines.join('\n')}\n`;
     }
     for (const s of report.suggestions) {

package/dist/events/eventArchive.d.ts

@@ -61,5 +61,7 @@ export declare function rootEventArchiveSegmentName(firstSeq: number, lastSeq: n
 export declare function planRootEventArchive(opts: RootEventArchiveOptions): RootEventArchivePlan;
 export declare function archiveRootEvents(opts: RootEventArchiveOptions): RootEventArchiveResult;
 export declare function readRootEventHistory(path: string, archiveDir?: string): RootEvent[];
+/** Strict replay for control-plane decisions that must fail closed on partial or conflicting history. */
+export declare function readRootEventHistoryStrict(path: string): RootEvent[];
 export declare function validateRootEventHistory(path: string): void;
 export declare function inspectRootEventArchive(path: string): RootEventArchiveStats;

package/dist/events/eventArchive.js

@@ -131,6 +131,9 @@ export function archiveRootEvents(opts) {
     }
 }
 export function readRootEventHistory(path, archiveDir = rootEventArchiveDir(path)) {
+    // Snapshot active first. Writers publish archive segments before replacing active, so this prevents a reader
+    // from combining an old archive inventory with the new active tail and temporarily dropping the rotated prefix.
+    const active = readEventsLenient(path);
     const bySeq = new Map();
     for (const file of archiveSegmentFiles(archiveDir)) {
         for (const event of readEventsLenient(join(archiveDir, file))) {
@@ -143,13 +146,20 @@ export function readRootEventHistory(path, archiveDir = rootEventArchiveDir(path
     }
     // Preserve the pre-archive fail-soft behavior for routine commands. The active log is the current writer
     // source, so it deterministically wins an active/archive conflict without crashing status/report readers.
-    for (const event of readEventsLenient(path))
+    for (const event of active)
         bySeq.set(event.seq, event);
     return [...bySeq.values()].sort((a, b) => a.seq - b.seq);
 }
-export function validateRootEventHistory(path) {
+/** Strict replay for control-plane decisions that must fail closed on partial or conflicting history. */
+export function readRootEventHistoryStrict(path) {
     const active = readActiveStrict(path);
-    readValidatedArchive(path, active);
+    const bySeq = readValidatedArchive(path, active);
+    for (const line of active)
+        bySeq.set(line.event.seq, line.event);
+    return [...bySeq.values()].sort((left, right) => left.seq - right.seq);
+}
+export function validateRootEventHistory(path) {
+    void readRootEventHistoryStrict(path);
 }
 export function inspectRootEventArchive(path) {
     const archiveDir = rootEventArchiveDir(path);

package/dist/events/eventSchema.d.ts

@@ -81,6 +81,11 @@ export declare const rootEvent: z.ZodObject<{
     }>>;
 }, "strip", z.ZodTypeAny, {
     type: string;
+    actor: {
+        kind: "machine" | "human";
+        id?: string | undefined;
+    };
+    schemaVersion: string;
     ts: string;
     human: {
         severity: "warn" | "info" | "notice" | "error";
@@ -92,12 +97,7 @@ export declare const rootEvent: z.ZodObject<{
     };
     seq: number;
     eventId: string;
-    schemaVersion: string;
     replayability: "deterministic" | "stochastic_recorded" | "stochastic_unreproducible";
-    actor: {
-        kind: "machine" | "human";
-        id?: string | undefined;
-    };
     payload?: unknown;
 }, {
     type: string;
@@ -113,12 +113,12 @@ export declare const rootEvent: z.ZodObject<{
     seq: number;
     eventId: string;
     payload?: unknown;
-    schemaVersion?: string | undefined;
-    replayability?: "deterministic" | "stochastic_recorded" | "stochastic_unreproducible" | undefined;
     actor?: {
         kind?: "machine" | "human" | undefined;
         id?: string | undefined;
     } | undefined;
+    schemaVersion?: string | undefined;
+    replayability?: "deterministic" | "stochastic_recorded" | "stochastic_unreproducible" | undefined;
 }>;
 export type RootEvent = z.infer<typeof rootEvent>;
 /** append 入参: seq/eventId/ts 由 store 生成. */

package/dist/events/eventStore.d.ts

@@ -22,6 +22,8 @@ export declare class EventStore {
     private appendLocked;
     /** 读全部事件 (跳过尾部半行/损坏行). */
     readAll(): RootEvent[];
+    /** Fail-closed replay for decision policies that cannot safely consume a partial history. */
+    readAllStrict(): RootEvent[];
     iterate(fromSeq?: number): Generator<RootEvent>;
     tail(n?: number): RootEvent[];
     /** 截断尾部半行 (崩溃恢复). */

package/dist/events/eventStore.js

@@ -2,7 +2,7 @@ import { openSync, writeSync, fsyncSync, closeSync, statSync, readSync, mkdirSyn
 import { dirname } from 'node:path';
 import { monotonicFactory } from 'ulid';
 import { acquireLock, releaseLock } from '../util/fileLock.js';
-import { readRootEventHistory } from './eventArchive.js';
+import { readRootEventHistory, readRootEventHistoryStrict } from './eventArchive.js';
 // Monotonic ULIDs: plain ulid() randomizes the low 80 bits, so two ids minted in the SAME millisecond can sort
 // out of order — the event log wants time-sortable eventIds (and a flaky CI test proved it). The monotonic
 // factory increments within a millisecond, guaranteeing each successive eventId is strictly greater.
@@ -76,6 +76,10 @@ export class EventStore {
     readAll() {
         return readRootEventHistory(this.path);
     }
+    /** Fail-closed replay for decision policies that cannot safely consume a partial history. */
+    readAllStrict() {
+        return readRootEventHistoryStrict(this.path);
+    }
     *iterate(fromSeq = 0) {
         for (const e of this.readAll())
             if (e.seq >= fromSeq)