@tangle-network/agent-profile-materialize 1.1.6 → 1.1.8

package/dist/prime-profile.js

@@ -1,297 +0,0 @@
-const PRIME_SKILL_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-const PRIME_MAX_SKILL_NAME_LENGTH = 64;
-export const PRIME_PROFILE_DIR_NAME = "profile";
-export const PRIME_SKILLS_DIR_NAME = "skills";
-export const PRIME_SYSTEM_PROMPT_FILE = "system-prompt.md";
-export const PRIME_APPEND_SYSTEM_PROMPT_FILE = "append-system-prompt.md";
-/** Agent-dir global context file the fork reads (resource-loader.ts:59,86). */
-export const PRIME_CONTEXT_FILE = "AGENTS.md";
-/** Fork continual-harness store location under the agent dir (refinement.ts:269-279). */
-export const PRIME_HARNESS_DIR_NAME = "harness";
-export const PRIME_HARNESS_STATE_FILE = "harness_state.json";
-export const PRIME_HARNESS_KINDS = [
-    "prompt",
-    "memory",
-    "skill",
-    "subagent",
-];
-/**
- * Provenance marker for entries pinned from the profile. Stale removal keys on
- * it, so agent-written (`source: "agent"`) and user-written entries are never
- * touched.
- */
-export const PRIME_PROFILE_ENTRY_SOURCE = "profile";
-/**
- * Provenance markers written by executors that predate this shared lowering.
- *
- * Pruning keys on the source tag, so an executor that switches to the shared
- * implementation would otherwise leave its own earlier entries behind forever:
- * they match no current profile and no current source, and the model's
- * spawnable roster silently accumulates duplicates of every subagent. They are
- * adopted (pruned or replaced) on the first shared run instead.
- */
-export const PRIME_LEGACY_PROFILE_ENTRY_SOURCES = [
-    "cli-bridge-profile",
-];
-/** True when the controls materialize anything at all. */
-export function hasPrimeProfileMaterial(controls) {
-    return (controls.systemPrompt !== undefined ||
-        controls.appendSystemPrompt !== undefined ||
-        primeProfileNeedsAgentDir(controls) ||
-        controls.skills.length > 0);
-}
-/**
- * True when the controls must WRITE INTO the agent dir itself.
- *
- * Prompt files and skill dirs are named by a flag, so they can live anywhere
- * the agent can read (`--system-prompt` / `--append-system-prompt` resolve a
- * path when it exists, fork resource-loader.ts:41-56; `--skill` takes an
- * arbitrary dir, :437-442). The context file and the continual-harness store
- * are located BY the agent dir and have no flag, so they cannot move.
- *
- * An executor pointed at an agent dir it does not own (an operator's shared
- * dir) uses this to refuse exactly the controls it would have to write there,
- * while still binding the ones it can materialize elsewhere.
- */
-export function primeProfileNeedsAgentDir(controls) {
-    return controls.instructions !== undefined || controls.subagents.length > 0;
-}
-/**
- * Read one instruction block, which the profile may carry inline or as a
- * resource ref. Only inline refs are accepted: resolving a GitHub-backed ref
- * fetches remote content, which is `resolveAgentProfileResources`' job and
- * must happen before a profile reaches an executor.
- */
-function primeInstructionBlock(value, control) {
-    if (typeof value === "string")
-        return value;
-    if (value.kind === "inline")
-        return value.content;
-    rejectPrimeControl(control, "only inline resource refs are accepted — resolve GitHub-backed refs " +
-        "(resolveAgentProfileResources) before handing the profile to this lowering.");
-}
-/**
- * Validate and extract the profile controls the prime agent-dir lowering
- * materializes. Throws {@link PrimeProfileError} on any control (or control
- * facet) the fork has no verified read path for — partial acceptance would
- * silently drop the rest.
- */
-export function readPrimeProfileControls(profile) {
-    const controls = { skills: [], subagents: [] };
-    if (!profile)
-        return controls;
-    rejectUnboundPrimeControls(profile);
-    const instructionBlocks = [];
-    if (profile.prompt) {
-        readPrimePromptControls(profile.prompt, controls, instructionBlocks);
-    }
-    if (profile.resources) {
-        readPrimeResourceControls(profile.resources, controls, instructionBlocks);
-    }
-    if (instructionBlocks.length > 0) {
-        controls.instructions = instructionBlocks.join("\n\n");
-    }
-    if (profile.subagents) {
-        readPrimeSubagents(profile.subagents, controls);
-    }
-    return controls;
-}
-/** Refuse every profile control prime-agent has no verified read path for. */
-function rejectUnboundPrimeControls(profile) {
-    if (profile.harness !== undefined && profile.harness !== "prime") {
-        rejectPrimeDeclaration("harness", `prime cannot run a profile pinned to harness "${profile.harness}" — ` +
-            'only "prime" (or an unset harness preference) is accepted.');
-    }
-    // An entry with `enabled: false` is OFF, not requested. A fully disabled map
-    // asks for nothing, so accepting it drops no control — which is the only
-    // thing this refusal exists to prevent.
-    const requestedMcp = Object.keys(activeMcpServers(profile.mcp));
-    if (requestedMcp.length > 0) {
-        rejectPrimeControl(`mcp: ${requestedMcp.join(", ")}`, PRIME_MCP_UNSUPPORTED_REASON);
-    }
-    if (profile.connections !== undefined) {
-        rejectPrimeControl("connections", `a hub connection grant resolves to MCP tools, and ${PRIME_MCP_UNSUPPORTED_REASON}`);
-    }
-    if (profile.permissions !== undefined) {
-        rejectPrimeControl("permissions", "prime-agent exposes no permission control at all (full flag scan of fork " +
-            "cli/args.ts:93-295; native tools run unconditionally), so a permission map " +
-            "would be accepted and never enforced.");
-    }
-    if (profile.tools !== undefined) {
-        rejectPrimeControl("tools", "the only per-run tool control is `--tools` over the single builtin `ipython` " +
-            "(fork cli/args.ts:63-64,156-167); bash/edit and the rest are extension-provided " +
-            "and not addressable per run, so a harness-neutral tool map cannot bind to it.");
-    }
-    if (profile.hooks !== undefined) {
-        rejectPrimeControl("hooks", "prime-agent has no hook mechanism (fork cli/args.ts flag scan; extensions are " +
-            "host-trusted JS modules loaded into the agent process, not caller command hooks).");
-    }
-    if (profile.modes !== undefined) {
-        rejectPrimeControl("modes", "prime-agent has no mode concept (fork cli/args.ts flag scan).");
-    }
-    if (profile.confidential !== undefined) {
-        rejectPrimeControl("confidential", "confidential execution is a property of the executor's isolation boundary, not " +
-            "of the agent dir; this lowering cannot establish it.");
-    }
-}
-function readPrimePromptControls(prompt, controls, instructionBlocks) {
-    const { systemPrompt, appendSystemPrompt, instructions } = prompt;
-    const knownPromptFields = new Set([
-        "systemPrompt",
-        "appendSystemPrompt",
-        "instructions",
-    ]);
-    const unknown = Object.entries(prompt)
-        .filter(([key, value]) => !knownPromptFields.has(key) && value !== undefined)
-        .map(([key]) => key);
-    if (unknown.length > 0) {
-        rejectPrimeControl(`prompt fields: ${unknown.join(", ")}`, "no verified prime-agent read path exists for them.");
-    }
-    if (systemPrompt !== undefined) {
-        if (typeof systemPrompt !== "string" || systemPrompt.trim() === "") {
-            rejectPrimeDeclaration("prompt.systemPrompt", "an empty replacement would delete the built-in system prompt and " +
-                "install nothing.");
-        }
-        controls.systemPrompt = systemPrompt;
-    }
-    if (appendSystemPrompt !== undefined) {
-        if (typeof appendSystemPrompt !== "string" ||
-            appendSystemPrompt.trim() === "") {
-            rejectPrimeDeclaration("prompt.appendSystemPrompt", "must be non-empty text.");
-        }
-        controls.appendSystemPrompt = appendSystemPrompt;
-    }
-    for (const block of instructions ?? []) {
-        if (typeof block === "string" && block.trim() !== "")
-            instructionBlocks.push(block);
-    }
-}
-function readPrimeResourceControls(resources, controls, instructionBlocks) {
-    const { skills, instructions, failOnError, ...unsupported } = resources;
-    const rejectedKeys = Object.entries(unsupported)
-        .filter(([, value]) => value !== undefined)
-        .map(([key]) => key);
-    if (rejectedKeys.length > 0) {
-        rejectPrimeControl(`resources: ${rejectedKeys.join(", ")}`, "only resources.skills (--skill dirs, fork resource-loader.ts:437-442) and " +
-            "resources.instructions (agent-dir AGENTS.md, resource-loader.ts:86) have a " +
-            "verified prime-agent read path. Generic workspace files, tool files, " +
-            "subagent-definition files and prompt templates either have no headless read " +
-            "path or would run caller-authored code inside the agent process.");
-    }
-    if (failOnError === false) {
-        rejectPrimeControl("resources.failOnError: false", "this lowering always fails loud on a resource it cannot " +
-            "materialize; lenient materialization is not implemented.");
-    }
-    if (instructions !== undefined) {
-        const block = primeInstructionBlock(instructions, "resources.instructions");
-        if (block.trim() !== "")
-            instructionBlocks.push(block);
-    }
-    const seen = new Set();
-    for (const [index, ref] of (skills ?? []).entries()) {
-        if (ref.kind !== "inline") {
-            rejectPrimeControl(`resources.skills[${index}]`, "only inline skill refs are accepted — resolve GitHub-backed refs " +
-                "(resolveAgentProfileResources) before handing the profile to " +
-                "this lowering.");
-        }
-        const name = ref.name;
-        if (!PRIME_SKILL_NAME_RE.test(name) ||
-            name.length > PRIME_MAX_SKILL_NAME_LENGTH) {
-            rejectPrimeDeclaration(`resources.skills[${index}]`, `name ${JSON.stringify(name)} is not a valid prime skill name — it becomes the ` +
-                "skill directory name, so it must be lowercase a-z0-9 with single hyphens, at " +
-                `most ${PRIME_MAX_SKILL_NAME_LENGTH} chars (fork skills.ts:122-147).`);
-        }
-        if (seen.has(name)) {
-            rejectPrimeDeclaration("resources.skills", `declares ${JSON.stringify(name)} twice; duplicate skill names collide in the ` +
-                "fork's skill registry, which keeps only the first and warns.");
-        }
-        seen.add(name);
-        if (ref.content.trim() === "") {
-            rejectPrimeDeclaration(`resources.skills[${index}]`, `skill ${JSON.stringify(name)} declares no content.`);
-        }
-        controls.skills.push({ name, content: ref.content });
-    }
-}
-function readPrimeSubagents(subagents, controls) {
-    const usedIds = new Map();
-    for (const [name, spec] of Object.entries(subagents)) {
-        if (name.trim() === "") {
-            rejectPrimeDeclaration("subagents", "a subagent name must be non-empty.");
-        }
-        const inexpressible = [
-            ["model", spec.model],
-            ["tools", spec.tools],
-            ["permissions", spec.permissions],
-            ["maxSteps", spec.maxSteps],
-        ]
-            .filter(([, value]) => value !== undefined)
-            .map(([key]) => key);
-        if (inexpressible.length > 0) {
-            rejectPrimeControl(`subagents[${JSON.stringify(name)}] fields: ${inexpressible.join(", ")}`, "a prime continual-harness subagent spec is prompt-roster " +
-                "guidance for `await rlm('<task>')` (fork refinement.ts:483-496) " +
-                "and pins no model, tool set, permission, or step budget on the " +
-                "spawned child.");
-        }
-        if (!spec.description?.trim() && !spec.prompt?.trim()) {
-            rejectPrimeDeclaration(`subagents[${JSON.stringify(name)}]`, "declares no behavior — a spec needs a description and/or prompt, since an " +
-                "empty entry gives the model an empty roster line.");
-        }
-        const id = primeSubagentEntryId(name);
-        const clash = usedIds.get(id);
-        if (clash !== undefined) {
-            rejectPrimeDeclaration(`subagents[${JSON.stringify(name)}]`, `collides with subagent ${JSON.stringify(clash)} on harness-state id ` +
-                `${JSON.stringify(id)}.`);
-        }
-        usedIds.set(id, name);
-        controls.subagents.push({
-            name,
-            description: spec.description,
-            prompt: spec.prompt,
-            metadata: spec.metadata,
-        });
-    }
-}
-/**
- * Refuse a run whose selected model disagrees with the profile's own.
- *
- * One authority per run: a profile names the model it was written and scored
- * against, so running it on a different one silently scores a different agent.
- * Both sides go through {@link modelIdsMatch}, so the qualification level a
- * caller happened to use is not a conflict.
- *
- * `provider` is the executor's PROVIDER SELECTION, and is compared only when
- * the executor's provider is part of model identity. An executor whose
- * provider key is merely a namespace inside the agent dir passes it as
- * undefined and gets the model-name comparison alone.
- */
-export function assertPrimeModelAgreement(profile, selected) {
-    const declared = profile?.model?.default;
-    const declaredProvider = profile?.model?.provider;
-    if (declared !== undefined) {
-        const selectedId = qualifyModelId(selected.provider, selected.model);
-        const declaredId = qualifyModelId(declaredProvider, declared);
-        if (!modelIdsMatch(selectedId, declaredId, selected.provider)) {
-            rejectPrimeDeclaration("model.default", `the run selects ${JSON.stringify(selectedId)} but the profile names ` +
-                `${JSON.stringify(declaredId)}; a profile must not be scored against a model it ` +
-                "does not name.");
-        }
-        return;
-    }
-    if (selected.provider !== undefined &&
-        declaredProvider !== undefined &&
-        declaredProvider !== selected.provider) {
-        rejectPrimeDeclaration("model.provider", `the run selects provider ${JSON.stringify(selected.provider)} but the profile names ` +
-            `${JSON.stringify(declaredProvider)}.`);
-    }
-}
-/** Deterministic harness-state entry id for a profile subagent name. */
-export function primeSubagentEntryId(name) {
-    const slug = name
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "");
-    return `profile-${slug || "subagent"}`;
-}
-import { modelIdsMatch, qualifyModelId } from "./model-id.js";
-import { PRIME_MCP_UNSUPPORTED_REASON, rejectPrimeControl, rejectPrimeDeclaration, } from "./prime-fork.js";
-import { activeMcpServers } from "./profile-support.js";

