@tea-agent/loop-agent 0.41.1-beta.0 → 0.42.0-next.1

package/dist/executors/shell-write-guard.js

@@ -124,13 +124,6 @@ export function isEphemeralToolCachePath(filePath) {
     if (normalized === ".coverage" || normalized.startsWith(".coverage.")) {
         return true;
     }
-    // vite/vitest runtime caches live under node_modules/.vite (e.g.
-    // node_modules/.vite/vitest/results.json). node_modules is the gitignored
-    // dependency tree — tool cache writes there are never a writer's product
-    // change and must not trip the write guard.
-    if (normalized.startsWith("node_modules/.vite/")) {
-        return true;
-    }
     if (/(?:^|\/)__pycache__(?:\/|$)/.test(normalized))
         return true;
     if (/\.(?:pyc|pyo)$/.test(normalized))

package/dist/{worker → infrastructure}/console/app-data.js

@@ -35,6 +35,8 @@ export function openConsoleAppData(options) {
         fingerprint,
         drafts: path.join(repoNamespace, "drafts"),
         operations: path.join(repoNamespace, "operations"),
+        contextExports: path.join(repoNamespace, "context-exports"),
+        artifactRevisions: path.join(repoNamespace, "artifact-revisions"),
         confirmations: path.join(repoNamespace, "confirmations"),
         dagReceipts: path.join(repoNamespace, "dag-receipts"),
         staged: path.join(repoNamespace, "staged"),
@@ -48,6 +50,8 @@ export function openConsoleAppData(options) {
     for (const dir of [
         paths.drafts,
         paths.operations,
+        paths.contextExports,
+        paths.artifactRevisions,
         paths.confirmations,
         paths.dagReceipts,
         paths.staged,

package/dist/infrastructure/console/artifact-revision-store.js

@@ -0,0 +1,430 @@
+import { createHash, randomBytes } from "node:crypto";
+import { lstat, readdir, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { validateAndDescribeArtifactRevision, } from "../../shared/context-transfer/artifact-revision.js";
+import { artifactRevisionV1Schema, computeOverrideSetHash, } from "../../shared/context-transfer.js";
+import { assertSafeAppDataPath, ensureSecureDir, readJsonIfExists, writeSecureJson, } from "./app-data.js";
+import { acquireDirLock, isDirLockStale, } from "./dir-lock.js";
+import { readFileBoundarySafe } from "../../shared/path-safety.js";
+export const DEFAULT_ARTIFACT_REVISION_TTL_MS = 60 * 60 * 1000;
+/** Per-repo staging quota across uploads + staged candidates (M4b). */
+export const ARTIFACT_REVISION_STAGING_QUOTA_BYTES = 200 * 1024 * 1024;
+export const DEFAULT_REVISION_LEASE_TTL_MS = 5 * 60 * 1000;
+/**
+ * Execute holds the revision across an entire child run (potentially hours);
+ * align with the Console default operation timeout instead of the short
+ * staging TTL.
+ */
+export const EXECUTE_REVISION_LEASE_TTL_MS = 4 * 60 * 60 * 1000;
+const STAGING_LOCK_DIR = ".staging-lock";
+const STAGING_LOCK_STALE_MS = 30_000;
+function stagingLockDirPath(appData) {
+    return path.join(root(appData), STAGING_LOCK_DIR);
+}
+function revisionMutationLockDirPath(appData, revisionId) {
+    if (!/^[a-f0-9]{32}$/.test(revisionId))
+        throw new Error("invalid revision id");
+    return assertSafeAppDataPath(root(appData), path.join(root(appData), "locks", `${revisionId}.lock`));
+}
+/**
+ * Cross-process repo-wide mutex around the quota "measure → decide → write"
+ * window. In-process promise chains alone leave a TOCTOU window between the
+ * Console upload route and sibling CLI stage processes; a stale-tolerant
+ * exclusive directory lock closes it.
+ *
+ * Ownership is token-guarded: each holder writes a unique owner file inside
+ * the lock directory and only ever removes a lock whose owner token matches
+ * its own. Release verifies owner + freshness BEFORE touching the path (B2):
+ * a stale lock is never moved by its former holder, so an old holder cannot
+ * race a successor's takeover and a third contender cannot acquire while the
+ * new holder is still in its critical section.
+ */
+export async function acquireRepoStagingLock(appData, options) {
+    return acquireDirLock(stagingLockDirPath(appData), {
+        staleMs: options?.staleMs ?? STAGING_LOCK_STALE_MS,
+        token: options?.token,
+    });
+}
+async function withRepoStagingLock(appData, operation) {
+    const handle = await acquireRepoStagingLock(appData);
+    try {
+        return await operation();
+    }
+    finally {
+        await handle.release();
+    }
+}
+/**
+ * Cross-process per-revision serialization of metadata read-modify-write
+ * (B1). `serializeRevision` only serializes within one process; the Console
+ * and sibling CLI processes are separate processes that can both read
+ * metadata.json, mutate it, and write it back — losing an update (e.g. two
+ * executes, or an execute racing a discard, both "taking over" the lease).
+ * A per-revision directory lock held across the whole read-modify-write
+ * closes that window.
+ */
+async function withRevisionMutationLock(appData, revisionId, operation) {
+    const lockDir = revisionMutationLockDirPath(appData, revisionId);
+    const handle = await acquireDirLock(lockDir);
+    try {
+        return await operation();
+    }
+    finally {
+        await handle.release();
+    }
+}
+function root(appData) {
+    if (!appData.artifactRevisions)
+        throw new Error("artifact revision root unavailable");
+    return assertSafeAppDataPath(appData.root, appData.artifactRevisions);
+}
+function dir(appData, revisionId) {
+    if (!/^[a-f0-9]{32}$/.test(revisionId))
+        throw new Error("invalid revision id");
+    return assertSafeAppDataPath(root(appData), path.join(root(appData), revisionId));
+}
+function metadataPath(appData, revisionId) {
+    return path.join(dir(appData, revisionId), "metadata.json");
+}
+export function artifactRevisionUploadPath(appData, candidateSha256) {
+    if (!/^[a-f0-9]{64}$/.test(candidateSha256)) {
+        throw new Error("invalid candidate upload hash");
+    }
+    const uploadsDir = assertSafeAppDataPath(root(appData), path.join(root(appData), "uploads"));
+    return assertSafeAppDataPath(uploadsDir, path.join(uploadsDir, `${candidateSha256}.bin`));
+}
+export async function totalArtifactRevisionStagingBytes(appData) {
+    let total = 0;
+    const stagingRoot = root(appData);
+    async function addFile(target) {
+        const stat = await lstat(target).catch(() => undefined);
+        if (stat?.isFile())
+            total += stat.size;
+    }
+    const uploadsDir = path.join(stagingRoot, "uploads");
+    const uploadsStat = await lstat(uploadsDir).catch(() => undefined);
+    if (uploadsStat?.isDirectory()) {
+        for (const entry of await readdir(uploadsDir)) {
+            if (!/^[a-f0-9]{64}\.bin$/.test(entry))
+                continue;
+            await addFile(path.join(uploadsDir, entry));
+        }
+    }
+    for (const name of await readdir(stagingRoot)) {
+        if (!/^[a-f0-9]{32}$/.test(name))
+            continue;
+        await addFile(path.join(stagingRoot, name, "candidate.bin"));
+    }
+    return total;
+}
+function assertStagingQuota(input) {
+    const quota = input.quotaBytes ?? ARTIFACT_REVISION_STAGING_QUOTA_BYTES;
+    if (!Number.isSafeInteger(quota) || quota < 1)
+        throw new Error("invalid staging quota");
+    if (input.incomingBytes > quota) {
+        throw new Error("ARTIFACT_REVISION_QUOTA_EXCEEDED: candidate exceeds staging quota");
+    }
+}
+export async function writeArtifactRevisionUpload(input) {
+    return withRepoStagingLock(input.appData, async () => {
+        const actual = createHash("sha256").update(input.candidateBytes).digest("hex");
+        if (actual !== input.candidateSha256) {
+            throw new Error("ARTIFACT_REVISION_DRIFT: candidate hash mismatch");
+        }
+        const uploadPath = artifactRevisionUploadPath(input.appData, input.candidateSha256);
+        // Idempotent upload (SF6): if the exact candidate already exists in the
+        // uploads dir, a retry of the same request must not consume quota again —
+        // the bytes are already accounted for. This prevents a spurious quota
+        // error when an idempotent retry arrives near the staging limit.
+        const existing = await lstat(uploadPath).catch(() => undefined);
+        if (existing) {
+            const existingBytes = await readFileBoundarySafe({
+                boundaryRoot: path.dirname(uploadPath),
+                targetPath: uploadPath,
+                label: "artifact revision upload",
+            });
+            if (createHash("sha256").update(existingBytes).digest("hex") !== input.candidateSha256) {
+                throw new Error("ARTIFACT_REVISION_DRIFT: existing staged upload hash mismatch");
+            }
+            return uploadPath;
+        }
+        assertStagingQuota({
+            appData: input.appData,
+            incomingBytes: input.candidateBytes.byteLength,
+            quotaBytes: input.quotaBytes,
+        });
+        const stagedBytes = await totalArtifactRevisionStagingBytes(input.appData);
+        const quota = input.quotaBytes ?? ARTIFACT_REVISION_STAGING_QUOTA_BYTES;
+        if (stagedBytes + input.candidateBytes.byteLength > quota) {
+            throw new Error("ARTIFACT_REVISION_QUOTA_EXCEEDED: repo staging quota exhausted");
+        }
+        ensureSecureDir(path.dirname(uploadPath));
+        await writeFile(uploadPath, input.candidateBytes, { flag: "wx", mode: 0o600 });
+        return uploadPath;
+    });
+}
+export async function createArtifactRevision(input) {
+    return withRepoStagingLock(input.appData, async () => {
+        const revisionId = randomBytes(16).toString("hex");
+        const revisionDir = dir(input.appData, revisionId);
+        ensureSecureDir(revisionDir);
+        const now = input.now ?? new Date();
+        const ttlMs = input.ttlMs ?? DEFAULT_ARTIFACT_REVISION_TTL_MS;
+        if (!Number.isSafeInteger(ttlMs) || ttlMs < 1)
+            throw new Error("invalid revision TTL");
+        assertStagingQuota({
+            appData: input.appData,
+            incomingBytes: input.candidateBytes.byteLength,
+            quotaBytes: input.quotaBytes,
+        });
+        const stagedBytes = await totalArtifactRevisionStagingBytes(input.appData);
+        const quota = input.quotaBytes ?? ARTIFACT_REVISION_STAGING_QUOTA_BYTES;
+        if (stagedBytes + input.candidateBytes.byteLength > quota) {
+            throw new Error("ARTIFACT_REVISION_QUOTA_EXCEEDED: repo staging quota exhausted");
+        }
+        const stagingPath = `artifact-revisions/${revisionId}/candidate.bin`;
+        const described = validateAndDescribeArtifactRevision({
+            revisionId,
+            parentRunId: input.parentRunId,
+            producerNodeId: input.producerNodeId,
+            declaration: input.declaration,
+            parentSha256: input.parentSha256,
+            parentBytes: input.parentBytes,
+            candidateBytes: input.candidateBytes,
+            mediaType: input.mediaType,
+            stagingPath,
+            uploadedAt: now.toISOString(),
+            expiresAt: new Date(now.getTime() + ttlMs).toISOString(),
+            ...(input.artifactSchemaResolver
+                ? { artifactSchemaResolver: input.artifactSchemaResolver }
+                : {}),
+        });
+        await writeFile(path.join(revisionDir, "candidate.bin"), input.candidateBytes, {
+            flag: "wx",
+            mode: 0o600,
+        });
+        if (described.diffPreview) {
+            await writeFile(path.join(revisionDir, "diff.txt"), described.diffPreview, {
+                flag: "wx",
+                mode: 0o600,
+            });
+        }
+        await writeSecureJson(metadataPath(input.appData, revisionId), described.revision);
+        return described.revision;
+    });
+}
+export async function readArtifactRevision(appData, revisionId) {
+    const raw = await readJsonIfExists(metadataPath(appData, revisionId));
+    if (raw === undefined)
+        return undefined;
+    return artifactRevisionV1Schema.parse(raw);
+}
+/**
+ * Explicit staging lease (M4c). A fresh lease held by another holder blocks
+ * conflicting mutations with LEASE_HELD; the same holder may renew (sliding
+ * TTL); a stale/expired lease is taken over. Recorded in metadata.json so a
+ * crashed holder stays visible until the TTL lapses.
+ */
+export async function acquireArtifactRevisionLease(input) {
+    return withRevisionMutationLock(input.appData, input.revisionId, async () => {
+        const current = await readArtifactRevision(input.appData, input.revisionId);
+        if (!current || current.state !== "validated") {
+            throw new Error("ARTIFACT_REVISION_EXPIRED");
+        }
+        const now = input.now ?? new Date();
+        const ttlMs = input.ttlMs ?? DEFAULT_REVISION_LEASE_TTL_MS;
+        if (!Number.isSafeInteger(ttlMs) || ttlMs < 1)
+            throw new Error("invalid lease TTL");
+        const existing = current.lease;
+        if (existing && Date.parse(existing.expiresAt) > now.getTime() && existing.holder !== input.holder) {
+            throw new Error("LEASE_HELD");
+        }
+        const leased = artifactRevisionV1Schema.parse({
+            ...current,
+            lease: {
+                holder: input.holder,
+                acquiredAt: now.toISOString(),
+                expiresAt: new Date(now.getTime() + ttlMs).toISOString(),
+            },
+        });
+        await writeSecureJson(metadataPath(input.appData, input.revisionId), leased);
+        return leased;
+    });
+}
+export async function releaseArtifactRevisionLease(input) {
+    return withRevisionMutationLock(input.appData, input.revisionId, async () => {
+        const current = await readArtifactRevision(input.appData, input.revisionId);
+        if (!current)
+            throw new Error("ARTIFACT_REVISION_EXPIRED");
+        if (!current.lease)
+            return current;
+        if (current.lease.holder !== input.holder)
+            throw new Error("LEASE_HELD");
+        const { lease: _released, ...withoutLease } = current;
+        const released = artifactRevisionV1Schema.parse(withoutLease);
+        await writeSecureJson(metadataPath(input.appData, input.revisionId), released);
+        return released;
+    });
+}
+export async function readArtifactRevisionCandidate(input) {
+    if (input.revision.state !== "validated")
+        throw new Error("ARTIFACT_REVISION_EXPIRED");
+    if (Date.parse(input.revision.expiresAt) <= (input.now ?? new Date()).getTime()) {
+        throw new Error("ARTIFACT_REVISION_EXPIRED");
+    }
+    const candidatePath = path.join(dir(input.appData, input.revision.revisionId), "candidate.bin");
+    // fd-based TOCTOU-safe read: open with O_NOFOLLOW and verify the opened fd
+    // (regular single-link) instead of lstat-then-readFile on the path. Map any
+    // path-safety rejection back to the stable ARTIFACT_REVISION_PATH_INVALID
+    // contract.
+    let bytes;
+    try {
+        bytes = await readFileBoundarySafe({
+            boundaryRoot: dir(input.appData, input.revision.revisionId),
+            targetPath: candidatePath,
+            label: `revision candidate ${input.revision.revisionId}`,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (/symlink|hardlink|single-link|regular|boundary|escap/i.test(message)) {
+            throw new Error("ARTIFACT_REVISION_PATH_INVALID");
+        }
+        throw error;
+    }
+    const actual = await import("node:crypto").then(({ createHash }) => createHash("sha256").update(bytes).digest("hex"));
+    if (actual !== input.revision.candidate.sha256 || bytes.byteLength !== input.revision.candidate.bytes) {
+        throw new Error("ARTIFACT_REVISION_DRIFT");
+    }
+    return bytes;
+}
+export function buildArtifactOverrideSet(revision) {
+    const overrides = [{
+            revisionId: revision.revisionId,
+            parentArtifact: {
+                runId: revision.parent.runId,
+                nodeId: revision.parent.nodeId,
+                path: revision.parent.artifactPath,
+                sha256: revision.parent.artifactSha256,
+            },
+            replacement: {
+                sha256: revision.candidate.sha256,
+                bytes: revision.candidate.bytes,
+                mediaType: revision.candidate.mediaType,
+            },
+            supersedes: revision.parent.artifactSha256,
+        }];
+    return { schemaVersion: 1, overrides, overrideSetHash: computeOverrideSetHash(overrides) };
+}
+export async function consumeArtifactRevision(input) {
+    return withRevisionMutationLock(input.appData, input.revisionId, async () => {
+        const current = await readArtifactRevision(input.appData, input.revisionId);
+        if (!current || current.state !== "validated")
+            throw new Error("ARTIFACT_REVISION_EXPIRED");
+        const now = input.now ?? new Date();
+        const existing = current.lease;
+        if (existing &&
+            Date.parse(existing.expiresAt) > now.getTime() &&
+            existing.holder !== (input.holder ?? "cli-mutation")) {
+            throw new Error("LEASE_HELD");
+        }
+        if (current.candidate.sha256 !== input.expectedSha256)
+            throw new Error("ARTIFACT_REVISION_DRIFT");
+        // Terminal states must never keep a live staging lock.
+        const consumed = artifactRevisionV1Schema.parse({
+            ...current,
+            state: "consumed",
+            lease: undefined,
+        });
+        await writeSecureJson(metadataPath(input.appData, input.revisionId), consumed);
+        return consumed;
+    });
+}
+export async function discardArtifactRevision(input) {
+    return withRevisionMutationLock(input.appData, input.revisionId, async () => {
+        const current = await readArtifactRevision(input.appData, input.revisionId);
+        if (!current)
+            throw new Error("ARTIFACT_REVISION_EXPIRED");
+        const now = input.now ?? new Date();
+        if (current.state === "discarded")
+            return current;
+        if (current.state === "consumed")
+            throw new Error("ARTIFACT_REVISION_ALREADY_CONSUMED");
+        const existing = current.lease;
+        if (existing &&
+            Date.parse(existing.expiresAt) > now.getTime() &&
+            existing.holder !== (input.holder ?? "cli-mutation")) {
+            throw new Error("LEASE_HELD");
+        }
+        const discarded = artifactRevisionV1Schema.parse({
+            ...current,
+            state: "discarded",
+            lease: undefined,
+        });
+        await writeSecureJson(metadataPath(input.appData, input.revisionId), discarded);
+        await Promise.all([
+            rm(path.join(dir(input.appData, input.revisionId), "candidate.bin"), { force: true }),
+            rm(path.join(dir(input.appData, input.revisionId), "diff.txt"), { force: true }),
+        ]);
+        return discarded;
+    });
+}
+export async function reconcileArtifactRevisions(input) {
+    ensureSecureDir(root(input.appData));
+    const now = input.now ?? new Date();
+    const removed = [];
+    for (const name of await readdir(root(input.appData))) {
+        if (!/^[a-f0-9]{32}$/.test(name))
+            continue;
+        const revision = await readArtifactRevision(input.appData, name).catch(() => undefined);
+        if (!revision || Date.parse(revision.expiresAt) <= now.getTime()) {
+            await rm(dir(input.appData, name), { recursive: true, force: true });
+            removed.push(name);
+        }
+    }
+    const uploadsDir = path.join(root(input.appData), "uploads");
+    const uploadsBefore = await lstat(uploadsDir).catch(() => undefined);
+    if (uploadsBefore?.isDirectory()) {
+        const cutoff = now.getTime() - DEFAULT_ARTIFACT_REVISION_TTL_MS;
+        for (const entry of await readdir(uploadsDir)) {
+            if (!/^[a-f0-9]{64}\.bin$/.test(entry))
+                continue;
+            const stat = await lstat(path.join(uploadsDir, entry)).catch(() => undefined);
+            if (!stat?.isFile() || stat.mtimeMs > cutoff)
+                continue;
+            await rm(path.join(uploadsDir, entry), { force: true });
+            removed.push(`uploads/${entry}`);
+        }
+    }
+    // Sweep orphaned staging-lock tombstones (takeover `.tomb` and release
+    // `.release` dirs left behind by a race) once they are older than the
+    // default TTL. Tombstones are never the live lock path.
+    const cutoff = now.getTime() - DEFAULT_ARTIFACT_REVISION_TTL_MS;
+    for (const entry of await readdir(root(input.appData))) {
+        if (!/^\.staging-lock\..+\.(?:tomb|release)$/.test(entry))
+            continue;
+        const stat = await lstat(path.join(root(input.appData), entry)).catch(() => undefined);
+        if (!stat?.isDirectory() || stat.mtimeMs > cutoff)
+            continue;
+        await rm(path.join(root(input.appData), entry), { recursive: true, force: true });
+        removed.push(`lock/${entry}`);
+    }
+    // Sweep orphaned per-revision mutation lock dirs (crashed holder) once they
+    // are older than the default TTL. The per-revision lock path is stable
+    // (`locks/<revisionId>.lock`); a fresh lock is never swept.
+    const locksDir = path.join(root(input.appData), "locks");
+    const locksStat = await lstat(locksDir).catch(() => undefined);
+    if (locksStat?.isDirectory()) {
+        for (const entry of await readdir(locksDir)) {
+            if (!/^[a-f0-9]{32}\.lock$/.test(entry))
+                continue;
+            const lockPath = path.join(locksDir, entry);
+            const stat = await lstat(lockPath).catch(() => undefined);
+            if (!stat?.isDirectory() || !await isDirLockStale(lockPath, DEFAULT_ARTIFACT_REVISION_TTL_MS, now.getTime()))
+                continue;
+            await rm(lockPath, { recursive: true, force: true });
+            removed.push(`lock/${entry}`);
+        }
+    }
+    return removed;
+}

package/dist/infrastructure/console/context-export-store.js

@@ -0,0 +1,160 @@
+import { randomBytes } from "node:crypto";
+import { constants } from "node:fs";
+import { chmod, mkdir, open, readdir, rm, writeFile, } from "node:fs/promises";
+import path from "node:path";
+import { assertSafeAppDataPath, ensureSecureDir, readJsonIfExists, writeSecureJson, } from "./app-data.js";
+export const DEFAULT_CONTEXT_EXPORT_TTL_MS = 60 * 60 * 1000;
+export const DEFAULT_CONTEXT_EXPORT_LEASE_TTL_MS = 5 * 60 * 1000;
+export const CONTEXT_EXPORT_SCHEMA_VERSION = 1;
+const exportWriteChains = new Map();
+function serializeExport(exportId, operation) {
+    const previous = exportWriteChains.get(exportId) ?? Promise.resolve();
+    const next = previous.then(operation, operation);
+    exportWriteChains.set(exportId, next.then(() => undefined, () => undefined));
+    return next;
+}
+function exportRoot(appData) {
+    const root = appData.contextExports;
+    if (!root)
+        throw new Error("console context export root unavailable");
+    return assertSafeAppDataPath(appData.root, root);
+}
+function exportDir(appData, exportId) {
+    if (!/^[a-f0-9]{32}$/.test(exportId))
+        throw new Error("invalid context export id");
+    return assertSafeAppDataPath(exportRoot(appData), path.join(exportRoot(appData), exportId));
+}
+function metadataPath(appData, exportId) {
+    return path.join(exportDir(appData, exportId), "metadata.json");
+}
+export async function createContextExport(input) {
+    const now = input.now ?? new Date();
+    const ttlMs = input.ttlMs ?? DEFAULT_CONTEXT_EXPORT_TTL_MS;
+    if (!Number.isSafeInteger(ttlMs) || ttlMs < 1)
+        throw new Error("invalid context export TTL");
+    const exportId = randomBytes(16).toString("hex");
+    const dir = exportDir(input.appData, exportId);
+    ensureSecureDir(dir);
+    const payloadPath = assertSafeAppDataPath(dir, path.join(dir, "bundle.zip"));
+    await writeFile(payloadPath, input.bundle.zipBytes, {
+        flag: "wx",
+        mode: 0o600,
+    });
+    await chmod(payloadPath, 0o600).catch(() => undefined);
+    const record = {
+        schemaVersion: CONTEXT_EXPORT_SCHEMA_VERSION,
+        exportId,
+        repoFingerprint: input.appData.fingerprint,
+        bundleId: input.bundle.manifest.bundleId,
+        bundleSha256: input.bundle.manifest.bundleSha256,
+        profile: input.bundle.manifest.profile,
+        target: input.bundle.manifest.target,
+        state: "ready",
+        createdAt: now.toISOString(),
+        expiresAt: new Date(now.getTime() + ttlMs).toISOString(),
+        bytes: input.bundle.zipBytes.byteLength,
+    };
+    await writeSecureJson(metadataPath(input.appData, exportId), record);
+    return record;
+}
+export async function readContextExport(appData, exportId) {
+    return readJsonIfExists(metadataPath(appData, exportId));
+}
+export async function acquireContextExportLease(input) {
+    return serializeExport(input.exportId, async () => {
+        const now = input.now ?? new Date();
+        const leaseTtlMs = input.leaseTtlMs ?? DEFAULT_CONTEXT_EXPORT_LEASE_TTL_MS;
+        if (!Number.isSafeInteger(leaseTtlMs) || leaseTtlMs < 1) {
+            throw new Error("invalid context export lease TTL");
+        }
+        const record = await readContextExport(input.appData, input.exportId);
+        if (!record || record.repoFingerprint !== input.appData.fingerprint) {
+            throw new Error("context export not found");
+        }
+        const expiresAt = Date.parse(record.expiresAt);
+        if (record.state !== "ready" ||
+            !Number.isFinite(expiresAt) ||
+            expiresAt <= now.getTime()) {
+            throw new Error("context export expired");
+        }
+        if (record.lease) {
+            const acquiredAt = Date.parse(record.lease.acquiredAt);
+            if (Number.isFinite(acquiredAt) &&
+                acquiredAt + leaseTtlMs > now.getTime()) {
+                throw new Error("context export already leased");
+            }
+        }
+        const payloadPath = path.join(exportDir(input.appData, input.exportId), "bundle.zip");
+        const handle = await open(payloadPath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        let bytes;
+        try {
+            const stat = await handle.stat();
+            if (!stat.isFile() || stat.nlink !== 1) {
+                throw new Error("context export payload is not an owned regular file");
+            }
+            bytes = await handle.readFile();
+        }
+        finally {
+            await handle.close();
+        }
+        const leaseId = randomBytes(16).toString("hex");
+        const leased = {
+            ...record,
+            lease: { leaseId, acquiredAt: now.toISOString() },
+        };
+        await writeSecureJson(metadataPath(input.appData, input.exportId), leased);
+        return { record: leased, leaseId, bytes };
+    });
+}
+export async function releaseContextExportLease(input) {
+    await serializeExport(input.exportId, async () => {
+        const record = await readContextExport(input.appData, input.exportId);
+        if (!record?.lease || record.lease.leaseId !== input.leaseId)
+            return;
+        const { lease: _lease, ...released } = record;
+        await writeSecureJson(metadataPath(input.appData, input.exportId), released);
+    });
+}
+export async function reconcileContextExports(input) {
+    const root = exportRoot(input.appData);
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    const now = input.now ?? new Date();
+    const leaseTtlMs = input.leaseTtlMs ?? DEFAULT_CONTEXT_EXPORT_LEASE_TTL_MS;
+    if (!Number.isSafeInteger(leaseTtlMs) || leaseTtlMs < 1) {
+        throw new Error("invalid context export lease TTL");
+    }
+    const removed = [];
+    const retainedLeased = [];
+    for (const name of await readdir(root)) {
+        if (!/^[a-f0-9]{32}$/.test(name))
+            continue;
+        const record = await readContextExport(input.appData, name).catch(() => undefined);
+        let reconciledRecord = record;
+        if (record?.lease) {
+            const acquiredAt = Date.parse(record.lease.acquiredAt);
+            if (Number.isFinite(acquiredAt) &&
+                acquiredAt + leaseTtlMs > now.getTime()) {
+                retainedLeased.push(name);
+                continue;
+            }
+            const { lease: _lease, ...released } = record;
+            reconciledRecord = released;
+        }
+        const expiresAt = reconciledRecord
+            ? Date.parse(reconciledRecord.expiresAt)
+            : Number.NaN;
+        if (!reconciledRecord ||
+            !Number.isFinite(expiresAt) ||
+            expiresAt <= now.getTime()) {
+            await rm(exportDir(input.appData, name), {
+                recursive: true,
+                force: true,
+            });
+            removed.push(name);
+        }
+        else if (record?.lease) {
+            await writeSecureJson(metadataPath(input.appData, name), reconciledRecord);
+        }
+    }
+    return { removed, retainedLeased };
+}