@nowcrew/daemon 0.6.87-beta.2 → 0.6.87-beta.3

package/dist/execution-runner.js

@@ -25,6 +25,7 @@ import { PROJECT_WORKSPACES_CAPABILITY } from "./machine-info.js";
 import { PROJECT_SKILL_PROJECTION_V2_CAPABILITY } from "./project-skills/types.js";
 import { dslog } from "./slog.js";
 import { identityRosterPromptFacts } from "./identity-roster-telemetry.js";
+import { renderLocalMemoryV2WriteGuard } from "./local-memory/runtime.js";
 export { supervisorLaunch } from "./supervised-runtime.js";
 const MAX_LOCAL_EXECUTION_ATTEMPTS = 3;
 const ACTIVITY_KIND = {
@@ -828,7 +829,8 @@ export async function runExecution(config, input, dependencies) {
         const baseSystemPromptBudget = spec.agent.abilityRelease === undefined
             ? systemPromptBudget
             : Math.max(0, Math.min(systemPromptBudget, Math.max(32 * 1024, systemPromptBudget - 168 * 1024)));
-        const systemPromptWithLocalFacts = withLocalExecutionFacts(spec.instructions.systemPrompt, baseSystemPromptBudget, {
+        const localMemoryV2Enabled = config.localMemoryV2Handles?.has(spec.agent.handle) === true;
+        const systemPromptWithLocalFacts = withLocalExecutionFacts(`${spec.instructions.systemPrompt}${localMemoryV2Enabled ? renderLocalMemoryV2WriteGuard() : ""}`, baseSystemPromptBudget, {
             ...(selfTraining ? { isolateLocalMemory: true } : {}),
             collaborationTools: config.codexCollaborationTools && spec.runtime.name === "codex",
         });
@@ -887,7 +889,7 @@ export async function runExecution(config, input, dependencies) {
                 maxTurns: config.sessionMaxTurns,
             },
             ...(selfTraining ? { maintenancePurpose: "self_training" } : {}),
-            localMemoryV2Enabled: config.localMemoryV2Handles?.has(spec.agent.handle) === true,
+            localMemoryV2Enabled,
         };
         const result = await Promise.race([
             execute(localInput, callbacks, localDependencies),

package/dist/local-executor.js

@@ -37,6 +37,7 @@ import { formatRuntimeStartupError } from "./runtime-startup-error.js";
 import { machinePackageManagerEnv, packageManagerEnvFacts } from "./package-manager-env.js";
 import { sanitizeEnvVars } from "./runtime-env.js";
 import { commitLocalMemoryResultAfterExit, initializeLocalMemoryV2ForWorkspace, isLocalMemoryV2Eligible, localMemoryResultPath as makeLocalMemoryResultPath, renderLocalMemoryResultInstructions, } from "./local-memory/runtime.js";
+import { renderPendingMemoryContext, searchPendingMemoryCandidates, } from "./local-memory/pending.js";
 export class RuntimeRunningCallbackTimeoutError extends Error {
     constructor(runtime, timeoutMs) {
         super(`${runtime} runtime-running callback timed out after ${timeoutMs}ms`);
@@ -381,6 +382,26 @@ async function executeLocalUnlocked(input, callbacks, dependencies) {
         }
         const attachmentPlan = routeRuntimeAttachments(runtime.name, materialized?.attachments ?? []);
         const wakePrompt = `${resolvePrompt(input.wakePrompt, promptContext)}${attachmentPlan.promptSuffix}`;
+        let pendingMemoryContext = "";
+        if (input.localMemoryV2Enabled === true) {
+            try {
+                const pendingCandidates = await searchPendingMemoryCandidates({
+                    agentDir: executionWorkspace.dir,
+                    query: wakePrompt,
+                    limit: 5,
+                });
+                pendingMemoryContext = renderPendingMemoryContext(pendingCandidates);
+            }
+            catch (error) {
+                dslog("local_memory.pending_recall_failed", "本地归档记忆召回失败", {
+                    level: "WARN",
+                    execution_id: input.executionId,
+                    agent_handle: input.handle,
+                    error_name: error instanceof Error ? error.name : "unknown",
+                    error_code: error?.code,
+                });
+            }
+        }
         memoryPruneTraceId = parseMemoryPruneTraceId(wakePrompt);
         if (input.localMemoryV2Enabled === true && memoryPruneTraceId !== null
             && isLocalMemoryV2Eligible({
@@ -392,14 +413,21 @@ async function executeLocalUnlocked(input, callbacks, dependencies) {
             })) {
             localMemoryResultPath = makeLocalMemoryResultPath(executionWorkspace.runDir, input.executionId);
         }
-        const baseSystemPrompt = resolvePrompt(input.systemPrompt, promptContext);
+        const promptWithoutPending = resolvePrompt(input.systemPrompt, promptContext);
+        let baseSystemPrompt = `${promptWithoutPending}${pendingMemoryContext}`;
         const structuredMemoryInstructions = localMemoryResultPath === null
             ? null
             : renderLocalMemoryResultInstructions(localMemoryResultPath);
-        const structuredPromptFits = structuredMemoryInstructions === null
+        const fitsPromptBudget = (prompt) => structuredMemoryInstructions === null
             || input.maxSystemPromptBytes === undefined
-            || Buffer.byteLength(baseSystemPrompt, "utf8") + Buffer.byteLength(structuredMemoryInstructions, "utf8")
+            || Buffer.byteLength(prompt, "utf8") + Buffer.byteLength(structuredMemoryInstructions, "utf8")
                 <= input.maxSystemPromptBytes;
+        // The structured prune contract is mandatory for V2. Drop optional archived
+        // recall before dropping the daemon result file when the prompt budget is tight.
+        if (!fitsPromptBudget(baseSystemPrompt) && pendingMemoryContext !== "") {
+            baseSystemPrompt = promptWithoutPending;
+        }
+        const structuredPromptFits = fitsPromptBudget(baseSystemPrompt);
         if (!structuredPromptFits)
             localMemoryResultPath = null;
         const systemPrompt = localMemoryResultPath === null

package/dist/local-memory/pending.js

@@ -2,6 +2,8 @@ import { randomUUID } from "node:crypto";
 import { lstat, mkdir, readdir, realpath, rename, rm, writeFile, readFile } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { z } from "zod";
+export const LOCAL_MEMORY_PENDING_SCAN_FILE_CAP = 128;
+export const LOCAL_MEMORY_PENDING_SCAN_BYTE_CAP = 1_000_000;
 const CandidateSchema = z.object({
     operation: z.enum(["create", "update", "supersede"]),
     memoryId: z.string().nullable(),
@@ -59,6 +61,44 @@ async function pendingDirectory(agentDir) {
     }
     return directory;
 }
+async function existingPendingDirectory(agentDir) {
+    const agentRoot = await realpath(agentDir);
+    const memoryRoot = resolve(agentRoot, ".crew", "memory");
+    let memoryStat;
+    try {
+        memoryStat = await lstat(memoryRoot);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    if (!memoryStat.isDirectory() || memoryStat.isSymbolicLink()) {
+        throw new Error("local_memory_pending_path_invalid");
+    }
+    const resolvedMemoryRoot = await realpath(memoryRoot);
+    if (resolvedMemoryRoot !== memoryRoot || !within(agentRoot, resolvedMemoryRoot)) {
+        throw new Error("local_memory_pending_path_invalid");
+    }
+    const directory = join(memoryRoot, "pending");
+    let stat;
+    try {
+        stat = await lstat(directory);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new Error("local_memory_pending_path_invalid");
+    }
+    const resolvedDirectory = await realpath(directory);
+    if (resolvedDirectory !== directory || !within(agentRoot, resolvedDirectory)) {
+        throw new Error("local_memory_pending_path_invalid");
+    }
+    return directory;
+}
 async function assertRegularFile(path) {
     try {
         const stat = await lstat(path);
@@ -91,15 +131,40 @@ export async function persistPendingMemoryCandidate(input) {
     await atomicWrite(target, `${JSON.stringify(parsed.data, null, 2)}\n`);
     return target;
 }
+export async function removePendingMemoryCandidate(input) {
+    const directory = await existingPendingDirectory(input.agentDir);
+    if (directory === null)
+        return;
+    const target = join(directory, `${input.pendingId}.json`);
+    await assertRegularFile(target);
+    await rm(target, { force: true });
+}
 export async function readPendingMemoryCandidates(input) {
-    const directory = await pendingDirectory(input.agentDir);
+    const directory = await existingPendingDirectory(input.agentDir);
+    if (directory === null)
+        return [];
     const names = (await readdir(directory)).filter((name) => name.endsWith(".json")).sort();
+    const maxFiles = Math.max(0, input.maxFiles ?? LOCAL_MEMORY_PENDING_SCAN_FILE_CAP);
+    const maxBytes = Math.max(0, input.maxBytes ?? LOCAL_MEMORY_PENDING_SCAN_BYTE_CAP);
     const result = [];
+    let scannedBytes = 0;
     for (const name of names) {
+        if (result.length >= maxFiles || scannedBytes >= maxBytes)
+            break;
         const path = join(directory, name);
         try {
             await assertRegularFile(path);
-            const parsed = PendingSchema.safeParse(JSON.parse(await readFile(path, "utf8")));
+            const stat = await lstat(path);
+            if (!stat.isFile() || stat.isSymbolicLink())
+                throw new Error("local_memory_pending_path_invalid");
+            if (scannedBytes + stat.size > maxBytes)
+                break;
+            const raw = await readFile(path, "utf8");
+            const size = Buffer.byteLength(raw, "utf8");
+            if (scannedBytes + size > maxBytes)
+                break;
+            scannedBytes += size;
+            const parsed = PendingSchema.safeParse(JSON.parse(raw));
             if (parsed.success && `${parsed.data.pendingId}.json` === name)
                 result.push(parsed.data);
         }
@@ -109,3 +174,72 @@ export async function readPendingMemoryCandidates(input) {
     }
     return result;
 }
+function normalize(value) {
+    return value.normalize("NFKC").toLocaleLowerCase().replace(/\s+/gu, " ").trim();
+}
+function priorityRank(priority) {
+    return priority === "high" ? 0 : priority === "medium" ? 1 : 2;
+}
+function candidateText(candidate) {
+    return [
+        candidate.candidate.title,
+        candidate.candidate.summary,
+        ...candidate.candidate.triggers,
+        candidate.candidate.detailCategory,
+        candidate.candidate.detailBody,
+    ].join("\n");
+}
+function recallScore(candidate, query) {
+    const normalizedQuery = normalize(query);
+    if (normalizedQuery === "")
+        return 1;
+    const text = normalize(candidateText(candidate));
+    if (text.includes(normalizedQuery))
+        return 100;
+    const terms = normalizedQuery.split(/[\s,，、。！？；：:()[\]{}"'`]+/u).filter((term) => term.length > 0);
+    return terms.reduce((score, term) => score + (text.includes(term) ? 1 : 0), 0);
+}
+export async function searchPendingMemoryCandidates(input) {
+    const candidates = await readPendingMemoryCandidates({ agentDir: input.agentDir });
+    const limit = Math.max(0, input.limit ?? 5);
+    if (limit === 0)
+        return [];
+    return candidates
+        .map((candidate) => ({ candidate, score: recallScore(candidate, input.query) }))
+        .filter((item) => normalize(input.query) === "" || item.score > 0)
+        .sort((left, right) => right.score - left.score
+        || priorityRank(left.candidate.candidate.priority) - priorityRank(right.candidate.candidate.priority)
+        || right.candidate.createdAt.localeCompare(left.candidate.createdAt)
+        || left.candidate.pendingId.localeCompare(right.candidate.pendingId))
+        .slice(0, limit)
+        .map((item) => item.candidate);
+}
+function truncateCodePoints(value, maxCodePoints) {
+    return Array.from(value).slice(0, Math.max(0, maxCodePoints)).join("");
+}
+export function renderPendingMemoryContext(candidates, maxCodePoints = 2_000) {
+    if (candidates.length === 0 || maxCodePoints <= 0)
+        return "";
+    const header = `\n\n## Archived memory candidates (daemon-managed)\n这些记忆已持久化，但尚未进入常驻热索引；只在当前请求相关时参考，必要时再由 memory-prune 提升。\n`;
+    let remaining = maxCodePoints - Array.from(header).length;
+    if (remaining <= 0)
+        return truncateCodePoints(header, maxCodePoints);
+    const sections = [];
+    for (const item of candidates) {
+        const change = item.candidate;
+        const prefix = `\n### ${change.title}\n`
+            + `- pending_file: .crew/memory/pending/${item.pendingId}.json\n`
+            + `- summary: ${change.summary}\n`
+            + `- triggers: ${change.triggers.join(", ")}\n`
+            + "- detail: ";
+        const prefixLength = Array.from(prefix).length;
+        if (prefixLength + 1 > remaining)
+            break;
+        const detail = truncateCodePoints(change.detailBody, remaining - prefixLength - 1);
+        const section = `${prefix}${detail}\n`;
+        const length = Array.from(section).length;
+        sections.push(section);
+        remaining -= length;
+    }
+    return `${header}${sections.join("")}`;
+}

package/dist/local-memory/runtime.js

@@ -57,9 +57,16 @@ ${resultPath}
 JSON 顶层必须包含：
 {"schemaVersion":1,"purpose":"memory_prune","baseCatalogRevision":0,"outcome":"no_change","changes":[],"statusChanges":[]}
 每个 changes 项使用 operation=create|update|supersede、title、kind、summary、triggers、priority、detailCategory、detailBody、reviewAfter；create 的 memoryId/baseRevision/supersedesMemoryId 必须为 null，update/supersede 按现有索引填写版本和 id。
-只提交可复用、与本次任务明确相关的少量候选；不要写入凭证、token、隐私或内部控制标记。daemon 会校验、去重、限制 MEMORY.md 大小，超出索引容量的候选会保存在 pending 中等待后续治理。
+只提交可复用、与本次任务明确相关的少量候选；不要写入凭证、token、隐私或内部控制标记。daemon 会校验、去重、限制 MEMORY.md 大小，超出索引容量的候选会保存在 pending 归档中；后续相关任务会按需召回，索引腾出空间后可自动提升。
 `;
 }
+/** Prevent ordinary V2 turns from racing the daemon-managed memory writer. */
+export function renderLocalMemoryV2WriteGuard() {
+    return `
+
+## V2 shared memory write safety
+本节覆盖前文关于普通任务直接更新共享记忆的例外规则。本 Agent 已启用结构化本地记忆 V2。普通任务不得直接编辑共享的 $CREW_HOME/MEMORY.md 或 $CREW_HOME/notes/ 文件；即使用户明确要求记住内容，也只把候选、用户授权和分类理由记录到本任务的 $CREW_TASK_LOG，留给任务结束后的 memory-prune 结构化收尾应用。只有 memory-prune 收尾提示明确要求写入 daemon 提供的 result 文件时，才按该协议提交候选。`;
+}
 export async function commitLocalMemoryResultAfterExit(input) {
     if (input.exitCode !== 0)
         return { status: "skipped" };

package/dist/local-memory/write.js

@@ -4,7 +4,7 @@ import { dirname, join, relative, resolve, sep } from "node:path";
 import { z } from "zod";
 import { containsLikelySecret } from "../agent-memory/policy.js";
 import { LOCAL_MEMORY_INDEX_CODE_POINT_CAP, LOCAL_MEMORY_INDEX_ENTRY_CAP, LOCAL_MEMORY_TOTAL_CODE_POINT_CAP, renderLocalMemoryIndexCard, selectLocalMemoryIndexEntries, } from "./index-budget.js";
-import { persistPendingMemoryCandidate } from "./pending.js";
+import { persistPendingMemoryCandidate, readPendingMemoryCandidates, removePendingMemoryCandidate, } from "./pending.js";
 const CategorySchema = z.enum([
     "preferences", "project-rules", "testing", "debugging", "git", "incidents", "lessons",
 ]);
@@ -228,6 +228,47 @@ function normalize(value) {
 function activeOrPinnedIds(entries) {
     return new Set(entries.filter((entry) => entry.status === "active" || entry.status === "pinned").map((entry) => entry.id));
 }
+function pinnedIds(entries) {
+    return new Set(entries.filter((entry) => entry.status === "pinned").map((entry) => entry.id));
+}
+const DETAIL_CATEGORIES = new Set([
+    "preferences", "project-rules", "testing", "debugging", "git", "incidents", "lessons",
+]);
+function detailCategoryFromFile(file) {
+    if (!file.startsWith("notes/") || !file.endsWith(".md"))
+        return null;
+    const category = file.slice("notes/".length, -".md".length);
+    return DETAIL_CATEGORIES.has(category) ? category : null;
+}
+function readNoteBody(content, id) {
+    const begin = content.indexOf(`<!-- NOWWORK:MEMORY_ENTRY:BEGIN id=${id}`);
+    if (begin < 0)
+        return null;
+    const bodyStart = content.indexOf("\n\n", begin);
+    const bodyEnd = content.indexOf(`\n<!-- NOWWORK:MEMORY_ENTRY:END id=${id}`, bodyStart + 2);
+    if (bodyStart < 0 || bodyEnd < 0)
+        return null;
+    return content.slice(bodyStart + 2, bodyEnd).trim();
+}
+function archivedChange(entry, detailBody) {
+    const detailCategory = detailCategoryFromFile(entry.file);
+    if (detailCategory === null)
+        return null;
+    return {
+        operation: "create",
+        memoryId: null,
+        baseRevision: null,
+        supersedesMemoryId: null,
+        title: entry.title,
+        kind: entry.type,
+        summary: entry.summary,
+        triggers: entry.triggers,
+        priority: entry.priority,
+        detailCategory,
+        detailBody,
+        reviewAfter: entry.reviewAfter,
+    };
+}
 function emptyResult() {
     return { createdIds: [], updatedIds: [], statusChangedIds: [], deferredIds: [], pendingIds: [] };
 }
@@ -341,7 +382,9 @@ export async function applyLocalMemoryResult(input) {
         const statusChangedIds = input.result.statusChanges.map((change) => change.memoryId);
         const deferredIds = [];
         const pendingCandidates = [];
+        const resolvedPendingIds = new Set();
         const noteUpdates = new Map();
+        let allowActiveEviction = false;
         const randomId = input.randomId ?? randomUUID;
         const executionId = input.executionId ?? "unknown";
         const defer = (change, index) => {
@@ -399,7 +442,10 @@ export async function applyLocalMemoryResult(input) {
                             : item),
                         entry,
                     ];
-            const protectedIds = new Set(activeOrPinnedIds(entries));
+            const allowEvictionForChange = change.operation === "create" && change.priority === "high";
+            const protectedIds = new Set(allowEvictionForChange ? pinnedIds(entries) : activeOrPinnedIds(entries));
+            if (allowEvictionForChange)
+                allowActiveEviction = true;
             if (change.supersedesMemoryId !== null)
                 protectedIds.delete(change.supersedesMemoryId);
             const projection = projectIndex(memory, candidateEntries, protectedIds);
@@ -428,15 +474,91 @@ export async function applyLocalMemoryResult(input) {
             else if (existingCreate === undefined)
                 createdIds.push(id);
         }
-        const finalProjection = projectIndex(memory, entries, activeOrPinnedIds(entries));
-        if (finalProjection.reason !== null)
+        // Pending create candidates are durable overflow, not dead ends. Promote only
+        // when the current catalog has room; supersede/update candidates stay pending
+        // until a fresh revision-aware decision can safely replay them.
+        const pendingCandidatesOnDisk = await readPendingMemoryCandidates({ agentDir: input.agentDir });
+        for (const pending of pendingCandidatesOnDisk) {
+            const change = pending.candidate;
+            if (change.operation !== "create")
+                continue;
+            const id = stableId(`pending:${pending.pendingId}`, 0, change);
+            const existing = entries.find((entry) => entry.id === id);
+            if (existing !== undefined) {
+                resolvedPendingIds.add(pending.pendingId);
+                continue;
+            }
+            const duplicate = entries.find((entry) => (entry.status === "active" || entry.status === "pinned")
+                && (normalize(entry.title) === normalize(change.title)
+                    || normalize(entry.summary) === normalize(change.summary)));
+            if (duplicate !== undefined) {
+                const duplicatePath = resolve(input.agentDir, duplicate.file);
+                const duplicateBody = readNoteBody(noteUpdates.get(duplicatePath) ?? await readNote(duplicatePath), duplicate.id);
+                if (duplicateBody === change.detailBody)
+                    resolvedPendingIds.add(pending.pendingId);
+                continue;
+            }
+            const entry = entryFromChange(change, id, 1, "active");
+            const candidateEntries = [...entries, entry];
+            const allowEvictionForPending = change.priority === "high";
+            const projection = projectIndex(memory, candidateEntries, allowEvictionForPending ? pinnedIds(entries) : activeOrPinnedIds(entries));
+            if (allowEvictionForPending)
+                allowActiveEviction = true;
+            if (projection.omittedIds.includes(id))
+                continue;
+            const notePath = resolve(input.agentDir, entry.file);
+            if (!isWithin(resolve(input.agentDir, "notes"), notePath))
+                throw new Error("local_memory_note_path_invalid");
+            const previous = noteUpdates.get(notePath) ?? await readNote(notePath);
+            const replacement = noteSection(id, 1, change.title, change.detailBody);
+            const existingSection = replaceNote(previous, id, replacement);
+            const next = existingSection ?? `${previous.trimEnd()}${previous.trimEnd() ? "\n\n" : ""}${replacement}`;
+            noteUpdates.set(notePath, next);
+            entries = candidateEntries;
+            createdIds.push(id);
+            resolvedPendingIds.add(pending.pendingId);
+        }
+        let finalProjection = projectIndex(memory, entries, allowActiveEviction ? pinnedIds(entries) : activeOrPinnedIds(entries));
+        if (finalProjection.reason !== null
+            && (!allowActiveEviction || finalProjection.reason === "index_over_budget_pinned")) {
             throw new Error(finalProjection.reason);
+        }
+        if (allowActiveEviction) {
+            const omittedActiveEntries = finalProjection.omittedIds
+                .map((id) => entries.find((entry) => entry.id === id))
+                .filter((entry) => entry?.status === "active");
+            for (const entry of omittedActiveEntries) {
+                const notePath = resolve(input.agentDir, entry.file);
+                const content = noteUpdates.get(notePath) ?? await readNote(notePath);
+                const detailBody = readNoteBody(content, entry.id);
+                const change = detailBody === null ? null : archivedChange(entry, detailBody);
+                if (change === null)
+                    throw new Error("local_memory_note_anchor_missing");
+                const pendingId = `pending-${stableId(`evicted:${executionId}`, 0, change).slice("mem_".length)}`;
+                pendingCandidates.push({
+                    schemaVersion: 1,
+                    pendingId,
+                    createdAt: new Date().toISOString(),
+                    reason: "index_over_budget",
+                    source: { executionId, pruneTraceId: input.pruneTraceId ?? null },
+                    candidate: change,
+                });
+                deferredIds.push(pendingId);
+                entries = entries.map((item) => item.id === entry.id ? { ...item, status: "archived" } : item);
+            }
+            finalProjection = projectIndex(memory, entries, pinnedIds(entries));
+            if (finalProjection.reason !== null)
+                throw new Error(finalProjection.reason);
+        }
         for (const candidate of pendingCandidates)
             await persistPendingMemoryCandidate({ agentDir: input.agentDir, candidate });
         for (const [path, content] of noteUpdates)
             await atomicWrite(path, content);
         if (noteUpdates.size > 0 || statusChangedIds.length > 0)
             await atomicWrite(memoryPath, finalProjection.memory);
+        for (const pendingId of resolvedPendingIds) {
+            await removePendingMemoryCandidate({ agentDir: input.agentDir, pendingId });
+        }
         return {
             createdIds,
             updatedIds,

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),
+        });
+    }));
+}