@nowcrew/daemon 0.6.16 → 0.6.18

package/dist/profile-layout.js

@@ -0,0 +1,41 @@
+import { posix, win32 } from "node:path";
+export const PROFILE_LAYOUT_VERSION = 1;
+const PROFILE_NAME = /^[a-z0-9][a-z0-9_-]{0,47}$/u;
+const LOCAL_INSTANCE_NAME = /^[a-z0-9][a-z0-9_-]{0,39}$/u;
+export function validateLocalInstanceName(value) {
+    const normalized = value.trim().toLowerCase();
+    if (!LOCAL_INSTANCE_NAME.test(normalized) || normalized.includes("..")) {
+        throw new Error("local instance name must use lowercase letters, digits, '_' or '-' and cannot contain '..'");
+    }
+    return normalized;
+}
+export function profileForLocalInstance(environment, localInstanceName) {
+    const profile = `nw-${environment}-${validateLocalInstanceName(localInstanceName)}`;
+    if (!PROFILE_NAME.test(profile))
+        throw new Error("derived daemon profile exceeds 48 characters");
+    return profile;
+}
+export function profileLayout(input) {
+    const localInstanceName = validateLocalInstanceName(input.localInstanceName);
+    const profile = profileForLocalInstance(input.environment, localInstanceName);
+    const paths = input.platform === "win32" ? win32 : posix;
+    const base = `${input.environment}-${localInstanceName}`;
+    return Object.freeze({
+        layoutVersion: PROFILE_LAYOUT_VERSION,
+        environment: input.environment,
+        localInstanceName,
+        profile,
+        daemonHome: paths.join(input.userHome, ".crew", `daemon-${base}`),
+        agentsRoot: paths.join(input.userHome, ".crew", `agents-${base}`),
+        npmPrefix: paths.join(input.userHome, ".crew", "daemon-runtimes", profile),
+    });
+}
+export function compareProfileLayout(current, expected) {
+    if (current === null || current.layoutVersion !== PROFILE_LAYOUT_VERSION)
+        return "unknown";
+    return current.profile === expected.profile
+        && current.daemonHome === expected.daemonHome
+        && current.agentsRoot === expected.agentsRoot
+        ? "standard"
+        : "migration_required";
+}

package/dist/project-skills/controller.js

@@ -1,10 +1,21 @@
 import { z } from "zod";
-import { scanProjects } from "./scanner.js";
+import { projectSkillResolutionRecords, scanProjects } from "./scanner.js";
 import { ProjectRegistryError } from "./registry.js";
-import { isProjectId, isProjectSkillName, MAX_AGENT_PROJECT_SKILL_BINDINGS, } from "./types.js";
+import { isProjectId, isProjectSkillName, compareProjectSkillRefs, MAX_AGENT_PROJECT_SKILL_BINDINGS, } from "./types.js";
+import { ProjectProjectionError, } from "./reconciler.js";
 import { AgentHandleSchema } from "../execution-protocol.js";
 import { createPromiseTail } from "../promise-tail.js";
 const ProjectIdSchema = z.string().refine(isProjectId);
