@wardby/cli 0.4.0 → 0.5.0

package/dist/providers/review-host/local.js

@@ -0,0 +1,434 @@
+import { LocalRepoError, loadLocalRepoRoots, normalizeLocalRepository, resolveLocalRepository, } from "../../coding/local-repo.js";
+import { SHA, isSafeRefName, isSafeRepoPath, localGit as git } from "../../coding/local-git.js";
+import { skippedInListing } from "./github.js";
+import { verdictConclusion } from "./review-format.js";
+import { ReviewHostError, } from "./types.js";
+/** GitHub lists at most 3 pages of 100 files; match it. */
+const MAX_PR_FILES = 300;
+const MAX_LISTED_FILES = 1000;
+const MAX_BODY_CHARS = 8000;
+const MAX_LOGGED_COMMITS = 100;
+const MAX_PG_INT = 2_147_483_647;
+const STATUS = {
+    A: "added",
+    M: "modified",
+    D: "removed",
+    R: "renamed",
+    C: "copied",
+    T: "changed",
+};
+function fail(message) {
+    throw new ReviewHostError("host_api_error", message);
+}
+function assertRepoPath(path) {
+    if (!isSafeRepoPath(path))
+        fail("path_invalid");
+}
+function prUrl(row) {
+    return row.runId ? `wardby://runs/${row.runId}/review` : `wardby://local-pulls/${row.number}`;
+}
+/** Hunks only, as GitHub's `patch` field: the `diff --git`/index/---/+++ header is dropped, no trailing newline. */
+function hunks(diff) {
+    const start = diff.startsWith("@@") ? 0 : diff.indexOf("\n@@") + 1;
+    // indexOf -1 + 1 = 0 without a leading "@@": no hunks (binary, mode or pure rename).
+    if (start === 0 && !diff.startsWith("@@"))
+        return "";
+    return diff.slice(start).replace(/\n$/, "");
+}
+function tooLarge(err) {
+    return err?.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER";
+}
+export class LocalReviewHost {
+    provider = "local";
+    db;
+    roots;
+    constructor(options) {
+        this.db = options.db;
+        this.roots = options.roots ?? (() => loadLocalRepoRoots(process.env).roots);
+    }
+    /** The canonical repository and its realpath, checked against the current roots. */
+    async repo(repository) {
+        try {
+            return await resolveLocalRepository(repository, this.roots());
+        }
+        catch (err) {
+            fail(err instanceof LocalRepoError ? err.code : "local_repo_invalid");
+        }
+    }
+    async pullRequest(canonical, requested, number) {
+        const row = Number.isSafeInteger(number) && number > 0 && number <= MAX_PG_INT
+            ? await this.db.localPullRequest.findUnique({ where: { number } })
+            : null;
+        if (!row || (row.repository !== canonical && row.repository !== normalizeLocalRepository(requested))) {
+            fail("no such local pull request");
+        }
+        return row;
+    }
+    /** Rejects anything but a plain branch/tag name before it can reach git as a revision or an option. */
+    async assertRefName(dir, name) {
+        if (!(await isSafeRefName(dir, name)))
+            fail("ref_invalid");
+    }
+    /** The commit a sha or branch name points at. */
+    async commitOf(dir, ref) {
+        if (!SHA.test(ref))
+            await this.assertRefName(dir, ref);
+        let out;
+        try {
+            out = await git(dir, ["rev-parse", "--verify", "--quiet", "--end-of-options", `${ref}^{commit}`], 64 * 1024);
+        }
+        catch {
+            fail("local_ref_not_found");
+        }
+        const sha = out.trim();
+        if (!SHA.test(sha))
+            fail("local_ref_not_found");
+        return sha;
+    }
+    /** The repository's checked-out HEAD commit (its "default branch"), and a label for it. */
+    async defaultRef(dir) {
+        let label = "HEAD";
+        try {
+            label = (await git(dir, ["symbolic-ref", "--short", "-q", "HEAD"], 64 * 1024)).trim() || "HEAD";
+        }
+        catch {
+            // detached HEAD
+        }
+        let sha;
+        try {
+            sha = (await git(dir, ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"], 64 * 1024)).trim();
+        }
+        catch {
+            fail("local_ref_not_found");
+        }
+        if (!SHA.test(sha))
+            fail("local_ref_not_found");
+        return { sha, label };
+    }
+    async resolveRef(dir, ref) {
+        return ref === undefined ? this.defaultRef(dir) : { sha: await this.commitOf(dir, ref), label: ref };
+    }
+    async isAncestor(dir, ancestor, descendant) {
+        try {
+            await git(dir, ["merge-base", "--is-ancestor", "--end-of-options", ancestor, descendant], 64 * 1024);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Files changed between two commits (both 40-hex), with rename detection, in git's order. */
+    async changedFiles(dir, from, to) {
+        const diff = ["diff", "--no-ext-diff", "--no-textconv", "--no-color", "-M", "-z"];
+        let nameStatus;
+        let numstat;
+        try {
+            nameStatus = await git(dir, [...diff, "--name-status", "--end-of-options", from, to]);
+            numstat = await git(dir, [...diff, "--numstat", "--end-of-options", from, to]);
+        }
+        catch {
+            fail("local_git_failed");
+        }
+        const counts = new Map();
+        const n = numstat.split("\0");
+        for (let i = 0; i < n.length && n[i] !== "";) {
+            const [add, del, ...rest] = n[i].split("\t");
+            let path = rest.join("\t");
+            if (path === "") {
+                path = n[i + 2] ?? "";
+                i += 3;
+            }
+            else {
+                i += 1;
+            }
+            // Binary files show "-": GitHub reports 0 for them.
+            counts.set(path, { additions: Number(add) || 0, deletions: Number(del) || 0 });
+        }
+        const files = [];
+        const s = nameStatus.split("\0");
+        for (let i = 0; i < s.length && s[i] !== "";) {
+            const code = s[i].charAt(0);
+            let filename;
+            let previousFilename;
+            if (code === "R" || code === "C") {
+                previousFilename = s[i + 1];
+                filename = s[i + 2] ?? "";
+                i += 3;
+            }
+            else {
+                filename = s[i + 1] ?? "";
+                i += 2;
+            }
+            files.push({
+                filename,
+                ...(previousFilename !== undefined ? { previousFilename } : {}),
+                status: STATUS[code] ?? "changed",
+                ...(counts.get(filename) ?? { additions: 0, deletions: 0 }),
+            });
+        }
+        return files.slice(0, MAX_PR_FILES);
+    }
+    /** Attaches patches, sharing one character budget across files and flagging truncation like GitHub. */
+    async withPatches(dir, from, to, files, maxPatchChars) {
+        let budget = maxPatchChars;
+        const out = [];
+        for (const file of files) {
+            const changes = file.additions + file.deletions;
+            if (budget <= 0) {
+                out.push({ ...file, patch: "", patchTruncated: changes > 0 });
+                continue;
+            }
+            let patch;
+            let complete = true;
+            try {
+                const paths = file.previousFilename ? [file.previousFilename, file.filename] : [file.filename];
+                patch = hunks(await git(dir, [
+                    "diff",
+                    "--no-ext-diff",
+                    "--no-textconv",
+                    "--no-color",
+                    "-M",
+                    "--end-of-options",
+                    from,
+                    to,
+                    "--",
+                    ...paths,
+                ]));
+            }
+            catch {
+                // Too large for the buffer (or unreadable): no patch, flagged.
+                patch = "";
+                complete = changes === 0;
+            }
+            const kept = patch.length <= budget ? patch : patch.slice(0, Math.max(0, budget));
+            budget -= kept.length;
+            out.push({ ...file, patch: kept, patchTruncated: kept.length < patch.length || !complete });
+        }
+        return out;
+    }
+    async repositoryPermission(_repository, _user) {
+        return { level: "admin", login: "local" };
+    }
+    async readPullRequest(repository, prNumber, opts) {
+        const { repository: canonical, path: dir } = await this.repo(repository);
+        const row = await this.pullRequest(canonical, repository, prNumber);
+        const headSha = await this.commitOf(dir, row.branch);
+        const baseTip = await this.commitOf(dir, row.base);
+        let baseSha;
+        try {
+            baseSha = (await git(dir, ["merge-base", "--end-of-options", baseTip, headSha], 64 * 1024)).trim();
+        }
+        catch {
+            fail("no common ancestor between the branch and its base");
+        }
+        if (!SHA.test(baseSha))
+            fail("no common ancestor between the branch and its base");
+        let from = baseSha;
+        let files = null;
+        let comparedFrom = null;
+        let baseMergedSince = false;
+        const since = opts.sinceSha;
+        if (since && SHA.test(since) && since !== headSha && (await this.isAncestor(dir, since, headSha))) {
+            comparedFrom = since;
+            files = await this.changedFiles(dir, since, headSha);
+            from = since;
+            let merges = "0";
+            try {
+                merges = await git(dir, ["rev-list", "--count", "--min-parents=2", "--end-of-options", `${since}..${headSha}`]);
+            }
+            catch {
+                fail("local_git_failed");
+            }
+            baseMergedSince = Number(merges.trim()) > 0;
+            if (baseMergedSince) {
+                // As on GitHub: the PR's own diff against its base, limited to files that changed since.
+                const changedSince = new Set(files.map((f) => f.filename));
+                files = (await this.changedFiles(dir, baseSha, headSha)).filter((f) => changedSince.has(f.filename));
+                from = baseSha;
+            }
+        }
+        files ??= await this.changedFiles(dir, baseSha, headSha);
+        let log = "";
+        try {
+            log = await git(dir, [
+                "log",
+                "--no-color",
+                `--max-count=${MAX_LOGGED_COMMITS}`,
+                "--format=- %h %s",
+                "--end-of-options",
+                `${baseSha}..${headSha}`,
+            ]);
+        }
+        catch {
+            // The commit list is a courtesy; the diff is the review.
+        }
+        const last = await this.db.localReview.findFirst({
+            where: { pullRequestId: row.id, agentId: opts.agentMarker },
+            orderBy: { createdAt: "desc" },
+            select: { headSha: true },
+        });
+        return {
+            number: row.number,
+            title: `${row.branch} into ${row.base}`,
+            body: (log.trim() ? `Commits on ${row.branch} since ${row.base}:\n${log.trimEnd()}` : "").slice(0, MAX_BODY_CHARS),
+            author: null,
+            state: "open",
+            merged: false,
+            draft: false,
+            baseRef: row.base,
+            headRef: row.branch,
+            headSha,
+            isFork: false,
+            htmlUrl: prUrl(row),
+            lastReviewedSha: last?.headSha ?? null,
+            comparedFrom,
+            baseMergedSince,
+            files: await this.withPatches(dir, from, headSha, files, opts.maxPatchChars),
+            openThreads: [],
+            ci: { headSha, state: "none", checks: [], truncated: false, statusesUnavailable: false },
+        };
+    }
+    async pullRequestHead(repository, prNumber) {
+        const { repository: canonical, path: dir } = await this.repo(repository);
+        const row = await this.pullRequest(canonical, repository, prNumber);
+        return { headSha: await this.commitOf(dir, row.branch), isFork: false, state: "open" };
+    }
+    async readFile(repository, path, ref, window) {
+        assertRepoPath(path);
+        const { path: dir } = await this.repo(repository);
+        const { sha, label } = await this.resolveRef(dir, ref);
+        const object = `${sha}:${path}`;
+        let type;
+        try {
+            type = (await git(dir, ["cat-file", "-t", "--end-of-options", object], 64 * 1024)).trim();
+        }
+        catch {
+            return { kind: "not_found", path };
+        }
+        if (type === "tree") {
+            let listing;
+            try {
+                listing = await git(dir, ["ls-tree", "-z", "--end-of-options", object]);
+            }
+            catch {
+                fail("local_git_failed");
+            }
+            const entries = listing
+                .split("\0")
+                .filter((entry) => entry !== "")
+                .map((entry) => {
+                const tab = entry.indexOf("\t");
+                const kind = entry.slice(0, tab).split(" ")[1];
+                return `${kind === "tree" ? "dir " : "file"} ${path}/${entry.slice(tab + 1)}`;
+            });
+            return { kind: "directory", path, entries };
+        }
+        if (type !== "blob")
+            return { kind: "not_found", path };
+        let text;
+        try {
+            text = await git(dir, ["cat-file", "blob", "--end-of-options", object]);
+        }
+        catch (err) {
+            fail(tooLarge(err) ? "file_too_large" : "local_git_failed");
+        }
+        const lines = text.split("\n");
+        const slice = lines.slice(window.startLine - 1, window.startLine - 1 + window.maxLines);
+        return {
+            kind: "file",
+            path,
+            ref: label,
+            totalLines: lines.length,
+            startLine: window.startLine,
+            endLine: window.startLine + slice.length - 1,
+            truncated: window.startLine - 1 + slice.length < lines.length,
+            content: slice.map((line, i) => `${window.startLine + i}: ${line}`).join("\n"),
+            text: slice.join("\n"),
+        };
+    }
+    async listFiles(repository, ref, pathPrefix = "") {
+        const { path: dir } = await this.repo(repository);
+        const { sha, label } = await this.resolveRef(dir, ref);
+        let listing;
+        try {
+            listing = await git(dir, ["ls-tree", "-r", "-l", "-z", "--full-tree", "--end-of-options", sha]);
+        }
+        catch {
+            fail("local_git_failed");
+        }
+        const entries = listing
+            .split("\0")
+            .filter((entry) => entry !== "")
+            .map((entry) => {
+            const tab = entry.indexOf("\t");
+            const [, kind, , size] = entry.slice(0, tab).split(/ +/);
+            return { kind, size: Number(size) || 0, path: entry.slice(tab + 1) };
+        })
+            .filter((e) => e.kind === "blob" && e.path.startsWith(pathPrefix) && !skippedInListing(e.path));
+        const shown = entries.slice(0, MAX_LISTED_FILES);
+        return {
+            ref: label,
+            count: entries.length,
+            truncated: entries.length > MAX_LISTED_FILES,
+            files: shown.map((e) => `${e.path} (${e.size} bytes)`),
+            paths: shown.map((e) => e.path),
+        };
+    }
+    async publishReview(repository, input) {
+        const { repository: canonical, path: dir } = await this.repo(repository);
+        const row = await this.pullRequest(canonical, repository, input.prNumber);
+        const currentHeadSha = await this.commitOf(dir, row.branch);
+        if (input.headSha !== currentHeadSha)
+            return { published: false, reason: "stale_head", currentHeadSha };
+        const review = await this.db.localReview.create({
+            data: {
+                pullRequestId: row.id,
+                agentId: input.agentMarker,
+                headSha: currentHeadSha,
+                verdict: input.verdict,
+                summary: input.summary,
+                body: input.body,
+                comments: input.comments.map(({ path, line, side, severity, body }) => ({ path, line, side, severity, body })),
+            },
+            select: { id: true },
+        });
+        const url = `${prUrl(row)}#${review.id}`;
+        return {
+            published: true,
+            reviewUrl: url,
+            summaryCommentUrl: url,
+            checkId: input.checkId ?? null,
+            checkConclusion: verdictConclusion(input.verdict),
+            inlineCount: input.comments.length,
+            outsideDiffCount: 0,
+            resolvedThreadIds: [],
+            // A local pull request has no threads to resolve.
+            skippedThreadIds: [...new Set(input.resolveThreadIds ?? [])],
+        };
+    }
+    /** Stored as a COMMENT review on the branch's current head. The host is not told who comments: agentId is "". */
+    async comment(repository, input) {
+        const { repository: canonical, path: dir } = await this.repo(repository);
+        const row = await this.pullRequest(canonical, repository, input.number);
+        const headSha = await this.commitOf(dir, row.branch);
+        const review = await this.db.localReview.create({
+            data: {
+                pullRequestId: row.id,
+                agentId: "",
+                headSha,
+                verdict: "COMMENT",
+                summary: "",
+                body: input.body,
+                comments: [],
+            },
+            select: { id: true },
+        });
+        return { url: `${prUrl(row)}#${review.id}`, id: review.id };
+    }
+    async editComment(_repository, _input) { }
+    async acknowledge(_repository, _target) { }
+    async startCheck(_repository, _input) {
+        return { checkId: "local" };
+    }
+    async completeCheck(_repository, _input) { }
+}

package/dist/providers/review-host/types.d.ts

@@ -1,12 +1,14 @@
 /**
- * Host-neutral code-review surface for native agents. GitHub is the first
- * implementation (./github.ts); Bitbucket Cloud is anticipated. Every method
+ * Host-neutral code-review surface for native agents. GitHub (./github.ts) and
+ * local git repositories (./local.ts) implement it; Bitbucket Cloud is anticipated. Every method
  * takes the repository and mints its own least-permission credential — no
  * method accepts a token or a permission. See
  * docs/private/2026-09-25-code-review-host-design.md §5.
  */
-export type ReviewHostProvider = "github";
+export type ReviewHostProvider = "github" | "local";
 export declare const REVIEW_HOST_PROVIDERS: readonly ReviewHostProvider[];
+/** Providers with host user accounts to link (link_host_account); a local repository has none. */
+export declare const HOST_ACCOUNT_PROVIDERS: readonly ReviewHostProvider[];
 export type ReviewVerdict = "APPROVE" | "CHANGES_REQUESTED" | "COMMENT";
 export type CheckConclusion = "success" | "failure" | "neutral";
 export type CommentSide = "LEFT" | "RIGHT";
@@ -30,6 +32,30 @@ export interface ReviewThreadView {
     /** The finding as posted, without its marker, capped at 1,000 characters. */
     body: string;
 }
+export type CiState = "passing" | "failing" | "pending" | "inconclusive" | "none" | "unavailable";
+/** One CI result on a commit: a check run or a commit status. */
+export interface CiCheckView {
+    /** Check run name or status context (repository-controlled text), capped at 100 characters. */
+    name: string;
+    kind: "check_run" | "status";
+    status: "queued" | "in_progress" | "completed";
+    /** Set when completed: success, failure, neutral, cancelled, skipped, timed_out, action_required, stale, startup_failure, error. */
+    conclusion: string | null;
+    /** The app that reported a check run (e.g. "github-actions"); null for statuses. */
+    app: string | null;
+}
+/** CI on the PR's head commit, excluding everything wardby's own App reported. */
+export interface CiView {
+    headSha: string;
+    state: CiState;
+    checks: CiCheckView[];
+    /** More results exist than are listed. */
+    truncated: boolean;
+    /** Commit statuses could not be read (permission not granted); only check runs are listed. */
+    statusesUnavailable: boolean;
+    /** Set when state is "unavailable": a host error code. */
+    unavailableReason?: string;
+}
 export interface PullRequestView {
     number: number;
     title: string;
@@ -56,12 +82,24 @@ export interface PullRequestView {
     files: PullRequestFileView[];
     /** This agent's own unresolved review threads on the PR (the first 100 threads are searched). */
     openThreads: ReviewThreadView[];
+    /** CI on headSha (check runs and commit statuses, minus wardby's own); absent on hosts that can't read CI. */
+    ci?: CiView;
 }
 export interface PullRequestHead {
     headSha: string;
     isFork: boolean;
     state: string;
 }
+export interface PullRequestOrigin extends PullRequestHead {
+    /** The run id in the description's marker; only on a PR the App itself authored. */
+    markerRunId?: string;
+    /** The PR's label names; empty on a host without labels. */
+    labels: string[];
+    /** True once merged; absent on hosts that can't say. */
+    merged?: boolean;
+    /** True while a draft; absent on hosts that can't say. */
+    draft?: boolean;
+}
 export type FileReadResult = {
     kind: "file";
     path: string;
@@ -200,6 +238,23 @@ export interface CodeReviewHost {
         agentMarker: string;
     }): Promise<PullRequestView>;
     pullRequestHead(repository: string, prNumber: number): Promise<PullRequestHead>;
+    /** CI on one commit, excluding wardby's own checks. Never throws. Hosts that can't say leave it out. */
+    readCi?(repository: string, headSha: string): Promise<CiView>;
+    /** Head, labels, and (on an App-authored PR) the run marker. Hosts that can't say leave it out. */
+    pullRequestOrigin?(repository: string, prNumber: number): Promise<PullRequestOrigin>;
+    /** Adds a label to a pull request (created if missing). Absent on hosts without labels. */
+    addLabel?(repository: string, prNumber: number, label: string): Promise<void>;
+    /**
+     * Replaces (or inserts) wardby's marked Related pull requests section in an
+     * open pull request's description — only on a PR the App itself authored
+     * whose run marker is `expectedMarkerRunId`. "skipped" covers every refusal
+     * (not the App's, another run's, closed, malformed markers, too long).
+     * Absent on hosts that can't edit descriptions.
+     */
+    replaceRelatedSection?(repository: string, prNumber: number, input: {
+        expectedMarkerRunId: string;
+        block: string;
+    }): Promise<"updated" | "unchanged" | "skipped">;
     readFile(repository: string, path: string, ref: string | undefined, window: {
         startLine: number;
         maxLines: number;
@@ -278,6 +333,13 @@ export type HostEvent = {
     repository: string;
     prNumber: number;
     merged: boolean;
+} | {
+    /** A CI check suite (not wardby's own) finished on a commit some open pull requests point at. */
+    kind: "ci_completed";
+    provider: ReviewHostProvider;
+    repository: string;
+    headSha: string;
+    prNumbers: number[];
 } | {
     kind: "check_rerun";
     provider: ReviewHostProvider;

package/dist/providers/review-host/types.js

@@ -1,11 +1,13 @@
 /**
- * Host-neutral code-review surface for native agents. GitHub is the first
- * implementation (./github.ts); Bitbucket Cloud is anticipated. Every method
+ * Host-neutral code-review surface for native agents. GitHub (./github.ts) and
+ * local git repositories (./local.ts) implement it; Bitbucket Cloud is anticipated. Every method
  * takes the repository and mints its own least-permission credential — no
  * method accepts a token or a permission. See
  * docs/private/2026-09-25-code-review-host-design.md §5.
  */
-export const REVIEW_HOST_PROVIDERS = ["github"];
+export const REVIEW_HOST_PROVIDERS = ["github", "local"];
+/** Providers with host user accounts to link (link_host_account); a local repository has none. */
+export const HOST_ACCOUNT_PROVIDERS = ["github"];
 export const HOST_PERMISSION_RANK = {
     none: 0,
     read: 1,

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

@@ -1,4 +1,5 @@
-import { type GitHubRepositoryAccess, type RepositoryFileInput } from "./github.js";
+import { type RepositoryFileInput } from "./github.js";
+import type { GitRemote } from "./remote.js";
 import type { ContinuationFinishedDetails, ContinuationOutcome, FinalizeChangesDetails, FinalizeChangesResult, PreparedWorkspace, VcsPrepareInput, VcsProvider } from "./types.js";
 export declare const DEFAULT_MAX_CHANGED_FILES = 1000;
 export declare const DEFAULT_MAX_DIFF_BYTES: number;
@@ -36,12 +37,11 @@ export declare class NodeGitCommandRunner implements GitCommandRunner {
 }
 export interface GitVcsProviderOptions {
     rootDir: string;
-    github: GitHubRepositoryAccess;
+    /** Where repositories are cloned from and pushed to (GitHubRemote in production). */
+    remote: GitRemote;
     git?: GitCommandRunner;
     maxChangedFiles?: number;
     maxDiffBytes?: number;
-    /** Test-only transport override; production composition always uses github.com. */
-    cloneUrlForRepository?: (repository: string) => string;
 }
 /**
  * Whether a changed path is protected, in this order: the WARDBY_PROTECTED_PATHS
@@ -55,37 +55,27 @@ export interface GitVcsProviderOptions {
  * in-flight run gets it.
  */
 export declare function protectedPathMatcher(patterns: readonly string[]): (path: string) => boolean;
+export declare function validateChangedPath(path: string): string;
 export declare class GitVcsProvider implements VcsProvider {
-    private readonly options;
     private readonly rootDir;
     private readonly git;
     private readonly maxChangedFiles;
     private readonly maxDiffBytes;
-    private readonly cloneUrlForRepository;
+    private readonly remote;
     constructor(options: GitVcsProviderOptions);
     prepareWorkspace(input: VcsPrepareInput): Promise<PreparedWorkspace>;
     recoverWorkspace(input: VcsPrepareInput): Promise<PreparedWorkspace | null>;
     finalizeChanges(workspace: PreparedWorkspace, details?: FinalizeChangesDetails): Promise<FinalizeChangesResult>;
     cleanup(workspace: PreparedWorkspace): Promise<void>;
     /**
-     * Best-effort "wardby is working on this PR" signal (see VcsProvider) --
-     * whole body wrapped so this can NEVER throw or otherwise affect the
-     * real coding run, mirroring docker.ts's readWorkerFailureDiagnostic
-     * ("diagnostics are optional and must never affect terminal cleanup").
-     * No-op for a fresh (non-continuation) workspace: there's no PR to
-     * attach anything to until its one commit lands.
+     * Best-effort "wardby is working on this PR" signal (see VcsProvider),
+     * delegated to the remote; a remote without one is a no-op. Wrapped so
+     * this can NEVER throw or otherwise affect the real coding run.
      */
     notifyContinuationStarted(workspace: PreparedWorkspace, details?: {
         agentName?: string;
     }): Promise<void>;
-    /**
-     * Companion to notifyContinuationStarted -- finds and updates whatever
-     * that call created, never creates fresh state itself (see
-     * upsertContinuationStatusComment vs updateContinuationStatusComment,
-     * and createContinuationCheckRun vs completeContinuationCheckRun in
-     * github.ts). Safe to call more than once for the same run. Same
-     * never-throw contract as notifyContinuationStarted.
-     */
+    /** Companion to notifyContinuationStarted, delegated to the remote under the same never-throw contract. */
     notifyContinuationFinished(workspace: PreparedWorkspace, outcome: ContinuationOutcome, details?: ContinuationFinishedDetails): Promise<void>;
     readRepositoryFile(input: RepositoryFileInput): Promise<string | null>;
     private validateInput;