@wardby/cli 0.6.0 → 0.7.0

package/dist/coding/transcript/resume/checkout.d.ts

@@ -0,0 +1,31 @@
+import { type TranscriptMeta } from "./download.js";
+export type Git = (args: string[], cwd: string) => Promise<string>;
+export declare const realGit: Git;
+export interface CheckoutOptions {
+    /** Where the command runs (a clone of the repository, for hosted runs). */
+    cwd: string;
+    /** --dir: the checkout directory. Default: a sibling `<repo>-run-<short run id>`. */
+    dir?: string;
+    /** --here: use cwd as it is; no checkout. */
+    here?: boolean;
+    /**
+     * Whether the link came from this machine (a loopback origin). A `local:` repository names a path on
+     * the server's machine; from any other origin, checking it out would let that server point the
+     * importer at any repository here, so it is refused unless the user chose --dir or --here.
+     */
+    linkIsLoopback?: boolean;
+    git?: Git;
+}
+export interface Checkout {
+    dir: string;
+    /** What is checked out: the branch name, or the base commit. */
+    ref: string;
+    /** "created", "reused" (an earlier import's worktree) or "here". */
+    outcome: "created" | "reused" | "here";
+    warnings: string[];
+}
+/** owner/name from a GitHub remote URL (https, ssh or scp form); undefined for anything else. */
+export declare function githubRemoteRepository(url: string): string | undefined;
+/** Fixed code: a remote server named a local: repository on this machine. */
+export declare const LOCAL_REPOSITORY_REFUSED = "local_repository_refused";
+export declare function prepareCheckout(meta: TranscriptMeta, opts: CheckoutOptions): Promise<Checkout>;

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

