@wardby/cli 0.6.0 → 0.7.0

package/dist/native-worker/worker.js

@@ -10,6 +10,7 @@ import { NativeEngine } from "../core/engine-native.js";
 import { computeCost } from "../providers/llm/pricing-core.js";
 import { PRIVILEGED_BRIDGE_NAMES } from "../sandbox/host-functions.js";
 import { runUserToolCall } from "../sandbox/user-tool.js";
+import { rememberSecretValue } from "./stderr-redaction.js";
 import { GatewayError, NATIVE_WORKER_PROTOCOL_VERSION, } from "./protocol.js";
 const isPending = (value) => typeof value === "object" && value !== null && value.pending === true;
 /** Runs one native run to its result and reports it with `finish`. Resolves when done. */
@@ -54,7 +55,11 @@ export async function runNativeWorker(input, transport) {
             bridge,
             async (argsJson) => {
                 try {
-                    return await call("host.call", { tool, invocation, bridge, argsJson });
+                    const result = await call("host.call", { tool, invocation, bridge, argsJson });
+                    // A secret value now lives in this process: keep it out of everything it writes to stderr.
+                    if (bridge === "__bridge_secretsGet" && typeof result === "string")
+                        rememberSecretValue(result);
+                    return result;
                 }
                 catch (err) {
                     // A bridge failure reaches the tool as the same error message it would see in-process.
@@ -103,7 +108,28 @@ export async function runNativeWorker(input, transport) {
             await call("progress", { turns: progress.turns, usage: progress.usage });
         },
     };
-    const result = await new NativeEngine().run(ctx);
+    let result;
+    try {
+        result = await new NativeEngine().run(ctx);
+    }
+    catch (err) {
+        // A gateway failure (a delegation that could not be created, say) ends the run as failed with
+        // its code, not as an opaque worker exit. run_not_drivable means the run already ended.
+        if (!(err instanceof GatewayError) || err.code === "run_not_drivable")
+            throw err;
+        await textSent;
+        await call("finish", {
+            status: "failed",
+            finalText: "",
+            turns: 0,
+            // `internal` wraps raw exception text on some transports, so only its code (and the cause
+            // code the gateway carried with it, if any) is persisted, never its message.
+            error: err.code === "internal"
+                ? `native_sandbox_gateway_error: internal${err.causeCode ? `: ${err.causeCode}` : ""}`
+                : `native_sandbox_gateway_error: ${err.code}: ${err.message.slice(0, 1024)}`,
+        });
+        return;
+    }
     // Live text reaches observers before the run is reported finished.
     await textSent;
     await call("finish", {

package/dist/observability/metrics.js

@@ -133,8 +133,13 @@ export class WardbyMetrics {
     }
     observeProxyAudit = (event) => {
         this.proxyAuditEvents.inc({ event: event.type });
-        if (event.reservationUsd !== undefined)
+        // A completed reply repeats its request's hold (for the overshoot audit): count it once, when held.
+        // A refused request carries the hold that did not fit, which was never reserved.
+        if (event.reservationUsd !== undefined &&
+            event.type !== "response.completed" &&
+            event.type !== "request.rejected") {
             this.proxyBudgetReserved.inc(event.reservationUsd);
+        }
         if (event.type !== "response.completed")
             return;
         if (event.costUsd !== undefined)

package/dist/providers/auth/self-hosted.d.ts

@@ -54,8 +54,8 @@ export declare class SelfHostedAuthProvider implements AuthProvider {
             id: string;
             state: string | null;
             resource: string;
-            clientId: string;
             expiresAt: Date;
+            clientId: string;
             consumedAt: Date | null;
             redirectUri: string;
             codeChallenge: string;

package/dist/providers/coding-proxy/dependency-cache/eviction.d.ts

@@ -0,0 +1,29 @@
+import type { BlobStore } from "../../storage/types.js";
+import type { DependencyCacheStore, EvictionRow } from "./store.js";
+/** How often the proxy runs an eviction pass. */
+export declare const DEFAULT_EVICTION_INTERVAL_MS: number;
+export interface EvictionLimits {
+    maxAgeMs: number;
+    repoCapBytes: number;
+    totalCapBytes: number;
+}
+/** The snapshots to evict, in the order to evict them. */
+export declare function selectEvictions(rows: readonly EvictionRow[], limits: EvictionLimits, now: Date): EvictionRow[];
+export interface EvictionOptions {
+    store: DependencyCacheStore;
+    blobs: Pick<BlobStore, "delete">;
+    limits: EvictionLimits;
+    now?: () => Date;
+}
+/** One eviction pass; `ran` is false when another holder had the lock. */
+export declare function runEviction(options: EvictionOptions): Promise<{
+    ran: boolean;
+    deleted: number;
+    failed: number;
+}>;
+/** Runs an eviction pass every `intervalMs` (the first one interval after start). */
+export declare function startEviction(options: EvictionOptions & {
+    intervalMs?: number;
+}): {
+    stop(): void;
+};

package/dist/providers/coding-proxy/dependency-cache/eviction.js

@@ -0,0 +1,87 @@
+/**
+ * Dependency cache eviction: a periodic pass inside the proxy, coordinated
+ * across replicas by a Postgres advisory lock (the store's
+ * withEvictionLock). It removes snapshots past the maximum age (by creation,
+ * so every snapshot is rebuilt at least that often), then the least recently
+ * used beyond each repository's cap, then beyond the total cap. A blob is
+ * deleted before its row, so a failed blob delete leaves the row for the next
+ * pass to retry rather than an orphaned blob.
+ */
+import { logger } from "../../../core/logger.js";
+const evictionLog = logger.child({ module: "dependency-cache" });
+/** How often the proxy runs an eviction pass. */
+export const DEFAULT_EVICTION_INTERVAL_MS = 60 * 60_000;
+const leastRecentlyUsed = (a, b) => a.lastUsedAt.getTime() - b.lastUsedAt.getTime() || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+/** The snapshots to evict, in the order to evict them. */
+export function selectEvictions(rows, limits, now) {
+    const cutoff = now.getTime() - limits.maxAgeMs;
+    const evicted = rows
+        .filter((row) => row.createdAt.getTime() <= cutoff)
+        .sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime() || leastRecentlyUsed(a, b));
+    let kept = rows.filter((row) => row.createdAt.getTime() > cutoff);
+    const byRepository = new Map();
+    for (const row of kept)
+        byRepository.set(row.repository, [...(byRepository.get(row.repository) ?? []), row]);
+    const overRepoCap = new Set();
+    for (const repoRows of byRepository.values()) {
+        let total = repoRows.reduce((sum, row) => sum + row.sizeBytes, 0);
+        for (const row of [...repoRows].sort(leastRecentlyUsed)) {
+            if (total <= limits.repoCapBytes)
+                break;
+            evicted.push(row);
+            overRepoCap.add(row.id);
+            total -= row.sizeBytes;
+        }
+    }
+    kept = kept.filter((row) => !overRepoCap.has(row.id));
+    let total = kept.reduce((sum, row) => sum + row.sizeBytes, 0);
+    for (const row of [...kept].sort(leastRecentlyUsed)) {
+        if (total <= limits.totalCapBytes)
+            break;
+        evicted.push(row);
+        total -= row.sizeBytes;
+    }
+    return evicted;
+}
+/** One eviction pass; `ran` is false when another holder had the lock. */
+export async function runEviction(options) {
+    const result = { ran: false, deleted: 0, failed: 0 };
+    result.ran = await options.store.withEvictionLock(async () => {
+        const rows = await options.store.listForEviction();
+        for (const row of selectEvictions(rows, options.limits, (options.now ?? (() => new Date()))())) {
+            try {
+                await options.blobs.delete(row.blobKey);
+            }
+            catch (error) {
+                result.failed += 1;
+                evictionLog.warn({ event: "dependency_cache.evict_blob_failed", snapshotId: row.id, err: error }, "dependency cache: a snapshot's blob could not be deleted; the next pass retries");
+                continue;
+            }
+            await options.store.delete(row.id);
+            result.deleted += 1;
+        }
+    });
+    return result;
+}
+/** Runs an eviction pass every `intervalMs` (the first one interval after start). */
+export function startEviction(options) {
+    let running = false;
+    const timer = setInterval(() => {
+        if (running)
+            return;
+        running = true;
+        runEviction(options)
+            .then((result) => {
+            if (result.deleted > 0 || result.failed > 0)
+                evictionLog.info({ event: "dependency_cache.evicted", deleted: result.deleted, failed: result.failed }, "dependency cache eviction pass");
+        })
+            .catch((error) => {
+            evictionLog.warn({ event: "dependency_cache.evict_failed", err: error }, "dependency cache eviction failed");
+        })
+            .finally(() => {
+            running = false;
+        });
+    }, options.intervalMs ?? DEFAULT_EVICTION_INTERVAL_MS);
+    timer.unref();
+    return { stop: () => clearInterval(timer) };
+}

package/dist/providers/coding-proxy/dependency-cache/key.d.ts

@@ -0,0 +1,33 @@
+/** The only ecosystem the cache serves today. */
+export declare const DEPENDENCY_CACHE_ECOSYSTEM = "npm";
+/** Lockfile hashes one session may hold (plans beyond this are not recorded). */
+export declare const MAX_DEPENDENCY_CACHE_LOCK_HASHES = 8;
+export declare function sha256Hex(data: string | Uint8Array): string;
+/** JSON with object keys sorted, so equal values always serialize alike. */
+export declare function canonicalJson(value: unknown): string;
+export declare function isLockHash(value: string): boolean;
+/**
+ * The project folder relative to the repository root, or null when it is not
+ * acceptable: "." (or absent) is the root; otherwise 1-3 plain segments, none
+ * empty, none starting with a dot, none named node_modules.
+ */
+export declare function parseProjectPath(raw: string | null | undefined): string | null;
+export interface SnapshotKeyParts {
+    repository: string;
+    projectPath: string;
+    lockHash: string;
+    workerImage: string;
+}
+export interface SnapshotKey extends SnapshotKeyParts {
+    ecosystem: string;
+    /** The opaque id a worker downloads the derived key by: sha256 of the canonical identity tuple. */
+    keyId: string;
+}
+export declare function deriveSnapshotKey(parts: SnapshotKeyParts): SnapshotKey;
+/**
+ * A fresh blob key for one upload of `key`. Each upload writes its own object
+ * (the random suffix), so a concurrent or refused upload can never replace
+ * the bytes of a snapshot already committed; a row always names the exact
+ * object its sha256 and size describe.
+ */
+export declare function newBlobKey(key: SnapshotKey): string;

package/dist/providers/coding-proxy/dependency-cache/key.js

@@ -0,0 +1,86 @@
+/**
+ * Dependency cache keys, derived only on the proxy. A worker names nothing
+ * in a key except its project folder (validated here); the lock hash comes
+ * from a lockfile plan the proxy approved, and the repository and image come
+ * from the run's own records.
+ *
+ * The agent's package policy is not part of a key. A snapshot's contents
+ * depend only on the lockfile and the image (`npm ci --ignore-scripts`
+ * installs exactly the lockfile's integrity-checked packages), and every
+ * restore already requires the proxy to have approved this run's lockfile
+ * under the restoring agent's current policy (the plan gate,
+ * `dependencyCacheLockHashes`). So a snapshot built under another policy, or
+ * by another agent on the same repository, restores only when today's policy
+ * approves the same lockfile.
+ */
+import { createHash, randomUUID } from "node:crypto";
+/** The only ecosystem the cache serves today. */
+export const DEPENDENCY_CACHE_ECOSYSTEM = "npm";
+/** Lockfile hashes one session may hold (plans beyond this are not recorded). */
+export const MAX_DEPENDENCY_CACHE_LOCK_HASHES = 8;
+const LOCK_HASH = /^[0-9a-f]{64}$/;
+/** A project-path segment: no leading dot (no `.`, `..` or dot-folder), no
+ *  separators, whitespace or control characters. */
+const PROJECT_SEGMENT = /^[A-Za-z0-9_@+-][A-Za-z0-9._@+-]{0,99}$/;
+const MAX_PROJECT_SEGMENTS = 3;
+export function sha256Hex(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map((item) => (item === undefined ? null : canonical(item)));
+    if (value !== null && typeof value === "object") {
+        const record = value;
+        // Code-unit order (the default sort), never locale order: the hash must
+        // be the same on every host.
+        return Object.fromEntries(Object.keys(record)
+            .filter((key) => record[key] !== undefined)
+            .sort()
+            .map((key) => [key, canonical(record[key])]));
+    }
+    return value;
+}
+/** JSON with object keys sorted, so equal values always serialize alike. */
+export function canonicalJson(value) {
+    return JSON.stringify(canonical(value)) ?? "null";
+}
+export function isLockHash(value) {
+    return LOCK_HASH.test(value);
+}
+/**
+ * The project folder relative to the repository root, or null when it is not
+ * acceptable: "." (or absent) is the root; otherwise 1-3 plain segments, none
+ * empty, none starting with a dot, none named node_modules.
+ */
+export function parseProjectPath(raw) {
+    if (raw === undefined || raw === null || raw === ".")
+        return ".";
+    const segments = raw.split("/");
+    if (segments.length > MAX_PROJECT_SEGMENTS)
+        return null;
+    for (const segment of segments) {
+        if (!PROJECT_SEGMENT.test(segment) || segment === "node_modules")
+            return null;
+    }
+    return raw;
+}
+export function deriveSnapshotKey(parts) {
+    const identity = {
+        ecosystem: DEPENDENCY_CACHE_ECOSYSTEM,
+        repository: parts.repository,
+        projectPath: parts.projectPath,
+        lockHash: parts.lockHash,
+        workerImage: parts.workerImage,
+    };
+    return { ...identity, keyId: sha256Hex(canonicalJson(identity)) };
+}
+/**
+ * A fresh blob key for one upload of `key`. Each upload writes its own object
+ * (the random suffix), so a concurrent or refused upload can never replace
+ * the bytes of a snapshot already committed; a row always names the exact
+ * object its sha256 and size describe.
+ */
+export function newBlobKey(key) {
+    return (`dependency-cache/${key.ecosystem}/${sha256Hex(key.repository)}/${sha256Hex(key.projectPath).slice(0, 16)}/` +
+        `${key.lockHash}-${sha256Hex(key.workerImage).slice(0, 16)}-${randomUUID()}.tgz`);
+}

package/dist/providers/coding-proxy/dependency-cache/model-request-seal.d.ts

@@ -0,0 +1,18 @@
+import type { DependencyCacheStore } from "./store.js";
+/**
+ * Seals a run's dependency-cache session on its first model request: the agent exists from that
+ * request on, so the cache's pre-agent phase is over whatever the worker did (or failed to do).
+ * The workers run the cache before they create the agent (Codex: driver.ts runs it before
+ * startThread; Claude Code: driver.ts calls the prepare tool before createQuery), so no model
+ * request precedes it. The seal is idempotent and conditional (only an unsealed session of a run
+ * with the cache on), remembered per run in this process so it costs one write per run per proxy
+ * replica, and never fails the model request: a database error is logged and retried on the
+ * run's next request.
+ */
+export declare class ModelRequestSeal {
+    private readonly store;
+    private readonly now;
+    private readonly sealed;
+    constructor(store: Pick<DependencyCacheStore, "sealForModelRequest">, now?: () => Date);
+    onModelRequest(runId: string): Promise<void>;
+}

package/dist/providers/coding-proxy/dependency-cache/model-request-seal.js

@@ -0,0 +1,40 @@
+import { logger } from "../../../core/logger.js";
+const sealLog = logger.child({ module: "dependency-cache" });
+/** Runs remembered as sealed per proxy process; the oldest are forgotten past this (a re-seal is a no-op write). */
+const MAX_REMEMBERED_RUNS = 10_000;
+/**
+ * Seals a run's dependency-cache session on its first model request: the agent exists from that
+ * request on, so the cache's pre-agent phase is over whatever the worker did (or failed to do).
+ * The workers run the cache before they create the agent (Codex: driver.ts runs it before
+ * startThread; Claude Code: driver.ts calls the prepare tool before createQuery), so no model
+ * request precedes it. The seal is idempotent and conditional (only an unsealed session of a run
+ * with the cache on), remembered per run in this process so it costs one write per run per proxy
+ * replica, and never fails the model request: a database error is logged and retried on the
+ * run's next request.
+ */
+export class ModelRequestSeal {
+    store;
+    now;
+    sealed = new Set();
+    constructor(store, now = () => new Date()) {
+        this.store = store;
+        this.now = now;
+    }
+    async onModelRequest(runId) {
+        if (this.sealed.has(runId))
+            return;
+        try {
+            await this.store.sealForModelRequest(runId, this.now());
+        }
+        catch (error) {
+            sealLog.warn({ event: "dependency_cache.model_seal_failed", runId, err: error }, "dependency cache: seal on the run's model request failed");
+            return;
+        }
+        this.sealed.add(runId);
+        if (this.sealed.size > MAX_REMEMBERED_RUNS) {
+            const oldest = this.sealed.values().next().value;
+            if (oldest !== undefined)
+                this.sealed.delete(oldest);
+        }
+    }
+}

package/dist/providers/coding-proxy/dependency-cache/prisma-store.d.ts

@@ -0,0 +1,25 @@
+import { type PrismaClient } from "#prisma";
+import type { DependencyCacheSessionState } from "../registry/store.js";
+import { type DependencyCacheStore, type EvictionRow, type NewSnapshot, type SnapshotIdentity, type SnapshotRow, type SnapshotScope } from "./store.js";
+export declare class PrismaDependencyCacheStore implements DependencyCacheStore {
+    private readonly db;
+    constructor(db: PrismaClient);
+    session(runId: string): Promise<DependencyCacheSessionState | null>;
+    seal(runId: string, now: Date): Promise<void>;
+    sealForModelRequest(runId: string, now: Date): Promise<void>;
+    findByIdentity(identity: SnapshotIdentity): Promise<SnapshotRow | null>;
+    findNearest(scope: SnapshotScope, excludeLockHash: string): Promise<SnapshotRow | null>;
+    hasUploaded(runId: string, ecosystem: string, projectPath: string): Promise<boolean>;
+    insert(snapshot: NewSnapshot): Promise<"inserted" | "exists">;
+    touch(id: string, now: Date): Promise<void>;
+    delete(id: string): Promise<void>;
+    deleteIfBlob(id: string, blobKey: string): Promise<boolean>;
+    listForEviction(): Promise<EvictionRow[]>;
+    /**
+     * A transaction-scoped advisory lock: Postgres releases it when the
+     * transaction ends, so a crashed proxy never leaves it held. The work runs
+     * on the ordinary client (each delete commits at once); the transaction
+     * only holds the lock.
+     */
+    withEvictionLock(work: () => Promise<void>): Promise<boolean>;
+}

package/dist/providers/coding-proxy/dependency-cache/prisma-store.js

@@ -0,0 +1,131 @@
+import { Prisma } from "#prisma";
+import { POLICY_ANY, } from "./store.js";
+/** How long one eviction pass may hold the lock (its transaction) before Postgres releases it. */
+const EVICTION_LOCK_MS = 15 * 60_000;
+/**
+ * Only the scope's own fields (callers may pass a wider object, such as a
+ * derived key), plus the fixed POLICY_ANY every row is written and matched with.
+ */
+const scopeOf = ({ ecosystem, repository, projectPath, workerImage }) => ({
+    ecosystem,
+    repository,
+    projectPath,
+    workerImage,
+    policyHash: POLICY_ANY,
+});
+const toSnapshot = ({ policyHash: _policyHash, ...row }) => ({
+    ...row,
+    sizeBytes: Number(row.sizeBytes),
+    unpackedBytes: row.unpackedBytes === null ? null : Number(row.unpackedBytes),
+});
+export class PrismaDependencyCacheStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async session(runId) {
+        const session = await this.db.codingProxySession.findUnique({
+            where: { runId },
+            select: { dependencyCacheLockHashes: true, dependencyCacheSealedAt: true, createdAt: true },
+        });
+        return session
+            ? {
+                lockHashes: session.dependencyCacheLockHashes,
+                sealedAt: session.dependencyCacheSealedAt,
+                createdAt: session.createdAt,
+            }
+            : null;
+    }
+    async seal(runId, now) {
+        await this.db.codingProxySession.updateMany({
+            where: { runId, dependencyCacheSealedAt: null },
+            data: { dependencyCacheSealedAt: now },
+        });
+    }
+    async sealForModelRequest(runId, now) {
+        await this.db.codingProxySession.updateMany({
+            where: { runId, dependencyCacheSealedAt: null, run: { dependencyCache: true } },
+            data: { dependencyCacheSealedAt: now },
+        });
+    }
+    async findByIdentity(identity) {
+        const row = await this.db.dependencySnapshot.findUnique({
+            where: {
+                ecosystem_repository_projectPath_lockHash_workerImage_policyHash: {
+                    ...scopeOf(identity),
+                    lockHash: identity.lockHash,
+                },
+            },
+        });
+        return row ? toSnapshot(row) : null;
+    }
+    async findNearest(scope, excludeLockHash) {
+        const row = await this.db.dependencySnapshot.findFirst({
+            where: { ...scopeOf(scope), lockHash: { not: excludeLockHash } },
+            orderBy: [{ createdAt: "desc" }, { id: "desc" }],
+        });
+        return row ? toSnapshot(row) : null;
+    }
+    async hasUploaded(runId, ecosystem, projectPath) {
+        const row = await this.db.dependencySnapshot.findFirst({
+            where: { createdByRunId: runId, projectPath, ecosystem },
+            select: { id: true },
+        });
+        return row !== null;
+    }
+    async insert(snapshot) {
+        try {
+            await this.db.dependencySnapshot.create({
+                data: {
+                    ...scopeOf(snapshot),
+                    lockHash: snapshot.lockHash,
+                    blobKey: snapshot.blobKey,
+                    sha256: snapshot.sha256,
+                    sizeBytes: BigInt(snapshot.sizeBytes),
+                    archiveScanVersion: snapshot.archiveScanVersion,
+                    archiveEntries: snapshot.archiveEntries,
+                    unpackedBytes: snapshot.unpackedBytes === null ? null : BigInt(snapshot.unpackedBytes),
+                    createdByRunId: snapshot.createdByRunId,
+                },
+            });
+            return "inserted";
+        }
+        catch (error) {
+            if (error instanceof Prisma.PrismaClientKnownRequestError && error.code === "P2002")
+                return "exists";
+            throw error;
+        }
+    }
+    async touch(id, now) {
+        await this.db.dependencySnapshot.updateMany({ where: { id }, data: { lastUsedAt: now } });
+    }
+    async delete(id) {
+        await this.db.dependencySnapshot.deleteMany({ where: { id } });
+    }
+    async deleteIfBlob(id, blobKey) {
+        const { count } = await this.db.dependencySnapshot.deleteMany({ where: { id, blobKey } });
+        return count > 0;
+    }
+    async listForEviction() {
+        const rows = await this.db.dependencySnapshot.findMany({
+            select: { id: true, repository: true, blobKey: true, sizeBytes: true, createdAt: true, lastUsedAt: true },
+        });
+        return rows.map((row) => ({ ...row, sizeBytes: Number(row.sizeBytes) }));
+    }
+    /**
+     * A transaction-scoped advisory lock: Postgres releases it when the
+     * transaction ends, so a crashed proxy never leaves it held. The work runs
+     * on the ordinary client (each delete commits at once); the transaction
+     * only holds the lock.
+     */
+    async withEvictionLock(work) {
+        return this.db.$transaction(async (tx) => {
+            const [row] = await tx.$queryRaw `
+          SELECT pg_try_advisory_xact_lock(hashtext('wardby.dependency-cache-eviction')) AS locked`;
+            if (!row?.locked)
+                return false;
+            await work();
+            return true;
+        }, { maxWait: 10_000, timeout: EVICTION_LOCK_MS });
+    }
+}

package/dist/providers/coding-proxy/dependency-cache/service.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The coding proxy's dependency cache: `/cache/npm/*`, authenticated by the
+ * run's registry-only token.
+ *
+ * Trust rules (the whole point of this file):
+ * - Every key is derived here, from the run's records and a lockfile hash the
+ *   proxy computed while approving a plan for this session. A worker names
+ *   only its project folder, which is validated, and which lockfile (one of
+ *   the session's approved hashes) it is asking about.
+ * - Only trusted wardby code runs before the run's seal; the agent runs after
+ *   it with the same token. The worker seals before it starts the agent, and
+ *   the proxy seals on the run's first model request whatever the worker did
+ *   (ModelRequestSeal). After the seal every route except the (idempotent)
+ *   seal answers 409 `sealed`, and an upload still streaming when the seal
+ *   lands is discarded.
+ * - A run uploads at most once per project, only within its upload window,
+ *   and only for its derived key. Each upload writes its own blob object
+ *   (a unique key), so no upload can replace a committed snapshot's bytes;
+ *   an upload that does not end in its own row deletes its own object.
+ * - The sha256 is computed while the upload streams and stored in Postgres;
+ *   downloads carry it so the worker verifies before extracting.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type BlobStore } from "../../storage/types.js";
+import type { RegistryStore } from "../registry/store.js";
+import type { DependencyCacheStore } from "./store.js";
+/** Uploads streaming at once across every run. */
+export declare const DEFAULT_MAX_CONCURRENT_UPLOADS = 4;
+export interface DependencyCacheServiceOptions {
+    registry: Pick<RegistryStore, "findRunByRegistryTokenHash">;
+    store: DependencyCacheStore;
+    blobs: BlobStore;
+    maxSnapshotBytes: number;
+    uploadMs: number;
+    now?: () => Date;
+    maxConcurrentUploads?: number;
+}
+export declare class DependencyCacheService {
+    private readonly options;
+    readonly uploadMs: number;
+    private readonly now;
+    /** `runId\0projectPath` and key ids of uploads streaming right now (per replica). */
+    private readonly uploading;
+    private activeUploads;
+    constructor(options: DependencyCacheServiceOptions);
+    /**
+     * Answers one `/cache/...` request. `token` is the registry token the
+     * request carried. `releaseBodyTimer` lifts the server's per-request body
+     * timer; it is called only for an authenticated, eligible upload that holds
+     * its upload slot (the upload window bounds it from then on).
+     */
+    handle(request: IncomingMessage, response: ServerResponse, token: string, releaseBodyTimer?: () => void): Promise<void>;
+    private route;
+    /** When the run's upload window closes (epoch ms): the one deadline lookups report and uploads enforce. */
+    private uploadDeadline;
+    private lookup;
+    /**
+     * Serves the run's derived key (by its keyId) or the snapshot a lookup
+     * offers as nearest for the same project and lockfile, recomputed now with
+     * the same query: nothing is remembered between requests, and no other id
+     * is ever served.
+     */
+    private download;
+    /** Removes a snapshot whose blob failed its row's checksum, so the key can be rebuilt. */
+    private dropCorrupt;
+    private upload;
+    private storeUpload;
+    /** Removes an upload's own blob object (unique to the upload, so no row refers to it). */
+    private discard;
+}