@wardby/cli 0.4.0 → 0.5.0

package/dist/providers/vcs/git.js

@@ -6,7 +6,7 @@ import { gitExcludePathspecs, normalizeCollectExclusions } from "../../coding/co
 import { WARDBY_PROTECTED_PATHS, isProtectedPathException, isWellFormedProtectedPath, protectedPathBody, protectsSomePath, } from "../../coding/protected-paths.js";
 import { ensurePrivateDirectory } from "../../core/private-directory.js";
 import { globRegex } from "../../core/glob.js";
-import { MAX_REDACTED_SPAN, redactTokenShapedValues, normalizeGitHubRepository, normalizeGitRef, } from "../../coding/protocol.js";
+import { MAX_REDACTED_SPAN, redactTokenShapedValues, normalizeGitRef } from "../../coding/protocol.js";
 import { isSafeGitHubInstallationToken } from "./github.js";
 export const DEFAULT_MAX_CHANGED_FILES = 1_000;
 export const DEFAULT_MAX_DIFF_BYTES = 1024 * 1024;
@@ -177,7 +177,7 @@ export function protectedPathMatcher(patterns) {
         return protectedPatterns.some((matcher) => matcher.test(path)) && !exceptions.has(path);
     };
 }
-function validateChangedPath(path) {
+export function validateChangedPath(path) {
     if (!path ||
         isAbsolute(path) ||
         path.includes("\\") ||
@@ -195,19 +195,13 @@ function nullSeparated(value) {
 function directChild(root, child) {
     return child.startsWith(`${root}${sep}`) && !child.slice(root.length + 1).includes(sep);
 }
-/** Human-readable label for continuation status notifications -- falls back to the opaque run id alone when no agent name is known. */
-function runLabel(agentName, runId) {
-    return agentName ? `${agentName} (wardby run ${runId})` : `wardby run ${runId}`;
-}
 export class GitVcsProvider {
-    options;
     rootDir;
     git;
     maxChangedFiles;
     maxDiffBytes;
-    cloneUrlForRepository;
+    remote;
     constructor(options) {
-        this.options = options;
         this.rootDir = resolve(options.rootDir);
         if (this.rootDir === resolve("/"))
             throw new Error("vcs_root_invalid");
@@ -220,11 +214,11 @@ export class GitVcsProvider {
             this.maxDiffBytes <= 0) {
             throw new Error("vcs_limits_invalid");
         }
-        this.cloneUrlForRepository =
-            options.cloneUrlForRepository ?? ((repository) => `https://github.com/${repository}.git`);
+        this.remote = options.remote;
     }
     async prepareWorkspace(input) {
         const normalized = this.validateInput(input);
+        await this.remote.assertContinuationOpen(normalized);
         await ensurePrivateDirectory(this.rootDir);
         await mkdir(resolve(this.rootDir, ".home"), { recursive: true, mode: 0o700 });
         const runRoot = resolve(this.rootDir, normalized.runId);
@@ -240,10 +234,9 @@ export class GitVcsProvider {
         }
         const workspacePath = resolve(runRoot, "workspace");
         const gitMetadataPath = resolve(runRoot, "git");
-        const cloneUrl = this.cloneUrlForRepository(normalized.repository);
-        if (!this.options.cloneUrlForRepository && cloneUrl !== `https://github.com/${normalized.repository}.git`) {
-            throw new Error("vcs_remote_invalid");
-        }
+        // The remote validates its own URL (GitHubRemote: vcs_remote_invalid
+        // unless it is exactly github.com's, outside the test-only override).
+        const cloneUrl = this.remote.cloneUrl(normalized.repository);
         // Revision-in-place: a continuation clones the EXISTING headRef branch
         // directly (its current tip becomes baseCommit below) instead of
         // baseRef -- everything after this line (branch/checkout/reset, and
@@ -252,9 +245,24 @@ export class GitVcsProvider {
         // round started."
         const cloneBranch = normalized.continuation ? normalized.headRef : normalized.baseRef;
         try {
-            await this.options.github.withRepositoryToken(normalized.repository, async (token) => {
+            await this.remote.withAccess(normalized.repository, async (token) => {
+                const auth = token !== undefined ? { authToken: token } : {};
+                if (this.remote.refNotFoundError) {
+                    const listed = await this.git.run([
+                        ...HARDENED_GIT_CONFIG,
+                        ...this.remote.gitConfig,
+                        "ls-remote",
+                        "--heads",
+                        cloneUrl,
+                        `refs/heads/${cloneBranch}`,
+                    ], { cwd: runRoot, ...auth });
+                    const found = listed.stdout.split("\n").some((line) => line.split("\t")[1] === `refs/heads/${cloneBranch}`);
+                    if (!found)
+                        throw this.remote.refNotFoundError(cloneBranch);
+                }
                 await this.git.run([
                     ...HARDENED_GIT_CONFIG,
+                    ...this.remote.gitConfig,
                     "clone",
                     "--no-checkout",
                     "--single-branch",
@@ -271,7 +279,7 @@ export class GitVcsProvider {
                     gitMetadataPath,
                     cloneUrl,
                     workspacePath,
-                ], { cwd: runRoot, authToken: token });
+                ], { cwd: runRoot, ...auth });
             });
             await rm(resolve(workspacePath, ".git"), { force: true });
             const baseCommit = await this.revParseRaw(gitMetadataPath, workspacePath, `refs/remotes/origin/${cloneBranch}^{commit}`);
@@ -417,28 +425,21 @@ export class GitVcsProvider {
                 throw new Error("vcs_finalized_workspace_changed");
             commitSha = currentHead;
         }
+        await this.remote.assertContinuationOpen(prepared);
         await this.pushOnce(prepared, commitSha);
-        // Revision-in-place: identify the PR by the run that originally opened
-        // it (createOrFindDraftPullRequest's marker-based lookup keys on that
-        // run's id), not this run's own -- this finds the existing open PR and
-        // returns it rather than creating a new one, since headRef/baseRef
-        // already match it exactly. No other change needed here: pushing a new
-        // commit onto that branch already updates the PR natively -- which is
-        // also why a PR a person has since marked ready for review is accepted
-        // (acceptReadyForReview) rather than failing an already-pushed run.
-        const pullRequest = await this.options.github.createOrFindDraftPullRequest({
-            runId: prepared.continuation?.rootRunId ?? prepared.runId,
-            ...(prepared.continuation ? { acceptReadyForReview: true } : {}),
-            repository: prepared.repository,
-            baseRef: prepared.baseRef,
-            headRef: prepared.headRef,
-            summary: details?.summary,
-            tests: details?.tests,
-            tag: details?.tag,
-            packages: details?.packages,
-            packageRefusals: details?.packageRefusals,
-            ...(details?.issue ? { issue: details.issue } : {}),
-        });
+        const published = await this.remote.publish({ workspace: prepared, details, changedPaths: changed });
+        if (published.kind === "branch") {
+            if (published.branch !== prepared.headRef)
+                throw new Error("vcs_head_ref_mismatch");
+            return {
+                outcome: "branch_pushed",
+                repository: prepared.repository,
+                baseRef: prepared.baseRef,
+                baseCommit: prepared.baseCommit,
+                headRef: prepared.headRef,
+                commitSha,
+            };
+        }
         return {
             outcome: prepared.continuation ? "pull_request_updated" : "pull_request_opened",
             repository: prepared.repository,
@@ -446,8 +447,8 @@ export class GitVcsProvider {
             baseCommit: prepared.baseCommit,
             headRef: prepared.headRef,
             commitSha,
-            pullRequestNumber: pullRequest.number,
-            pullRequestUrl: pullRequest.url,
+            pullRequestNumber: published.number,
+            pullRequestUrl: published.url,
         };
     }
     async cleanup(workspace) {
@@ -460,102 +461,36 @@ export class GitVcsProvider {
         await rm(expected.runRoot, { recursive: true, force: true });
     }
     /**
-     * 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.
      */
     async notifyContinuationStarted(workspace, details) {
-        if (!workspace.continuation)
-            return;
         try {
-            const identity = {
-                runId: workspace.runId,
-                rootRunId: workspace.continuation.rootRunId,
-                repository: workspace.repository,
-                baseRef: workspace.baseRef,
-                headRef: workspace.headRef,
-            };
-            await Promise.allSettled([
-                this.options.github.upsertContinuationStatusComment({
-                    ...identity,
-                    body: `🔄 ${runLabel(details?.agentName, workspace.runId)} is working on this PR...`,
-                }),
-                this.options.github.createContinuationCheckRun({
-                    repository: workspace.repository,
-                    headSha: workspace.baseCommit,
-                    runId: workspace.runId,
-                }),
-            ]);
+            await this.remote.notifyContinuationStarted?.(workspace, details);
         }
         catch {
             // Best-effort observability only -- must never affect the real run.
         }
     }
-    /**
-     * 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. */
     async notifyContinuationFinished(workspace, outcome, details) {
-        if (!workspace.continuation)
-            return;
         try {
-            const identity = {
-                runId: workspace.runId,
-                rootRunId: workspace.continuation.rootRunId,
-                repository: workspace.repository,
-                baseRef: workspace.baseRef,
-                headRef: workspace.headRef,
-            };
-            const label = runLabel(details?.agentName, workspace.runId);
-            const summarySuffix = details?.summary ? `\n\n${details.summary}` : "";
-            const budgetSuffix = details?.budgetSentence ? ` ${details.budgetSentence}` : "";
-            const body = outcome === "succeeded"
-                ? `✅ ${label} finished.${summarySuffix}`
-                : outcome === "budget_exhausted"
-                    ? `❌ ${label} ran out of budget.${budgetSuffix}${summarySuffix}`
-                    : details?.serviceSentence
-                        ? `❌ ${label} could not start: ${details.serviceSentence}${summarySuffix}`
-                        : details?.providerSentence
-                            ? `❌ ${label} could not run: ${details.providerSentence}${summarySuffix}`
-                            : details?.protectedPathSentence
-                                ? `❌ ${label} could not open its changes: ${details.protectedPathSentence}${summarySuffix}`
-                                : `❌ ${label} failed.${summarySuffix}`;
-            await Promise.allSettled([
-                this.options.github.updateContinuationStatusComment({ ...identity, body }),
-                this.options.github.completeContinuationCheckRun({
-                    repository: workspace.repository,
-                    headSha: workspace.baseCommit,
-                    runId: workspace.runId,
-                    outcome: outcome === "succeeded" ? "succeeded" : "failed",
-                }),
-            ]);
+            await this.remote.notifyContinuationFinished?.(workspace, outcome, details);
         }
         catch {
             // Best-effort observability only -- must never affect the real run.
         }
     }
     async readRepositoryFile(input) {
-        const github = this.options.github;
-        if (!github.readFileAtRef)
+        if (!this.remote.readRepositoryFile)
             throw new Error("vcs_read_file_unsupported");
-        return github.readFileAtRef({
-            repository: normalizeGitHubRepository(input.repository),
-            ref: normalizeGitRef(input.ref),
-            path: validateChangedPath(input.path),
-            maxBytes: input.maxBytes,
-        });
+        return this.remote.readRepositoryFile(input);
     }
     validateInput(input) {
         if (!SAFE_RUN_ID.test(input.runId))
             throw new Error("vcs_run_id_invalid");
-        const repository = normalizeGitHubRepository(input.repository);
+        const repository = this.remote.normalizeRepository(input.repository);
         const baseRef = normalizeGitRef(input.baseRef);
         const headRef = normalizeGitRef(input.headRef);
         // Revision-in-place: a continuation's headRef legitimately belongs to a
@@ -660,7 +595,7 @@ export class GitVcsProvider {
         await visit(workspacePath);
     }
     async assertRemote(workspace) {
-        const expectedUrl = this.cloneUrlForRepository(workspace.repository);
+        const expectedUrl = this.remote.cloneUrl(workspace.repository);
         const remotes = (await this.gitFor(workspace, ["remote"])).stdout.trim().split("\n").filter(Boolean);
         const fetchUrls = (await this.gitFor(workspace, ["remote", "get-url", "--all", "origin"])).stdout
             .trim()
@@ -701,33 +636,42 @@ export class GitVcsProvider {
         }
     }
     async pushOnce(workspace, commitSha) {
-        await this.options.github.withRepositoryToken(workspace.repository, async (token) => {
-            const remote = await this.remoteHead(workspace, token);
+        this.remote.assertPushRef?.(workspace.headRef);
+        await this.remote.withAccess(workspace.repository, async (token) => {
+            const auth = token !== undefined ? { authToken: token } : {};
+            const remote = await this.remoteHead(workspace, auth);
             if (remote === commitSha)
                 return;
+            await this.remote.beforePush?.(workspace.repository, workspace.headRef);
             // A continuation's remote branch legitimately already sits at
             // baseCommit (that's the tip we cloned and committed on top of) --
             // that's the expected fast-forward pre-push state, not a conflict.
             // Any OTHER non-null value means something else moved the branch
             // since we cloned (a human push, a race), which is a real conflict.
             if (remote && remote !== workspace.baseCommit)
-                throw new Error("vcs_head_ref_conflict");
+                throw this.remote.conflictError();
             try {
-                await this.gitFor(workspace, ["push", "origin", `${commitSha}:refs/heads/${workspace.headRef}`], {
-                    authToken: token,
-                });
+                await this.gitFor(workspace, [...this.remote.gitConfig, "push", "origin", `${commitSha}:refs/heads/${workspace.headRef}`], auth);
             }
             catch (error) {
-                if ((await this.remoteHead(workspace, token)) === commitSha)
+                const after = await this.remoteHead(workspace, auth);
+                if (after === commitSha)
                     return;
+                // The branch moved between the check above and the push (to something
+                // other than where we started or where we were going): report it as the
+                // remote's conflict rather than the push's own (non-fast-forward)
+                // failure. A remote still at baseCommit (a continuation) or still absent
+                // means the push itself failed -- auth, a protected branch, a network
+                // error, a rejecting hook -- so that error is the one to surface.
+                if (after !== null && after !== workspace.baseCommit && after !== commitSha) {
+                    throw this.remote.conflictError();
+                }
                 throw error;
             }
         });
     }
-    async remoteHead(workspace, token) {
-        const result = await this.gitFor(workspace, ["ls-remote", "--heads", "origin", `refs/heads/${workspace.headRef}`], {
-            authToken: token,
-        });
+    async remoteHead(workspace, auth) {
+        const result = await this.gitFor(workspace, [...this.remote.gitConfig, "ls-remote", "--heads", "origin", `refs/heads/${workspace.headRef}`], auth);
         const line = result.stdout.trim();
         if (!line)
             return null;

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

@@ -0,0 +1,67 @@
+import { type GitHubRepositoryAccess, type RepositoryFileInput } from "./github.js";
+import type { GitRemote, PublishInput, PublishResult } from "./remote.js";
+import type { ContinuationFinishedDetails, ContinuationOutcome, PreparedWorkspace } from "./types.js";
+export interface GitHubRemoteOptions {
+    github: GitHubRepositoryAccess;
+    /** Test-only transport override; production composition always uses github.com. */
+    cloneUrlForRepository?: (repository: string) => string;
+    /** Test-only delay override for assertContinuationOpen's single retry wait. */
+    sleep?: (milliseconds: number) => Promise<void>;
+}
+/** github.com through a GitHub App: installation tokens for git, draft pull requests after a push. */
+export declare class GitHubRemote implements GitRemote {
+    private readonly options;
+    readonly gitConfig: readonly string[];
+    private readonly cloneUrlForRepository;
+    private readonly sleep;
+    constructor(options: GitHubRemoteOptions);
+    normalizeRepository(repository: string): string;
+    cloneUrl(repository: string): string;
+    withAccess<T>(repository: string, fn: (token: string | undefined) => Promise<T>): Promise<T>;
+    conflictError(): Error;
+    /**
+     * A continuation never pushes to a pull request that is no longer open.
+     * Fresh runs (no `continuation`) skip this, and so does a GitHub client
+     * that exposes no `findOpenPullRequest` (optional on GitHubRepositoryAccess).
+     *
+     * GitHub's answer is trusted only when it is definite: a found open PR
+     * proceeds normally, and a confirmed "no open PR" (a successful call that
+     * returns null) refuses outright with CONTINUATION_CLOSED_ERROR. A
+     * transient failure -- network error, 5xx, timeout, rate limit, anything
+     * that makes the call itself throw rather than answer -- is retried once;
+     * if it throws again, this proceeds as if the pull request were still
+     * open and logs a warning, rather than failing the run on an unconfirmed
+     * answer (especially not here, right before the push, after all the
+     * work is already done).
+     */
+    assertContinuationOpen(input: {
+        repository: string;
+        baseRef: string;
+        headRef: string;
+        continuation?: {
+            rootRunId: string;
+        };
+    }): Promise<void>;
+    publish({ workspace: prepared, details, changedPaths }: PublishInput): Promise<PublishResult>;
+    /**
+     * 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.
+     */
+    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.
+     */
+    notifyContinuationFinished(workspace: PreparedWorkspace, outcome: ContinuationOutcome, details?: ContinuationFinishedDetails): Promise<void>;
+    readRepositoryFile(input: RepositoryFileInput): Promise<string | null>;
+}

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

@@ -0,0 +1,201 @@
+import { CONTINUATION_CLOSED_ERROR } from "../../coding/continuation-wording.js";
+import { normalizeGitHubRepository, normalizeGitRef } from "../../coding/protocol.js";
+import { logger } from "../../core/logger.js";
+import { validateChangedPath } from "./git.js";
+import { isLockfilePath, } from "./github.js";
+/** How long assertContinuationOpen waits before its single retry on a transient open-PR check failure. */
+const CONTINUATION_OPEN_RETRY_DELAY_MS = 1_000;
+/** Human-readable label for continuation status notifications -- falls back to the opaque run id alone when no agent name is known. */
+function runLabel(agentName, runId) {
+    return agentName ? `${agentName} (wardby run ${runId})` : `wardby run ${runId}`;
+}
+/** github.com through a GitHub App: installation tokens for git, draft pull requests after a push. */
+export class GitHubRemote {
+    options;
+    gitConfig = [];
+    cloneUrlForRepository;
+    sleep;
+    constructor(options) {
+        this.options = options;
+        this.cloneUrlForRepository =
+            options.cloneUrlForRepository ?? ((repository) => `https://github.com/${repository}.git`);
+        this.sleep =
+            options.sleep ?? ((milliseconds) => new Promise((resolvePromise) => setTimeout(resolvePromise, milliseconds)));
+    }
+    normalizeRepository(repository) {
+        return normalizeGitHubRepository(repository);
+    }
+    cloneUrl(repository) {
+        const cloneUrl = this.cloneUrlForRepository(repository);
+        if (!this.options.cloneUrlForRepository && cloneUrl !== `https://github.com/${repository}.git`) {
+            throw new Error("vcs_remote_invalid");
+        }
+        return cloneUrl;
+    }
+    withAccess(repository, fn) {
+        return this.options.github.withRepositoryToken(repository, fn);
+    }
+    conflictError() {
+        return new Error("vcs_head_ref_conflict");
+    }
+    /**
+     * A continuation never pushes to a pull request that is no longer open.
+     * Fresh runs (no `continuation`) skip this, and so does a GitHub client
+     * that exposes no `findOpenPullRequest` (optional on GitHubRepositoryAccess).
+     *
+     * GitHub's answer is trusted only when it is definite: a found open PR
+     * proceeds normally, and a confirmed "no open PR" (a successful call that
+     * returns null) refuses outright with CONTINUATION_CLOSED_ERROR. A
+     * transient failure -- network error, 5xx, timeout, rate limit, anything
+     * that makes the call itself throw rather than answer -- is retried once;
+     * if it throws again, this proceeds as if the pull request were still
+     * open and logs a warning, rather than failing the run on an unconfirmed
+     * answer (especially not here, right before the push, after all the
+     * work is already done).
+     */
+    async assertContinuationOpen(input) {
+        if (!input.continuation || !this.options.github.findOpenPullRequest)
+            return;
+        const request = {
+            runId: input.continuation.rootRunId,
+            repository: input.repository,
+            baseRef: input.baseRef,
+            headRef: input.headRef,
+        };
+        let open;
+        try {
+            open = await this.options.github.findOpenPullRequest(request);
+        }
+        catch {
+            await this.sleep(CONTINUATION_OPEN_RETRY_DELAY_MS);
+            try {
+                open = await this.options.github.findOpenPullRequest(request);
+            }
+            catch (error) {
+                logger.warn({ err: error, runId: request.runId, repository: request.repository }, "continuation open-PR check failed twice in a row; proceeding as if the pull request is still open");
+                return;
+            }
+        }
+        if (!open)
+            throw new Error(CONTINUATION_CLOSED_ERROR);
+    }
+    async publish({ workspace: prepared, details, changedPaths }) {
+        // Revision-in-place: identify the PR by the run that originally opened
+        // it (createOrFindDraftPullRequest's marker-based lookup keys on that
+        // run's id), not this run's own -- this finds the existing open PR and
+        // returns it rather than creating a new one, since headRef/baseRef
+        // already match it exactly. No other change needed here: pushing a new
+        // commit onto that branch already updates the PR natively -- which is
+        // also why a PR a person has since marked ready for review is accepted
+        // (acceptReadyForReview) rather than failing an already-pushed run.
+        const pullRequest = await this.options.github.createOrFindDraftPullRequest({
+            runId: prepared.continuation?.rootRunId ?? prepared.runId,
+            ...(prepared.continuation ? { acceptReadyForReview: true } : {}),
+            repository: prepared.repository,
+            baseRef: prepared.baseRef,
+            headRef: prepared.headRef,
+            summary: details?.summary,
+            tests: details?.tests,
+            tag: details?.tag,
+            packages: details?.packages,
+            packageRefusals: details?.packageRefusals,
+            changedLockfiles: changedPaths.filter(isLockfilePath),
+            ...(details?.issue ? { issue: details.issue } : {}),
+            ...(details?.related ? { related: details.related } : {}),
+        });
+        return { kind: "pull_request", number: pullRequest.number, url: pullRequest.url };
+    }
+    /**
+     * 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.
+     */
+    async notifyContinuationStarted(workspace, details) {
+        if (!workspace.continuation)
+            return;
+        try {
+            const identity = {
+                runId: workspace.runId,
+                rootRunId: workspace.continuation.rootRunId,
+                repository: workspace.repository,
+                baseRef: workspace.baseRef,
+                headRef: workspace.headRef,
+            };
+            await Promise.allSettled([
+                this.options.github.upsertContinuationStatusComment({
+                    ...identity,
+                    body: `🔄 ${runLabel(details?.agentName, workspace.runId)} is working on this PR...`,
+                }),
+                this.options.github.createContinuationCheckRun({
+                    repository: workspace.repository,
+                    headSha: workspace.baseCommit,
+                    runId: workspace.runId,
+                }),
+            ]);
+        }
+        catch {
+            // Best-effort observability only -- must never affect the real run.
+        }
+    }
+    /**
+     * 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.
+     */
+    async notifyContinuationFinished(workspace, outcome, details) {
+        if (!workspace.continuation)
+            return;
+        try {
+            const identity = {
+                runId: workspace.runId,
+                rootRunId: workspace.continuation.rootRunId,
+                repository: workspace.repository,
+                baseRef: workspace.baseRef,
+                headRef: workspace.headRef,
+            };
+            const label = runLabel(details?.agentName, workspace.runId);
+            const summarySuffix = details?.summary ? `\n\n${details.summary}` : "";
+            const budgetSuffix = details?.budgetSentence ? ` ${details.budgetSentence}` : "";
+            const body = outcome === "succeeded"
+                ? `✅ ${label} finished.${summarySuffix}`
+                : outcome === "budget_exhausted"
+                    ? `❌ ${label} ran out of budget.${budgetSuffix}${summarySuffix}`
+                    : details?.serviceSentence
+                        ? `❌ ${label} could not start: ${details.serviceSentence}${summarySuffix}`
+                        : details?.providerSentence
+                            ? `❌ ${label} could not run: ${details.providerSentence}${summarySuffix}`
+                            : details?.protectedPathSentence
+                                ? `❌ ${label} could not open its changes: ${details.protectedPathSentence}${summarySuffix}`
+                                : `❌ ${label} failed.${summarySuffix}`;
+            await Promise.allSettled([
+                this.options.github.updateContinuationStatusComment({ ...identity, body }),
+                this.options.github.completeContinuationCheckRun({
+                    repository: workspace.repository,
+                    headSha: workspace.baseCommit,
+                    runId: workspace.runId,
+                    outcome: outcome === "succeeded" ? "succeeded" : "failed",
+                }),
+            ]);
+        }
+        catch {
+            // Best-effort observability only -- must never affect the real run.
+        }
+    }
+    async readRepositoryFile(input) {
+        const github = this.options.github;
+        if (!github.readFileAtRef)
+            throw new Error("vcs_read_file_unsupported");
+        return github.readFileAtRef({
+            repository: normalizeGitHubRepository(input.repository),
+            ref: normalizeGitRef(input.ref),
+            path: validateChangedPath(input.path),
+            maxBytes: input.maxBytes,
+        });
+    }
+}