@@ -0,0 +1,203 @@
+/**
+ * The checkout a resumed session continues in: a detached git worktree at
+ * the run's branch (detached, so it works while that branch is checked out
+ * elsewhere).
+ *
+ * - `local:/abs/path` repositories: the worktree comes from that repository.
+ * - Hosted repositories: the current directory must be a clone of the run's
+ *   repository; the branch is fetched from the matching remote.
+ * - A branch that no longer exists (a failed run that pushed nothing) falls
+ *   back to the run's base commit, with a warning.
+ *
+ * git runs with argument arrays (no shell), and every ref and path from the
+ * server is validated before it reaches git.
+ */
+import { execFile } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { isLocalRepository, normalizeGitHubRepository, normalizeGitRef, normalizeLocalRepository, } from "../../protocol.js";
+import { ResumeError } from "./download.js";
+const execFileAsync = promisify(execFile);
+const SHA = /^[0-9a-f]{7,64}$/i;
+export const realGit = async (args, cwd) => {
+    const { stdout } = await execFileAsync("git", args, {
+        cwd,
+        maxBuffer: 16 * 1024 * 1024,
+        env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+    });
+    return stdout.trim();
+};
+async function tryGit(git, args, cwd) {
+    try {
+        return await git(args, cwd);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** owner/name from a GitHub remote URL (https, ssh or scp form); undefined for anything else. */
+export function githubRemoteRepository(url) {
+    const trimmed = url.trim();
+    const scp = /^[^@/\s]+@github\.com:(.+)$/i.exec(trimmed);
+    let path;
+    if (scp)
+        path = scp[1];
+    else {
+        try {
+            const parsed = new URL(trimmed);
+            if (parsed.hostname.toLowerCase() === "github.com" && ["https:", "ssh:", "git:"].includes(parsed.protocol)) {
+                path = parsed.pathname;
+            }
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (!path)
+        return undefined;
+    try {
+        return normalizeGitHubRepository(path.replace(/^\/+|\/+$/g, ""));
+    }
+    catch {
+        return undefined;
+    }
+}
+function shortRunId(runId) {
+    return runId.slice(-8);
+}
+function validRef(ref) {
+    if (!ref)
+        return undefined;
+    try {
+        return normalizeGitRef(ref);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function commonDir(git, dir) {
+    const out = await tryGit(git, ["rev-parse", "--path-format=absolute", "--git-common-dir"], dir);
+    return out ? realpathSync(out) : undefined;
+}
+/**
+ * Creates the worktree, or reuses one an earlier import made for the same repository. A reused
+ * worktree is left as it is (it may hold local work), with a warning when its HEAD is elsewhere.
+ */
+async function addWorktree(git, repoDir, dir, commit, warnings) {
+    if (existsSync(dir)) {
+        const [mine, theirs] = await Promise.all([commonDir(git, repoDir), commonDir(git, dir)]);
+        if (!mine || !theirs || mine !== theirs) {
+            throw new ResumeError(`${dir} already exists and is not a checkout of this repository. Pass --dir <path> or --here.`);
+        }
+        const [head, wanted] = await Promise.all([
+            tryGit(git, ["rev-parse", "--verify", "--quiet", "HEAD"], dir),
+            tryGit(git, ["rev-parse", "--verify", "--quiet", `${commit}^{commit}`], repoDir),
+        ]);
+        if (!head || !wanted || head !== wanted) {
+            warnings.push(`The existing worktree at ${dir} is at ${head ?? "an unknown commit"}, not the run's ${wanted ?? commit}. ` +
+                "It was left as it is (it may hold your local work); check out the run's commit there, or pass --dir <path>.");
+        }
+        return "reused";
+    }
+    try {
+        await git(["worktree", "add", "--detach", dir, commit], repoDir);
+    }
+    catch {
+        throw new ResumeError(`git could not create a worktree at ${dir}. Pass --dir <path>, or --here to use this directory.`);
+    }
+    return "created";
+}
+/** Fixed code: a remote server named a local: repository on this machine. */
+export const LOCAL_REPOSITORY_REFUSED = "local_repository_refused";
+export async function prepareCheckout(meta, opts) {
+    const git = opts.git ?? realGit;
+    const branch = validRef(meta.resultBranch ?? meta.headRef);
+    const baseSha = meta.baseSha && SHA.test(meta.baseSha) ? meta.baseSha : undefined;
+    if (opts.here)
+        return { dir: resolve(opts.cwd), ref: branch ?? baseSha ?? "", outcome: "here", warnings: [] };
+    const warnings = [];
+    const fallbackWarning = (why) => `${why}; checked out the run's base commit ${baseSha} instead. The run's changes are not in this checkout.`;
+    if (isLocalRepository(meta.repository)) {
+        if (!opts.linkIsLoopback && opts.dir === undefined) {
+            throw new ResumeError(`${LOCAL_REPOSITORY_REFUSED}: the run's repository is a local: folder on the server's machine, but this ` +
+                "link is from another machine. Pass --here to continue in the current directory, or --dir <path> to " +
+                "check the run out from that folder here anyway.");
+        }
+        let repoDir;
+        try {
+            repoDir = normalizeLocalRepository(meta.repository).slice("local:".length);
+        }
+        catch {
+            throw new ResumeError("The run's local repository path is invalid.");
+        }
+        if (!existsSync(repoDir))
+            throw new ResumeError(`The run's repository ${repoDir} does not exist on this machine.`);
+        let commit;
+        let ref = branch;
+        if (branch)
+            commit = await tryGit(git, ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}^{commit}`], repoDir);
+        if (!commit) {
+            if (!baseSha || !(await tryGit(git, ["rev-parse", "--verify", "--quiet", `${baseSha}^{commit}`], repoDir))) {
+                throw new ResumeError(`The run's branch ${branch ?? "(none)"} and base commit are not in ${repoDir}.`);
+            }
+            warnings.push(fallbackWarning(`The branch ${branch ?? "(none)"} is not in ${repoDir}`));
+            commit = baseSha;
+            ref = baseSha;
+        }
+        const dir = opts.dir
+            ? resolve(opts.cwd, opts.dir)
+            : join(dirname(repoDir), `${basename(repoDir)}-run-${shortRunId(meta.runId)}`);
+        const outcome = await addWorktree(git, repoDir, dir, commit, warnings);
+        return { dir, ref: ref, outcome, warnings };
+    }
+    let repository;
+    try {
+        repository = normalizeGitHubRepository(meta.repository);
+    }
+    catch {
+        throw new ResumeError("The run's repository is not one wardby resume can check out. Pass --here to skip the checkout.");
+    }
+    const cloneUrl = `https://github.com/${repository}.git`;
+    const top = await tryGit(git, ["rev-parse", "--show-toplevel"], opts.cwd);
+    if (!top) {
+        throw new ResumeError(`Run this inside a clone of ${repository} (git clone ${cloneUrl}), or pass --here to skip the checkout.`);
+    }
+    const remotes = (await tryGit(git, ["remote"], top))?.split("\n").filter(Boolean) ?? [];
+    let remote;
+    for (const name of remotes) {
+        const url = await tryGit(git, ["remote", "get-url", name], top);
+        if (url && githubRemoteRepository(url) === repository) {
+            remote = name;
+            break;
+        }
+    }
+    if (!remote) {
+        throw new ResumeError(`This directory is not a clone of ${repository}. Run the command inside one (git clone ${cloneUrl}), or pass --here to skip the checkout.`);
+    }
+    let commit;
+    let ref = branch;
+    if (branch && (await tryGit(git, ["fetch", "--quiet", remote, `refs/heads/${branch}`], top)) !== undefined) {
+        commit = await tryGit(git, ["rev-parse", "--verify", "--quiet", "FETCH_HEAD^{commit}"], top);
+    }
+    if (!commit) {
+        if (!baseSha)
+            throw new ResumeError(`The run's branch ${branch ?? "(none)"} could not be fetched from ${remote}.`);
+        let found = await tryGit(git, ["rev-parse", "--verify", "--quiet", `${baseSha}^{commit}`], top);
+        if (!found && (await tryGit(git, ["fetch", "--quiet", remote, baseSha], top)) !== undefined) {
+            found = await tryGit(git, ["rev-parse", "--verify", "--quiet", `${baseSha}^{commit}`], top);
+        }
+        if (!found)
+            throw new ResumeError(`Neither the run's branch nor its base commit could be fetched from ${remote}.`);
+        warnings.push(fallbackWarning(`The branch ${branch ?? "(none)"} could not be fetched from ${remote}`));
+        commit = found;
+        ref = baseSha;
+    }
+    const dir = opts.dir
+        ? isAbsolute(opts.dir)
+            ? opts.dir
+            : resolve(opts.cwd, opts.dir)
+        : join(dirname(top), `${basename(top)}-run-${shortRunId(meta.runId)}`);
+    const outcome = await addWorktree(git, top, dir, commit, warnings);
+    return { dir, ref: ref, outcome, warnings };
+}

package/dist/coding/transcript/resume/command.d.ts

@@ -0,0 +1,17 @@
+import { type Git } from "./checkout.js";
+export declare const RESUME_USAGE = "usage: wardby resume - [--dir <path> | --here] [--force] [--print]\n       wardby resume '<link>' [options]\n\nContinue a wardby coding run's Claude Code session on this machine. Get the\nlink (valid for 10 minutes) from the get_run_transcript MCP tool. With \"-\",\npaste the link when asked (or pipe it in): this keeps it out of your shell\nhistory and the process list, where a link given as an argument stays while\nClaude Code runs.\n\n  --dir <path>  Check the run out here (default: a sibling <repo>-run-<id>)\n  --here        Use the current directory as it is; no checkout\n  --force       Replace a different session file already imported for this run\n  --print       Print the claude command instead of starting it";
+export interface ResumeDeps {
+    cwd?: string;
+    sessionsRoot?: string;
+    fetch?: typeof globalThis.fetch;
+    git?: Git;
+    claudeVersion?: () => Promise<string | undefined>;
+    launch?: (cwd: string, args: string[]) => Promise<number>;
+    out?: (line: string) => void;
+    /** Reads the link for "-" (default: standard input). */
+    readLink?: () => Promise<string>;
+}
+/** Returns the process exit code. */
+export declare function resumeCommand(argv: string[], deps?: ResumeDeps): Promise<number>;
+/** Removes the link and its token, in every form they could be quoted, from a message. */
+export declare function withoutLink(message: string, rawLink: string): string;

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

@@ -0,0 +1,176 @@
+/**
+ * `wardby resume '<link>'`: continue a wardby coding run's Claude Code
+ * session on this machine. The link comes from the get_run_transcript MCP
+ * tool. Downloads and verifies the transcript, writes it under
+ * ~/.wardby/sessions/<runId>/, checks out the run's branch, and starts
+ * `claude --resume` there with the stand-in tool server.
+ *
+ * Runs without a database or any server configuration. Output never
+ * includes the link (it is a credential until it expires).
+ */
+import { parseArgs } from "node:util";
+import { createInterface } from "node:readline";
+import { downloadTranscript, isLoopbackLink, parseResumeLink, ResumeError } from "./download.js";
+import { writeSessionFile } from "./session-file.js";
+import { prepareCheckout } from "./checkout.js";
+import { WORKER_WORKSPACE, claudeArgs, claudeVersion, launchClaude, mcpConfig, moveNote, parseClaudeVersion, printableCommand, UNKNOWN_VERSION_NOTE, writeMcpConfig, } from "./launch.js";
+export const RESUME_USAGE = `usage: wardby resume - [--dir <path> | --here] [--force] [--print]
+       wardby resume '<link>' [options]
+
+Continue a wardby coding run's Claude Code session on this machine. Get the
+link (valid for 10 minutes) from the get_run_transcript MCP tool. With "-",
+paste the link when asked (or pipe it in): this keeps it out of your shell
+history and the process list, where a link given as an argument stays while
+Claude Code runs.
+
+  --dir <path>  Check the run out here (default: a sibling <repo>-run-<id>)
+  --here        Use the current directory as it is; no checkout
+  --force       Replace a different session file already imported for this run
+  --print       Print the claude command instead of starting it`;
+/** Largest link read from standard input. */
+const MAX_LINK_BYTES = 8192;
+/** Reads the link from standard input: one pasted line on a terminal, else the piped text. */
+async function readLinkFromStdin(out) {
+    if (process.stdin.isTTY) {
+        out("Paste the get_run_transcript link and press Enter:");
+        const rl = createInterface({ input: process.stdin, terminal: false });
+        try {
+            for await (const line of rl)
+                return line.slice(0, MAX_LINK_BYTES);
+            return "";
+        }
+        finally {
+            rl.close();
+        }
+    }
+    let text = "";
+    for await (const chunk of process.stdin) {
+        text += String(chunk);
+        if (text.length > MAX_LINK_BYTES)
+            throw new ResumeError("The link read from standard input is too long.");
+    }
+    return text;
+}
+/** Returns the process exit code. */
+export async function resumeCommand(argv, deps = {}) {
+    const out = deps.out ?? ((line) => process.stderr.write(`${line}\n`));
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                dir: { type: "string" },
+                here: { type: "boolean" },
+                force: { type: "boolean" },
+                print: { type: "boolean" },
+                help: { type: "boolean", short: "h" },
+            },
+        });
+    }
+    catch {
+        out(RESUME_USAGE);
+        return 2;
+    }
+    const { values, positionals } = parsed;
+    if (values.help) {
+        out(RESUME_USAGE);
+        return 0;
+    }
+    if (positionals.length !== 1 || (values.dir !== undefined && values.here)) {
+        out(RESUME_USAGE);
+        return 2;
+    }
+    const cwd = deps.cwd ?? process.cwd();
+    let rawLink = positionals[0];
+    try {
+        if (rawLink === "-")
+            rawLink = (await (deps.readLink ?? (() => readLinkFromStdin(out)))()).trim();
+        const link = parseResumeLink(rawLink);
+        out(`Downloading the transcript from ${link.origin} ...`);
+        const transcript = await downloadTranscript(link, deps.fetch);
+        const { meta } = transcript;
+        if (meta.provider !== "claude-code") {
+            throw new ResumeError(`Resuming ${meta.provider} runs locally is not supported yet.`);
+        }
+        // Check out first, so a refused checkout leaves nothing behind.
+        const checkout = await prepareCheckout(meta, {
+            cwd,
+            dir: values.dir,
+            here: values.here,
+            git: deps.git,
+            linkIsLoopback: isLoopbackLink(link),
+        });
+        const session = await writeSessionFile(transcript, { root: deps.sessionsRoot, force: values.force });
+        const from = WORKER_WORKSPACE;
+        const configPath = await writeMcpConfig(session.dir, mcpConfig({ checkout: checkout.dir, from }));
+        const versionText = await (deps.claudeVersion ?? claudeVersion)();
+        const version = versionText ? parseClaudeVersion(versionText) : undefined;
+        const args = claudeArgs({
+            sessionFile: session.path,
+            mcpConfigPath: configPath,
+            note: moveNote({
+                runId: meta.runId,
+                ref: checkout.ref,
+                from,
+                checkout: checkout.dir,
+                // prepareCheckout checks out the base commit only when the run's branch is missing.
+                runChanges: checkout.outcome === "here" ? undefined : checkout.ref !== meta.baseSha,
+            }),
+            version,
+        });
+        out(`Run:          ${meta.runId}`);
+        out(`Session file: ${session.path}` +
+            (session.outcome === "same"
+                ? " (already imported)"
+                : session.outcome === "continued"
+                    ? " (kept: it holds your local continuation)"
+                    : session.outcome === "replaced"
+                        ? " (replaced)"
+                        : ""));
+        out(`MCP config:   ${configPath}`);
+        out(`Checkout:     ${checkout.dir} at ${checkout.ref}` +
+            (checkout.outcome === "reused" ? " (existing worktree reused)" : checkout.outcome === "here" ? " (as is)" : ""));
+        for (const warning of checkout.warnings)
+            out(`Warning: ${warning}`);
+        if (!version)
+            out(`Note: ${UNKNOWN_VERSION_NOTE}`);
+        out(`To remove the import later: delete ${session.dir}${checkout.outcome === "created" ? ` and run git worktree remove ${checkout.dir}` : ""}.`);
+        const command = printableCommand(checkout.dir, args);
+        if (values.print || !versionText) {
+            if (!versionText && !values.print)
+                out("Claude Code (claude) was not found on PATH. Install it, then run:");
+            process.stdout.write(`${command}\n`);
+            return 0;
+        }
+        out("Starting Claude Code ...");
+        return await (deps.launch ?? launchClaude)(checkout.dir, args);
+    }
+    catch (error) {
+        if (error instanceof ResumeError) {
+            out(`wardby resume: ${error.message}`);
+            return 1;
+        }
+        // Unexpected (a file system or git failure): its message, with the link removed by exact value.
+        out(`wardby resume: ${withoutLink(error instanceof Error ? error.message : String(error), rawLink)}`);
+        return 1;
+    }
+}
+/** Removes the link and its token, in every form they could be quoted, from a message. */
+export function withoutLink(message, rawLink) {
+    const values = new Set([rawLink, rawLink.trim()]);
+    try {
+        const token = new URL(rawLink.trim()).searchParams.get("t");
+        if (token)
+            for (const v of [token, encodeURIComponent(token)])
+                values.add(v);
+    }
+    catch {
+        // Not a URL: only the raw value can appear.
+    }
+    let result = message;
+    for (const value of [...values].filter(Boolean).sort((a, b) => b.length - a.length)) {
+        result = result.split(value).join("[link]");
+    }
+    return result;
+}

