@nowcrew/daemon 0.6.19 → 0.6.21

package/dist/project-skills/runtime-root-domain.js

@@ -0,0 +1,268 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { compareProjectSkillRefs, isProjectId, isProjectSkillName, MAX_AGENT_PROJECT_SKILL_BINDINGS, MAX_PROJECT_ID_LENGTH, MAX_PROJECT_SKILL_NAME_LENGTH, } from "./types.js";
+const RUNTIME_ROOT_MANAGED_BY = "nowcrew-project-skill-runtime-root";
+const RUNTIME_STORE_MANAGED_BY = "nowcrew-project-skill-runtime-store";
+const RUNTIME_LEASE_MANAGED_BY = "nowcrew-project-skill-runtime-lease";
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const DECIMAL_BIGINT = /^(?:0|[1-9][0-9]*)$/u;
+const PATH_FREE_IDENTITY = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/u;
+const CANONICAL_ROOT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+const MAX_LOCAL_IDENTITY_LENGTH = 512;
+const MAX_PUBLISHED_SEQUENCE = Number.MAX_SAFE_INTEGER - 1;
+/** Deployment algorithm/layout revision. This is deliberately not a source-content hash. */
+export const PROJECT_SKILL_RUNTIME_MATERIALIZATION_REVISION = 1;
+export class ProjectSkillRuntimeStoreError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = "ProjectSkillRuntimeStoreError";
+    }
+}
+const corrupt = () => {
+    throw new ProjectSkillRuntimeStoreError("skill_projection_snapshot_corrupt");
+};
+const unmanaged = () => {
+    throw new ProjectSkillRuntimeStoreError("skill_projection_runtime_root_unmanaged");
+};
+const SafeSequenceSchema = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+const PublishedSequenceSchema = SafeSequenceSchema.max(MAX_PUBLISHED_SEQUENCE);
+const PositiveMaterializationRevisionSchema = z.number().int().positive().max(Number.MAX_SAFE_INTEGER);
+export const isCanonicalProjectSkillRuntimeRootId = (value) => CANONICAL_ROOT_ID.test(value);
+const RootIdSchema = z.string().refine(isCanonicalProjectSkillRuntimeRootId);
+const DigestSchema = z.string().regex(DIGEST);
+const DirectoryIdentitySchema = z.object({
+    dev: z.string().regex(DECIMAL_BIGINT),
+    ino: z.string().regex(DECIMAL_BIGINT),
+    birthtimeNs: z.string().regex(DECIMAL_BIGINT),
+}).strict();
+const ProjectionModeSchema = z.object({
+    projectId: z.string().min(1).max(MAX_PROJECT_ID_LENGTH),
+    skillName: z.string().min(1).max(MAX_PROJECT_SKILL_NAME_LENGTH),
+    mode: z.enum(["symlink", "junction", "copy", "missing"]),
+}).strict();
+const RuntimeRootManifestSchema = z.object({
+    managedBy: z.literal(RUNTIME_ROOT_MANAGED_BY),
+    version: z.literal(1),
+    rootId: RootIdSchema,
+    publishedSequence: PublishedSequenceSchema,
+    materializationRevision: PositiveMaterializationRevisionSchema,
+    directoryIdentity: DirectoryIdentitySchema,
+    bindingDigest: DigestSchema,
+    resolutionDigest: DigestSchema,
+    projectionModes: z.array(ProjectionModeSchema).max(MAX_AGENT_PROJECT_SKILL_BINDINGS),
+}).strict();
+const RuntimeRootManifestInputSchema = RuntimeRootManifestSchema
+    .omit({ managedBy: true, version: true, materializationRevision: true })
+    .partial({ publishedSequence: true, directoryIdentity: true });
+const RuntimeRootRecordSchema = z.object({
+    rootId: RootIdSchema,
+    publishedSequence: PublishedSequenceSchema,
+    materializationRevision: PositiveMaterializationRevisionSchema,
+    directoryIdentity: DirectoryIdentitySchema,
+    bindingDigest: DigestSchema,
+    resolutionDigest: DigestSchema,
+}).strict();
+const RuntimeStoreStateSchema = z.object({
+    managedBy: z.literal(RUNTIME_STORE_MANAGED_BY),
+    version: z.literal(1),
+    nextSequence: SafeSequenceSchema,
+    roots: z.array(RuntimeRootRecordSchema),
+}).strict();
+const RuntimeStoreStateInputSchema = RuntimeStoreStateSchema.omit({ managedBy: true, version: true });
+const PathFreeIdentitySchema = z.string()
+    .min(1)
+    .max(MAX_LOCAL_IDENTITY_LENGTH)
+    .regex(PATH_FREE_IDENTITY);
+const RuntimeLeaseRecordSchema = z.object({
+    managedBy: z.literal(RUNTIME_LEASE_MANAGED_BY),
+    version: z.literal(1),
+    executionId: PathFreeIdentitySchema,
+    rootId: RootIdSchema,
+    nonce: PathFreeIdentitySchema,
+}).strict();
+const RuntimeLeaseRecordInputSchema = RuntimeLeaseRecordSchema.omit({ managedBy: true, version: true });
+const immutableDirectoryIdentity = (identity) => Object.freeze({
+    dev: identity.dev,
+    ino: identity.ino,
+    birthtimeNs: identity.birthtimeNs,
+});
+const sameProjectionRef = (left, right) => left.projectId === right.projectId && left.skillName === right.skillName;
+const immutableProjectionMode = (projection) => Object.freeze({
+    projectId: projection.projectId,
+    skillName: projection.skillName,
+    mode: projection.mode,
+});
+const canonicalProjectionModes = (modes) => {
+    const seen = new Set();
+    const canonical = modes.map((mode) => {
+        if (!isProjectId(mode.projectId) || !isProjectSkillName(mode.skillName))
+            return corrupt();
+        const key = `${mode.projectId}\0${mode.skillName}`;
+        if (seen.has(key))
+            return corrupt();
+        seen.add(key);
+        return immutableProjectionMode(mode);
+    }).sort(compareProjectSkillRefs);
+    return Object.freeze(canonical);
+};
+const requireCanonicalProjectionModes = (modes) => {
+    const canonical = canonicalProjectionModes(modes);
+    if (canonical.some((mode, index) => {
+        const input = modes[index];
+        return input === undefined || !sameProjectionRef(mode, input) || mode.mode !== input.mode;
+    }))
+        return corrupt();
+    return canonical;
+};
+const immutableRootRecord = (record) => Object.freeze({
+    rootId: record.rootId,
+    publishedSequence: record.publishedSequence,
+    materializationRevision: record.materializationRevision,
+    directoryIdentity: immutableDirectoryIdentity(record.directoryIdentity),
+    bindingDigest: record.bindingDigest,
+    resolutionDigest: record.resolutionDigest,
+});
+const compareRootRecords = (left, right) => left.publishedSequence - right.publishedSequence
+    || (left.rootId < right.rootId ? -1 : left.rootId > right.rootId ? 1 : 0);
+const canonicalRootRecords = (records) => {
+    const rootIds = new Set();
+    const sequences = new Set();
+    const canonical = records.map((record) => {
+        const parsed = RuntimeRootRecordSchema.safeParse(record);
+        if (!parsed.success)
+            return corrupt();
+        if (rootIds.has(parsed.data.rootId) || sequences.has(parsed.data.publishedSequence))
+            return corrupt();
+        rootIds.add(parsed.data.rootId);
+        sequences.add(parsed.data.publishedSequence);
+        return immutableRootRecord(parsed.data);
+    }).sort(compareRootRecords);
+    return Object.freeze(canonical);
+};
+const requireCanonicalRootRecords = (records) => {
+    const canonical = canonicalRootRecords(records);
+    if (canonical.some((record, index) => {
+        const input = records[index];
+        return input === undefined
+            || record.rootId !== input.rootId
+            || record.publishedSequence !== input.publishedSequence;
+    }))
+        return corrupt();
+    return canonical;
+};
+const requireNextSequence = (nextSequence, roots) => {
+    const latest = roots.at(-1);
+    if (latest !== undefined && latest.publishedSequence >= nextSequence)
+        corrupt();
+};
+const rejectUnknownOwner = (candidate, expected) => {
+    if (candidate && typeof candidate === "object" && "managedBy" in candidate
+        && candidate.managedBy !== expected)
+        unmanaged();
+};
+export function createProjectSkillRuntimeRootManifest(input) {
+    const parsedInput = RuntimeRootManifestInputSchema.safeParse(input);
+    if (!parsedInput.success)
+        return corrupt();
+    const candidate = RuntimeRootManifestSchema.safeParse({
+        managedBy: RUNTIME_ROOT_MANAGED_BY,
+        version: 1,
+        rootId: parsedInput.data.rootId,
+        publishedSequence: parsedInput.data.publishedSequence ?? 0,
+        materializationRevision: PROJECT_SKILL_RUNTIME_MATERIALIZATION_REVISION,
+        directoryIdentity: parsedInput.data.directoryIdentity ?? { dev: "0", ino: "0", birthtimeNs: "0" },
+        bindingDigest: parsedInput.data.bindingDigest,
+        resolutionDigest: parsedInput.data.resolutionDigest,
+        projectionModes: parsedInput.data.projectionModes,
+    });
+    if (!candidate.success)
+        return corrupt();
+    return Object.freeze({
+        ...candidate.data,
+        directoryIdentity: immutableDirectoryIdentity(candidate.data.directoryIdentity),
+        projectionModes: canonicalProjectionModes(candidate.data.projectionModes),
+    });
+}
+export function parseProjectSkillRuntimeRootManifest(candidate) {
+    rejectUnknownOwner(candidate, RUNTIME_ROOT_MANAGED_BY);
+    const parsed = RuntimeRootManifestSchema.safeParse(candidate);
+    if (!parsed.success)
+        return corrupt();
+    return Object.freeze({
+        ...parsed.data,
+        directoryIdentity: immutableDirectoryIdentity(parsed.data.directoryIdentity),
+        projectionModes: requireCanonicalProjectionModes(parsed.data.projectionModes),
+    });
+}
+export function createProjectSkillRuntimeRootRecord(input) {
+    const parsed = RuntimeRootRecordSchema.safeParse(input);
+    if (!parsed.success)
+        return corrupt();
+    return immutableRootRecord(parsed.data);
+}
+export function parseProjectSkillRuntimeRootRecord(candidate) {
+    const parsed = RuntimeRootRecordSchema.safeParse(candidate);
+    if (!parsed.success)
+        return corrupt();
+    return immutableRootRecord(parsed.data);
+}
+export function createProjectSkillRuntimeStoreState(input) {
+    const parsedInput = RuntimeStoreStateInputSchema.safeParse(input);
+    if (!parsedInput.success)
+        return corrupt();
+    const parsed = RuntimeStoreStateSchema.safeParse({
+        managedBy: RUNTIME_STORE_MANAGED_BY,
+        version: 1,
+        nextSequence: parsedInput.data.nextSequence,
+        roots: parsedInput.data.roots,
+    });
+    if (!parsed.success)
+        return corrupt();
+    const roots = canonicalRootRecords(parsed.data.roots);
+    requireNextSequence(parsed.data.nextSequence, roots);
+    return Object.freeze({
+        managedBy: RUNTIME_STORE_MANAGED_BY,
+        version: 1,
+        nextSequence: parsed.data.nextSequence,
+        roots,
+    });
+}
+export function parseProjectSkillRuntimeStoreState(candidate) {
+    rejectUnknownOwner(candidate, RUNTIME_STORE_MANAGED_BY);
+    const parsed = RuntimeStoreStateSchema.safeParse(candidate);
+    if (!parsed.success)
+        return corrupt();
+    const roots = requireCanonicalRootRecords(parsed.data.roots);
+    requireNextSequence(parsed.data.nextSequence, roots);
+    return Object.freeze({
+        managedBy: RUNTIME_STORE_MANAGED_BY,
+        version: 1,
+        nextSequence: parsed.data.nextSequence,
+        roots,
+    });
+}
+export function createProjectSkillRuntimeLeaseRecord(input) {
+    const parsedInput = RuntimeLeaseRecordInputSchema.safeParse(input);
+    if (!parsedInput.success)
+        return corrupt();
+    const parsed = RuntimeLeaseRecordSchema.safeParse({
+        managedBy: RUNTIME_LEASE_MANAGED_BY,
+        version: 1,
+        ...parsedInput.data,
+    });
+    if (!parsed.success)
+        return corrupt();
+    return Object.freeze(parsed.data);
+}
+export function parseProjectSkillRuntimeLeaseRecord(candidate) {
+    rejectUnknownOwner(candidate, RUNTIME_LEASE_MANAGED_BY);
+    const parsed = RuntimeLeaseRecordSchema.safeParse(candidate);
+    if (!parsed.success)
+        return corrupt();
+    return Object.freeze(parsed.data);
+}
+export function projectSkillRuntimeLeaseKey(executionId) {
+    return createHash("sha256").update(executionId, "utf8").digest("hex");
+}

