@evomap/evolver-proxy 2.0.0-beta.2 → 2.0.0-beta.22

package/dist/daemon/systemdNotifier.js

@@ -0,0 +1,163 @@
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+const SYSTEMD_NOTIFY_TIMEOUT_MS = 5_000;
+const MIN_WATCHDOG_INTERVAL_MS = 1_000;
+const DEFAULT_READY_RETRY_DELAYS_MS = [250, 750];
+const MAX_READY_RETRIES = 4;
+const MAX_READY_RETRY_DELAY_MS = 5_000;
+const SYSTEMD_NOTIFY_CANDIDATES = [
+    '/usr/bin/systemd-notify',
+    '/bin/systemd-notify',
+    '/run/current-system/sw/bin/systemd-notify',
+];
+const defaultSystemdNotifyExec = (command, args, options, callback) => {
+    execFile(command, [...args], options, (error) => { callback(error); });
+};
+export function systemdWatchdogIntervalMs(env = process.env) {
+    const usec = parsePositiveSafeInteger(env['WATCHDOG_USEC']);
+    if (usec === undefined)
+        return 0;
+    return Math.max(MIN_WATCHDOG_INTERVAL_MS, Math.floor(usec / 2_000));
+}
+export class SystemdNotifier {
+    options;
+    env;
+    platform;
+    now;
+    execFile;
+    readyRetryDelaysMs;
+    sleep;
+    notifyCommand;
+    timer;
+    readySent = false;
+    readyInFlight;
+    constructor(options) {
+        this.options = options;
+        this.env = options.env ?? process.env;
+        this.platform = options.platform ?? process.platform;
+        this.now = options.now ?? Date.now;
+        this.execFile = options.execFile ?? defaultSystemdNotifyExec;
+        this.readyRetryDelaysMs = normalizeReadyRetryDelays(options.readyRetryDelaysMs ?? DEFAULT_READY_RETRY_DELAYS_MS);
+        this.sleep = options.sleep ?? sleepMs;
+        this.notifyCommand = options.notifyCommand
+            ?? SYSTEMD_NOTIFY_CANDIDATES.find((candidate) => existsSync(candidate))
+            ?? SYSTEMD_NOTIFY_CANDIDATES[0];
+    }
+    async ready() {
+        if (!this.active())
+            return false;
+        if (this.readySent)
+            return true;
+        if (this.readyInFlight)
+            return this.readyInFlight;
+        const health = this.readHealth();
+        if (!health?.running || !health.ipcListening || !health.lifecycleArmed)
+            return false;
+        const attempt = this.announceReady();
+        this.readyInFlight = attempt;
+        void attempt.then(() => { if (this.readyInFlight === attempt)
+            this.readyInFlight = undefined; }, () => { if (this.readyInFlight === attempt)
+            this.readyInFlight = undefined; });
+        return attempt;
+    }
+    async readyOrThrow() {
+        if (!this.active())
+            return;
+        if (!await this.ready())
+            throw new Error('systemd_ready_notification_failed');
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+    }
+    active() {
+        return this.platform === 'linux' && Boolean(this.env['NOTIFY_SOCKET']?.trim());
+    }
+    startWatchdog() {
+        if (this.timer)
+            return;
+        // The installed unit may run a stable recovery controller as MainPID and the
+        // proxy as its child. NotifyAccess=all intentionally authorizes that child.
+        const intervalMs = systemdWatchdogIntervalMs(this.env);
+        if (intervalMs === 0)
+            return;
+        this.timer = setInterval(() => { this.pingWatchdog(intervalMs); }, intervalMs);
+        this.timer.unref?.();
+    }
+    pingWatchdog(freshnessMs) {
+        const health = this.readHealth();
+        if (!health?.running || !health.ipcListening || !health.lifecycleArmed)
+            return;
+        if (health.consecutiveFailures !== 0 || health.lastTickAt === undefined)
+            return;
+        const ageMs = this.now() - health.lastTickAt;
+        const plannedSleepHealthy = health.nextTickDueAt !== undefined
+            && this.now() <= health.nextTickDueAt + freshnessMs;
+        if (!Number.isFinite(ageMs) || ageMs < 0 || (ageMs > freshnessMs && !plannedSleepHealthy))
+            return;
+        void this.notify('WATCHDOG=1');
+    }
+    async announceReady() {
+        const attempts = this.readyRetryDelaysMs.length + 1;
+        for (let attempt = 0; attempt < attempts; attempt += 1) {
+            const health = this.readHealth();
+            if (!health?.running || !health.ipcListening || !health.lifecycleArmed)
+                return false;
+            if (await this.notify('READY=1')) {
+                this.readySent = true;
+                this.startWatchdog();
+                return true;
+            }
+            const delayMs = this.readyRetryDelaysMs[attempt];
+            if (delayMs !== undefined) {
+                try {
+                    await this.sleep(delayMs);
+                }
+                catch {
+                    return false;
+                }
+            }
+        }
+        return false;
+    }
+    readHealth() {
+        try {
+            return this.options.health();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    notify(state) {
+        return new Promise((resolve) => {
+            try {
+                this.execFile(this.notifyCommand, [state], {
+                    env: this.env,
+                    timeout: SYSTEMD_NOTIFY_TIMEOUT_MS,
+                    windowsHide: true,
+                }, (error) => { resolve(error === null); });
+            }
+            catch {
+                // Keep delivery failures as data: READY is enforced by readyOrThrow(), while watchdog pings stay best-effort.
+                resolve(false);
+            }
+        });
+    }
+}
+function normalizeReadyRetryDelays(values) {
+    return values.slice(0, MAX_READY_RETRIES).map((value) => (Number.isFinite(value)
+        ? Math.min(MAX_READY_RETRY_DELAY_MS, Math.max(0, Math.floor(value)))
+        : 0));
+}
+function sleepMs(delayMs) {
+    return new Promise((resolve) => { setTimeout(resolve, delayMs); });
+}
+function parsePositiveSafeInteger(value) {
+    const trimmed = value?.trim();
+    if (!trimmed || !/^\d+$/.test(trimmed))
+        return undefined;
+    const parsed = Number(trimmed);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
+}

package/dist/index.d.ts

@@ -1,8 +1,11 @@
 export declare const PACKAGE = "@evomap/evolver-proxy";
 export * from './sync/engine.js';
 export * from './lifecycle/manager.js';
+export * from './lifecycle/claimNudge.js';
 export * from './daemon/proxyDaemon.js';
+export * from './daemon/publishRecallVerifier.js';
 export * from './lifecycle/deployGuard.js';
 export * from './router/index.js';
 export * from './llm/index.js';
-export * from './selfUpdate/index.js';
+export * from './selfUpdate/index.js';
+export * from './private/adapterLoader.js';

package/dist/index.js

@@ -1,8 +1,11 @@
 export const PACKAGE = '@evomap/evolver-proxy';
 export * from './sync/engine.js';
 export * from './lifecycle/manager.js';
+export * from './lifecycle/claimNudge.js';
 export * from './daemon/proxyDaemon.js';
+export * from './daemon/publishRecallVerifier.js';
 export * from './lifecycle/deployGuard.js';
 export * from './router/index.js';
 export * from './llm/index.js';
-export * from './selfUpdate/index.js';
+export * from './selfUpdate/index.js';
+export * from './private/adapterLoader.js';

package/dist/lifecycle/claimNudge.d.ts

@@ -0,0 +1,20 @@
+export interface ClaimNudgeHelloResult {
+    ok: boolean;
+    claimCode?: string;
+    claimUrl?: string;
+}
+export interface ClaimNudgeStateStore {
+    getState(key: string): string | undefined;
+    setState(key: string, value: string): void;
+}
+export interface ClaimNudgeOptions {
+    store: ClaimNudgeStateStore;
+    hubUrl: string;
+    env?: Readonly<Record<string, string | undefined>>;
+    now?: () => number;
+    write?: (text: string) => void;
+}
+export type ClaimNudge = (result: ClaimNudgeHelloResult) => boolean;
+export declare function createClaimNudge(options: ClaimNudgeOptions): ClaimNudge;
+export declare function wrapHelloWithClaimNudge<T extends ClaimNudgeHelloResult, O>(hello: (options: O) => Promise<T>, nudge: ClaimNudge): (options: O) => Promise<T>;
+export declare function claimNudgeCooldownMs(raw: string | undefined): number;

package/dist/lifecycle/claimNudge.js

@@ -0,0 +1,124 @@
+const DEFAULT_COOLDOWN_MS = 6 * 60 * 60_000;
+const MIN_COOLDOWN_MS = 60_000;
+const MAX_COOLDOWN_MS = 30 * 24 * 60 * 60_000;
+const MAX_STATE_ENTRIES = 32;
+const STATE_KEY = 'lifecycle:claim_nudge:v1';
+const CLAIM_CODE_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{1,127}$/;
+export function createClaimNudge(options) {
+    const env = options.env ?? process.env;
+    const now = options.now ?? (() => Date.now());
+    const write = options.write ?? ((text) => { process.stderr.write(text); });
+    let memory = { version: 1, entries: {} };
+    return (result) => {
+        if (!result.ok || env['EVOLVER_DISABLE_CLAIM_NUDGE'] === '1')
+            return false;
+        const code = normalizeClaimCode(result.claimCode);
+        const url = code ? trustedClaimUrl(result.claimUrl, options.hubUrl) : undefined;
+        if (!code || !url)
+            return false;
+        const at = now();
+        const cooldownMs = claimNudgeCooldownMs(env['EVOLVER_CLAIM_NUDGE_COOLDOWN_MS']);
+        const state = mergeState(readState(options.store), memory);
+        const lastPrintedAt = state.entries[code] ?? 0;
+        if (lastPrintedAt > 0 && at - lastPrintedAt < cooldownMs)
+            return false;
+        const message = [
+            '',
+            '[evolver-proxy] This node is not linked to an EvoMap web account.',
+            `Claim URL: ${url}`,
+            `Claim code: ${code}`,
+            'Claiming is optional; the proxy continues to run without it.',
+            '',
+        ].join('\n');
+        try {
+            write(message);
+        }
+        catch {
+            return false;
+        }
+        memory = pruneState({ ...state.entries, [code]: at });
+        try {
+            options.store.setState(STATE_KEY, JSON.stringify(memory));
+        }
+        catch { /* memory still suppresses repeats */ }
+        return true;
+    };
+}
+export function wrapHelloWithClaimNudge(hello, nudge) {
+    return async (options) => {
+        const result = await hello(options);
+        try {
+            nudge(result);
+        }
+        catch { /* a terminal nudge must never break hello */ }
+        return result;
+    };
+}
+export function claimNudgeCooldownMs(raw) {
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return DEFAULT_COOLDOWN_MS;
+    return Math.max(MIN_COOLDOWN_MS, Math.min(Math.floor(parsed), MAX_COOLDOWN_MS));
+}
+function normalizeClaimCode(value) {
+    const code = value?.trim();
+    return code && CLAIM_CODE_RE.test(code) ? code : undefined;
+}
+function trustedClaimUrl(value, hubUrl) {
+    const raw = value?.trim();
+    if (!raw || raw.length > 2_048)
+        return undefined;
+    try {
+        const url = new URL(raw);
+        const hub = new URL(hubUrl);
+        if (url.username || url.password)
+            return undefined;
+        const sameOrigin = url.origin === hub.origin;
+        const evomapHost = url.hostname === 'evomap.ai' || url.hostname.endsWith('.evomap.ai');
+        if (url.protocol === 'https:' && (sameOrigin || evomapHost))
+            return url.toString();
+        if (url.protocol === 'http:' && sameOrigin && isLoopback(url.hostname))
+            return url.toString();
+    }
+    catch {
+        // Invalid or non-absolute URLs are never printed.
+    }
+    return undefined;
+}
+function isLoopback(hostname) {
+    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]';
+}
+function readState(store) {
+    try {
+        const raw = store.getState(STATE_KEY);
+        if (!raw)
+            return { version: 1, entries: {} };
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== 1 || !parsed.entries || typeof parsed.entries !== 'object' || Array.isArray(parsed.entries)) {
+            return { version: 1, entries: {} };
+        }
+        const entries = {};
+        for (const [code, value] of Object.entries(parsed.entries)) {
+            if (CLAIM_CODE_RE.test(code) && typeof value === 'number' && Number.isFinite(value) && value > 0)
+                entries[code] = value;
+        }
+        return { version: 1, entries };
+    }
+    catch {
+        return { version: 1, entries: {} };
+    }
+}
+function mergeState(a, b) {
+    const entries = { ...a.entries };
+    for (const [code, at] of Object.entries(b.entries))
+        entries[code] = Math.max(entries[code] ?? 0, at);
+    return { version: 1, entries };
+}
+function pruneState(entries) {
+    return {
+        version: 1,
+        entries: Object.fromEntries(Object.entries(entries)
+            .sort((left, right) => right[1] - left[1])
+            .slice(0, MAX_STATE_ENTRIES)),
+    };
+}