package/dist/profile-bundle-cache.d.ts

@@ -1,37 +0,0 @@
-import { type ProfileBundleCache, type ProfileBundleClaim, type ProfileBundleClaimResult, type ProfileBundleManifest } from "./profile-bundle-key.js";
-export * from "./profile-bundle-key.js";
-export { evictProfileBundles, profileBundleManifestPath, sweepProfileBundleCache, } from "./profile-bundle-lru.js";
-/**
- * Admit a just-delivered bundle to the host cache, all-or-nothing. Every
- * object's bytes are verified against its content hash BEFORE anything is
- * renamed into place; a mismatch throws with nothing published. Objects
- * already present are re-verified against the incoming bytes, then the temp
- * copy is dropped — the existing object was verified when it was admitted.
- * The manifest is written LAST as the commit point, followed by lru update
- * and eviction down to the default cap.
- */
-export declare function admitProfileBundle(root: string, manifest: ProfileBundleManifest, readObject: (sha256: string) => Promise<Uint8Array> | Uint8Array): Promise<void>;
-/**
- * Claim a bundle from a (possibly read-only mounted) cache. Verify-on-read:
- * every object's bytes are re-hashed and compared to BOTH the manifest entry
- * and the claim's expected sha256 before `linkFile` is called — a read-only
- * mount must never serve unverified bytes. `linkFile` returning false sends
- * the file to `missing` (the caller delivers it normally). Status is "hit"
- * only when nothing is missing; a partial bundle is NEVER a hit. The only
- * write is a best-effort lru touch, wrapped so EROFS on a read-only mount is
- * harmless.
- */
-export declare function claimProfileBundle(root: string, claim: ProfileBundleClaim, linkFile: (objectPath: string, entry: {
-    mountPath: string;
-    target: string;
-    sha256: string;
-    mode: number;
-}) => Promise<boolean>): Promise<ProfileBundleClaimResult>;
-/**
- * Open a host-side cache handle over `root`, creating the layout and sweeping
- * stale `incoming/` residue synchronously when the root is idle. A busy root
- * leaves cleanup to its serialized admissions and sweeps.
- */
-export declare function openProfileBundleCache(root: string, options?: {
-    maxBytes?: number;
-}): ProfileBundleCache;