package/dist/project-skills/runtime-root-gc.js

@@ -0,0 +1,293 @@
+import { randomUUID } from "node:crypto";
+import { chmod, lstat, mkdir, opendir, readFile, readdir, rename, rm, } from "node:fs/promises";
+import { posix, win32 } from "node:path";
+import { durableDirectorySync } from "../atomic-private-write.js";
+import { isCanonicalProjectSkillRuntimeRootId, parseProjectSkillRuntimeRootManifest, } from "./runtime-root-domain.js";
+import { createProjectSkillRuntimeRootStore, projectSkillRuntimeRootDirectory, } from "./runtime-root-store.js";
+const MANIFEST = "MANIFEST.json";
+const MAX_SCAN_ENTRIES = 2_048;
+const MAX_TREE_ENTRIES = 20_480;
+const MAX_TREE_DEPTH = 64;
+const MAX_TREE_BYTES = 8 * 1024 * 1024;
+const MAX_DELETE_COUNT = 64;
+const MAX_MANIFEST_BYTES = 256 * 1024;
+const QUARANTINE = /^\.gc-([0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$/u;
+const codeOf = (error) => error.code;
+const isMissing = (error) => codeOf(error) === "ENOENT";
+const isBusy = (error) => ["EPERM", "EACCES", "EBUSY"].includes(codeOf(error) ?? "");
+const owned = (uid) => process.getuid === undefined || uid === BigInt(process.getuid());
+const diagnostic = (code) => Object.freeze({ code });
+const sortIds = (ids) => Object.freeze([...new Set(ids)].sort());
+const treeSafe = async (root, path, maxEntries, maxDepth, maxBytes) => {
+    const pending = [{ path: root, depth: 0 }];
+    let entries = 0;
+    let bytes = 0;
+    while (pending.length > 0) {
+        const current = pending.pop();
+        let info;
+        try {
+            info = await lstat(current.path, { bigint: true });
+        }
+        catch {
+            return false;
+        }
+        if (!owned(info.uid))
+            return false;
+        if (info.isSymbolicLink())
+            continue;
+        if (!info.isDirectory()) {
+            if (!info.isFile())
+                return false;
+            bytes += Number(info.size);
+            if (bytes > maxBytes)
+                return false;
+            continue;
+        }
+        if (current.depth > maxDepth)
+            return false;
+        let names;
+        try {
+            names = await opendir(current.path).then(async (handle) => {
+                const result = [];
+                try {
+                    for (;;) {
+                        const entry = await handle.read();
+                        if (entry === null)
+                            break;
+                        result.push(entry.name);
+                        entries += 1;
+                        if (entries > maxEntries)
+                            return [];
+                    }
+                    return result;
+                }
+                finally {
+                    await handle.close().catch(() => undefined);
+                }
+            });
+        }
+        catch {
+            return false;
+        }
+        if (entries > maxEntries)
+            return false;
+        for (const name of names)
+            pending.push({ path: path.join(current.path, name), depth: current.depth + 1 });
+    }
+    return true;
+};
+const exactNames = async (directory, expected) => {
+    try {
+        const actual = await readdir(directory);
+        return JSON.stringify([...actual].sort()) === JSON.stringify([...expected].sort());
+    }
+    catch {
+        return false;
+    }
+};
+const readCandidate = async (rootPath, rootId, path, maxEntries, maxDepth, maxBytes) => {
+    let info;
+    try {
+        info = await lstat(rootPath, { bigint: true });
+    }
+    catch {
+        return null;
+    }
+    if (!info.isDirectory() || info.isSymbolicLink() || !owned(info.uid))
+        return null;
+    const manifestPath = path.join(rootPath, MANIFEST);
+    const manifestInfo = await lstat(manifestPath, { bigint: true }).catch(() => null);
+    if (manifestInfo === null || !manifestInfo.isFile() || manifestInfo.isSymbolicLink()
+        || !owned(manifestInfo.uid) || manifestInfo.size > BigInt(MAX_MANIFEST_BYTES))
+        return null;
+    let raw;
+    try {
+        raw = await readFile(manifestPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    if (Buffer.byteLength(raw, "utf8") > MAX_MANIFEST_BYTES)
+        return null;
+    let manifest;
+    try {
+        manifest = parseProjectSkillRuntimeRootManifest(JSON.parse(raw));
+    }
+    catch {
+        return null;
+    }
+    if (manifest.rootId !== rootId
+        || manifest.directoryIdentity.dev !== String(info.dev)
+        || manifest.directoryIdentity.ino !== String(info.ino)
+        || manifest.directoryIdentity.birthtimeNs !== String(info.birthtimeNs))
+        return null;
+    const runtime = path.join(rootPath, "runtime");
+    const claude = path.join(runtime, ".claude");
+    const skills = path.join(claude, "skills");
+    const structural = await Promise.all([runtime, claude, skills].map(async (directory) => {
+        const directoryInfo = await lstat(directory, { bigint: true }).catch(() => null);
+        return directoryInfo !== null && directoryInfo.isDirectory() && !directoryInfo.isSymbolicLink();
+    }));
+    if (structural.some((value) => !value)
+        || !(await exactNames(rootPath, [MANIFEST, "runtime"]))
+        || !(await exactNames(runtime, [".claude"]))
+        || !(await exactNames(claude, ["skills"])))
+        return null;
+    const materialized = manifest.projectionModes.filter(({ mode }) => mode !== "missing");
+    if (!(await exactNames(skills, materialized.map(({ skillName }) => skillName))))
+        return null;
+    for (const projection of manifest.projectionModes) {
+        const child = path.join(skills, projection.skillName);
+        const childInfo = await lstat(child, { bigint: true }).catch(() => null);
+        if (projection.mode === "missing") {
+            if (childInfo !== null)
+                return null;
+            continue;
+        }
+        if (childInfo === null || !owned(childInfo.uid))
+            return null;
+        if ((projection.mode === "symlink" || projection.mode === "junction") !== childInfo.isSymbolicLink()) {
+            return null;
+        }
+    }
+    if (!(await treeSafe(rootPath, path, maxEntries, maxDepth, maxBytes)))
+        return null;
+    return Object.freeze({
+        id: rootId,
+        path: rootPath,
+        record: Object.freeze({
+            rootId: manifest.rootId,
+            publishedSequence: manifest.publishedSequence,
+            materializationRevision: manifest.materializationRevision,
+            directoryIdentity: manifest.directoryIdentity,
+            bindingDigest: manifest.bindingDigest,
+            resolutionDigest: manifest.resolutionDigest,
+        }),
+        identity: Object.freeze({ dev: info.dev, ino: info.ino, birthtimeNs: info.birthtimeNs }),
+        raw,
+    });
+};
+export function createProjectSkillRuntimeRootGc(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const path = platform === "win32" ? win32 : posix;
+    const syncDirectory = options.directorySync ?? (platform === "win32" ? async () => undefined : durableDirectorySync);
+    const claimRename = options.rename ?? rename;
+    const removeClaim = options.remove ?? rm;
+    const rootStore = options.runtimeRoots ?? options.rootStore ?? createProjectSkillRuntimeRootStore({ platform });
+    const randomId = options.randomId ?? randomUUID;
+    const maxScanEntries = options.maximumScanEntries ?? MAX_SCAN_ENTRIES;
+    const maxTreeEntries = options.maximumTreeEntries ?? MAX_TREE_ENTRIES;
+    const maxTreeDepth = options.maximumTreeDepth ?? MAX_TREE_DEPTH;
+    const maxTreeBytes = options.maximumTreeBytes ?? MAX_TREE_BYTES;
+    const maxDeleteCount = options.maximumDeleteCount ?? MAX_DELETE_COUNT;
+    const collect = async (agentRoot, input) => {
+        const retained = new Set(input.leasedRootIds);
+        if (input.currentRootId !== null)
+            retained.add(input.currentRootId);
+        const removed = new Set();
+        const diagnostics = [];
+        const rootsDirectory = projectSkillRuntimeRootDirectory(agentRoot, platform);
+        let handle;
+        try {
+            handle = await opendir(rootsDirectory);
+        }
+        catch (error) {
+            if (isMissing(error))
+                return Object.freeze({ retained: sortIds(retained), removed: [], diagnostics: [] });
+            return Object.freeze({ retained: sortIds(retained), removed: [], diagnostics: [diagnostic("skill_projection_gc_deferred")] });
+        }
+        const names = [];
+        try {
+            for (;;) {
+                const entry = await handle.read();
+                if (entry === null)
+                    break;
+                names.push(entry.name);
+                if (names.length > maxScanEntries) {
+                    diagnostics.push(diagnostic("skill_projection_gc_deferred"));
+                    return Object.freeze({ retained: sortIds(retained), removed: [], diagnostics: Object.freeze(diagnostics) });
+                }
+            }
+        }
+        finally {
+            await handle.close().catch(() => undefined);
+        }
+        const candidates = [];
+        for (const name of names) {
+            if (QUARANTINE.test(name))
+                continue;
+            if (!isCanonicalProjectSkillRuntimeRootId(name)) {
+                diagnostics.push(diagnostic("skill_projection_runtime_root_unmanaged"));
+                continue;
+            }
+            const candidate = await readCandidate(path.join(rootsDirectory, name), name, path, maxTreeEntries, maxTreeDepth, maxTreeBytes);
+            if (candidate === null) {
+                diagnostics.push(diagnostic("skill_projection_runtime_root_unmanaged"));
+                continue;
+            }
+            candidates.push(candidate);
+        }
+        candidates.sort((a, b) => a.record.publishedSequence - b.record.publishedSequence || a.id.localeCompare(b.id));
+        const unleasedHistory = candidates.filter(({ id }) => !retained.has(id));
+        for (const candidate of unleasedHistory.slice(-input.keepHistory))
+            retained.add(candidate.id);
+        const deleteCandidates = unleasedHistory.slice(0, Math.min(maxDeleteCount, Math.max(0, unleasedHistory.length - input.keepHistory)));
+        if (unleasedHistory.length - input.keepHistory > maxDeleteCount) {
+            diagnostics.push(diagnostic("skill_projection_gc_deferred"));
+            for (const candidate of unleasedHistory.slice(maxDeleteCount, unleasedHistory.length - input.keepHistory)) {
+                retained.add(candidate.id);
+            }
+        }
+        if (deleteCandidates.length === 0)
+            return Object.freeze({ retained: sortIds(retained), removed: [], diagnostics: Object.freeze(diagnostics) });
+        if (rootStore !== undefined) {
+            try {
+                await (rootStore.checkpointNextSequenceForGc ?? rootStore.checkpointNextSequence)(agentRoot);
+            }
+            catch {
+                diagnostics.push(diagnostic("skill_projection_gc_deferred"));
+                for (const candidate of deleteCandidates)
+                    retained.add(candidate.id);
+                return Object.freeze({ retained: sortIds(retained), removed: [], diagnostics: Object.freeze(diagnostics) });
+            }
+        }
+        for (const candidate of deleteCandidates) {
+            if (retained.has(candidate.id))
+                continue;
+            const claim = path.join(rootsDirectory, `.gc-${randomId()}`);
+            if (!QUARANTINE.test(path.basename(claim))) {
+                diagnostics.push(diagnostic("skill_projection_gc_deferred"));
+                retained.add(candidate.id);
+                continue;
+            }
+            try {
+                await options.beforeClaim?.(candidate.path, claim);
+                await claimRename(candidate.path, claim);
+                await syncDirectory(rootsDirectory);
+                const claimed = await lstat(claim, { bigint: true });
+                if (!claimed.isDirectory() || claimed.isSymbolicLink() || !owned(claimed.uid)
+                    || claimed.dev !== candidate.identity.dev || claimed.ino !== candidate.identity.ino
+                    || claimed.birthtimeNs !== candidate.identity.birthtimeNs) {
+                    retained.add(candidate.id);
+                    continue;
+                }
+                const raw = await readFile(path.join(claim, MANIFEST), "utf8");
+                if (raw !== candidate.raw) {
+                    retained.add(candidate.id);
+                    continue;
+                }
+                await chmod(claim, 0o700).catch(() => undefined);
+                await removeClaim(claim, { recursive: true, force: true });
+                await syncDirectory(rootsDirectory);
+                removed.add(candidate.id);
+            }
+            catch (error) {
+                if (!isMissing(error))
+                    diagnostics.push(diagnostic("skill_projection_gc_deferred"));
+                retained.add(candidate.id);
+            }
+        }
+        return Object.freeze({ retained: sortIds(retained), removed: sortIds(removed), diagnostics: Object.freeze(diagnostics) });
+    };
+    return Object.freeze({ collect });
+}

package/dist/project-skills/runtime-root-lease-artifact.js

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import { ProjectSkillRuntimeStoreError, parseProjectSkillRuntimeLeaseRecord, } from "./runtime-root-domain.js";
+const LEASE_ARTIFACT_MANAGED_BY = "nowcrew-project-skill-runtime-lease-artifact";
+const DECIMAL_BIGINT = /^(?:0|[1-9][0-9]*)$/u;
+const ArtifactIdentitySchema = z.object({
+    dev: z.string().regex(DECIMAL_BIGINT),
+    ino: z.string().regex(DECIMAL_BIGINT),
+    birthtimeNs: z.string().regex(DECIMAL_BIGINT),
+}).strict();
+const LeaseArtifactSchema = z.object({
+    managedBy: z.literal(LEASE_ARTIFACT_MANAGED_BY),
+    version: z.literal(1),
+    record: z.unknown(),
+    fileIdentity: ArtifactIdentitySchema,
+}).strict();
+const invalidArtifact = () => {
+    throw new ProjectSkillRuntimeStoreError("skill_projection_snapshot_corrupt");
+};
+const immutableIdentity = (identity) => Object.freeze({ ...identity });
+export function createProjectSkillRuntimeLeaseArtifact(input) {
+    return parseProjectSkillRuntimeLeaseArtifact({
+        managedBy: LEASE_ARTIFACT_MANAGED_BY,
+        version: 1,
+        ...input,
+    });
+}
+export function parseProjectSkillRuntimeLeaseArtifact(candidate) {
+    const parsed = LeaseArtifactSchema.safeParse(candidate);
+    if (!parsed.success)
+        return invalidArtifact();
+    const record = parseProjectSkillRuntimeLeaseRecord(parsed.data.record);
+    return Object.freeze({
+        managedBy: LEASE_ARTIFACT_MANAGED_BY,
+        version: 1,
+        record,
+        fileIdentity: immutableIdentity(parsed.data.fileIdentity),
+    });
+}
+export const leaseArtifactIdentityFromStat = (identity) => Object.freeze({
+    dev: String(identity.dev),
+    ino: String(identity.ino),
+    birthtimeNs: String(identity.birthtimeNs),
+});
+export const matchesLeaseArtifactIdentity = (expected, actual) => expected.dev === String(actual.dev)
+    && expected.ino === String(actual.ino)
+    && expected.birthtimeNs === String(actual.birthtimeNs);