@wardby/cli 0.4.1 → 0.5.1

package/dist/providers/vcs/github.d.ts

@@ -32,6 +32,8 @@ export interface PullRequestInput {
     /** Deduplicated by the caller isn't required — pullRequestBody dedupes itself (ecosystem+name+version / +reason). */
     packages?: readonly PackageReport[];
     packageRefusals?: readonly PackageRefusal[];
+    /** Lock files the run changed (repository paths); with refusals, the PR body warns they may be incomplete. */
+    changedLockfiles?: readonly string[];
     /**
      * A continuation re-finds the PR its root run opened, and a person may
      * have marked that PR ready for review since. The push has already updated
@@ -53,6 +55,11 @@ export interface PullRequestInput {
         url?: string;
         trackerName?: string;
     };
+    /**
+     * The request's other pull requests (control-plane rows only), rendered as
+     * the marked "Related pull requests" section. Rendering failures omit it.
+     */
+    related?: RelatedPullRequestsInput;
 }
 export interface PullRequestResult {
     number: number;
@@ -90,6 +97,17 @@ export interface RepositoryFileInput {
 export interface GitHubRepositoryAccess {
     withRepositoryToken<T>(repository: string, action: (token: string) => Promise<T>): Promise<T>;
     createOrFindDraftPullRequest(input: PullRequestInput): Promise<PullRequestResult>;
+    /**
+     * The root run's marked pull request if it is still open (draft or ready),
+     * else null (merged, closed, or gone). Optional: without it, continuations
+     * are not checked.
+     */
+    findOpenPullRequest?(input: {
+        runId: string;
+        repository: string;
+        baseRef: string;
+        headRef: string;
+    }): Promise<PullRequestResult | null>;
     /** Creates the status comment if none exists yet for this run, else updates it. */
     upsertContinuationStatusComment(input: ContinuationStatusCommentInput): Promise<void>;
     /** Updates the status comment if one already exists for this run; a no-op otherwise (never creates). */
@@ -115,10 +133,61 @@ export declare function isSafeGitHubInstallationToken(value: unknown): value is
  */
 export declare const PR_ISSUE_KEY: RegExp;
 export declare function pullRequestTitle(input: PullRequestInput): string;
+export declare const RELATED_SECTION_START = "<!-- wardby-related:start -->";
+export declare const RELATED_SECTION_END = "<!-- wardby-related:end -->";
+/** At most this many pull requests are listed; the rest are counted. */
+export declare const MAX_RELATED_PULL_REQUESTS = 20;
+/** GitHub rejects a pull request body longer than this. */
+export declare const MAX_PULL_REQUEST_BODY_CHARS = 65536;
+export type RelatedPullRequestState = "open" | "draft" | "merged" | "closed";
+/** One pull request of the request's set, from stored control-plane rows only. */
+export interface RelatedPullRequestEntry {
+    repository: string;
+    /** Absent only for `self` while the pull request is being created. */
+    number?: number;
+    /** Live state; absent when unknown (at creation). */
+    state?: RelatedPullRequestState;
+    /** The pull request whose description this section is in. */
+    self?: boolean;
+}
+export interface RelatedPullRequestsInput {
+    /** In suggested merge order (the order the request's coding runs were dispatched). */
+    entries: readonly RelatedPullRequestEntry[];
+    issue?: {
+        key: string;
+        url?: string;
+        trackerName?: string;
+    };
+}
+/**
+ * The "Related pull requests" block, markers included, built only from
+ * stored rows (never agent text). Open (and draft, and not-yet-known) pull
+ * requests form the numbered suggested merge order; merged and closed ones
+ * follow as context. Undefined when no other valid pull request is left after
+ * validation: a set of one is not a set.
+ */
+export declare function renderRelatedSection(input: RelatedPullRequestsInput): string | undefined;
+/**
+ * The body with `block` in place of the existing marked section, or inserted
+ * after the run marker (and the issue line) when there is none. Null — do not
+ * write — when the body has no leading run marker, its section markers are
+ * malformed (one missing, reversed, or repeated), or `block` isn't a marked block.
+ */
+export declare function upsertRelatedSection(body: string, block: string): string | null;
 /** At most this many packages, and separately this many refusals, are listed
  *  in a PR body; the rest are counted in a "…and N more" line pointing at
  *  get_run, which returns the full list. */
 export declare const MAX_PR_PACKAGE_LINES = 100;
+export declare function isLockfilePath(path: string): boolean;
+/**
+ * A visible warning when the registry refused packages: the run's own
+ * installs were then incomplete, so failed checks in Tests may be the
+ * sandbox, not the change, and a changed lock file may not install in CI.
+ * Built only from registry records and the run's own diff, never from the
+ * agent's summary, so it cannot be softened or left out by the model.
+ */
+/** Rendered verbatim in refusalWarning's first line, and used to locate it in tests. */
+export declare const DEPENDENCY_INSTALL_INCOMPLETE = "Dependency install incomplete.";
 /** The hidden run marker stays first and unconditional: createOrFindDraftPullRequest's idempotent lookup depends on it. */
 export declare function pullRequestBody(input: PullRequestInput): string;
 export declare class GitHubAppClient implements GitHubRepositoryAccess {
@@ -169,6 +238,18 @@ export declare class GitHubAppClient implements GitHubRepositoryAccess {
     createContinuationCheckRun(input: ContinuationCheckRunInput): Promise<void>;
     completeContinuationCheckRun(input: ContinuationCheckRunCompleteInput): Promise<void>;
     createOrFindDraftPullRequest(input: PullRequestInput): Promise<PullRequestResult>;
+    /**
+     * The root run's marked pull request if GitHub's `state=open` list still
+     * contains it (draft or ready for review), else null -- merged, closed, or
+     * gone. Used by git.ts's revision-in-place continuation to refuse a push to
+     * a pull request that is no longer open.
+     */
+    findOpenPullRequest(input: {
+        runId: string;
+        repository: string;
+        baseRef: string;
+        headRef: string;
+    }): Promise<PullRequestResult | null>;
     private appJwt;
     private mintRepositoryToken;
     /**

package/dist/providers/vcs/github.js

@@ -49,14 +49,22 @@ export function pullRequestTitle(input) {
     const key = validIssueKey(input);
     return key ? `[${key}] ${base}` : base;
 }
-function issueLine(input) {
-    const key = validIssueKey(input);
-    const url = input.issue?.url;
-    if (!key || typeof url !== "string" || !url.startsWith("https://") || /[\s<>()]/.test(url))
+/** Validated issue parts; the tracker prefix is "" or "<Name> ". */
+function issueParts(issue) {
+    const key = issue?.key;
+    if (typeof key !== "string" || !PR_ISSUE_KEY.test(key))
         return undefined;
-    const name = input.issue?.trackerName;
+    const url = issue?.url;
+    const safeUrl = typeof url === "string" && url.startsWith("https://") && !/[\s<>()]/.test(url) ? url : undefined;
+    const name = issue?.trackerName;
     const tracker = typeof name === "string" && /^[A-Za-z][A-Za-z0-9 .-]{0,39}$/.test(name) ? `${name.trim()} ` : "";
-    return `Resolves ${tracker}issue [${key}](${url})`;
+    return { key, ...(safeUrl ? { url: safeUrl } : {}), tracker };
+}
+function issueLine(input) {
+    const parts = issueParts(input.issue);
+    if (!parts?.url)
+        return undefined;
+    return `Resolves ${parts.tracker}issue [${parts.key}](${parts.url})`;
 }
 /**
  * Package names/versions/reasons come from registry metadata, not from
@@ -69,6 +77,105 @@ function issueLine(input) {
 function isSafeMarkdownFragment(value) {
     return !value.includes("`") && !value.includes("\n") && !value.includes("\r");
 }
+export const RELATED_SECTION_START = "<!-- wardby-related:start -->";
+export const RELATED_SECTION_END = "<!-- wardby-related:end -->";
+/** At most this many pull requests are listed; the rest are counted. */
+export const MAX_RELATED_PULL_REQUESTS = 20;
+/** GitHub rejects a pull request body longer than this. */
+export const MAX_PULL_REQUEST_BODY_CHARS = 65_536;
+const RELATED_STATES = new Set(["open", "draft", "merged", "closed"]);
+/** The repository normalized, or undefined when it isn't a plain owner/name safe inside a link. */
+function safeRepository(value) {
+    try {
+        const repository = normalizeGitHubRepository(value);
+        return isSafeMarkdownFragment(repository) && !/[[\]()<>\s]/.test(repository) ? repository : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** One list line; `prefix` is "1." … for the merge order, "-" for the context list. */
+function relatedLine(entry, prefix) {
+    const repository = safeRepository(entry.repository);
+    if (!repository)
+        return undefined;
+    const state = entry.state && RELATED_STATES.has(entry.state) ? ` — ${entry.state}` : "";
+    if (entry.self)
+        return `${prefix} **This pull request**${state}`;
+    if (!Number.isSafeInteger(entry.number) || (entry.number ?? 0) <= 0)
+        return undefined;
+    return `${prefix} [${repository}#${entry.number}](https://github.com/${repository}/pull/${entry.number})${state}`;
+}
+const isDone = (entry) => entry.state === "merged" || entry.state === "closed";
+/**
+ * The "Related pull requests" block, markers included, built only from
+ * stored rows (never agent text). Open (and draft, and not-yet-known) pull
+ * requests form the numbered suggested merge order; merged and closed ones
+ * follow as context. Undefined when no other valid pull request is left after
+ * validation: a set of one is not a set.
+ */
+export function renderRelatedSection(input) {
+    const valid = input.entries.filter((entry) => relatedLine(entry, "-") !== undefined);
+    if (!valid.some((entry) => !entry.self))
+        return undefined;
+    const issue = issueParts(input.issue);
+    const issueText = issue ? ` for ${issue.tracker}issue ${issue.url ? `[${issue.key}](${issue.url})` : issue.key}` : "";
+    const open = valid.filter((entry) => !isDone(entry)).slice(0, MAX_RELATED_PULL_REQUESTS);
+    const done = valid.filter(isDone).slice(0, MAX_RELATED_PULL_REQUESTS - open.length);
+    const more = valid.length - open.length - done.length;
+    return [
+        RELATED_SECTION_START,
+        "**Related pull requests**",
+        "",
+        `Wardby opened these pull requests for the same request${issueText}.`,
+        ...(open.length > 0
+            ? [
+                "",
+                "Suggested merge order (the order Wardby's agent opened them in; not a guarantee, so check dependencies before merging):",
+                "",
+                ...open.map((entry, index) => relatedLine(entry, `${index + 1}.`)),
+            ]
+            : []),
+        ...(done.length > 0
+            ? ["", "Already merged or closed (context only):", "", ...done.map((entry) => relatedLine(entry, "-"))]
+            : []),
+        ...(more > 0 ? ["", `…and ${more} more`] : []),
+        "",
+        "<sub>Written by Wardby from its run records; this section is replaced when the request's runs finish.</sub>",
+        RELATED_SECTION_END,
+    ].join("\n");
+}
+/** The run marker, then optionally blank lines and the "Resolves …" line: the section goes right after. */
+const BODY_HEAD = /^[^\S\n]*<!-- (?:wardby|reevo-run):\S+ -->[^\S\n]*(?:\n|$)(?:[^\S\n]*\n)*(?:Resolves [^\n]*(?:\n|$))?/;
+/**
+ * The body with `block` in place of the existing marked section, or inserted
+ * after the run marker (and the issue line) when there is none. Null — do not
+ * write — when the body has no leading run marker, its section markers are
+ * malformed (one missing, reversed, or repeated), or `block` isn't a marked block.
+ */
+export function upsertRelatedSection(body, block) {
+    if (!block.startsWith(RELATED_SECTION_START) || !block.endsWith(RELATED_SECTION_END))
+        return null;
+    const text = body.replace(/\r\n/g, "\n");
+    const start = text.indexOf(RELATED_SECTION_START);
+    const end = text.indexOf(RELATED_SECTION_END);
+    if (start !== -1 || end !== -1) {
+        if (start === -1 ||
+            end === -1 ||
+            end < start ||
+            text.indexOf(RELATED_SECTION_START, start + 1) !== -1 ||
+            text.indexOf(RELATED_SECTION_END, end + 1) !== -1) {
+            return null;
+        }
+        return text.slice(0, start) + block + text.slice(end + RELATED_SECTION_END.length);
+    }
+    const head = BODY_HEAD.exec(text);
+    if (!head)
+        return null;
+    const before = text.slice(0, head[0].length).trimEnd();
+    const rest = text.slice(head[0].length).trimStart();
+    return rest ? `${before}\n\n${block}\n\n${rest}` : `${before}\n\n${block}`;
+}
 /** At most this many packages, and separately this many refusals, are listed
  *  in a PR body; the rest are counted in a "…and N more" line pointing at
  *  get_run, which returns the full list. */
@@ -122,6 +229,66 @@ function packagesSection(input) {
         "</details>",
     ].join("\n");
 }
+/** Lock file names whose change, alongside a refusal, means CI's clean install may fail. */
+const LOCKFILE_NAMES = new Set([
+    "package-lock.json",
+    "npm-shrinkwrap.json",
+    "yarn.lock",
+    "pnpm-lock.yaml",
+    "poetry.lock",
+    "uv.lock",
+    "Pipfile.lock",
+]);
+export function isLockfilePath(path) {
+    return LOCKFILE_NAMES.has(path.slice(path.lastIndexOf("/") + 1));
+}
+/** What each refusal code means to someone reading the PR, without the registry's internals. */
+const REFUSAL_MEANING = {
+    wardby_package_not_allowed: "not on the allowlist, or only reachable through a refused package",
+    wardby_version_filtered: "withheld: newer than the release-age limit, or a high-severity advisory",
+    wardby_graph_incomplete: "its dependencies could not be confirmed (usually transient)",
+    wardby_lockfile_integrity_mismatch: "the lock file's integrity does not match the registry's",
+    wardby_upstream_error: "the upstream registry failed (transient)",
+    wardby_audit_unavailable: "the advisory check was unavailable (transient)",
+};
+/** At most this many refused packages are named in the warning; the full list stays in the details. */
+const MAX_WARNING_NAMES = 8;
+/**
+ * A visible warning when the registry refused packages: the run's own
+ * installs were then incomplete, so failed checks in Tests may be the
+ * sandbox, not the change, and a changed lock file may not install in CI.
+ * Built only from registry records and the run's own diff, never from the
+ * agent's summary, so it cannot be softened or left out by the model.
+ */
+/** Rendered verbatim in refusalWarning's first line, and used to locate it in tests. */
+export const DEPENDENCY_INSTALL_INCOMPLETE = "Dependency install incomplete.";
+function refusalWarning(input) {
+    const refusals = (input.packageRefusals ?? []).filter((r) => isSafeMarkdownFragment(r.ecosystem) && isSafeMarkdownFragment(r.name) && isSafeMarkdownFragment(r.reason));
+    if (refusals.length === 0)
+        return undefined;
+    const byReason = new Map();
+    for (const r of refusals) {
+        const names = byReason.get(r.reason) ?? new Set();
+        names.add(`${r.ecosystem} \`${r.name}\``);
+        byReason.set(r.reason, names);
+    }
+    const lines = [
+        "> [!WARNING]",
+        `> **${DEPENDENCY_INSTALL_INCOMPLETE}** Wardby's package registry refused packages during this run, so its installs did not finish and failed checks under **Tests** may come from the sandbox rather than this change.`,
+    ];
+    for (const [reason, names] of byReason) {
+        const listed = [...names];
+        const shown = listed.slice(0, MAX_WARNING_NAMES).join(", ");
+        const more = listed.length > MAX_WARNING_NAMES ? ` and ${listed.length - MAX_WARNING_NAMES} more` : "";
+        const meaning = REFUSAL_MEANING[reason];
+        lines.push(`> - ${shown}${more}: \`${reason}\`${meaning ? ` (${meaning})` : ""}`);
+    }
+    const lockfiles = (input.changedLockfiles ?? []).filter(isSafeMarkdownFragment);
+    if (lockfiles.length > 0) {
+        lines.push(`> ${lockfiles.map((f) => `\`${f}\``).join(", ")} changed in this run and may be incomplete: a clean install (\`npm ci\` or similar) in CI may fail until it is regenerated.`);
+    }
+    return lines.join("\n");
+}
 /** The hidden run marker stays first and unconditional: createOrFindDraftPullRequest's idempotent lookup depends on it. */
 export function pullRequestBody(input) {
     const sections = [`${RUN_MARKER_PREFIX}${input.runId} -->`];
@@ -129,6 +296,22 @@ export function pullRequestBody(input) {
     const issue = issueLine(input);
     if (issue)
         sections.push(issue);
+    try {
+        const related = input.related ? renderRelatedSection(input.related) : undefined;
+        if (related)
+            sections.push(related);
+    }
+    catch {
+        // omitted, like the packages section
+    }
+    try {
+        const warning = refusalWarning(input);
+        if (warning)
+            sections.push(warning);
+    }
+    catch {
+        // omitted, like the packages section
+    }
     if (input.summary)
         sections.push(input.summary);
     if (input.tests?.length) {
@@ -420,6 +603,20 @@ export class GitHubAppClient {
             throw safeApiError(response);
         });
     }
+    /**
+     * The root run's marked pull request if GitHub's `state=open` list still
+     * contains it (draft or ready for review), else null -- merged, closed, or
+     * gone. Used by git.ts's revision-in-place continuation to refuse a push to
+     * a pull request that is no longer open.
+     */
+    async findOpenPullRequest(input) {
+        const repository = normalizeGitHubRepository(input.repository);
+        const baseRef = normalizeGitRef(input.baseRef);
+        const headRef = normalizeGitRef(input.headRef);
+        if (!SAFE_RUN_ID.test(input.runId))
+            throw new Error("github_pull_request_input_invalid");
+        return this.withRepositoryToken(repository, (token) => this.findPullRequest(token, { runId: input.runId, repository, baseRef, headRef, acceptReadyForReview: true }));
+    }
     async appJwt() {
         let keyObject;
         try {

package/dist/providers/vcs/index.d.ts

@@ -3,4 +3,19 @@ import type { VcsProvider } from "./types.js";
 export * from "./types.js";
 export { GitHubAppClient } from "./github.js";
 export { GitVcsProvider, NodeGitCommandRunner } from "./git.js";
-export declare function buildVcsProvider(providerConfig: Pick<ProviderConfig, "vcs">, config: GitHubVcsConfig): VcsProvider;
+export { GitHubRemote } from "./github-remote.js";
+export { LocalRemote } from "./local-remote.js";
+export { RoutingVcsProvider, VCS_GITHUB_NOT_CONFIGURED_ERROR } from "./routing.js";
+export type { GitRemote, PublishInput, PublishResult } from "./remote.js";
+export interface BuildVcsProviderOptions {
+    /** Startup warnings; the module logger by default. */
+    warn?: (message: string) => void;
+}
+/**
+ * GitHub is built only with App credentials, local repositories only with
+ * LOCAL_REPO_ROOTS; neither being set is allowed (the server still starts) and
+ * surfaces when a repository of the missing kind is used (see
+ * RoutingVcsProvider). With neither configured no coding run can succeed, so a
+ * startup warning names both options. Only container launchers build this.
+ */
+export declare function buildVcsProvider(providerConfig: Pick<ProviderConfig, "vcs">, config: GitHubVcsConfig, env?: NodeJS.ProcessEnv, options?: BuildVcsProviderOptions): VcsProvider;

package/dist/providers/vcs/index.js

@@ -2,25 +2,53 @@ import { tmpdir } from "node:os";
 import { resolve } from "node:path";
 import { GitHubAppClient } from "./github.js";
 import { GitVcsProvider } from "./git.js";
+import { loadLocalRepoRoots } from "../../coding/local-repo.js";
+import { GitHubRemote } from "./github-remote.js";
+import { LocalRemote } from "./local-remote.js";
+import { RoutingVcsProvider } from "./routing.js";
+import { logger } from "../../core/logger.js";
+const vcsLog = logger.child({ module: "vcs" });
 export * from "./types.js";
 export { GitHubAppClient } from "./github.js";
 export { GitVcsProvider, NodeGitCommandRunner } from "./git.js";
-export function buildVcsProvider(providerConfig, config) {
+export { GitHubRemote } from "./github-remote.js";
+export { LocalRemote } from "./local-remote.js";
+export { RoutingVcsProvider, VCS_GITHUB_NOT_CONFIGURED_ERROR } from "./routing.js";
+/**
+ * GitHub is built only with App credentials, local repositories only with
+ * LOCAL_REPO_ROOTS; neither being set is allowed (the server still starts) and
+ * surfaces when a repository of the missing kind is used (see
+ * RoutingVcsProvider). With neither configured no coding run can succeed, so a
+ * startup warning names both options. Only container launchers build this.
+ */
+export function buildVcsProvider(providerConfig, config, env = process.env, options = {}) {
     if (providerConfig.vcs !== "github")
         throw new Error(`VCS_PROVIDER=${String(providerConfig.vcs)} is not supported.`);
-    if (!config.appId || !config.privateKey) {
-        throw new Error("GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY are required by the GitHub VCS adapter.");
-    }
     const rootDir = resolve(config.workRoot ?? resolve(tmpdir(), "wardby-vcs"));
-    const github = new GitHubAppClient({
-        appId: config.appId,
-        privateKey: config.privateKey,
-        apiVersion: config.apiVersion,
-    });
-    return new GitVcsProvider({
-        rootDir,
-        github,
-        maxChangedFiles: config.maxChangedFiles,
-        maxDiffBytes: config.maxDiffBytes,
-    });
+    const limits = { maxChangedFiles: config.maxChangedFiles, maxDiffBytes: config.maxDiffBytes };
+    let github = null;
+    if (config.appId && config.privateKey) {
+        const client = new GitHubAppClient({
+            appId: config.appId,
+            privateKey: config.privateKey,
+            apiVersion: config.apiVersion,
+        });
+        github = new GitVcsProvider({ rootDir, remote: new GitHubRemote({ github: client }), ...limits });
+    }
+    let local = null;
+    if (loadLocalRepoRoots(env).roots.length > 0) {
+        // Re-read per call so a root that disappears (or appears) takes effect without a restart.
+        local = new GitVcsProvider({
+            rootDir,
+            remote: new LocalRemote({ roots: () => loadLocalRepoRoots(env).roots }),
+            ...limits,
+        });
+    }
+    if (!github && !local) {
+        const warn = options.warn ?? ((message) => vcsLog.warn(message));
+        warn("No repositories are configured for coding agents: set GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY " +
+            "for GitHub repositories, or LOCAL_REPO_ROOTS for local git repositories on this server. " +
+            "Coding runs fail until one of them is set.");
+    }
+    return new RoutingVcsProvider({ github, local });
 }

package/dist/providers/vcs/local-remote.d.ts

@@ -0,0 +1,44 @@
+import type { RepositoryFileInput } from "./github.js";
+import type { GitRemote, PublishInput, PublishResult } from "./remote.js";
+export interface LocalRemoteOptions {
+    /** Trusted roots (realpaths), re-read on every call so a change takes effect without a restart. */
+    roots: () => readonly string[];
+}
+/**
+ * A git repository on the control plane's own disk (`local:/abs/path`).
+ *
+ * The source repository is touched only by `ls-remote`, the clone's
+ * upload-pack, and a push to `refs/heads/wardby/run-*`: the clone goes through
+ * a `file://` URL (so `--depth 1` is honored and nothing is hard-linked), never
+ * reads the source's working tree, and every hardening check in GitVcsProvider
+ * still applies. `protocol.file.allow=always` is set only on this remote's
+ * clone/ls-remote/push invocations; HARDENED_GIT_CONFIG's `protocol.allow=never`
+ * keeps every other transport off.
+ */
+export declare class LocalRemote implements GitRemote {
+    private readonly options;
+    readonly gitConfig: readonly string[];
+    constructor(options: LocalRemoteOptions);
+    normalizeRepository(repository: string): string;
+    /** The repository must already be named by its realpath (withAccess verifies it against the roots). */
+    cloneUrl(repository: string): string;
+    withAccess<T>(repository: string, fn: (token: string | undefined) => Promise<T>): Promise<T>;
+    /** No pull request to check: a continuation's branch must exist, which prepare's ls-remote pre-check enforces. */
+    assertContinuationOpen(): Promise<void>;
+    /**
+     * One committed file at a ref, read from git objects (never the working tree).
+     * null = the file does not exist at that ref; a missing ref is
+     * local_ref_not_found; a repository outside the roots is refused.
+     */
+    readRepositoryFile(input: RepositoryFileInput): Promise<string | null>;
+    publish({ workspace }: PublishInput): Promise<PublishResult>;
+    conflictError(): Error;
+    refNotFoundError(ref: string): Error;
+    /**
+     * receive.denyCurrentBranch=updateInstead (a user setting) would rewrite the
+     * working tree of whichever worktree has the pushed branch checked out --
+     * the main checkout or any linked worktree -- so refuse before pushing.
+     */
+    beforePush(repository: string, headRef: string): Promise<void>;
+    assertPushRef(headRef: string): void;
+}

package/dist/providers/vcs/local-remote.js

@@ -0,0 +1,108 @@
+import { pathToFileURL } from "node:url";
+import { LOCAL_REPO_PREFIX, LocalRepoError, normalizeLocalRepository, resolveLocalRepository, } from "../../coding/local-repo.js";
+import { SHA, isSafeRefName, isSafeRepoPath, localGit, localGitBytes } from "../../coding/local-git.js";
+/** The only refs a local remote ever writes into the user's repository. */
+const LOCAL_PUSH_REF = /^wardby\/run-[A-Za-z0-9_-]+$/;
+/**
+ * A git repository on the control plane's own disk (`local:/abs/path`).
+ *
+ * The source repository is touched only by `ls-remote`, the clone's
+ * upload-pack, and a push to `refs/heads/wardby/run-*`: the clone goes through
+ * a `file://` URL (so `--depth 1` is honored and nothing is hard-linked), never
+ * reads the source's working tree, and every hardening check in GitVcsProvider
+ * still applies. `protocol.file.allow=always` is set only on this remote's
+ * clone/ls-remote/push invocations; HARDENED_GIT_CONFIG's `protocol.allow=never`
+ * keeps every other transport off.
+ */
+export class LocalRemote {
+    options;
+    gitConfig = ["-c", "protocol.file.allow=always"];
+    constructor(options) {
+        this.options = options;
+    }
+    normalizeRepository(repository) {
+        return normalizeLocalRepository(repository);
+    }
+    /** The repository must already be named by its realpath (withAccess verifies it against the roots). */
+    cloneUrl(repository) {
+        return pathToFileURL(normalizeLocalRepository(repository).slice(LOCAL_REPO_PREFIX.length)).href;
+    }
+    async withAccess(repository, fn) {
+        const requested = normalizeLocalRepository(repository);
+        const resolved = await resolveLocalRepository(requested, this.options.roots());
+        // cloneUrl is built from the requested path, so it must be the path that
+        // was just checked: a symlinked or otherwise non-canonical name is refused.
+        if (resolved.repository !== requested) {
+            throw new LocalRepoError("local_repo_not_allowed", "repository must be named by its real path");
+        }
+        return fn(undefined);
+    }
+    /** No pull request to check: a continuation's branch must exist, which prepare's ls-remote pre-check enforces. */
+    async assertContinuationOpen() { }
+    /**
+     * One committed file at a ref, read from git objects (never the working tree).
+     * null = the file does not exist at that ref; a missing ref is
+     * local_ref_not_found; a repository outside the roots is refused.
+     */
+    async readRepositoryFile(input) {
+        const { path: dir } = await resolveLocalRepository(input.repository, this.options.roots());
+        if (!isSafeRepoPath(input.path))
+            throw new LocalRepoError("local_path_invalid", "invalid repository file path");
+        if (!SHA.test(input.ref) && !(await isSafeRefName(dir, input.ref))) {
+            throw new LocalRepoError("local_ref_invalid", "invalid ref");
+        }
+        let sha;
+        try {
+            sha = (await localGit(dir, ["rev-parse", "--verify", "--quiet", "--end-of-options", `${input.ref}^{commit}`], 64 * 1024)).trim();
+        }
+        catch {
+            throw new LocalRepoError("local_ref_not_found", `ref ${input.ref} does not exist in the local repository`);
+        }
+        if (!SHA.test(sha))
+            throw new LocalRepoError("local_ref_not_found", `ref ${input.ref} does not exist`);
+        const listing = await localGit(dir, ["ls-tree", "-z", "--end-of-options", sha, "--", input.path], 64 * 1024);
+        if (!listing)
+            return null;
+        if (!/^100(?:644|755) blob /.test(listing))
+            throw new Error("local_file_not_a_file");
+        const object = `${sha}:${input.path}`;
+        const size = Number((await localGit(dir, ["cat-file", "-s", "--end-of-options", object], 64 * 1024)).trim());
+        if (!Number.isSafeInteger(size) || size > input.maxBytes)
+            throw new Error("local_file_too_large");
+        const bytes = await localGitBytes(dir, ["cat-file", "blob", "--end-of-options", object], input.maxBytes + 1024);
+        if (bytes.byteLength > input.maxBytes)
+            throw new Error("local_file_too_large");
+        try {
+            return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+        }
+        catch {
+            throw new Error("local_file_not_utf8");
+        }
+    }
+    async publish({ workspace }) {
+        this.assertPushRef(workspace.headRef);
+        return { kind: "branch", branch: workspace.headRef };
+    }
+    conflictError() {
+        return new LocalRepoError("local_branch_conflict", "the branch moved in the local repository since the run started");
+    }
+    refNotFoundError(ref) {
+        return new LocalRepoError("local_ref_not_found", `branch ${ref} does not exist in the local repository`);
+    }
+    /**
+     * receive.denyCurrentBranch=updateInstead (a user setting) would rewrite the
+     * working tree of whichever worktree has the pushed branch checked out --
+     * the main checkout or any linked worktree -- so refuse before pushing.
+     */
+    async beforePush(repository, headRef) {
+        const path = normalizeLocalRepository(repository).slice(LOCAL_REPO_PREFIX.length);
+        const listing = await localGit(path, ["worktree", "list", "--porcelain"], 1024 * 1024);
+        if (listing.split("\n").some((line) => line.trim() === `branch refs/heads/${headRef}`)) {
+            throw new LocalRepoError("local_branch_conflict", `branch ${headRef} is checked out in the local repository`);
+        }
+    }
+    assertPushRef(headRef) {
+        if (!LOCAL_PUSH_REF.test(headRef))
+            throw new Error("vcs_head_ref_invalid");
+    }
+}