+const AgentSkillsSyncSchema = z.object({
+    type: z.literal("agent:skills:sync"),
+    reqId: z.string().min(1).max(128),
+    handle: AgentHandleSchema,
+    bindings: z.array(z.object({
+        projectId: ProjectIdSchema,
+        skillName: z.string().refine(isProjectSkillName),
+    }).strict()).max(MAX_AGENT_PROJECT_SKILL_BINDINGS),
+    generation: z.number().int().min(0).max(2_147_483_647).optional(),
+}).strict();
 const ProjectCommandSchema = z.discriminatedUnion("type", [
     z.object({
         type: z.literal("project:add"),
@@ -22,16 +33,21 @@ const ProjectCommandSchema = z.discriminatedUnion("type", [
         reqId: z.string().min(1).max(128),
         projectId: ProjectIdSchema,
     }).strict(),
-    z.object({
-        type: z.literal("agent:skills:sync"),
-        reqId: z.string().min(1).max(128),
-        handle: AgentHandleSchema,
-        bindings: z.array(z.object({
-            projectId: ProjectIdSchema,
-            skillName: z.string().refine(isProjectSkillName),
-        }).strict()).max(MAX_AGENT_PROJECT_SKILL_BINDINGS),
-    }).strict(),
-]);
+    AgentSkillsSyncSchema,
+]).superRefine((command, ctx) => {
+    if (command.type !== "agent:skills:sync" || command.generation === undefined)
+        return;
+    for (let index = 1; index < command.bindings.length; index += 1) {
+        if (compareProjectSkillRefs(command.bindings[index - 1], command.bindings[index]) >= 0) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "project_skill_bindings_not_canonical",
+                path: ["bindings", index],
+            });
+            return;
+        }
+    }
+});
 const DEFAULT_PROJECT_SCAN_TIMEOUT_MS = 10_000;
 class ProjectScanTimeoutError extends Error {
     code = "project_scan_timeout";
@@ -63,6 +79,7 @@ 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 scanCurrent = async (deferredProjectId) => withinScanDeadline(scan(await deps.registry.list(), undefined, [
         ...scanned
             .map((project) => project.inventory.projectId)
@@ -80,6 +97,34 @@ export function createProjectSkillsController(deps) {
         }));
     };
     const enqueue = (operation) => operationTail.enqueue(operation);
+    const applyV2Snapshot = async (handle, snapshot) => {
+        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,
+            }));
+        }
+        return Object.freeze(projectSkillResolutionRecords(snapshot.bindings, scanned)
+            .map((record) => Object.freeze({
+            projectId: record.projectId,
+            skillName: record.skillName,
+            status: record.mode === "resolved" ? "linked" : "unavailable",
+        })));
+    };
+    const reapplyV2Snapshots = async () => {
+        if (deps.ensureSnapshot === undefined) {
+            if (v2Snapshots.size > 0)
+                throw new ProjectProjectionError("skill_projection_failed");
+            return;
+        }
+        for (const [handle, snapshot] of [...v2Snapshots.entries()].sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)) {
+            await deps.ensureSnapshot(handle, snapshot);
+        }
+    };
     const initialize = () => {
         if (initializationState === "ready" && initialization !== null)
             return initialization;
@@ -115,11 +160,23 @@ export function createProjectSkillsController(deps) {
                 const command = parsed.data;
                 try {
                     if (command.type === "agent:skills:sync") {
+                        if (command.generation !== undefined) {
+                            const snapshot = Object.freeze({
+                                bindings: Object.freeze(command.bindings.map((binding) => Object.freeze({ ...binding }))),
+                                generation: command.generation,
+                            });
+                            return {
+                                ok: true,
+                                data: { bindings: await applyV2Snapshot(command.handle, snapshot) },
+                            };
+                        }
                         if (deps.reconcile === undefined)
                             return { ok: false, error: "skill_projection_failed" };
+                        const bindings = await deps.reconcile(command.handle, command.bindings);
+                        v2Snapshots.delete(command.handle);
                         return {
                             ok: true,
-                            data: { bindings: await deps.reconcile(command.handle, command.bindings) },
+                            data: { bindings },
                         };
                     }
                     if (command.type === "project:add") {
@@ -146,6 +203,7 @@ export function createProjectSkillsController(deps) {
                     if (command.type !== "project:add") {
                         await refresh(command.type === "project:rescan" ? command.projectId : undefined);
                     }
+                    await reapplyV2Snapshots();
                     await publishCurrent();
                     return { ok: true, data: { projectId: command.projectId } };
                 }
@@ -158,7 +216,9 @@ export function createProjectSkillsController(deps) {
                                 ? "skill_name_conflict"
                                 : error.code === "skill_projection_failed"
                                     ? "skill_projection_failed"
-                                    : "project_operation_failed",
+                                    : error.code === "skill_projection_snapshot_corrupt"
+                                        ? "skill_projection_snapshot_corrupt"
+                                        : "project_operation_failed",
                     };
                 }
             });

package/dist/project-skills/execution-adapter.js

@@ -0,0 +1,11 @@
+import { ProjectProjectionError } from "./reconciler.js";
+/** Converts the protocol's flat Agent fields without adding daemon-local paths to the wire shape. */
+export function projectSkillExecutionProjection(bindings, generation) {
+    return generation === undefined
+        ? bindings
+        : Object.freeze({
+            bindings,
+            generation,
+        });
+}
+export const projectSkillProjectionErrorCode = (error) => error instanceof ProjectProjectionError ? error.code : null;

package/dist/project-skills/initialized-reconciler.js

@@ -0,0 +1,20 @@
+import { ProjectProjectionError, } from "./reconciler.js";
+/** Gates every projection entrypoint on the daemon's bounded registry/scanner initialization. */
+export function initializedProjectSkillsReconciler(ensureInitialized, reconciler) {
+    const ready = async () => {
+        if (await ensureInitialized())
+            return reconciler;
+        throw new ProjectProjectionError("skill_projection_failed");
+    };
+    return {
+        async reconcile(handle, bindings) {
+            return (await ready()).reconcile(handle, bindings);
+        },
+        async ensureSnapshot(handle, snapshot) {
+            return (await ready()).ensureSnapshot(handle, snapshot);
+        },
+        async prepareAndLaunch(agentsRoot, handle, projection, launch, onWarning) {
+            return (await ready()).prepareAndLaunch(agentsRoot, handle, projection, launch, onWarning);
+        },
+    };
+}

package/dist/project-skills/projection-set-switch.js

@@ -0,0 +1,419 @@
+import { lstat, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { durableAtomicPrivateWrite, durableDirectorySync, durablePrivateUnlink, } from "../atomic-private-write.js";
+import { commitPreparedProjectSkillManifestUpdate, parseProjectSkillManifestUpdateRecord, preparedProjectSkillManifestUpdateFromRecord, projectSkillManifestUpdateRecord, publishPreparedProjectSkillManifestUpdate, rollbackPreparedProjectSkillManifestUpdate, } from "./projection-state.js";
+export const PROJECTION_ROOT_MARKER_NAME = ".nowcrew-project-skills-root.json";
+const JOURNAL_NAME = "project-skills-switch.json";
+const MAX_JOURNAL_BYTES = 768 * 1024;
+const MAX_ROOT_MARKER_BYTES = 16 * 1024;
+const NONCE = /^[A-Za-z0-9-]{1,128}$/u;
+const PHASES = new Set([
+    "prepared",
+    "codex:backup_moved",
+    "codex:activated",
+    "claude:backup_moved",
+    "claude:activated",
+    "committed",
+    "rolling_back",
+    "rollback_failed",
+]);
+const errorCode = (error) => error.code;
+export const projectionPathExists = async (path, statPath = lstat) => {
+    try {
+        await statPath(path);
+        return true;
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return false;
+        throw error;
+    }
+};
+const exists = projectionPathExists;
+const sameIdentity = (left, right) => left.dev === right.dev
+    && left.ino === right.ino
+    && left.birthtimeNs === right.birthtimeNs;
+const directoryIdentity = async (path) => {
+    try {
+        const info = await lstat(path, { bigint: true });
+        if (!info.isDirectory() || info.isSymbolicLink())
+            throw new Error("projection_switch_path_unmanaged");
+        return Object.freeze({
+            dev: String(info.dev),
+            ino: String(info.ino),
+            birthtimeNs: String(info.birthtimeNs),
+        });
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return null;
+        throw error;
+    }
+};
+export const projectionSwitchJournalPath = (agentRoot) => join(agentRoot, ".crew", JOURNAL_NAME);
+export const projectionTargets = (agentRoot, nonce) => Object.freeze([
+    Object.freeze({
+        runtime: "codex",
+        target: join(agentRoot, ".agents", "skills"),
+        staging: join(agentRoot, ".agents", `.skills-next-${nonce}`),
+        backup: join(agentRoot, ".agents", `.skills-previous-${nonce}`),
+        discard: join(agentRoot, ".agents", `.skills-discard-${nonce}`),
+    }),
+    Object.freeze({
+        runtime: "claude",
+        target: join(agentRoot, ".crew", "claude-skills", ".claude", "skills"),
+        staging: join(agentRoot, ".crew", "claude-skills", ".claude", `.skills-next-${nonce}`),
+        backup: join(agentRoot, ".crew", "claude-skills", ".claude", `.skills-previous-${nonce}`),
+        discard: join(agentRoot, ".crew", "claude-skills", ".claude", `.skills-discard-${nonce}`),
+    }),
+]);
+const rootMarker = (target, nonce) => Object.freeze({
+    managedBy: "nowcrew-project-skills-root",
+    version: 1,
+    nonce,
+    runtime: target.runtime,
+    target: target.target,
+});
+const readRootMarker = async (root) => {
+    const markerPath = join(root, PROJECTION_ROOT_MARKER_NAME);
+    try {
+        const info = await lstat(markerPath);
+        if (!info.isFile() || info.isSymbolicLink() || Number(info.size) > MAX_ROOT_MARKER_BYTES)
+            return null;
+        const candidate = JSON.parse(await readFile(markerPath, "utf8"));
+        return candidate.managedBy === "nowcrew-project-skills-root"
+            && candidate.version === 1
+            && NONCE.test(candidate.nonce ?? "")
+            && (candidate.runtime === "codex" || candidate.runtime === "claude")
+            && typeof candidate.target === "string"
+            ? candidate
+            : null;
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT" || error instanceof SyntaxError)
+            return null;
+        throw error;
+    }
+};
+const markerMatches = (marker, target, nonce) => marker !== null
+    && marker.runtime === target.runtime
+    && marker.target === target.target
+    && (nonce === undefined || marker.nonce === nonce);
+const assertOwnedRoot = async (root, target, nonce) => {
+    const info = await directoryIdentity(root);
+    if (info === null || !markerMatches(await readRootMarker(root), target, nonce)) {
+        throw new Error("projection_switch_path_unmanaged");
+    }
+};
+export const markProjectionStaging = async (target, nonce) => {
+    await writeFile(join(target.staging, PROJECTION_ROOT_MARKER_NAME), JSON.stringify(rootMarker(target, nonce)), {
+        encoding: "utf8",
+        mode: 0o600,
+        flag: "wx",
+    });
+};
+export const isManagedProjectionRoot = async (root, target) => markerMatches(await readRootMarker(root), target);
+export const cleanupProjectionStaging = async (target, nonce, syncDirectory = durableDirectorySync) => {
+    if (!await exists(target.staging))
+        return;
+    await assertOwnedRoot(target.staging, target, nonce);
+    await rm(target.staging, { recursive: true, force: true });
+    await syncDirectory(dirname(target.target));
+};
+const exactJournalTargets = (agentRoot, nonce, candidates) => {
+    const expected = projectionTargets(agentRoot, nonce);
+    return candidates.length === expected.length && expected.every((target, index) => {
+        const candidate = candidates[index];
+        return candidate?.runtime === target.runtime
+            && candidate.target === target.target
+            && candidate.staging === target.staging
+            && candidate.backup === target.backup
+            && candidate.discard === target.discard
+            && typeof candidate.hadPrevious === "boolean"
+            && (candidate.previousIdentity === null
+                || (typeof candidate.previousIdentity?.dev === "string"
+                    && typeof candidate.previousIdentity.ino === "string"
+                    && typeof candidate.previousIdentity.birthtimeNs === "string"))
+            && typeof candidate.activatedIdentity?.dev === "string"
+            && typeof candidate.activatedIdentity.ino === "string"
+            && typeof candidate.activatedIdentity.birthtimeNs === "string";
+    });
+};
+const parseJournal = (raw, agentRoot) => {
+    const candidate = JSON.parse(raw);
+    if (candidate.managedBy !== "nowcrew-project-skills-switch"
+        || candidate.version !== 1
+        || !NONCE.test(candidate.nonce ?? "")
+        || !PHASES.has(candidate.phase)
+        || !Array.isArray(candidate.targets)
+        || !exactJournalTargets(agentRoot, candidate.nonce, candidate.targets)
+        || Object.keys(candidate).some((key) => ![
+            "managedBy", "version", "nonce", "phase", "targets", "manifestUpdate",
+        ].includes(key))) {
+        throw new Error("projection_switch_journal_invalid");
+    }
+    const manifestUpdate = candidate.manifestUpdate === undefined
+        ? undefined
+        : parseProjectSkillManifestUpdateRecord(candidate.manifestUpdate);
+    return Object.freeze({
+        managedBy: "nowcrew-project-skills-switch",
+        version: 1,
+        nonce: candidate.nonce,
+        phase: candidate.phase,
+        targets: candidate.targets,
+        ...(manifestUpdate === undefined ? {} : { manifestUpdate }),
+    });
+};
+const readJournal = async (agentRoot) => {
+    const path = projectionSwitchJournalPath(agentRoot);
+    let info;
+    try {
+        info = await lstat(path);
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return null;
+        throw error;
+    }
+    if (!info.isFile() || info.isSymbolicLink() || Number(info.size) > MAX_JOURNAL_BYTES) {
+        throw new Error("projection_switch_journal_invalid");
+    }
+    return parseJournal(await readFile(path, "utf8"), agentRoot);
+};
+const writeJournal = async (agentRoot, journal) => durableAtomicPrivateWrite(projectionSwitchJournalPath(agentRoot), `${JSON.stringify(journal)}\n`);
+const withPhase = (journal, phase) => Object.freeze({ ...journal, phase });
+const unlinkExactJournal = async (agentRoot, nonce) => {
+    const current = await readJournal(agentRoot);
+    if (current === null)
+        return;
+    if (current.nonce !== nonce)
+        throw new Error("projection_switch_journal_invalid");
+    await durablePrivateUnlink(projectionSwitchJournalPath(agentRoot));
+};
+const assertPrevious = async (path, expected) => {
+    const actual = await directoryIdentity(path);
+    if (actual === null || !sameIdentity(actual, expected))
+        throw new Error("projection_switch_backup_unmanaged");
+};
+const assertActivated = async (path, target, nonce) => {
+    await assertOwnedRoot(path, target, nonce);
+    await assertPrevious(path, target.activatedIdentity);
+};
+const cleanupDiscard = async (target, journal, syncDirectory) => {
+    const discardIdentity = await directoryIdentity(target.discard);
+    if (discardIdentity === null)
+        return;
+    if (target.previousIdentity !== null && sameIdentity(discardIdentity, target.previousIdentity)) {
+        await rm(target.discard, { recursive: true, force: true });
+        await syncDirectory(dirname(target.target));
+        return;
+    }
+    await assertActivated(target.discard, target, journal.nonce);
+    await rm(target.discard, { recursive: true, force: true });
+    await syncDirectory(dirname(target.target));
+};
+const finalizeCommitted = async (agentRoot, journal, syncDirectory, manifestOperations, unlinkJournal = unlinkExactJournal) => {
+    for (const target of journal.targets)
+        await assertActivated(target.target, target, journal.nonce);
+    const manifestUpdate = journal.manifestUpdate === undefined
+        ? null
+        : preparedProjectSkillManifestUpdateFromRecord(agentRoot, journal.manifestUpdate);
+    if (manifestUpdate !== null)
+        await manifestOperations.publish(manifestUpdate);
+    for (const target of journal.targets) {
+        if (target.hadPrevious && await exists(target.backup)) {
+            if (target.previousIdentity === null)
+                throw new Error("projection_switch_backup_unmanaged");
+            await assertPrevious(target.backup, target.previousIdentity);
+            if (await exists(target.discard))
+                throw new Error("projection_switch_path_unmanaged");
+            await rename(target.backup, target.discard);
+            await syncDirectory(dirname(target.target));
+            await assertPrevious(target.discard, target.previousIdentity);
+        }
+        if (await exists(target.discard)) {
+            if (target.previousIdentity === null)
+                throw new Error("projection_switch_backup_unmanaged");
+            await assertPrevious(target.discard, target.previousIdentity);
+            await rm(target.discard, { recursive: true, force: true });
+            await syncDirectory(dirname(target.target));
+        }
+        await cleanupProjectionStaging(target, journal.nonce, syncDirectory);
+    }
+    for (const target of journal.targets)
+        await syncDirectory(dirname(target.target));
+    if (manifestUpdate !== null)
+        await manifestOperations.commit(manifestUpdate);
+    await unlinkJournal(agentRoot, journal.nonce);
+};
+const rollback = async (agentRoot, journal, syncDirectory, manifestOperations) => {
+    let currentJournal = withPhase(journal, "rolling_back");
+    await writeJournal(agentRoot, currentJournal);
+    try {
+        for (const target of [...currentJournal.targets].reverse()) {
+            const currentIdentity = await directoryIdentity(target.target);
+            const currentIsPrevious = currentIdentity !== null
+                && target.previousIdentity !== null
+                && sameIdentity(currentIdentity, target.previousIdentity);
+            if (!currentIsPrevious && currentIdentity !== null) {
+                await assertActivated(target.target, target, currentJournal.nonce);
+                if (await exists(target.discard))
+                    throw new Error("projection_switch_path_unmanaged");
+                await rename(target.target, target.discard);
+                await syncDirectory(dirname(target.target));
+                await assertActivated(target.discard, target, currentJournal.nonce);
+            }
+            const afterActivationRemoved = await directoryIdentity(target.target);
+            if (target.hadPrevious) {
+                if (target.previousIdentity === null)
+                    throw new Error("projection_switch_backup_unmanaged");
+                if (afterActivationRemoved === null) {
+                    await assertPrevious(target.backup, target.previousIdentity);
+                    await rename(target.backup, target.target);
+                    await syncDirectory(dirname(target.target));
+                    await assertPrevious(target.target, target.previousIdentity);
+                }
+                else if (!sameIdentity(afterActivationRemoved, target.previousIdentity)) {
+                    throw new Error("projection_switch_path_unmanaged");
+                }
+            }
+            else if (afterActivationRemoved !== null) {
+                throw new Error("projection_switch_path_unmanaged");
+            }
+            await cleanupDiscard(target, currentJournal, syncDirectory);
+            await cleanupProjectionStaging(target, currentJournal.nonce, syncDirectory);
+        }
+        if (currentJournal.manifestUpdate !== undefined) {
+            await manifestOperations.rollback(preparedProjectSkillManifestUpdateFromRecord(agentRoot, currentJournal.manifestUpdate));
+        }
+        for (const target of currentJournal.targets)
+            await syncDirectory(dirname(target.target));
+        await unlinkExactJournal(agentRoot, currentJournal.nonce);
+    }
+    catch (error) {
+        currentJournal = withPhase(currentJournal, "rollback_failed");
+        await writeJournal(agentRoot, currentJournal);
+        throw error;
+    }
+};
+export const recoverProjectionSwitch = async (agentRoot, syncDirectory = durableDirectorySync, manifestOperations = {}) => {
+    const operations = {
+        publish: manifestOperations.publish ?? publishPreparedProjectSkillManifestUpdate,
+        commit: manifestOperations.commit ?? commitPreparedProjectSkillManifestUpdate,
+        rollback: manifestOperations.rollback ?? rollbackPreparedProjectSkillManifestUpdate,
+    };
+    const journal = await readJournal(agentRoot);
+    if (journal === null)
+        return;
+    if (journal.phase === "committed") {
+        await finalizeCommitted(agentRoot, journal, syncDirectory, operations);
+        return;
+    }
+    await rollback(agentRoot, journal, syncDirectory, operations);
+};
+/**
+ * Switches the Codex/Claude roots as one recoverable projection set while the Agent coordinator lock is held.
+ * This is not a mythical two-directory filesystem transaction: each root is individually published by rename,
+ * so a mixed pair may exist inside the locked switch interval. Every bounded, path-exact journal phase fsyncs its
+ * temporary contents before rename and its parent directory afterward. Each target-parent mutation is also fsynced:
+ * activations before the durable commit phase, and restoration/cleanup plus a final parent barrier before journal
+ * deletion. A v2 state publication is bound into the same journal: recovery rolls every pre-commit phase back to
+ * the recorded prior roots and manifest, while a durable committed phase can only finish the next pair's cleanup.
+ * No launch using this coordinator observes a successfully returned mixed set. Activated roots require both their
+ * nonce marker and their recorded filesystem identity before rollback cleanup.
+ */
+export const switchProjectionSet = async (agentRoot, targets, nonce, fault, syncDirectory = durableDirectorySync, publication) => {
+    const manifestOperations = {
+        publish: publication?.operations?.publish ?? publishPreparedProjectSkillManifestUpdate,
+        commit: publication?.operations?.commit ?? commitPreparedProjectSkillManifestUpdate,
+        rollback: publication?.operations?.rollback ?? rollbackPreparedProjectSkillManifestUpdate,
+    };
+    const journalTargets = [];
+    try {
+        if (!NONCE.test(nonce) || targets.length !== 2)
+            throw new Error("projection_switch_journal_invalid");
+        const expected = projectionTargets(agentRoot, nonce);
+        if (targets.some((target, index) => JSON.stringify(target) !== JSON.stringify(expected[index]))) {
+            throw new Error("projection_switch_journal_invalid");
+        }
+        for (const target of targets) {
+            await assertOwnedRoot(target.staging, target, nonce);
+            if (await exists(target.backup) || await exists(target.discard)) {
+                throw new Error("projection_switch_path_unmanaged");
+            }
+            const previousIdentity = await directoryIdentity(target.target);
+            const activatedIdentity = await directoryIdentity(target.staging);
+            if (activatedIdentity === null)
+                throw new Error("projection_switch_path_unmanaged");
+            journalTargets.push(Object.freeze({
+                ...target,
+                hadPrevious: previousIdentity !== null,
+                previousIdentity,
+                activatedIdentity,
+            }));
+        }
+    }
+    catch (error) {
+        if (publication !== undefined)
+            await manifestOperations.rollback(publication.update);
+        throw error;
+    }
+    let journal = Object.freeze({
+        managedBy: "nowcrew-project-skills-switch",
+        version: 1,
+        nonce,
+        phase: "prepared",
+        targets: Object.freeze(journalTargets),
+        ...(publication === undefined
+            ? {}
+            : { manifestUpdate: projectSkillManifestUpdateRecord(publication.update) }),
+    });
+    try {
+        await writeJournal(agentRoot, journal);
+    }
+    catch (error) {
+        if (publication !== undefined)
+            await manifestOperations.rollback(publication.update);
+        throw error;
+    }
+    let committedDurable = false;
+    try {
+        await fault?.(journal.phase);
+        for (const target of journal.targets) {
+            if (target.hadPrevious) {
+                await rename(target.target, target.backup);
+                await syncDirectory(dirname(target.target));
+                await assertPrevious(target.backup, target.previousIdentity);
+            }
+            journal = withPhase(journal, `${target.runtime}:backup_moved`);
+            await writeJournal(agentRoot, journal);
+            await fault?.(journal.phase);
+            await rename(target.staging, target.target);
+            await syncDirectory(dirname(target.target));
+            await assertActivated(target.target, target, nonce);
+            journal = withPhase(journal, `${target.runtime}:activated`);
+            await writeJournal(agentRoot, journal);
+            await fault?.(journal.phase);
+        }
+        if (publication !== undefined) {
+            await manifestOperations.publish(publication.update);
+            await publication.verify();
+            await publication.afterPublishedBeforeCommit?.();
+        }
+        const committedJournal = withPhase(journal, "committed");
+        await writeJournal(agentRoot, committedJournal);
+        journal = committedJournal;
+        committedDurable = true;
+        await fault?.(journal.phase);
+        await finalizeCommitted(agentRoot, journal, syncDirectory, manifestOperations, publication?.unlinkJournal);
+    }
+    catch (error) {
+        if (committedDurable)
+            throw error;
+        const persisted = await readJournal(agentRoot);
+        if (persisted?.phase === "committed")
+            throw error;
+        await rollback(agentRoot, persisted ?? journal, syncDirectory, manifestOperations);
+        throw error;
+    }
+};