package/dist/coding/transcript/resume/download.d.ts

@@ -0,0 +1,20 @@
+import { type TranscriptDownloadMeta } from "../download-protocol.js";
+export declare class ResumeError extends Error {
+    constructor(message: string);
+}
+export type TranscriptMeta = TranscriptDownloadMeta;
+export interface DownloadedTranscript {
+    meta: TranscriptMeta;
+    /** The stored object: gzip bytes, verified against the server's sha256. */
+    gzip: Buffer;
+}
+/** Whether the link points at this machine. */
+export declare function isLoopbackLink(link: URL): boolean;
+/** Checks the link's shape without echoing it. */
+export declare function parseResumeLink(raw: string): URL;
+export declare function downloadTranscript(link: URL, fetchImpl?: typeof globalThis.fetch, maxBytes?: number): Promise<DownloadedTranscript>;
+/**
+ * Reads a response body up to `max` bytes, streaming, so a missing or false Content-Length cannot
+ * make it read an unbounded body. Refuses a Content-Length that is not a whole number.
+ */
+export declare function readBounded(res: Response, max: number): Promise<Buffer>;

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

@@ -0,0 +1,153 @@
+/**
+ * Downloads a run transcript from a get_run_transcript link and verifies it.
+ *
+ * The link is a bearer credential: it is only ever sent to the server it
+ * names, over HTTPS (plain HTTP only to this machine's loopback, where a
+ * stdio MCP server serves it), and no message here quotes it.
+ */
+import { createHash } from "node:crypto";
+import { RUN_TRANSCRIPT_DOWNLOAD_PATH as DOWNLOAD_PATH, TRANSCRIPT_META_HEADER as META_HEADER, TRANSCRIPT_SESSION_HEADER as SESSION_HEADER, TRANSCRIPT_SHA256_HEADER as SHA256_HEADER, } from "../download-protocol.js";
+/** Above the server's largest stored transcript (64 MiB before compression). */
+const MAX_DOWNLOAD_BYTES = 80 * 1024 * 1024;
+const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Run ids are cuids; anything else is refused before it names a path. */
+const RUN_ID = /^[a-z0-9]{8,64}$/i;
+const SHA256 = /^[0-9a-f]{64}$/;
+export class ResumeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ResumeError";
+    }
+}
+const LOOPBACK = new Set(["127.0.0.1", "localhost", "[::1]"]);
+/** Largest refusal body read (a JSON error code). */
+const MAX_ERROR_BYTES = 4096;
+const PROVIDER = /^[a-z0-9-]{1,40}$/;
+/** C0, DEL and C1 controls: never printed from server data (terminal escapes). */
+// eslint-disable-next-line no-control-regex -- refusing untrusted control characters.
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/;
+/** Whether the link points at this machine. */
+export function isLoopbackLink(link) {
+    return LOOPBACK.has(link.hostname);
+}
+/** Checks the link's shape without echoing it. */
+export function parseResumeLink(raw) {
+    let url;
+    try {
+        url = new URL(raw.trim());
+    }
+    catch {
+        throw new ResumeError("That is not a get_run_transcript download link. Copy the whole link from the tool's result.");
+    }
+    const secure = url.protocol === "https:" || (url.protocol === "http:" && LOOPBACK.has(url.hostname));
+    if (!secure) {
+        throw new ResumeError("The download link must use https (or http to this machine). Refusing to send it over plain http.");
+    }
+    if (url.username || url.password || !url.pathname.endsWith(DOWNLOAD_PATH) || !url.searchParams.get("t")) {
+        throw new ResumeError("That is not a get_run_transcript download link. Copy the whole link from the tool's result.");
+    }
+    return url;
+}
+const REFUSALS = {
+    link_invalid: "The link is invalid or has expired (links work for 10 minutes). Call get_run_transcript again for a new one.",
+    not_found: "The server has no transcript you can read for this run.",
+    transcript_expired: "The run's transcript has been deleted after the server's retention period.",
+    transcript_unavailable: "The server could not read the stored transcript. Try again later, or ask your operator.",
+    transcript_corrupt: "The stored transcript no longer matches what was recorded; the server refused to send it.",
+};
+function parseMeta(header) {
+    let meta;
+    try {
+        meta = JSON.parse(Buffer.from(header ?? "", "base64url").toString("utf8"));
+    }
+    catch {
+        throw new ResumeError("The server's response is missing the run's details. Is the server running a matching wardby version?");
+    }
+    // Every string here may be printed or reach git: no control characters.
+    const str = (v) => typeof v === "string" && !CONTROL.test(v);
+    const optional = (v) => v === null || str(v);
+    if (!meta ||
+        !str(meta.runId) ||
+        !RUN_ID.test(meta.runId) ||
+        !str(meta.sessionId) ||
+        !SESSION_ID.test(meta.sessionId) ||
+        !str(meta.provider) ||
+        !PROVIDER.test(meta.provider) ||
+        !str(meta.repository) ||
+        !str(meta.headRef) ||
+        !optional(meta.resultBranch) ||
+        !optional(meta.baseSha) ||
+        !str(meta.sha256) ||
+        !SHA256.test(meta.sha256)) {
+        throw new ResumeError("The server's response has invalid run details.");
+    }
+    return meta;
+}
+export async function downloadTranscript(link, fetchImpl = globalThis.fetch, maxBytes = MAX_DOWNLOAD_BYTES) {
+    let res;
+    try {
+        res = await fetchImpl(link, { redirect: "error", headers: { accept: "application/gzip" } });
+    }
+    catch {
+        throw new ResumeError(`Could not reach ${link.origin}. Check your connection (for a stdio MCP server: is it still running?).`);
+    }
+    if (!res.ok) {
+        let code = "";
+        try {
+            const body = await readBounded(res, MAX_ERROR_BYTES);
+            code = JSON.parse(body.toString("utf8")).error;
+        }
+        catch {
+            // Not a wardby refusal body.
+        }
+        const message = typeof code === "string" && Object.hasOwn(REFUSALS, code) ? REFUSALS[code] : undefined;
+        throw new ResumeError(message ?? `The server refused the download (HTTP ${res.status}).`);
+    }
+    const gzip = await readBounded(res, maxBytes);
+    const meta = parseMeta(res.headers.get(META_HEADER));
+    const sha = createHash("sha256").update(gzip).digest("hex");
+    if (res.headers.get(SHA256_HEADER) !== meta.sha256 || sha !== meta.sha256) {
+        throw new ResumeError("The downloaded transcript does not match the server's checksum. Nothing was written; try again.");
+    }
+    if (res.headers.get(SESSION_HEADER) !== meta.sessionId) {
+        throw new ResumeError("The server's response has invalid run details.");
+    }
+    return { meta, gzip };
+}
+/**
+ * Reads a response body up to `max` bytes, streaming, so a missing or false Content-Length cannot
+ * make it read an unbounded body. Refuses a Content-Length that is not a whole number.
+ */
+export async function readBounded(res, max) {
+    const declared = res.headers.get("content-length");
+    if (declared !== null && !/^\d+$/.test(declared.trim())) {
+        throw new ResumeError("The server's response has an invalid length.");
+    }
+    if (declared !== null && Number(declared) > max) {
+        await res.body?.cancel().catch(() => undefined);
+        throw new ResumeError("The transcript is larger than wardby resume accepts.");
+    }
+    if (!res.body)
+        return Buffer.alloc(0);
+    const reader = res.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        let chunk;
+        try {
+            chunk = await reader.read();
+        }
+        catch {
+            throw new ResumeError("The download was interrupted. Try again.");
+        }
+        if (chunk.done || !chunk.value)
+            break;
+        total += chunk.value.byteLength;
+        if (total > max) {
+            await reader.cancel().catch(() => undefined);
+            throw new ResumeError("The transcript is larger than wardby resume accepts.");
+        }
+        chunks.push(chunk.value);
+    }
+    return Buffer.concat(chunks);
+}

