@nowcrew/daemon 0.6.18 → 0.6.20

package/dist/local-executor.js

@@ -2,9 +2,10 @@ import { createInterface } from "node:readline";
 import { readFile, rm, writeFile } from "node:fs/promises";
 import { delimiter, join } from "node:path";
 import { prepareWorkspace, rotateAgentSession, safeKey, } from "./workspace.js";
-import { CLAUDE_ADDITIONAL_DIRECTORY_INSTRUCTIONS_ENV, isClaudeAdditionalDirectoryInstructionsSupported, probeClaudeVersion, resolveOrderedUniqueClaudeDirectories, spawnClaude, } from "./runtimes/claude.js";
+import { CLAUDE_ADDITIONAL_DIRECTORY_INSTRUCTIONS_ENV, isClaudeAdditionalDirectoryInstructionsSupported, probeClaudeVersion, spawnClaude, } from "./runtimes/claude.js";
 import { spawnCodex } from "./runtimes/codex.js";
 import { DEEPSEEK_CODEX_MODEL, DEEPSEEK_CODEX_REASONING_LEVELS, materializeDeepSeekCodexHome, } from "./runtimes/codex-deepseek-config.js";
+import { materializeDefaultCodexHome } from "./runtimes/codex-home.js";
 import { spawnKimi, KIMI_EFFORT_LEVELS } from "./runtimes/kimi.js";
 import { applyDeepSeekHarnessMachineEnv, applyProviderEnv, providerFingerprint, } from "./provider-env.js";
 import { augmentedPath } from "./runtime-path.js";
@@ -20,7 +21,9 @@ import { awaitWithCancellation, RuntimeCancelledError, } from "./runtime-cancell
 import { isRuntimeReadyEvent, } from "./runtime-startup-gate.js";
 import { dslog } from "./slog.js";
 import { boundedDiagnosticJsonArray } from "./diagnostic-json.js";
+import { ProjectProjectionError, } from "./project-skills/reconciler.js";
 import { formatProjectSkillRuntimeWarning } from "./project-skills/runtime-warning.js";
+import { projectSkillRuntimeDirectories, redactProjectSkillRuntimeRootText, redactProjectSkillRuntimeRootValue, } from "./project-skills/runtime-launch.js";
 import { diffMemoryPruneNotes, evaluateMemoryPrunePostcondition, inspectMemoryPruneFilesWithinDeadline, parseMemoryPruneTraceId, } from "./memory-prune-diagnostics.js";
 import { createLocalMemoryTelemetry, logLocalMemoryContextPrepareFailure, logLocalMemoryDiagnosticsFailure, } from "./local-memory-telemetry.js";
 import { CodexStartupStageParser } from "./codex-startup-stage.js";