package/dist/lifecycle/legacyNodeId.d.ts

@@ -12,31 +12,29 @@ export interface LegacyNodeIdCandidateOptions {
  * Legacy node_id file locations, in priority order. Mirror of v1
  * `_loadPersistedNodeId`:
  *
- *  0. `<EVOMAP_DIR>/node_id` — the explicit dir the CLI recipe / ATP / proxy
+ *  0. `<EVOMAP_HOME>/node_id` — when an explicit identity home is configured, it
+ *     must precede every state-root candidate. The legacy node_secret resolver uses
+ *     the same priority, keeping both credentials on one identity in split layouts.
+ *  1. `<EVOMAP_DIR>/node_id` — the explicit dir the CLI recipe / ATP / proxy
  *     anti-abuse code write under (`recipeHomeCandidates` puts EVOMAP_DIR ahead
  *     of EVOLVER_HOME/EVOMAP_HOME). `resolveEvomapHome` never consults EVOMAP_DIR,
  *     so a deployment that pivots on it would otherwise send no node_id on hello
- *     and let the hub mint a duplicate. Probed FIRST and ADDITIVELY (the
- *     EVOLVER_HOME/EVOMAP_HOME candidates below are kept), so setting EVOMAP_DIR
- *     never hides an id that lives under one of the home overrides. Deduped.
- *  1. `<evomapHome>/node_id` — the override-aware home file. `resolveEvomapHome()`
- *     honours EVOLVER_HOME (matching v1 `getEvomapDir`) and ADDITIONALLY
- *     EVOMAP_HOME after dropping blank/relative overrides. It wins first so a
- *     home relocated via EVOLVER_HOME reads the file the v1 writer put there —
- *     the lesson of v1 #120, which routed the reader through the same helper as
- *     the writer.
- *  2. `~/.evomap/node_id` — the UNCONDITIONAL v1 location. v1's writer pivots on
+ *     and let the hub mint a duplicate. It remains first when EVOMAP_HOME is not
+ *     configured, preserving the existing EVOMAP_DIR-only contract. Deduped.
+ *  2. `<EVOLVER_HOME>/node_id` — the state-home compatibility candidate, kept
+ *     after the identity roots so readers still walk every dir a writer may have used.
+ *  3. `~/.evomap/node_id` — the UNCONDITIONAL v1 location. v1's writer pivots on
  *     `getEvomapDir` = `EVOLVER_HOME || ~/.evomap` and ignores EVOMAP_HOME
  *     entirely, so unless EVOLVER_HOME was set a v1 file always physically lands
  *     here. We probe it explicitly so a v2 install that sets only EVOMAP_HOME
  *     (which steers candidate 1 away from `~/.evomap`) still recovers the v1
  *     identity instead of letting the hub mint a duplicate orphan node. Deduped
  *     against candidate 1 for the common no-override case where they coincide.
- *  3. `<proxy package>/.evomap_node_id` — the install-root file the writer falls
+ *  4. `<proxy package>/.evomap_node_id` — the install-root file the writer falls
  *     back to when `~/.evomap/` isn't writable (read-only $HOME in
  *     containers / restricted CI). Kept first for parity with the old v2
  *     candidate.
