@wardby/cli 0.6.0 → 0.7.0

package/dist/coding/transcript/resume/launch.js

@@ -0,0 +1,128 @@
+/**
+ * Starts Claude Code on the imported session:
+ *
+ *   claude --resume <session file> --mcp-config <stand-in config>
+ *          [--system-prompt-snapshot off] --append-system-prompt <move note>
+ *
+ * in the checkout. The MCP config starts the stand-in `wardby_tools` server
+ * (stand-in.ts) from this same wardby install, so the run's tool calls
+ * render and a call to run_command explains the move.
+ *
+ * System prompt flags on resume (Claude Code CLI reference, "System prompt
+ * flags in resumed conversations"): from v2.1.265 Claude Code records the
+ * system prompt on a conversation's first request and reuses it after
+ * --resume, so new flag text would apply only after compaction.
+ * `--system-prompt-snapshot off` (v2.1.257 and later) rebuilds the prompt on
+ * every request, so the note applies. Older versions did not record it
+ * while a system prompt flag was passed, so the note applies without it.
+ * When the version cannot be read, the flag is included (every current
+ * release has it) and the output says to remove it for a version before
+ * 2.1.257.
+ */
+import { execFile, spawn } from "node:child_process";
+import { constants } from "node:fs";
+import { open, rename } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomBytes } from "node:crypto";
+import { promisify } from "node:util";
+import { STAND_IN_SERVER_NAME } from "./stand-in.js";
+const execFileAsync = promisify(execFile);
+/** Where the run's commands ran in the worker (run_command's workspace, claude-tool-runner/main.mjs). */
+export const WORKER_WORKSPACE = "/workspace";
+/** First Claude Code version with --system-prompt-snapshot. */
+const SNAPSHOT_FLAG_SINCE = [2, 1, 257];
+/** This install's wardby entry point, for the MCP config to start the stand-in with. */
+export function wardbyBinPath() {
+    // src/coding/transcript/resume/ and dist/coding/transcript/resume/ are both four levels below the package root.
+    return fileURLToPath(new URL("../../../../bin/wardby.js", import.meta.url));
+}
+/**
+ * `runChanges`: true when the checkout is at the run's branch, false when it fell back to the base
+ * commit, undefined for --here (the importer did not choose what is checked out).
+ */
+export function moveNote(opts) {
+    const changes = opts.runChanges === true
+        ? "This checkout already contains the run's changes: do not redo them. "
+        : opts.runChanges === false
+            ? "This checkout is at the run's base commit: the run's changes are not in it. "
+            : "";
+    return (`This conversation was moved from wardby run ${opts.runId} to the user's machine. ` +
+        `The worker path ${opts.from} is now ${opts.checkout} (checked out at ${opts.ref}). ` +
+        changes +
+        `The run_command tool only worked inside the worker and is gone: use your local tools (Bash, Read, Edit) in ${opts.checkout}.`);
+}
+export function mcpConfig(opts) {
+    return {
+        mcpServers: {
+            [STAND_IN_SERVER_NAME]: {
+                type: "stdio",
+                command: opts.node ?? process.execPath,
+                args: [opts.bin ?? wardbyBinPath(), "resume-tools", "--checkout", opts.checkout, "--from", opts.from],
+            },
+        },
+    };
+}
+/** Writes the MCP config next to the session file (mode 0600, atomically). */
+export async function writeMcpConfig(dir, config) {
+    const path = join(dir, "mcp-config.json");
+    const temp = join(dir, `.mcp-config.${randomBytes(6).toString("hex")}.tmp`);
+    const handle = await open(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+    try {
+        await handle.writeFile(`${JSON.stringify(config, null, 2)}\n`);
+    }
+    finally {
+        await handle.close();
+    }
+    await rename(temp, path);
+    return path;
+}
+export function parseClaudeVersion(output) {
+    const match = /(\d+)\.(\d+)\.(\d+)/.exec(output);
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : undefined;
+}
+function atLeast(version, min) {
+    for (let i = 0; i < 3; i++)
+        if (version[i] !== min[i])
+            return version[i] > min[i];
+    return true;
+}
+/** `claude --version`, or undefined when claude is not on PATH. */
+export async function claudeVersion() {
+    try {
+        const { stdout } = await execFileAsync("claude", ["--version"], { timeout: 15_000 });
+        return stdout.trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+export const UNKNOWN_VERSION_NOTE = "Could not read the Claude Code version: the command includes --system-prompt-snapshot off (Claude Code 2.1.257 or later); remove that flag for an older version.";
+export function claudeArgs(opts) {
+    // Unknown version (claude missing or unparseable): include it, as every current release supports it.
+    const snapshot = !opts.version || atLeast(opts.version, SNAPSHOT_FLAG_SINCE) ? ["--system-prompt-snapshot", "off"] : [];
+    return [
+        "--resume",
+        opts.sessionFile,
+        "--mcp-config",
+        opts.mcpConfigPath,
+        ...snapshot,
+        "--append-system-prompt",
+        opts.note,
+    ];
+}
+/** POSIX shell quoting, for printing a command the user can paste. */
+export function shellQuote(arg) {
+    return /^[A-Za-z0-9_@%+=:,./-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+export function printableCommand(cwd, args) {
+    return `cd ${shellQuote(cwd)} && claude ${args.map(shellQuote).join(" ")}`;
+}
+/** Runs claude in the checkout with this terminal; resolves with its exit code. */
+export function launchClaude(cwd, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("claude", args, { cwd, stdio: "inherit" });
+        child.once("error", reject);
+        child.once("exit", (code, signal) => resolve(code ?? (signal ? 1 : 0)));
+    });
+}

package/dist/coding/transcript/resume/session-file.d.ts

@@ -0,0 +1,13 @@
+import { type DownloadedTranscript } from "./download.js";
+export declare function defaultSessionsRoot(): string;
+export interface SessionFile {
+    path: string;
+    /** The directory that holds the session file and the MCP config. */
+    dir: string;
+    /** "written": new; "same": identical file already there; "continued": a local continuation kept; "replaced": --force. */
+    outcome: "written" | "same" | "continued" | "replaced";
+}
+export declare function writeSessionFile(transcript: DownloadedTranscript, opts?: {
+    root?: string;
+    force?: boolean;
+}): Promise<SessionFile>;

package/dist/coding/transcript/resume/session-file.js

@@ -0,0 +1,79 @@
+/**
+ * Writes a downloaded transcript where `claude --resume <file>` can load it:
+ * `<root>/<runId>/<sessionId>.jsonl` (root: ~/.wardby/sessions), the body
+ * without wardby's header line, mode 0600, atomically (temp file + rename).
+ * Never writes into a Claude Code config directory, and never replaces a
+ * different file unless asked to.
+ */
+import { randomBytes } from "node:crypto";
+import { constants } from "node:fs";
+import { mkdir, open, readFile, rename, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { gunzip } from "node:zlib";
+import { parseTranscriptFile } from "../format.js";
+import { ResumeError } from "./download.js";
+const gunzipAsync = promisify(gunzip);
+const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const RUN_ID = /^[a-z0-9]{8,64}$/i;
+const MAX_BODY_BYTES = 64 * 1024 * 1024;
+export function defaultSessionsRoot() {
+    return join(homedir(), ".wardby", "sessions");
+}
+export async function writeSessionFile(transcript, opts = {}) {
+    const { meta } = transcript;
+    // Re-checked here: these name a path.
+    if (!RUN_ID.test(meta.runId) || !SESSION_ID.test(meta.sessionId)) {
+        throw new ResumeError("The server's response has invalid run details.");
+    }
+    let text;
+    try {
+        const raw = await gunzipAsync(transcript.gzip, { maxOutputLength: MAX_BODY_BYTES + 1024 * 1024 });
+        text = raw.toString("utf8");
+    }
+    catch {
+        throw new ResumeError("The downloaded transcript could not be decompressed.");
+    }
+    const file = parseTranscriptFile(text);
+    if (!file || file.header.sessionId !== meta.sessionId || file.header.status !== "ok" || !file.body) {
+        throw new ResumeError("The downloaded transcript is not one wardby resume can load.");
+    }
+    const body = Buffer.from(file.body, "utf8");
+    const dir = join(opts.root ?? defaultSessionsRoot(), meta.runId);
+    const path = join(dir, `${meta.sessionId}.jsonl`);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    let existing;
+    try {
+        existing = await readFile(path);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    if (existing) {
+        if (existing.equals(body))
+            return { path, dir, outcome: "same" };
+        // Claude Code appends the continued conversation to the file it resumed.
+        if (!opts.force && existing.byteLength > body.byteLength && existing.subarray(0, body.byteLength).equals(body)) {
+            return { path, dir, outcome: "continued" };
+        }
+        if (!opts.force) {
+            throw new ResumeError(`A different session file already exists at ${path}. Nothing was changed. Pass --force to replace it with the downloaded transcript.`);
+        }
+    }
+    const temp = join(dir, `.${meta.sessionId}.${randomBytes(6).toString("hex")}.tmp`);
+    const handle = await open(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+    try {
+        await handle.writeFile(body);
+        await handle.sync();
+    }
+    catch (error) {
+        await handle.close();
+        await rm(temp, { force: true });
+        throw error;
+    }
+    await handle.close();
+    await rename(temp, path);
+    return { path, dir, outcome: existing ? "replaced" : "written" };
+}

package/dist/coding/transcript/resume/stand-in.d.ts

@@ -0,0 +1,11 @@
+import { type McpServerFactory } from "@modelcontextprotocol/server";
+export declare const STAND_IN_SERVER_NAME = "wardby_tools";
+export interface StandInOptions {
+    /** The local checkout the session continues in. */
+    checkout: string;
+    /** The worker path the run's commands ran in. */
+    from: string;
+}
+export declare function movedMessage(opts: StandInOptions): string;
+export declare function standInFactory(opts: StandInOptions): McpServerFactory;
+export declare function resumeToolsCommand(argv: string[]): Promise<void>;

package/dist/coding/transcript/resume/stand-in.js

@@ -0,0 +1,49 @@
+/**
+ * The stand-in for a run's worker tool, started by `wardby resume` through
+ * the MCP config it writes: a stdio MCP server named `wardby_tools` that
+ * offers `run_command` with the worker's input schema, so a resumed session
+ * renders the run's calls. It runs nothing: every call answers with an error
+ * telling the model the session moved and to use its local tools.
+ *
+ *   wardby resume-tools --checkout <dir> --from <podPath>   (hidden; started by Claude Code)
+ */
+import { parseArgs } from "node:util";
+import { McpServer, fromJsonSchema } from "@modelcontextprotocol/server";
+import { serveStdio, StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+export const STAND_IN_SERVER_NAME = "wardby_tools";
+export function movedMessage(opts) {
+    return (`This session moved from a wardby worker. ${opts.from} is now ${opts.checkout}. ` +
+        `run_command only ran inside the worker; use your local tools (Bash, Read, Edit) in ${opts.checkout}.`);
+}
+/** The worker's run_command input schema (claude-tool-runner/main.mjs), so recorded calls still match it. */
+const RUN_COMMAND_SCHEMA = {
+    type: "object",
+    properties: {
+        command: { type: "string", minLength: 1 },
+        timeout_ms: { type: "integer" },
+    },
+    required: ["command"],
+};
+export function standInFactory(opts) {
+    return () => {
+        const server = new McpServer({ name: STAND_IN_SERVER_NAME, version: "1.0.0" });
+        server.registerTool("run_command", {
+            description: "Ran shell commands inside the wardby worker during the run. Not available locally: it runs nothing. Use your own tools.",
+            inputSchema: fromJsonSchema(RUN_COMMAND_SCHEMA),
+        }, () => ({ isError: true, content: [{ type: "text", text: movedMessage(opts) }] }));
+        return server;
+    };
+}
+export async function resumeToolsCommand(argv) {
+    const { values } = parseArgs({
+        args: argv,
+        options: { checkout: { type: "string" }, from: { type: "string" } },
+        strict: true,
+    });
+    if (!values.checkout || !values.from)
+        throw new Error("usage: wardby resume-tools --checkout <dir> --from <path>");
+    // Serves until Claude Code closes its end of stdin.
+    serveStdio(standInFactory({ checkout: values.checkout, from: values.from }), {
+        transport: new StdioServerTransport(),
+    });
+}

package/dist/coding-worker/artifact.d.ts

@@ -1,4 +1,4 @@
-import { type CodingAgentOutput } from "../coding/protocol.js";
+import { type CodingWorkerOutput } from "../coding/protocol.js";
 /**
  * Reads a regular file of at most `maxBytes`, refusing symlinks and anything
  * that is not a regular file.
@@ -12,9 +12,9 @@ import { type CodingAgentOutput } from "../coding/protocol.js";
  */
 export declare function readBoundedRegularFile(path: string, maxBytes: number, errorCode: string): Promise<string>;
 export declare function readCodingInput(path: string): Promise<{
-    repository: string;
     schemaVersion: 1;
     runId: string;
+    repository: string;
     baseRef: string;
     headRef: string;
     task: string;
@@ -25,7 +25,12 @@ export declare function readCodingInput(path: string): Promise<{
         runId: string;
     } | undefined;
     debugTrace?: boolean | undefined;
+    dependencyCache?: true | undefined;
+    sessionResume?: true | undefined;
+    diskMb?: number | undefined;
+    debugTraceMaxMb?: number | undefined;
     maxTurns?: number | undefined;
+    maxOutputTokens?: number | undefined;
     services?: {
         name: string;
         version: string;
@@ -40,4 +45,4 @@ export declare function readCodingInput(path: string): Promise<{
         }[];
     } | undefined;
 }>;
-export declare function writeCodingOutputAtomic(path: string, output: CodingAgentOutput): Promise<void>;
+export declare function writeCodingOutputAtomic(path: string, output: CodingWorkerOutput): Promise<void>;

package/dist/coding-worker/artifact.js

@@ -16,7 +16,9 @@ import { MAX_CODING_ARTIFACT_BYTES, MAX_CODING_INPUT_BYTES, parseCodingTaskInput
 export async function readBoundedRegularFile(path, maxBytes, errorCode) {
     let file;
     try {
-        file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+        // The mode only applies to a created file, and this open never creates one; an owner-only mode
+        // states that, so CodeQL's temporary-file rule doesn't read the open as a world-readable create.
+        file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0), 0o600);
     }
     catch (error) {
         // ELOOP: the path is a symlink.

package/dist/coding-worker/debug-trace.d.ts

@@ -1,8 +1,9 @@
 import { MAX_DEBUG_TRACE_LINE_BYTES } from "../coding/protocol.js";
+import { redactSecrets } from "../coding/redact.js";
 /**
  * Admin-requested debug trace (CodingTaskInput.debugTrace). When a run is
- * traced, the worker writes every Codex stream event and the full text of any
- * stream failure to its own stdout, one JSON line each, so an operator can read
+ * traced, the worker writes every agent stream event (Codex events, Claude Agent
+ * SDK messages) and the full text of any stream failure to its own stdout, one JSON line each, so an operator can read
  * why a run failed from the run pod's log. Nothing here reaches the control
  * plane: the launchers only ever parse `{"error": "<code>"}` lines, and a trace
  * line's single top-level key is `debugTrace`.
@@ -11,10 +12,9 @@ import { MAX_DEBUG_TRACE_LINE_BYTES } from "../coding/protocol.js";
  * values are redacted. Lines and the per-run total are capped so a runaway
  * stream cannot flood the log.
  */
-export { MAX_DEBUG_TRACE_LINE_BYTES };
+export { MAX_DEBUG_TRACE_LINE_BYTES, redactSecrets };
+/** The per-run total when the input sets no cap (CodingTaskInput.debugTraceMaxMb). */
 export declare const MAX_DEBUG_TRACE_TOTAL_BYTES: number;
-/** Redacts the given exact secrets, then every token-shaped value. */
-export declare function redactSecrets(text: string, secrets?: readonly string[]): string;
 /** An error as plain data: name, message, stack, code, and its cause chain. */
 export declare function describeError(error: unknown, depth?: number): unknown;
 export interface DebugTracer {
@@ -34,4 +34,5 @@ export declare function createDebugTracer(options: DebugTracerOptions): DebugTra
 export declare function workerDebugTracer(input: {
     runId: string;
     debugTrace?: boolean;
+    debugTraceMaxMb?: number;
 }, capability: string, write: (line: string) => void): DebugTracer | undefined;

package/dist/coding-worker/debug-trace.js

@@ -1,9 +1,10 @@
-import { MAX_DEBUG_TRACE_LINE_BYTES, MAX_REDACTED_SPAN, redactTokenShapedValues } from "../coding/protocol.js";
+import { DEFAULT_DEBUG_TRACE_MAX_MB, MAX_DEBUG_TRACE_LINE_BYTES, MAX_REDACTED_SPAN } from "../coding/protocol.js";
+import { redactSecrets } from "../coding/redact.js";
 import { deriveRegistryToken } from "../coding/registry/token.js";
 /**
  * Admin-requested debug trace (CodingTaskInput.debugTrace). When a run is
- * traced, the worker writes every Codex stream event and the full text of any
- * stream failure to its own stdout, one JSON line each, so an operator can read
+ * traced, the worker writes every agent stream event (Codex events, Claude Agent
+ * SDK messages) and the full text of any stream failure to its own stdout, one JSON line each, so an operator can read
  * why a run failed from the run pod's log. Nothing here reaches the control
  * plane: the launchers only ever parse `{"error": "<code>"}` lines, and a trace
  * line's single top-level key is `debugTrace`.
@@ -12,23 +13,12 @@ import { deriveRegistryToken } from "../coding/registry/token.js";
  * values are redacted. Lines and the per-run total are capped so a runaway
  * stream cannot flood the log.
  */
-export { MAX_DEBUG_TRACE_LINE_BYTES };
-export const MAX_DEBUG_TRACE_TOTAL_BYTES = 2 * 1024 * 1024;
+export { MAX_DEBUG_TRACE_LINE_BYTES, redactSecrets };
+/** The per-run total when the input sets no cap (CodingTaskInput.debugTraceMaxMb). */
+export const MAX_DEBUG_TRACE_TOTAL_BYTES = DEFAULT_DEBUG_TRACE_MAX_MB * 1024 * 1024;
 const MAX_DEPTH = 32;
 const MAX_CAUSE_DEPTH = 8;
 const MAX_ENTRIES = 1000;
-const REDACTED = "[REDACTED]";
-/** Shapes protocol.ts's list does not cover, or covers only at longer lengths. */
-const EXTRA_TOKEN_PATTERNS = [/rrp_[A-Za-z0-9_-]{8,}/g, /rrg_[A-Za-z0-9_-]{8,}/g, /\bBearer\s+[^\s"',;]+/gi];
-/** Redacts the given exact secrets, then every token-shaped value. */
-export function redactSecrets(text, secrets = []) {
-    let redacted = text;
-    for (const secret of secrets)
-        if (secret)
-            redacted = redacted.split(secret).join(REDACTED);
-    redacted = redactTokenShapedValues(redacted);
-    return EXTRA_TOKEN_PATTERNS.reduce((value, pattern) => value.replace(pattern, REDACTED), redacted);
-}
 /** An error as plain data: name, message, stack, code, and its cause chain. */
 export function describeError(error, depth = 0) {
     if (!(error instanceof Error))
@@ -113,5 +103,10 @@ export function createDebugTracer(options) {
 export function workerDebugTracer(input, capability, write) {
     if (input.debugTrace !== true)
         return undefined;
-    return createDebugTracer({ runId: input.runId, secrets: [capability, deriveRegistryToken(capability)], write });
+    return createDebugTracer({
+        runId: input.runId,
+        secrets: [capability, deriveRegistryToken(capability)],
+        write,
+        ...(input.debugTraceMaxMb ? { maxTotalBytes: input.debugTraceMaxMb * 1024 * 1024 } : {}),
+    });
 }

package/dist/coding-worker/dependency-cache.d.mts

@@ -0,0 +1,229 @@
+// Types for dependency-cache.mjs, so the driver and the tool runner's TypeScript callers can import it.
+
+export type PrepareOutcome = "hit" | "nearest" | "cold" | "skipped" | "refused";
+
+export interface PrepareResult {
+  readonly result: PrepareOutcome;
+  /** The proxy's opaque snapshot key for this run's lockfile (hit, nearest, cold). */
+  readonly key?: string;
+  /** Archive bytes downloaded (hit) or uploaded (nearest, cold). */
+  readonly sizeBytes?: number;
+  readonly restoreMs?: number;
+  readonly installMs?: number;
+  /** A stable code, never raw output: why it was skipped or refused, or why a cold tree was not snapshotted. */
+  readonly reason?: string;
+}
+
+/** `npm rebuild` after the seal (hit, nearest and cold only): `skipped` when the lockfile lists no install
+ *  script under node_modules/; `unsealed` when the proxy did not confirm the seal, so no third-party
+ *  script ran while the upload window might still be open. */
+export type RebuildOutcome = "ok" | "failed" | "timeout" | "skipped" | "unsealed";
+
+export interface ProjectResult extends PrepareResult {
+  /** The project folder relative to the workspace: "." for the root, else e.g. "app" or "web/client". */
+  readonly path: string;
+  readonly rebuild?: RebuildOutcome;
+}
+
+/** One entry per discovered project, root first then by path. A repo with no
+ *  lockfile has one entry: `{ path: ".", result: "skipped", reason: "no_lockfile" }`.
+ *  Skipped up front: `workspace_member`, `too_many_projects`. */
+export interface PrepareDependenciesResult {
+  readonly projects: readonly ProjectResult[];
+  /** Set (with `projects: []`) only when the projects could not be planned at all: `internal_error` or `timeout`. */
+  readonly reason?: string;
+}
+
+export interface DependencyCacheTimeouts {
+  /** Each small proxy call (lookup, seal): 120 s. */
+  readonly httpMs: number;
+  /** The lockfile plan request (a cold proxy checks every package first): 10 min, still bounded by `totalMs`. */
+  readonly planMs: number;
+  /** Pause before sending a plan again after the proxy's 503 `wardby_plan_incomplete` (it resumes where it stopped). */
+  readonly planRetryPauseMs: number;
+  readonly transferMs: number;
+  readonly transferMsPerMiB: number;
+  readonly installMs: number;
+  /** Packing a snapshot: 5 min, plus `tarMsPerMiB` (0.5 s) per MiB of the installed tree; never past the upload deadline. */
+  readonly tarMs: number;
+  readonly tarMsPerMiB: number;
+  readonly totalMs: number;
+  readonly killGraceMs: number;
+  readonly settleMs: number;
+  /** Each `npm rebuild` after the seal. */
+  readonly rebuildMs: number;
+  /** The proxy's upload window (WARDBY_DEPENDENCY_CACHE_UPLOAD_SECONDS), measured from this module's start;
+   *  a snapshot is not uploaded once less than `uploadMarginMs` of it is left (`upload_window_passed`,
+   *  log only). Independent of `totalMs`: past the window a run still restores and installs, it only
+   *  stops uploading. A lookup's `uploadExpiresInMs`, if a proxy reports one, wins when sooner. */
+  readonly uploadWindowMs: number;
+  readonly uploadMarginMs: number;
+}
+
+export type DependencyCacheLog = (event: string, fields: Record<string, unknown>) => void;
+
+export interface DependencyCacheEvent {
+  readonly event: string;
+  readonly [field: string]: unknown;
+}
+
+export declare const DEFAULT_TIMEOUTS: Readonly<DependencyCacheTimeouts>;
+export declare const DEFAULT_BUDGET_MB: number;
+export declare const MAX_ARCHIVE_ENTRIES: number;
+export declare const MAX_PROJECTS: number;
+/** The least room a cold install needs when this project's tree size is unknown (`budget_too_small` below it). */
+export declare const MIN_INSTALL_BUDGET_BYTES: number;
+/** Plan requests one project may send (retries of an incomplete plan included). */
+export declare const MAX_PLAN_ATTEMPTS: number;
+/** Plan requests the cache sends in one run, leaving the rest of REGISTRY_PLAN_MAX_PER_RUN to the agent's npm. */
+export declare const MAX_PLAN_REQUESTS_PER_RUN: number;
+
+export interface PrepareDependenciesOptions {
+  readonly workspace: string;
+  /** Required: the agent-equivalent shell env (registry settings: npm_config_registry, npm_config_userconfig,
+   *  WARDBY_NPM_PLAN_REGISTRY, PATH), never the driver's secrets. `npm rebuild` gets only PATH, HOME, LANG,
+   *  TMPDIR and npm_config_* / NPM_CONFIG_* / WARDBY_NPM_* from it. */
+  readonly env: Readonly<Record<string, string | undefined>>;
+  /** The proxy origin; defaults to the one npm_config_registry / WARDBY_NPM_PLAN_REGISTRY names. */
+  readonly proxyUrl?: string;
+  /** The registry token; defaults to the npmrc's _authToken for that registry. */
+  readonly token?: string;
+  readonly npmPath?: string;
+  readonly log?: DependencyCacheLog;
+  /** Workspace disk budget in bytes; defaults to CODING_DISK_MB, else DEFAULT_BUDGET_MB. */
+  readonly budgetBytes?: number;
+  /** What the workspace used when `budgetBytes` was measured (dependencyCacheBudget's `usedBytes`); the
+   *  snapshot step re-measures and counts the growth from it. Measured at the start when omitted. */
+  readonly usedBytes?: number;
+  /** Tests only: the cold-install floor; defaults to MIN_INSTALL_BUDGET_BYTES. */
+  readonly minInstallBytes?: number;
+  readonly timeouts?: Partial<DependencyCacheTimeouts>;
+  /** The run's cancellation: aborting it ends the work like the deadline (the module still seals and settles). */
+  readonly signal?: AbortSignal;
+  /** Tests only: hooks into the flow. */
+  readonly testHooks?: DependencyCacheTestHooks;
+}
+
+export interface DependencyCacheTestHooks {
+  readonly beforeRename?: () => Promise<void>;
+  readonly beforeDiscovery?: () => Promise<void>;
+  /** After npm's `_cacache` was found and checked, before it is moved. */
+  readonly beforeNpmCacheMove?: () => Promise<void>;
+  /** After npm's `_cacache` was moved to the module's own temp, before it is removed. */
+  readonly beforeNpmCacheRemove?: () => Promise<void>;
+  /** After a restore's extraction, before its symlinks are verified (the temp folder it wrote). */
+  readonly beforeVerifyLinks?: (temp: string) => Promise<void>;
+  /** After an archive that outgrew the budget was stopped and removed. */
+  readonly afterArchiveAborted?: (archive: string) => Promise<void>;
+}
+
+export declare const DEADLINE_SHARE: number;
+
+/** How long packing a snapshot may take for a tree of `treeBytes`: `tarMs` plus `tarMsPerMiB` per MiB,
+ *  cut to what is left before `uploadDeadline` (`limit: "upload_window"`). */
+export declare function archiveLimit(
+  timeouts: Pick<DependencyCacheTimeouts, "tarMs" | "tarMsPerMiB">,
+  treeBytes: number,
+  uploadDeadline: number | undefined,
+  now?: number,
+): { limit: "pack" | "upload_window"; limitMs: number };
+/** min(DEFAULT_TIMEOUTS.totalMs, DEADLINE_SHARE × time left before `deadlineAt`), ≥ 0; the default without a usable deadline. */
+export declare function dependencyCacheTimeLimit(deadlineAt: string | Date | number | undefined, now?: number): number;
+
+export declare const MIN_BUDGET_BYTES: number;
+export declare const BUDGET_MEASURE_TIMEOUT_MS: number;
+
+export interface DependencyCacheBudgetOptions {
+  readonly workspace: string;
+  /** The run's workspace volume size in MiB (CodingTaskInput.diskMb / the tool setup's diskMb). */
+  readonly diskMb: number | undefined;
+  readonly signal?: AbortSignal;
+  readonly timeoutMs?: number;
+  readonly maxEntries?: number;
+}
+
+export type DependencyCacheBudget =
+  | { readonly budgetBytes: number; readonly usedBytes: number; readonly reason?: undefined }
+  | {
+      readonly reason: "budget_unknown" | "budget_too_small";
+      readonly usedBytes?: number;
+      readonly budgetBytes?: undefined;
+    };
+
+/** diskMb MiB − the workspace's current usage − max(64 MiB, 5%); a skip reason when unknown or too small. Never throws. */
+export declare function dependencyCacheBudget(options: DependencyCacheBudgetOptions): Promise<DependencyCacheBudget>;
+
+export interface SealUploadWindowOptions {
+  /** The same agent-equivalent env `prepareDependencies` takes (registry settings and the npmrc). */
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly proxyUrl?: string;
+  readonly token?: string;
+  /** Defaults to DEFAULT_TIMEOUTS.httpMs. */
+  readonly timeoutMs?: number;
+}
+
+/** POST /cache/npm/seal on its own (idempotent on the proxy). `status` 0: no registry, or no answer. Never throws. */
+export declare function sealUploadWindow(
+  options: SealUploadWindowOptions,
+): Promise<{ readonly status: number; readonly confirmed: boolean }>;
+
+export declare function prepareDependencies(options: PrepareDependenciesOptions): Promise<PrepareDependenciesResult>;
+
+/** Project folders with a committed package-lock.json, root first then by path (no cap applied). */
+export declare function discoverProjects(workspace: string, signal?: AbortSignal): Promise<string[]>;
+
+export interface PrepareProjectOptions {
+  readonly workspace: string;
+  readonly projectPath?: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly npmPath: string;
+  readonly log: DependencyCacheLog;
+  readonly auth: { readonly base: string; readonly token: string } | undefined;
+  /** Shared across projects: decremented by what each restore unpacks. */
+  /** Shared across projects: decremented by what each restore unpacks and each install writes, and re-measured
+   *  before each snapshot from `limit` (the starting budget) and `baseUsed` (the workspace's usage then). */
+  readonly budget: { remaining: number; limit?: number; baseUsed?: number };
+  readonly timeouts: DependencyCacheTimeouts;
+  readonly signal: AbortSignal;
+  /** `sealed` is set before the seal is sent (no upload starts after it);
+   *  `closed` once the caller stops waiting (no workspace change after it). */
+  readonly session: {
+    sealed: boolean;
+    closed: boolean;
+    children: Set<number>;
+    temps?: Set<string>;
+    /** Plan requests sent so far in this run (at most MAX_PLAN_REQUESTS_PER_RUN). */
+    planRequests?: number;
+  };
+  readonly testHooks?: DependencyCacheTestHooks;
+  /** Filled from the committed lockfile before anything runs: whether `npm rebuild` is needed. */
+  readonly facts?: { needsRebuild?: boolean };
+  /** Epoch ms after which no snapshot upload starts. */
+  readonly uploadDeadline?: number;
+  /** Tests only: the cold-install floor; defaults to MIN_INSTALL_BUDGET_BYTES. */
+  readonly minInstallBytes?: number;
+}
+
+export declare function prepareProject(options: PrepareProjectOptions): Promise<PrepareResult>;
+
+export declare function scanArchive(
+  file: string,
+  options: { budgetBytes: number; maxEntries?: number; signal?: AbortSignal },
+): Promise<{ entries: number; unpackedBytes: number }>;
+
+export declare function extractArchive(
+  file: string,
+  destination: string,
+  options: { budgetBytes: number; maxEntries?: number; signal?: AbortSignal },
+): Promise<{ links: string[] }>;
+
+export declare function verifyLinks(root: string, links: readonly string[], signal?: AbortSignal): Promise<void>;
+
+export declare function checkConsistency(
+  projectRoot: string,
+  lockfile: { packages: Record<string, unknown> },
+  signal?: AbortSignal,
+): Promise<{ ok: true } | { ok: false; detail: string }>;
+
+export declare function readRegularFile(path: string, maxBytes: number): Promise<Buffer>;
+export declare function readRegularFile(path: string, maxBytes: number, encoding: BufferEncoding): Promise<string>;