package/dist/coding/transcript/resume/launch.d.ts

@@ -0,0 +1,38 @@
+/** Where the run's commands ran in the worker (run_command's workspace, claude-tool-runner/main.mjs). */
+export declare const WORKER_WORKSPACE = "/workspace";
+/** This install's wardby entry point, for the MCP config to start the stand-in with. */
+export declare function wardbyBinPath(): string;
+/**
+ * `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 declare function moveNote(opts: {
+    runId: string;
+    ref: string;
+    from: string;
+    checkout: string;
+    runChanges?: boolean;
+}): string;
+export declare function mcpConfig(opts: {
+    checkout: string;
+    from: string;
+    node?: string;
+    bin?: string;
+}): unknown;
+/** Writes the MCP config next to the session file (mode 0600, atomically). */
+export declare function writeMcpConfig(dir: string, config: unknown): Promise<string>;
+export declare function parseClaudeVersion(output: string): [number, number, number] | undefined;
+/** `claude --version`, or undefined when claude is not on PATH. */
+export declare function claudeVersion(): Promise<string | undefined>;
+export declare 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 declare function claudeArgs(opts: {
+    sessionFile: string;
+    mcpConfigPath: string;
+    note: string;
+    version: [number, number, number] | undefined;
+}): string[];
+/** POSIX shell quoting, for printing a command the user can paste. */
+export declare function shellQuote(arg: string): string;
+export declare function printableCommand(cwd: string, args: string[]): string;
+/** Runs claude in the checkout with this terminal; resolves with its exit code. */
+export declare function launchClaude(cwd: string, args: string[]): Promise<number>;