- *  4. `<outer package/workspace root>/.evomap_node_id` — the v1/outer install
+ *  5. `<outer package/workspace root>/.evomap_node_id` — the v1/outer install
  *     root fallback. In v2's multi-package layout the proxy code lives below
  *     `packages/evolver-proxy`, so only checking the proxy package root misses
  *     a file written at the install/workspace root.

package/dist/lifecycle/legacyNodeId.js

@@ -17,11 +17,23 @@ function cleanAbsolutePath(value) {
         return undefined;
     return isAbsolute(trimmed) ? trimmed : undefined;
 }
-function resolveEvomapHome(opts, fallbackHomeDir) {
-    return cleanAbsolutePath(opts.evomapHomeDir)
-        ?? cleanAbsolutePath(process.env['EVOLVER_HOME'])
-        ?? cleanAbsolutePath(process.env['EVOMAP_HOME'])
-        ?? (fallbackHomeDir === undefined ? undefined : join(fallbackHomeDir, '.evomap'));
+// Identity homes in probe order (#555 T2): the explicit test/caller override wins outright; otherwise
+// EVOMAP_HOME (THE identity home) outranks EVOLVER_HOME (the state root) so the evox agentDir split
+// (`--evomap-home <agentDir>/evomap` + `--home <agentDir>/evolver`) reads node files from the evomap dir.
+// legacyNodeIdCandidates() splices that explicit identity home ahead of EVOMAP_DIR so node_id and
+// node_secret cannot come from different halves of the split layout. Both homes stay in the candidate union,
+// so single-home setups resolve exactly as before.
+function identityHomeCandidates(opts, fallbackHomeDir) {
+    const fromOpts = cleanAbsolutePath(opts.evomapHomeDir);
+    if (fromOpts !== undefined)
+        return [fromOpts];
+    const homes = [
+        cleanAbsolutePath(process.env['EVOMAP_HOME']),
+        cleanAbsolutePath(process.env['EVOLVER_HOME']),
+    ].filter((value) => value !== undefined);
+    if (homes.length > 0)
+        return homes;
+    return fallbackHomeDir === undefined ? [] : [join(fallbackHomeDir, '.evomap')];
 }
 function packageNameAt(dir) {
     const pkgPath = join(dir, 'package.json');
@@ -59,31 +71,29 @@ function installRootNodeIdCandidates(moduleDir) {
  * Legacy node_id file locations, in priority order. Mirror of v1
  * `_loadPersistedNodeId`:
  *
- *  0. `<EVOMAP_DIR>/node_id` — the explicit dir the CLI recipe / ATP / proxy
+ *  0. `<EVOMAP_HOME>/node_id` — when an explicit identity home is configured, it
+ *     must precede every state-root candidate. The legacy node_secret resolver uses
+ *     the same priority, keeping both credentials on one identity in split layouts.
+ *  1. `<EVOMAP_DIR>/node_id` — the explicit dir the CLI recipe / ATP / proxy
  *     anti-abuse code write under (`recipeHomeCandidates` puts EVOMAP_DIR ahead
  *     of EVOLVER_HOME/EVOMAP_HOME). `resolveEvomapHome` never consults EVOMAP_DIR,
  *     so a deployment that pivots on it would otherwise send no node_id on hello
- *     and let the hub mint a duplicate. Probed FIRST and ADDITIVELY (the
- *     EVOLVER_HOME/EVOMAP_HOME candidates below are kept), so setting EVOMAP_DIR
- *     never hides an id that lives under one of the home overrides. Deduped.
- *  1. `<evomapHome>/node_id` — the override-aware home file. `resolveEvomapHome()`
- *     honours EVOLVER_HOME (matching v1 `getEvomapDir`) and ADDITIONALLY
- *     EVOMAP_HOME after dropping blank/relative overrides. It wins first so a
- *     home relocated via EVOLVER_HOME reads the file the v1 writer put there —
- *     the lesson of v1 #120, which routed the reader through the same helper as
- *     the writer.
- *  2. `~/.evomap/node_id` — the UNCONDITIONAL v1 location. v1's writer pivots on
+ *     and let the hub mint a duplicate. It remains first when EVOMAP_HOME is not
+ *     configured, preserving the existing EVOMAP_DIR-only contract. Deduped.
+ *  2. `<EVOLVER_HOME>/node_id` — the state-home compatibility candidate, kept
+ *     after the identity roots so readers still walk every dir a writer may have used.
+ *  3. `~/.evomap/node_id` — the UNCONDITIONAL v1 location. v1's writer pivots on
  *     `getEvomapDir` = `EVOLVER_HOME || ~/.evomap` and ignores EVOMAP_HOME
  *     entirely, so unless EVOLVER_HOME was set a v1 file always physically lands
  *     here. We probe it explicitly so a v2 install that sets only EVOMAP_HOME
  *     (which steers candidate 1 away from `~/.evomap`) still recovers the v1
  *     identity instead of letting the hub mint a duplicate orphan node. Deduped
  *     against candidate 1 for the common no-override case where they coincide.
- *  3. `<proxy package>/.evomap_node_id` — the install-root file the writer falls
+ *  4. `<proxy package>/.evomap_node_id` — the install-root file the writer falls
  *     back to when `~/.evomap/` isn't writable (read-only $HOME in
  *     containers / restricted CI). Kept first for parity with the old v2
  *     candidate.
- *  4. `<outer package/workspace root>/.evomap_node_id` — the v1/outer install
+ *  5. `<outer package/workspace root>/.evomap_node_id` — the v1/outer install
  *     root fallback. In v2's multi-package layout the proxy code lives below
  *     `packages/evolver-proxy`, so only checking the proxy package root misses
  *     a file written at the install/workspace root.
@@ -97,12 +107,17 @@ function installRootNodeIdCandidates(moduleDir) {
 export function legacyNodeIdCandidates(opts = {}) {
     const home = cleanAbsolutePath(opts.homeDir) ?? cleanAbsolutePath(homedir());
     const moduleDir = opts.moduleDir ?? _moduleDir;
-    const evomapHome = resolveEvomapHome(opts, home);
+    const evomapHomes = identityHomeCandidates(opts, home);
+    const identityHome = cleanAbsolutePath(opts.evomapHomeDir)
+        ?? cleanAbsolutePath(process.env['EVOMAP_HOME']);
     const evomapDir = cleanAbsolutePath(opts.evomapDir) ?? cleanAbsolutePath(process.env['EVOMAP_DIR']);
     return [
         ...new Set([
+            ...(identityHome === undefined ? [] : [join(identityHome, 'node_id')]),
             ...(evomapDir === undefined ? [] : [join(evomapDir, 'node_id')]),
-            ...(evomapHome === undefined ? [] : [join(evomapHome, 'node_id')]),
+            ...evomapHomes
+                .filter((dir) => dir !== identityHome)
+                .map((dir) => join(dir, 'node_id')),
             ...(home === undefined ? [] : [join(home, '.evomap', 'node_id')]),
             ...installRootNodeIdCandidates(moduleDir),
         ]),

package/dist/lifecycle/manager.d.ts

@@ -18,6 +18,8 @@ export interface HelloResult {
     ok: boolean;
     authError?: boolean;
     nodeId?: string;
+    claimCode?: string;
+    claimUrl?: string;
     rateLimitUntilMs?: number;
     error?: string;
     details?: unknown;
@@ -40,6 +42,7 @@ export interface HeartbeatResult {
     httpStatus?: number;
     lastUpdateAck?: LastUpdateAck;
     forceUpdate?: ForceUpdateDirective;
+    capabilityGaps?: readonly string[];
 }
 export interface HeartbeatTickResult {
     ok: boolean;
@@ -98,6 +101,7 @@ export declare class LifecycleManager {
     private recordHubUnreachable;
     private clearLegacyNodeSecretVersion;
     private verifyReauthHeartbeat;
+    private persistCapabilityGaps;
     private heartbeatOptions;
     private callHello;
     private handleLastUpdateAck;

package/dist/lifecycle/manager.js

@@ -1,4 +1,4 @@
-import { mailbox, hub as hubNs } from '@evomap/evolver-core';
+import { mailbox, hub as hubNs, signals } from '@evomap/evolver-core';
 import { clearLastUpdateOnAck, isLastUpdateRelatedError, readPendingLastUpdate, shouldClearForLastUpdateAck, } from '../selfUpdate/lastUpdate.js';
 export const DEFAULT_HEARTBEAT_INTERVAL_MS = 360_000;
 export const MIN_HEARTBEAT_INTERVAL_MS = 30_000;
@@ -125,6 +125,7 @@ export class LifecycleManager {
             this.handleLastUpdateAck(res, sentLastUpdate, now);
             this.maybeTriggerForceUpdate(res);
             if (res.ok) {
+                this.persistCapabilityGaps(res.capabilityGaps, now);
                 this.deps.store.setState(K.hubUnreachableUntil, '0');
                 this.deps.store.setState(K.authStatus, 'ok');
                 this.deps.store.setState(K.lastError, '');
@@ -293,8 +294,10 @@ export class LifecycleManager {
             const hb = await this.deps.heartbeat(opts);
             this.handleLastUpdateAck(hb, opts?.lastUpdate, now);
             this.maybeTriggerForceUpdate(hb);
-            if (hb.ok)
+            if (hb.ok) {
+                this.persistCapabilityGaps(hb.capabilityGaps, now);
                 return 'ok';
+            }
             if (isHubUnreachableResult(hb)) {
                 this.recordHubUnreachable(hb, now);
                 return 'hub_unreachable';
@@ -309,6 +312,16 @@ export class LifecycleManager {
             throw err;
         }
     }
+    persistCapabilityGaps(capabilityGaps, observedAt) {
+        if (capabilityGaps === undefined)
+            return;
+        try {
+            this.deps.store.setState(signals.CAPABILITY_GAPS_STATE_KEY, signals.serializeCapabilityGapsState(capabilityGaps, observedAt));
+        }
+        catch {
+            // Curriculum is advisory; a failed optional KV write must not turn a healthy heartbeat into a failure.
+        }
+    }
     heartbeatOptions() {
         const opts = {};
         if (this.deps.evolverVersion)

package/dist/llm/server.js

@@ -5,8 +5,10 @@
 // host (other local users, container neighbors, postinstall scripts), hence the mandatory token.
 import { createServer } from 'node:http';
 import { timingSafeEqual } from 'node:crypto';
+import { util } from '@evomap/evolver-core';
 export const DEFAULT_LLM_PORT = 19821; // one above the mailbox IPC default — the two daemons co-exist
 const MAX_PORT_ATTEMPTS = 100;
+const MAX_EPHEMERAL_LLM_LISTEN_ATTEMPTS = 5;
 /** /v1/messages bodies legitimately reach tens of MiB (long contexts); the 1 MiB IPC-style cap would break
  * real clients. Still bounded — an unauthenticated local writer must not be able to balloon memory. */
 export const DEFAULT_LLM_MAX_BODY_BYTES = 32 * 1024 * 1024;
@@ -193,19 +195,35 @@ export class LlmProxyServer {
         const basePort = this.opts.port ?? Number(this.env['EVOLVER_LLM_PORT'] || DEFAULT_LLM_PORT);
         const server = createServer((req, res) => { void this.handle(req, res); });
         const tryListen = (port) => new Promise((resolve, reject) => {
-            server.once('error', (err) => {
+            const onError = (err) => {
                 if (err.code === 'EADDRINUSE')
                     resolve(false);
                 else
                     reject(err);
+            };
+            server.once('error', onError);
+            server.listen(port, host, () => {
+                server.removeListener('error', onError);
+                resolve(true);
             });
-            server.listen(port, host, () => resolve(true));
+        });
+        const closeListener = () => new Promise((resolve, reject) => {
+            server.close((err) => { if (err)
+                reject(err);
+            else
+                resolve(); });
         });
         let port = basePort;
-        for (let i = 0; i < MAX_PORT_ATTEMPTS; i++) {
+        const maxAttempts = basePort === 0 ? MAX_EPHEMERAL_LLM_LISTEN_ATTEMPTS : MAX_PORT_ATTEMPTS;
+        for (let i = 0; i < maxAttempts; i++) {
             if (await tryListen(port)) {
                 const addr = server.address();
-                this.actualPort = typeof addr === 'object' && addr ? addr.port : port;
+                const actualPort = typeof addr === 'object' && addr ? addr.port : port;
+                if (basePort === 0 && util.isFetchForbiddenPort(actualPort)) {
+                    await closeListener();
+                    continue;
+                }
+                this.actualPort = actualPort;
                 this.server = server;
                 const url = `http://${host}:${this.actualPort}`;
                 this.log.log?.(`[evolver-llm-proxy] listening on ${url}`);
@@ -215,6 +233,8 @@ export class LlmProxyServer {
                 break; // kernel-assigned can't collide; a failure here is real
             port++;
         }
+        if (basePort === 0)
+            throw new Error('llm_proxy_safe_port_unavailable');
         throw new Error(`LlmProxyServer: no free port after ${MAX_PORT_ATTEMPTS} attempts from ${basePort}`);
     }
     async stop() {

package/dist/llm/traceControl.js

@@ -1,7 +1,7 @@
 import { verify } from 'node:crypto';
 export const DEFAULT_TRACE_CONFIG_SIGNING_PUBLIC_KEY = [
     '-----BEGIN PUBLIC KEY-----',
-    'MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEA7kJvWUP3HC4FJPQtkh74',
+    'MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEA7kJvWUP3HC4FJPQtkh74', // gitleaks:allow -- public verification key, not a credential.
     'y75h9Rzc2NSZC9e4fiIWdax4iv+yWeMeIHGNsMr7YI8Ws7ck1BimJWt026gwRW8I',
     'c2A7h97oZQ0Z0zFcjEZ8FpYFSu++Yz/dGrARAV7uCQg289jvo89F5fWNdX2k+lTH',
     'hBoBm0G71vkiAYlbQEjq1xm1WzYf8CVXmbr+J1z+ydQf9jczcFL79u3eQZhIPs3R',

package/dist/llm/upstream.d.ts

@@ -49,6 +49,9 @@ export interface BedrockRuntimeFactory {
     createInvokeModelCommand(input: BedrockInvokeInput): unknown;
     createInvokeModelWithResponseStreamCommand(input: BedrockInvokeInput): unknown;
 }
+declare function warnDeprecatedOpenAICompatible(env: NodeJS.ProcessEnv): void;
+/** Test helper: reset once-warn latch (unit tests only). */
+declare function resetDeprecatedOpenAICompatibleWarning(): void;
 export declare function resolveOpenAIUpstreamUrl(env?: NodeJS.ProcessEnv): string;
 /** Resolve the upstream base URL. OpenAI-compatible routes never inherit the Anthropic-wide override. */
 export declare function resolveUpstreamUrl(env?: NodeJS.ProcessEnv, upstreamMode?: string): string;
@@ -65,4 +68,5 @@ export declare function makeAnthropicUpstream(opts?: AnthropicUpstreamOptions):
 export declare function makeOpenAIUpstream(opts?: ProviderUpstreamOptions): AnthropicProxy;
 export declare function makeGeminiUpstream(opts?: ProviderUpstreamOptions): AnthropicProxy;
 export declare function makeOllamaUpstream(opts?: ProviderUpstreamOptions): AnthropicProxy;
-export declare function makeVertexUpstream(opts?: ProviderUpstreamOptions): AnthropicProxy;
+export declare function makeVertexUpstream(opts?: ProviderUpstreamOptions): AnthropicProxy;
+export { warnDeprecatedOpenAICompatible, resetDeprecatedOpenAICompatibleWarning };