package/dist/profile-bundle-cache.js

@@ -1,320 +0,0 @@
-import { createHash, randomUUID } from "node:crypto";
-import { mkdirSync, readdirSync, rmSync } from "node:fs";
-import { mkdir, open, readFile, rename, rm, stat, writeFile, } from "node:fs/promises";
-import { join } from "node:path";
-import { PROFILE_BUNDLE_DEFAULT_MAX_BYTES, PROFILE_BUNDLE_MAX_BYTES, PROFILE_BUNDLE_MAX_FILE_BYTES, PROFILE_BUNDLE_MAX_FILES, PROFILE_BUNDLE_SCHEMA, } from "./profile-bundle-key.js";
-import { evictProfileBundles, evictUnlocked, fsyncDir, hasPendingRootWork, loadLru, pathExistsFollowingLinks, profileBundleManifestPath, readManifestFile, saveLru, sweepProfileBundleCache, sweepUnlocked, withRootLock, } from "./profile-bundle-lru.js";
-import { hasControlCharacter, normalizeWorkspaceRelativePath, validateFileMode, } from "./workspace-files.js";
-export * from "./profile-bundle-key.js";
-export { evictProfileBundles, profileBundleManifestPath, sweepProfileBundleCache, } from "./profile-bundle-lru.js";
-const SHA256_HEX_RE = /^[0-9a-f]{64}$/;
-const sha256Hex = (bytes) => createHash("sha256").update(bytes).digest("hex");
-const nowIso = () => new Date().toISOString();
-/**
- * Content-addressed, per-host cache of delivered profile-file bundles.
- *
- * A production cold sandbox start spends seconds re-delivering the same inline
- * profile file mounts through the box file API on every fresh box. The host
- * owns a cache directory (mounted read-only into boxes) of immutable,
- * content-addressed file objects plus per-bundle manifests. A box "claims" a
- * bundle by verifying every object against its content hash and hardlinking it
- * into the workspace, skipping network delivery; after a normal miss-delivery
- * the box-side publisher "admits" the just-delivered bytes to the host.
- *
- * Durability invariants:
- * - `objects/<sha256>` bytes are immutable and self-certifying: the filename
- *   IS the SHA-256 of the bytes. Objects are written to a unique `incoming/`
- *   dir and renamed into place only after every byte is verified, so a crash
- *   mid-admit leaves no half-published object behind.
- * - `bundles/<key>.json` is the commit point: readers treat a bundle as
- *   present only if its manifest exists, and verify every object anyway
- *   (verify-on-read), so a read-only or partially corrupt cache mount can
- *   never serve unverified bytes.
- * - `lru.json` is advisory accounting only; corruption never breaks admit or
- *   claim (see profile-bundle-lru.ts).
- */
-function validateManifestShape(manifest) {
-    if (manifest.schema !== PROFILE_BUNDLE_SCHEMA) {
-        throw new Error(`Profile bundle manifest schema mismatch: ${String(manifest.schema)}`);
-    }
-    if (typeof manifest.bundle !== "string" || manifest.bundle.length === 0) {
-        throw new Error("Profile bundle manifest requires a non-empty bundle key");
-    }
-    if (typeof manifest.createdAt !== "string") {
-        throw new Error("Profile bundle manifest requires an ISO createdAt");
-    }
-    if (!Number.isInteger(manifest.sizeBytes) ||
-        manifest.sizeBytes < 0 ||
-        manifest.sizeBytes > PROFILE_BUNDLE_MAX_BYTES) {
-        throw new Error(`Profile bundle sizeBytes exceeds ${PROFILE_BUNDLE_MAX_BYTES}: ${manifest.sizeBytes}`);
-    }
-    if (!Array.isArray(manifest.files)) {
-        throw new Error("Profile bundle manifest requires a files array");
-    }
-}
-/**
- * Reject anything that could link outside the cache or the workspace:
- * mount paths must already be canonical workspace-relative paths, and targets
- * must not contain traversal segments (targets MAY be absolute — the staged
- * manifest's `path` can be a file-API absolute prefix — but never `..`).
- */
-function validateTarget(target) {
-    if (typeof target !== "string" || target.length === 0) {
-        throw new Error("Profile bundle file requires a non-empty target");
-    }
-    if (hasControlCharacter(target)) {
-        throw new Error(`Profile bundle target has control characters: ${target}`);
-    }
-    const segments = target.replace(/\\/g, "/").split("/");
-    if (segments.some((segment) => segment === "..")) {
-        throw new Error(`Profile bundle target must not traverse: ${target}`);
-    }
-    return target;
-}
-function validateManifestFiles(manifest) {
-    if (manifest.files.length > PROFILE_BUNDLE_MAX_FILES) {
-        throw new Error(`Profile bundle has ${manifest.files.length} files; limit is ${PROFILE_BUNDLE_MAX_FILES}`);
-    }
-    const mountPaths = new Set();
-    const targets = new Set();
-    const entries = [];
-    for (const file of manifest.files) {
-        if (normalizeWorkspaceRelativePath(file.mountPath) !== file.mountPath) {
-            throw new Error(`Profile bundle mount path must be canonical: ${file.mountPath}`);
-        }
-        const target = validateTarget(file.target);
-        if (!SHA256_HEX_RE.test(file.sha256)) {
-            throw new Error(`Profile bundle sha256 must be lowercase hex without prefix: ${file.sha256}`);
-        }
-        const mode = validateFileMode(file.mode);
-        if (mountPaths.has(file.mountPath)) {
-            throw new Error(`Profile bundle has duplicate mount path: ${file.mountPath}`);
-        }
-        if (targets.has(target)) {
-            throw new Error(`Profile bundle has duplicate target: ${target}`);
-        }
-        mountPaths.add(file.mountPath);
-        targets.add(target);
-        entries.push({
-            mountPath: file.mountPath,
-            sha256: file.sha256,
-            mode,
-            target,
-        });
-    }
-    return entries;
-}
-/**
- * Admit a just-delivered bundle to the host cache, all-or-nothing. Every
- * object's bytes are verified against its content hash BEFORE anything is
- * renamed into place; a mismatch throws with nothing published. Objects
- * already present are re-verified against the incoming bytes, then the temp
- * copy is dropped — the existing object was verified when it was admitted.
- * The manifest is written LAST as the commit point, followed by lru update
- * and eviction down to the default cap.
- */
-export async function admitProfileBundle(root, manifest, readObject) {
-    validateManifestShape(manifest);
-    const entries = validateManifestFiles(manifest);
-    await mkdir(join(root, "objects"), { recursive: true });
-    await mkdir(join(root, "bundles"), { recursive: true });
-    await mkdir(join(root, "incoming"), { recursive: true });
-    await withRootLock(root, async () => {
-        await sweepUnlocked(root);
-        const manifestPath = profileBundleManifestPath(root, manifest.bundle);
-        const existing = await readManifestFile(manifestPath);
-        if (existing && existing.bundle !== manifest.bundle) {
-            throw new Error(`Profile bundle key collides with an admitted bundle: ${manifest.bundle}`);
-        }
-        const incoming = join(root, "incoming", randomUUID());
-        await mkdir(incoming, { recursive: true });
-        try {
-            const staged = [];
-            let totalBytes = 0;
-            for (const entry of entries) {
-                const bytes = await readObject(entry.sha256);
-                const buffer = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
-                if (buffer.byteLength > PROFILE_BUNDLE_MAX_FILE_BYTES) {
-                    throw new Error(`Profile bundle file ${entry.mountPath} exceeds ${PROFILE_BUNDLE_MAX_FILE_BYTES} bytes`);
-                }
-                if (sha256Hex(buffer) !== entry.sha256) {
-                    throw new Error(`Profile bundle object hash mismatch for ${entry.mountPath}`);
-                }
-                totalBytes += buffer.byteLength;
-                const object = join(root, "objects", entry.sha256);
-                if (await pathExistsFollowingLinks(object)) {
-                    // Already admitted; the bytes above were re-verified, so drop the temp.
-                    continue;
-                }
-                const temporary = join(incoming, entry.sha256);
-                const handle = await open(temporary, "w", (entry.mode & 0o100) !== 0 ? 0o755 : 0o644);
-                try {
-                    await handle.write(buffer);
-                    await handle.sync();
-                }
-                finally {
-                    await handle.close();
-                }
-                staged.push({ temporary, object });
-            }
-            if (totalBytes > PROFILE_BUNDLE_MAX_BYTES) {
-                throw new Error(`Profile bundle exceeds ${PROFILE_BUNDLE_MAX_BYTES} bytes: ${totalBytes}`);
-            }
-            for (const { temporary, object } of staged) {
-                await rename(temporary, object);
-            }
-            await fsyncDir(join(root, "objects"));
-            const stagedManifest = join(incoming, "manifest.json");
-            await writeFile(stagedManifest, JSON.stringify(manifest));
-            const manifestHandle = await open(stagedManifest, "r");
-            try {
-                await manifestHandle.sync();
-            }
-            finally {
-                await manifestHandle.close();
-            }
-            await rename(stagedManifest, manifestPath);
-            await fsyncDir(join(root, "bundles"));
-            const lru = await loadLru(root);
-            const used = nowIso();
-            for (const entry of entries) {
-                lru.objects[entry.sha256] = {
-                    bytes: (await stat(join(root, "objects", entry.sha256))).size,
-                    lastUsed: used,
-                };
-            }
-            lru.bundles[manifest.bundle] = {
-                bytes: totalBytes,
-                lastUsed: used,
-                createdAt: manifest.createdAt,
-            };
-            await saveLru(root, lru);
-        }
-        finally {
-            await rm(incoming, { recursive: true, force: true });
-        }
-        await evictUnlocked(root, PROFILE_BUNDLE_DEFAULT_MAX_BYTES);
-    });
-}
-/**
- * Claim a bundle from a (possibly read-only mounted) cache. Verify-on-read:
- * every object's bytes are re-hashed and compared to BOTH the manifest entry
- * and the claim's expected sha256 before `linkFile` is called — a read-only
- * mount must never serve unverified bytes. `linkFile` returning false sends
- * the file to `missing` (the caller delivers it normally). Status is "hit"
- * only when nothing is missing; a partial bundle is NEVER a hit. The only
- * write is a best-effort lru touch, wrapped so EROFS on a read-only mount is
- * harmless.
- */
-export async function claimProfileBundle(root, claim, linkFile) {
-    const missAll = () => ({
-        status: "miss",
-        missing: claim.files.map((file) => file.mountPath),
-    });
-    const manifest = await readManifestFile(profileBundleManifestPath(root, claim.bundle));
-    if (!manifest ||
-        manifest.schema !== PROFILE_BUNDLE_SCHEMA ||
-        manifest.bundle !== claim.bundle ||
-        !Array.isArray(manifest.files)) {
-        return missAll();
-    }
-    let entries;
-    try {
-        entries = validateManifestFiles(manifest);
-    }
-    catch {
-        return missAll();
-    }
-    const expected = new Map();
-    for (const file of claim.files) {
-        // Fail closed: a claim with a non-canonical path is rejected outright so a
-        // tampered claim can never link outside the workspace.
-        if (normalizeWorkspaceRelativePath(file.mountPath) !== file.mountPath) {
-            throw new Error(`Profile bundle claim path is not canonical: ${file.mountPath}`);
-        }
-        if (!SHA256_HEX_RE.test(file.sha256)) {
-            throw new Error(`Profile bundle claim sha256 is not hex: ${file.sha256}`);
-        }
-        if (expected.has(file.mountPath)) {
-            throw new Error(`Profile bundle claim has duplicate mount path: ${file.mountPath}`);
-        }
-        expected.set(file.mountPath, file.sha256);
-    }
-    const tableMatches = entries.length === expected.size &&
-        entries.every((entry) => expected.get(entry.mountPath) === entry.sha256);
-    if (!tableMatches) {
-        return missAll();
-    }
-    const linked = [];
-    const missing = [];
-    for (const entry of entries) {
-        const objectPath = join(root, "objects", entry.sha256);
-        let bytes;
-        try {
-            bytes = await readFile(objectPath);
-        }
-        catch {
-            missing.push(entry.mountPath);
-            continue;
-        }
-        if (sha256Hex(bytes) !== entry.sha256 ||
-            entry.sha256 !== expected.get(entry.mountPath)) {
-            missing.push(entry.mountPath);
-            continue;
-        }
-        if (await linkFile(objectPath, entry)) {
-            linked.push(entry.mountPath);
-        }
-        else {
-            missing.push(entry.mountPath);
-        }
-    }
-    if (missing.length > 0)
-        return { status: "miss", missing };
-    try {
-        await withRootLock(root, async () => {
-            const lru = await loadLru(root);
-            const used = nowIso();
-            for (const entry of entries) {
-                const object = lru.objects[entry.sha256];
-                if (object)
-                    object.lastUsed = used;
-            }
-            const bundleEntry = lru.bundles[claim.bundle];
-            if (bundleEntry)
-                bundleEntry.lastUsed = used;
-            await saveLru(root, lru);
-        });
-    }
-    catch {
-        // Best-effort accounting on a possibly read-only mount.
-    }
-    return { status: "hit", linked };
-}
-/**
- * Open a host-side cache handle over `root`, creating the layout and sweeping
- * stale `incoming/` residue synchronously when the root is idle. A busy root
- * leaves cleanup to its serialized admissions and sweeps.
- */
-export function openProfileBundleCache(root, options) {
-    const maxBytes = options?.maxBytes ?? PROFILE_BUNDLE_DEFAULT_MAX_BYTES;
-    if (!Number.isFinite(maxBytes) || maxBytes < 0) {
-        throw new Error(`Profile bundle cache maxBytes must be >= 0: ${maxBytes}`);
-    }
-    mkdirSync(join(root, "objects"), { recursive: true });
-    mkdirSync(join(root, "bundles"), { recursive: true });
-    const incoming = join(root, "incoming");
-    mkdirSync(incoming, { recursive: true });
-    if (!hasPendingRootWork(root)) {
-        for (const entry of readdirSync(incoming)) {
-            rmSync(join(incoming, entry), { recursive: true, force: true });
-        }
-    }
-    return {
-        root,
-        maxBytes,
-        admit: (manifest, readObject) => admitProfileBundle(root, manifest, readObject),
-        evict: () => evictProfileBundles(root, maxBytes),
-        sweep: () => sweepProfileBundleCache(root),
-    };
-}