@@ -194,6 +197,19 @@ async function withKeyedLease(key, operation, cancellation) {
     }
 }
 export async function executeLocal(input, callbacks = {}, dependencies = {}) {
+    const versionedProjectSkills = input.projectSkills !== undefined
+        && !Array.isArray(input.projectSkills);
+    if (versionedProjectSkills && (input.runtime.name !== "codex" && input.runtime.name !== "claude")) {
+        throw new ProjectProjectionError("skill_projection_failed");
+    }
+    if (versionedProjectSkills && dependencies.projectSkills === undefined) {
+        throw new ProjectProjectionError("skill_projection_failed");
+    }
+    if (input.projectSkills !== undefined
+        && dependencies.projectSkills !== undefined
+        && dependencies.projectSkillLeaseSafeLaunchOwner === undefined) {
+        throw new ProjectProjectionError("skill_projection_failed");
+    }
     const stableProtocolRuntime = dependencies.launchRuntime !== undefined;
     const supportsNativeResume = input.runtime.name === "claude"
         || (stableProtocolRuntime && runtimeCapability(input.runtime.name).nativeResume);
@@ -257,6 +273,11 @@ async function executeLocalUnlocked(input, callbacks, dependencies) {
     let memoryPruneSharedWriteKey = null;
     let executionWorkspace = workspace;
     let localMemoryTelemetry = null;
+    const inheritedEnv = { ...process.env };
+    for (const key of Object.keys(inheritedEnv)) {
+        if (key.startsWith("CREW_AGENT_MEMORY_"))
+            delete inheritedEnv[key];
+    }
     try {
         if (isDeepSeekCodex && !providerConfig.providerApiKey) {
             throw new Error("DeepSeek API key is not configured for this Agent");
@@ -264,6 +285,11 @@ async function executeLocalUnlocked(input, callbacks, dependencies) {
         if (isDeepSeekCodex) {
             await awaitWithCancellation((dependencies.materializeDeepSeekCodexHome ?? materializeDeepSeekCodexHome)(workspace.homeDir), dependencies.cancellation);
         }
+        else if (runtime.name === "codex") {
+            const sourceCodexHome = inheritedEnv.CODEX_HOME
+                ?? (inheritedEnv.HOME === undefined ? undefined : join(inheritedEnv.HOME, ".codex"));
+            await awaitWithCancellation((dependencies.materializeDefaultCodexHome ?? materializeDefaultCodexHome)(workspace.homeDir, sourceCodexHome), dependencies.cancellation);
+        }
         const supportsNativeResume = runtime.name === "claude"
             || (dependencies.launchRuntime !== undefined && runtimeCapability(runtime.name).nativeResume);
         const storedCurrentPrior = input.session.enabled && supportsNativeResume
@@ -422,11 +448,6 @@ async function executeLocalUnlocked(input, callbacks, dependencies) {
             }
         }
         memoryPruneFailurePhase = "runtime_prepare";
-        const inheritedEnv = { ...process.env };
-        for (const key of Object.keys(inheritedEnv)) {
-            if (key.startsWith("CREW_AGENT_MEMORY_"))
-                delete inheritedEnv[key];
-        }
         const baseEnv = {
             ...inheritedEnv,
             ...sanitizeEnvVars(providerConfig.envVars),
@@ -479,7 +500,9 @@ async function executeLocalUnlocked(input, callbacks, dependencies) {
         }
         const runtimeLaunchAt = Date.now();
         memoryPruneFailurePhase = "runtime_launch";
-        const launchPreparedRuntime = async (abilityContext) => {
+        let activeProjectSkillRuntimeRoot;
+        const launchPreparedRuntime = async (runtimeRoot, abilityContext) => {
+            activeProjectSkillRuntimeRoot = runtimeRoot;
             const effectiveSystemPrompt = abilityContext === undefined
                 ? systemPrompt
                 : `${systemPrompt}\n\n${abilityContext.prompt}`;
@@ -515,31 +538,16 @@ async function executeLocalUnlocked(input, callbacks, dependencies) {
                     skill_count: abilityContext.skillCount,
                 });
             }
-            const codexSkillRoots = runtime.name === "codex" && input.projectContext !== undefined
-                ? [
-                    ...(input.projectSkills === undefined
-                        ? []
-                        : [join(workspace.dir, ".agents", "skills")]),
-                    ...(abilityContext?.skillRoot === undefined ? [] : [abilityContext.skillRoot]),
-                ]
-                : [];
-            const claudeAdditionalDirectories = runtime.name === "claude"
-                ? input.projectContext === undefined
-                    ? abilityContext?.skillRoot === undefined
-                        ? []
-                        : await resolveOrderedUniqueClaudeDirectories([
-                            join(workspace.dir, ".crew", "claude-skills"),
-                            workspace.dir,
-                            abilityContext.skillRoot,
-                        ])
-                    : await resolveOrderedUniqueClaudeDirectories([
-                        ...input.projectContext.secondary.map((project) => project.root),
-                        ...(input.projectSkills === undefined
-                            ? []
-                            : [join(workspace.dir, ".crew", "claude-skills")]),
-                        ...(abilityContext?.skillRoot === undefined ? [] : [abilityContext.skillRoot]),
-                    ], input.projectContext.primary === undefined ? [] : [input.projectContext.primary.root])
-                : [];
+            const { codexSkillRoots, claudeAdditionalDirectories } = await projectSkillRuntimeDirectories({
+                runtime: runtime.name,
+                ...(runtimeRoot === undefined ? {} : { runtimeRoot }),
+                agentRoot: workspace.dir,
+                projectSkillsPresent: input.projectSkills !== undefined,
+                ...(input.projectContext === undefined ? {} : { projectContext: input.projectContext }),
+                ...(abilityContext?.skillRoot === undefined
+                    ? {}
+                    : { abilitySkillRoot: abilityContext.skillRoot }),
+            });
             let runtimeEnv = childEnv;
             if (runtime.name === "claude"
                 && input.projectContext !== undefined
@@ -565,7 +573,10 @@ async function executeLocalUnlocked(input, callbacks, dependencies) {
                 runtime: runtime.name,
                 bin: runtime.name === "deepseek-harness" ? "dsh-acp-demo" : runtime.name,
                 cwd: input.projectContext?.primary?.root ?? executionWorkspace.runDir,
-                ...(input.projectSkills === undefined && input.abilityRelease === undefined ? {} : { agentRoot: workspace.dir }),
+                ...(runtimeRoot !== undefined
+                    || (input.projectSkills === undefined && input.abilityRelease === undefined)
+                    ? {}
+                    : { agentRoot: workspace.dir }),
                 systemPromptPath: workspace.systemPromptPath,
                 systemPrompt: effectiveSystemPrompt,
                 wakePrompt,
@@ -592,17 +603,22 @@ async function executeLocalUnlocked(input, callbacks, dependencies) {
             memoryPruneFailurePhase = "runtime_launch";
             return launchRuntime(launchRequest);
         };
-        const launchWithAbility = () => input.abilityRelease !== undefined && dependencies.abilityRelease !== undefined
-            ? dependencies.abilityRelease.prepareAndLaunch(input.launch.agentsRoot, input.handle, input.abilityRelease, launchPreparedRuntime)
-            : launchPreparedRuntime();
-        const child = input.projectSkills !== undefined && dependencies.projectSkills !== undefined
-            ? await (Array.isArray(input.projectSkills)
-                ? dependencies.projectSkills.prepareAndLaunch(input.launch.agentsRoot, input.handle, input.projectSkills, launchWithAbility)
-                : dependencies.projectSkills.prepareAndLaunch(input.launch.agentsRoot, input.handle, input.projectSkills, launchWithAbility, (warning) => callbacks.onConsole?.({
-                    stream: "system",
-                    text: formatProjectSkillRuntimeWarning(warning),
-                })))
-            : await launchWithAbility();
+        const launchWithAbility = (runtimeRoot) => input.abilityRelease !== undefined && dependencies.abilityRelease !== undefined
+            ? dependencies.abilityRelease.prepareAndLaunch(input.launch.agentsRoot, input.handle, input.abilityRelease, (abilityContext) => launchPreparedRuntime(runtimeRoot, abilityContext))
+            : launchPreparedRuntime(runtimeRoot);
+        let child;
+        if (input.projectSkills !== undefined && dependencies.projectSkills !== undefined) {
+            const launchOwner = dependencies.projectSkillLeaseSafeLaunchOwner;
+            if (launchOwner === undefined)
+                throw new ProjectProjectionError("skill_projection_failed");
+            child = await dependencies.projectSkills.prepareAndLaunch(input.launch.agentsRoot, input.executionId, input.handle, input.projectSkills, launchOwner.claim(launchWithAbility), (warning) => callbacks.onConsole?.({
+                stream: "system",
+                text: formatProjectSkillRuntimeWarning(warning),
+            }));
+        }
+        else {
+            child = await launchWithAbility();
+        }
         localMemoryTelemetry?.markRuntimeStarted();
         memoryPruneFailurePhase = "runtime_execution";
         if (child.cancel !== undefined) {
@@ -654,7 +670,8 @@ async function executeLocalUnlocked(input, callbacks, dependencies) {
                 usage = meta.usage;
             if (meta.model)
                 observedModel = meta.model;
-            for (const activity of normalizeEvent(event)) {
+            for (const rawActivity of normalizeEvent(event)) {
+                const activity = redactProjectSkillRuntimeRootValue(rawActivity, activeProjectSkillRuntimeRoot);
                 if (activity.kind === "sending")
                     sentViaCrew = true;
                 activities.push(activity);
@@ -662,18 +679,20 @@ async function executeLocalUnlocked(input, callbacks, dependencies) {
             }
             const extracted = extractFinalText(event);
             if (extracted) {
+                const safeExtracted = redactProjectSkillRuntimeRootText(extracted, activeProjectSkillRuntimeRoot);
                 const incremental = typeof event === "object" && event !== null
                     && "type" in event && (event.type === "kimi.acp.text_delta"
                     || event.type === "hermes.acp.text_delta"
                     || event.type === "deepseek-harness.acp.text_delta"
                     || event.type === "opencode.text_delta");
-                finalText = incremental ? `${finalText ?? ""}${extracted}` : extracted;
+                finalText = incremental ? `${finalText ?? ""}${safeExtracted}` : safeExtracted;
             }
             for (const text of decodeExternalOutputEvent(runtime.name, event, externalOutput)) {
-                callbacks.onExternalOutput?.(text);
+                callbacks.onExternalOutput?.(redactProjectSkillRuntimeRootText(text, activeProjectSkillRuntimeRoot));
+            }
+            for (const chunk of consoleFormatter.format(event)) {
+                callbacks.onConsole?.(redactProjectSkillRuntimeRootValue(chunk, activeProjectSkillRuntimeRoot));
             }
-            for (const chunk of consoleFormatter.format(event))
-                callbacks.onConsole?.(chunk);
         });
         let stderrTail = "";
         const codexStartupStageState = { last: null };
@@ -694,8 +713,8 @@ async function executeLocalUnlocked(input, callbacks, dependencies) {
             })
             : null;
         child.stderr.on("data", (data) => {
-            process.stderr.write(data);
-            const text = String(data);
+            const text = redactProjectSkillRuntimeRootText(String(data), activeProjectSkillRuntimeRoot);
+            process.stderr.write(text);
             stderrTail = (stderrTail + text).slice(-STDERR_TAIL_CAP);
             codexStartupStageParser?.push(text);
         });
@@ -755,7 +774,9 @@ async function executeLocalUnlocked(input, callbacks, dependencies) {
         memoryPruneRuntimeExitCode = exitCode;
         const errorTail = [
             stderrTail.trim(),
-            spawnError,
+            spawnError === undefined
+                ? undefined
+                : redactProjectSkillRuntimeRootText(spawnError, activeProjectSkillRuntimeRoot),
             terminationSignal ? `terminated by ${terminationSignal}` : undefined,
         ].filter(Boolean).join(" ").trim();
         const finish = exitActivity(runtime.name, exitCode, errorTail);

package/dist/machine-info.js

@@ -61,7 +61,9 @@ export const daemonCapabilities = (runtimePlatform = process.platform, readiness
 export const daemonCapabilityBindings = (runtimePlatform = process.platform, injectedCapabilities) => {
     const snapshot = injectedCapabilities === undefined
         ? daemonCapabilities(runtimePlatform)
-        : Object.freeze([...injectedCapabilities]);
+        : (Object.isFrozen(injectedCapabilities)
+            ? injectedCapabilities
+            : Object.freeze([...injectedCapabilities]));
     return Object.freeze({
         controlPlaneUrl: snapshot,
         machineHello: snapshot,
@@ -169,6 +171,10 @@ export async function collectMachineHello(agentsRoot, executionLimits, runtimePl
     const executionRuntimes = backend.supported
         ? await (dependencies.detectExecutable ?? detectExecutionRuntimes)(runtimes)
         : [];
+    const baseCapabilities = dependencies.capabilities ?? daemonCapabilities(runtimePlatform);
+    const capabilities = additionalCapabilities.length === 0 && Object.isFrozen(baseCapabilities)
+        ? baseCapabilities
+        : Object.freeze([...baseCapabilities, ...additionalCapabilities]);
     return {
         type: "machine:hello",
         hostname: hostname(),
@@ -176,10 +182,7 @@ export async function collectMachineHello(agentsRoot, executionLimits, runtimePl
         daemonVersion: daemonVersion(),
         runtimes,
         executionRuntimes,
-        capabilities: Object.freeze([
-            ...(dependencies.capabilities ?? daemonCapabilities(runtimePlatform)),
-            ...additionalCapabilities,
-        ]),
+        capabilities,
         ...(dependencies.profileName === undefined ? {} : {
             layoutVersion: 1,
             profileName: dependencies.profileName,

package/dist/project-skills/capability.js

@@ -0,0 +1,109 @@
+import { PROJECT_SKILLS_CAPABILITY, PROJECT_SKILL_PROJECTION_V2_CAPABILITY, } from "./types.js";
+export function projectSkillV2RolloutReady(platform, readiness) {
+    const platformReady = platform === "darwin"
+        || platform === "linux"
+        || (platform === "win32" && readiness.nativeWindowsSmokePassed);
+    return platformReady
+        && readiness.runtimeRootStorePrimitiveReady
+        && readiness.runtimeRootStoreRecoveryReady
+        && readiness.leaseRecoveryReady
+        && readiness.controllerReady
+        && readiness.executionHandlerReady
+        && readiness.codexAdapterReady
+        && readiness.claudeAdapterReady;
+}
+export function effectiveProjectSkillCapabilities(capabilities, projectSkillsReady, projectSkillV2Ready) {
+    const projectSkillCapabilitiesReady = projectSkillsReady && projectSkillV2Ready;
+    if (!projectSkillCapabilitiesReady
+        && !capabilities.includes(PROJECT_SKILLS_CAPABILITY)
+        && !capabilities.includes(PROJECT_SKILL_PROJECTION_V2_CAPABILITY)
+        && Object.isFrozen(capabilities))
+        return capabilities;
+    const filtered = capabilities.filter((capability) => capability !== PROJECT_SKILL_PROJECTION_V2_CAPABILITY
+        && (projectSkillCapabilitiesReady || capability !== PROJECT_SKILLS_CAPABILITY));
+    if (!projectSkillCapabilitiesReady || !filtered.includes(PROJECT_SKILLS_CAPABILITY)) {
+        return Object.freeze(filtered);
+    }
+    const v1Index = filtered.indexOf(PROJECT_SKILLS_CAPABILITY);
+    return Object.freeze([
+        ...filtered.slice(0, v1Index + 1),
+        PROJECT_SKILL_PROJECTION_V2_CAPABILITY,
+        ...filtered.slice(v1Index + 1),
+    ]);
+}
+export function withProjectSkillCapabilityStatus(value, status) {
+    return {
+        ...value,
+        projectSkillsStatus: status,
+        capabilities: status === "ready"
+            ? value.capabilities
+            : effectiveProjectSkillCapabilities(value.capabilities, false, false),
+    };
+}
+const settleReadinessGate = async (operation) => {
+    try {
+        return await operation() === true;
+    }
+    catch {
+        return false;
+    }
+};
+export async function createProjectSkillConnectionCapabilitySnapshot(input) {
+    const runtimeRootStorePrimitiveReady = await settleReadinessGate(input.probeRuntimeRootStorePrimitive);
+    const controllerReady = await settleReadinessGate(input.initializeController);
+    const recoveryReady = await settleReadinessGate(input.recoverRuntimeRootsAndLeases);
+    const readiness = Object.freeze({
+        runtimeRootStorePrimitiveReady,
+        runtimeRootStoreRecoveryReady: recoveryReady,
+        leaseRecoveryReady: recoveryReady,
+        controllerReady,
+        executionHandlerReady: true,
+        codexAdapterReady: true,
+        claudeAdapterReady: true,
+        nativeWindowsSmokePassed: false,
+    });
+    const projectSkillsReady = projectSkillV2RolloutReady(input.platform, readiness);
+    return Object.freeze({
+        capabilities: effectiveProjectSkillCapabilities(input.baseCapabilities, projectSkillsReady, projectSkillsReady),
+        projectSkillsReady,
+        readiness,
+    });
+}
+export async function prepareProjectSkillConnectionCapabilities(input) {
+    const snapshot = await createProjectSkillConnectionCapabilitySnapshot({
+        ...input,
+        baseCapabilities: [...input.baseCapabilities, ...await input.additionalCapabilities()],
+    });
+    input.applyReadiness(snapshot.projectSkillsReady);
+    return snapshot.capabilities;
+}
+export function createProjectSkillControllerReadiness(input) {
+    let status = "initializing";
+    let initialization = null;
+    const ensure = () => {
+        if (status === "ready")
+            return Promise.resolve(true);
+        if (initialization !== null)
+            return initialization;
+        status = "initializing";
+        const attempt = input.initialize().then(() => {
+            status = "ready";
+            return true;
+        }, (error) => {
+            status = "unavailable";
+            input.onUnavailable(error);
+            return false;
+        }).finally(() => {
+            if (initialization === attempt)
+                initialization = null;
+            input.onSettled();
+        });
+        initialization = attempt;
+        return attempt;
+    };
+    return Object.freeze({
+        status: () => status,
+        ensure,
+        applyPreflight: (ready) => { status = ready ? "ready" : "unavailable"; },
+    });
+}

package/dist/project-skills/controller-convergence.js

@@ -0,0 +1,57 @@
+import { ProjectProjectionError, } from "./reconciler.js";
+export const MAX_REMEMBERED_PROJECT_SKILL_AGENTS = 64;
+const compareBinary = (left, right) => {
+    if (left < right)
+        return -1;
+    if (left > right)
+        return 1;
+    return 0;
+};
+const copySnapshot = (snapshot) => Object.freeze({
+    bindings: Object.freeze(snapshot.bindings.map((binding) => Object.freeze({ ...binding }))),
+    generation: snapshot.generation,
+});
+export function createProjectSkillSnapshotEpoch(maxEntries = MAX_REMEMBERED_PROJECT_SKILL_AGENTS) {
+    if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
+        throw new ProjectProjectionError("skill_projection_failed");
+    }
+    const snapshots = new Map();
+    return Object.freeze({
+        begin() {
+            snapshots.clear();
+        },
+        remember(handle, snapshot) {
+            const previous = snapshots.get(handle);
+            if (previous !== undefined && snapshot.generation < previous.generation)
+                return;
+            if (previous === undefined && snapshots.size >= maxEntries) {
+                throw new ProjectProjectionError("skill_projection_failed");
+            }
+            snapshots.set(handle, copySnapshot(snapshot));
+        },
+        forget(handle) {
+            snapshots.delete(handle);
+        },
+        entries() {
+            return Object.freeze([...snapshots.entries()]
+                .sort(([left], [right]) => compareBinary(left, right))
+                .map(([handle, snapshot]) => Object.freeze([handle, copySnapshot(snapshot)])));
+        },
+    });
+}
+const stableErrorCode = (reason) => reason?.code === "skill_projection_snapshot_corrupt"
+    ? "skill_projection_snapshot_corrupt"
+    : "skill_projection_failed";
+export function toPathPrivateConvergenceResults(entries, results) {
+    return Object.freeze(entries.map(([handle], index) => {
+        const result = results[index];
+        if (result?.status === "fulfilled") {
+            return Object.freeze({ handle, status: "fulfilled" });
+        }
+        return Object.freeze({
+            handle,
+            status: "rejected",
+            errorCode: stableErrorCode(result?.reason),
+        });
+    }));
+}

package/dist/project-skills/controller.js

@@ -5,6 +5,7 @@ import { isProjectId, isProjectSkillName, compareProjectSkillRefs, MAX_AGENT_PRO
 import { ProjectProjectionError, } from "./reconciler.js";
 import { AgentHandleSchema } from "../execution-protocol.js";
 import { createPromiseTail } from "../promise-tail.js";
+import { createProjectSkillSnapshotEpoch, MAX_REMEMBERED_PROJECT_SKILL_AGENTS, toPathPrivateConvergenceResults, } from "./controller-convergence.js";
 const ProjectIdSchema = z.string().refine(isProjectId);
 const AgentSkillsSyncSchema = z.object({
     type: z.literal("agent:skills:sync"),
@@ -56,6 +57,13 @@ class ProjectScanTimeoutError extends Error {
         this.name = "ProjectScanTimeoutError";
     }
 }
+class ProjectSkillStaleEpochError extends Error {
+    code = "skill_projection_stale";
+    constructor() {
+        super("skill_projection_stale");
+        this.name = "ProjectSkillStaleEpochError";
+    }
+}
 const withinScanDeadline = async (operation, timeoutMs) => {
     let timer;
     try {
@@ -79,7 +87,12 @@ export function createProjectSkillsController(deps) {
     let initializationState = "idle";
     const scan = deps.scan ?? scanProjects;
     const scanTimeoutMs = deps.scanTimeoutMs ?? DEFAULT_PROJECT_SCAN_TIMEOUT_MS;
-    const v2Snapshots = new Map();
+    const snapshotEpoch = createProjectSkillSnapshotEpoch();
+    let connectionEpochIdentity = Object.freeze({});
+    const assertCurrentEpoch = (token) => {
+        if (token !== undefined && token !== connectionEpochIdentity)
+            throw new ProjectSkillStaleEpochError();
+    };
     const scanCurrent = async (deferredProjectId) => withinScanDeadline(scan(await deps.registry.list(), undefined, [
         ...scanned
             .map((project) => project.inventory.projectId)
@@ -97,17 +110,25 @@ export function createProjectSkillsController(deps) {
         }));
     };
     const enqueue = (operation) => operationTail.enqueue(operation);
-    const applyV2Snapshot = async (handle, snapshot) => {
+    const applyV2Snapshot = async (handle, snapshot, epochToken) => {
         if (deps.ensureSnapshot === undefined)
             throw new ProjectProjectionError("skill_projection_failed");
-        await deps.ensureSnapshot(handle, snapshot);
-        const previous = v2Snapshots.get(handle);
-        if (previous === undefined || snapshot.generation >= previous.generation) {
-            v2Snapshots.set(handle, Object.freeze({
-                bindings: Object.freeze(snapshot.bindings.map((binding) => Object.freeze({ ...binding }))),
-                generation: snapshot.generation,
-            }));
+        assertCurrentEpoch(epochToken);
+        const acceptedEpochIdentity = connectionEpochIdentity;
+        const rememberedEntries = snapshotEpoch.entries();
+        const firstAcceptedInEpoch = !rememberedEntries.some(([candidate]) => candidate === handle);
+        if (firstAcceptedInEpoch && rememberedEntries.length >= MAX_REMEMBERED_PROJECT_SKILL_AGENTS) {
+            throw new ProjectProjectionError("skill_projection_failed");
+        }
+        if (firstAcceptedInEpoch) {
+            await deps.ensureSnapshot(handle, snapshot, Object.freeze({ refreshCopyProjection: true }));
+        }
+        else {
+            await deps.ensureSnapshot(handle, snapshot);
         }
+        assertCurrentEpoch(epochToken);
+        if (acceptedEpochIdentity === connectionEpochIdentity)
+            snapshotEpoch.remember(handle, snapshot);
         return Object.freeze(projectSkillResolutionRecords(snapshot.bindings, scanned)
             .map((record) => Object.freeze({
             projectId: record.projectId,
@@ -115,15 +136,24 @@ export function createProjectSkillsController(deps) {
             status: record.mode === "resolved" ? "linked" : "unavailable",
         })));
     };
-    const reapplyV2Snapshots = async () => {
-        if (deps.ensureSnapshot === undefined) {
-            if (v2Snapshots.size > 0)
-                throw new ProjectProjectionError("skill_projection_failed");
+    const convergeV2Snapshots = async (refreshCopyProjection, epochToken) => {
+        assertCurrentEpoch(epochToken);
+        const acceptedEpochIdentity = connectionEpochIdentity;
+        const entries = snapshotEpoch.entries();
+        if (deps.ensureSnapshot === undefined || entries.length === 0)
+            return;
+        const results = await Promise.allSettled(entries.map(([handle, snapshot]) => refreshCopyProjection
+            ? deps.ensureSnapshot(handle, snapshot, Object.freeze({ refreshCopyProjection: true }))
+            : deps.ensureSnapshot(handle, snapshot)));
+        if (acceptedEpochIdentity !== connectionEpochIdentity) {
+            if (epochToken !== undefined)
+                throw new ProjectSkillStaleEpochError();
             return;
         }
-        for (const [handle, snapshot] of [...v2Snapshots.entries()].sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)) {
-            await deps.ensureSnapshot(handle, snapshot);
+        try {
+            deps.onConvergence?.(toPathPrivateConvergenceResults(entries, results));
         }
+        catch { /* convergence diagnostics must not change a successful inventory mutation */ }
     };
     const initialize = () => {
         if (initializationState === "ready" && initialization !== null)
@@ -141,24 +171,40 @@ export function createProjectSkillsController(deps) {
         return attempt;
     };
     return {
+        beginConnectionEpoch: () => {
+            connectionEpochIdentity = Object.freeze({});
+            snapshotEpoch.begin();
+            return connectionEpochIdentity;
+        },
         initialize,
         publishCurrent: () => enqueue(publishCurrent),
         scannedProjects: () => scanned,
-        async handle(input) {
+        async handle(input, epochToken) {
             const parsed = ProjectCommandSchema.safeParse(input);
             if (!parsed.success)
                 return { ok: false, error: "invalid_project_command" };
+            try {
+                assertCurrentEpoch(epochToken);
+            }
+            catch (error) {
+                return { ok: false, error: error.code };
+            }
             if (parsed.data.type === "agent:skills:sync") {
                 try {
                     await initialize();
+                    assertCurrentEpoch(epochToken);
                 }
                 catch {
+                    if (epochToken !== undefined && epochToken !== connectionEpochIdentity) {
+                        return { ok: false, error: "skill_projection_stale" };
+                    }
                     return { ok: false, error: "project_skills_unavailable" };
                 }
             }
             return enqueue(async () => {
                 const command = parsed.data;
                 try {
+                    assertCurrentEpoch(epochToken);
                     if (command.type === "agent:skills:sync") {
                         if (command.generation !== undefined) {
                             const snapshot = Object.freeze({
@@ -167,13 +213,14 @@ export function createProjectSkillsController(deps) {
                             });
                             return {
                                 ok: true,
-                                data: { bindings: await applyV2Snapshot(command.handle, snapshot) },
+                                data: { bindings: await applyV2Snapshot(command.handle, snapshot, epochToken) },
                             };
                         }
                         if (deps.reconcile === undefined)
                             return { ok: false, error: "skill_projection_failed" };
                         const bindings = await deps.reconcile(command.handle, command.bindings);
-                        v2Snapshots.delete(command.handle);
+                        assertCurrentEpoch(epochToken);
+                        snapshotEpoch.forget(command.handle);
                         return {
                             ok: true,
                             data: { bindings },
@@ -182,8 +229,11 @@ export function createProjectSkillsController(deps) {
                     if (command.type === "project:add") {
                         const existed = (await deps.registry.list())
                             .some((project) => project.projectId === command.projectId);
+                        assertCurrentEpoch(epochToken);
                         await deps.registry.add(command.projectId, command.root);
+                        assertCurrentEpoch(epochToken);
                         const next = await scanCurrent();
+                        assertCurrentEpoch(epochToken);
                         const added = next.find((project) => project.inventory.projectId === command.projectId);
                         if (!existed && added?.inventory.errorCode === "machine_project_skill_limit_exceeded") {
                             await deps.registry.remove(command.projectId);
@@ -193,9 +243,11 @@ export function createProjectSkillsController(deps) {
                     }
                     else if (command.type === "project:remove") {
                         await deps.registry.remove(command.projectId);
+                        assertCurrentEpoch(epochToken);
                     }
                     else {
                         const projects = await deps.registry.list();
+                        assertCurrentEpoch(epochToken);
                         if (!projects.some((project) => project.projectId === command.projectId)) {
                             return { ok: false, error: "project_not_found" };
                         }
@@ -203,8 +255,10 @@ export function createProjectSkillsController(deps) {
                     if (command.type !== "project:add") {
                         await refresh(command.type === "project:rescan" ? command.projectId : undefined);
                     }
-                    await reapplyV2Snapshots();
+                    assertCurrentEpoch(epochToken);
                     await publishCurrent();
+                    assertCurrentEpoch(epochToken);
+                    await convergeV2Snapshots(command.type === "project:rescan", epochToken);
                     return { ok: true, data: { projectId: command.projectId } };
                 }
                 catch (error) {
@@ -214,11 +268,13 @@ export function createProjectSkillsController(deps) {
                             ? error.code
                             : error.code === "skill_name_conflict"
                                 ? "skill_name_conflict"
-                                : error.code === "skill_projection_failed"
-                                    ? "skill_projection_failed"
-                                    : error.code === "skill_projection_snapshot_corrupt"
-                                        ? "skill_projection_snapshot_corrupt"
-                                        : "project_operation_failed",
+                                : error.code === "skill_projection_stale"
+                                    ? "skill_projection_stale"
+                                    : error.code === "skill_projection_failed"
+                                        ? "skill_projection_failed"
+                                        : error.code === "skill_projection_snapshot_corrupt"
+                                            ? "skill_projection_snapshot_corrupt"
+                                            : "project_operation_failed",
                     };
                 }
             });