@wardby/cli 0.2.1 → 0.4.0

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

@@ -0,0 +1,59 @@
+/** Agent ids are cuids; anything else could break out of the HTML comment. */
+export const SAFE_AGENT_MARKER = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+const SAFE_SHA = /^[0-9a-f]{40}$/;
+const MARKER_PREFIX = "<!-- wardby:review:";
+function assertMarker(agentMarker) {
+    if (!SAFE_AGENT_MARKER.test(agentMarker))
+        throw new Error("review_marker_invalid");
+}
+export function reviewMarker(agentMarker, headSha) {
+    assertMarker(agentMarker);
+    if (!SAFE_SHA.test(headSha))
+        throw new Error("review_marker_invalid");
+    return `${MARKER_PREFIX}${agentMarker} sha=${headSha} -->`;
+}
+export function hasReviewMarker(body, agentMarker) {
+    assertMarker(agentMarker);
+    return body.includes(`${MARKER_PREFIX}${agentMarker} sha=`);
+}
+export function parseReviewMarker(body, agentMarker) {
+    assertMarker(agentMarker);
+    const match = new RegExp(`${MARKER_PREFIX}${agentMarker} sha=([0-9a-f]{40}) -->`).exec(body);
+    return match ? match[1] : null;
+}
+export function verdictConclusion(verdict) {
+    if (verdict === "APPROVE")
+        return "success";
+    if (verdict === "CHANGES_REQUESTED")
+        return "failure";
+    return "neutral";
+}
+const BADGES = {
+    APPROVE: "✅ **Approved**",
+    CHANGES_REQUESTED: "❌ **Changes requested**",
+    COMMENT: "💬 **Comments**",
+};
+const FINDING_PREFIX = "<!-- wardby:finding:";
+/** Tags an inline comment with the agent that wrote it, so only that agent resolves its thread. */
+export function findingMarker(agentMarker) {
+    assertMarker(agentMarker);
+    return `${FINDING_PREFIX}${agentMarker} -->`;
+}
+export function hasFindingMarker(body, agentMarker) {
+    return body.includes(findingMarker(agentMarker));
+}
+export function renderInlineComment(comment, agentMarker) {
+    return `**[${comment.severity}]** ${comment.body}\n\n${findingMarker(agentMarker)}`;
+}
+export function renderSummaryComment(input) {
+    const sections = [
+        reviewMarker(input.agentMarker, input.headSha),
+        `${BADGES[input.verdict]} — reviewed \`${input.headSha.slice(0, 7)}\``,
+        input.summary,
+        input.body,
+    ];
+    if (input.outside.length > 0) {
+        sections.push(["## Outside the diff", ...input.outside.map((c) => `- **[${c.severity}] ${c.path}:${c.line}** ${c.body}`)].join("\n"));
+    }
+    return sections.join("\n\n");
+}

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

@@ -0,0 +1,309 @@
+/**
+ * Host-neutral code-review surface for native agents. GitHub is the first
+ * implementation (./github.ts); 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 declare const REVIEW_HOST_PROVIDERS: readonly ReviewHostProvider[];
+export type ReviewVerdict = "APPROVE" | "CHANGES_REQUESTED" | "COMMENT";
+export type CheckConclusion = "success" | "failure" | "neutral";
+export type CommentSide = "LEFT" | "RIGHT";
+export interface PullRequestFileView {
+    filename: string;
+    status: string;
+    additions: number;
+    deletions: number;
+    previousFilename?: string;
+    patch: string;
+    patchTruncated: boolean;
+}
+/** One of this agent's own review threads that is still unresolved. */
+export interface ReviewThreadView {
+    /** Opaque host id; pass it back in PublishReviewInput.resolveThreadIds. */
+    id: string;
+    path: string;
+    /** The line in the current head, or null when the thread is outdated (its line no longer exists). */
+    line: number | null;
+    outdated: boolean;
+    /** The finding as posted, without its marker, capped at 1,000 characters. */
+    body: string;
+}
+export interface PullRequestView {
+    number: number;
+    title: string;
+    body: string;
+    author: string | null;
+    state: string;
+    merged: boolean;
+    draft: boolean;
+    baseRef: string;
+    headRef: string;
+    headSha: string;
+    isFork: boolean;
+    htmlUrl: string;
+    /** Head sha recorded in this agent's summary comment, if it reviewed before. */
+    lastReviewedSha: string | null;
+    /** Set when `files` is the compare of `comparedFrom...headSha` rather than the whole PR. */
+    comparedFrom: string | null;
+    /**
+     * The base branch was merged into the PR since `comparedFrom`: `files` is
+     * then the PR's own diff (against its base), limited to files that changed
+     * since `comparedFrom`, so base-branch changes are left out.
+     */
+    baseMergedSince: boolean;
+    files: PullRequestFileView[];
+    /** This agent's own unresolved review threads on the PR (the first 100 threads are searched). */
+    openThreads: ReviewThreadView[];
+}
+export interface PullRequestHead {
+    headSha: string;
+    isFork: boolean;
+    state: string;
+}
+export type FileReadResult = {
+    kind: "file";
+    path: string;
+    ref: string;
+    totalLines: number;
+    startLine: number;
+    endLine: number;
+    truncated: boolean;
+    /** The window with `N: ` line-number prefixes: the display form shown to agents. */
+    content: string;
+    /** The same window without line-number prefixes, lines joined by "\n": for machine parsing. */
+    text: string;
+} | {
+    kind: "directory";
+    path: string;
+    entries: string[];
+} | {
+    kind: "not_found";
+    path: string;
+};
+export interface FileListView {
+    ref: string;
+    count: number;
+    truncated: boolean;
+    /** Display strings (path plus size) shown to agents. */
+    files: string[];
+    /** Bare repository paths, same order and length as `files`. */
+    paths: string[];
+}
+export interface InlineComment {
+    path: string;
+    line: number;
+    side: CommentSide;
+    severity: string;
+    body: string;
+}
+export interface PublishReviewInput {
+    prNumber: number;
+    headSha: string;
+    verdict: ReviewVerdict;
+    summary: string;
+    body: string;
+    comments: InlineComment[];
+    /** Identifies this agent's summary comment; the agent id. */
+    agentMarker: string;
+    /**
+     * Names a completed check to create when no checkId is supplied (a run not
+     * started by a host event). With neither, no check is created.
+     */
+    checkName?: string;
+    /** The run's own in-progress check, when the control plane started one. */
+    checkId?: string;
+    /**
+     * Threads to resolve because this head fixes them. Only this agent's own
+     * unresolved threads on this PR are resolved; any other id is skipped.
+     */
+    resolveThreadIds?: string[];
+}
+export type PublishReviewResult = {
+    published: true;
+    reviewUrl: string | null;
+    summaryCommentUrl: string;
+    /** Null when no check was completed or created (neither checkId nor checkName). */
+    checkId: string | null;
+    /** The verdict's check mapping — informational when checkId is null. */
+    checkConclusion: CheckConclusion;
+    inlineCount: number;
+    outsideDiffCount: number;
+    resolvedThreadIds: string[];
+    /** Requested ids that were not resolved: not this agent's open thread on this PR, or the host refused. */
+    skippedThreadIds: string[];
+} | {
+    published: false;
+    reason: "stale_head";
+    currentHeadSha: string;
+};
+export interface CommentInput {
+    number: number;
+    body: string;
+    replyToReviewCommentId?: string;
+}
+/** A comment the App wrote, to edit later: a conversation comment or a reply in a review thread. */
+export interface EditCommentInput {
+    kind: "conversation" | "inline";
+    id: string;
+    body: string;
+}
+export interface CommentRef {
+    /**
+     * "conversation" = a top-level comment on an issue/PR conversation; "inline" = a comment on a diff line (review
+     * thread); "subject" = the issue or PR itself (its title/description), with `id` its number.
+     */
+    kind: "conversation" | "inline" | "subject";
+    id: string;
+}
+export interface StartCheckInput {
+    headSha: string;
+    name: string;
+}
+export interface CompleteCheckInput {
+    checkId: string;
+    conclusion: CheckConclusion;
+    title: string;
+    summary: string;
+    text?: string;
+    detailsUrl?: string;
+}
+/**
+ * A user's effective permission on one repository, host-neutral and ranked
+ * none < read < triage < write < maintain < admin. GitHub maps its
+ * collaborator permission onto these directly; GitLab would map reporter ->
+ * read, developer -> write, maintainer -> maintain, owner -> admin.
+ */
+export type HostPermission = "none" | "read" | "triage" | "write" | "maintain" | "admin";
+export declare const HOST_PERMISSION_RANK: Readonly<Record<HostPermission, number>>;
+/** A host user, by its immutable numeric id (as text) and its current login. */
+export interface HostUser {
+    id: string;
+    login: string;
+}
+export interface CodeReviewHost {
+    readonly provider: ReviewHostProvider;
+    /**
+     * The user's effective permission on `repository`, asked with the App's own
+     * installation credential (never a user token). Answers only for the user
+     * with this id: a login that now names someone else is re-resolved by id,
+     * and `login` in the result is the user's current login.
+     */
+    repositoryPermission(repository: string, user: HostUser): Promise<{
+        level: HostPermission;
+        login: string;
+    }>;
+    readPullRequest(repository: string, prNumber: number, opts: {
+        sinceSha?: string;
+        maxPatchChars: number;
+        agentMarker: string;
+    }): Promise<PullRequestView>;
+    pullRequestHead(repository: string, prNumber: number): Promise<PullRequestHead>;
+    readFile(repository: string, path: string, ref: string | undefined, window: {
+        startLine: number;
+        maxLines: number;
+    }): Promise<FileReadResult>;
+    listFiles(repository: string, ref: string | undefined, pathPrefix?: string): Promise<FileListView>;
+    publishReview(repository: string, input: PublishReviewInput): Promise<PublishReviewResult>;
+    /** `id` identifies the new comment for editComment; a reply is an "inline" comment, anything else "conversation". */
+    comment(repository: string, input: CommentInput): Promise<{
+        url: string;
+        id: string;
+    }>;
+    /** Replaces the body of a comment the App wrote. */
+    editComment(repository: string, input: EditCommentInput): Promise<void>;
+    /** Marks a comment as picked up (GitHub: a 👀 reaction); a host without reactions may do nothing. */
+    acknowledge(repository: string, target: CommentRef): Promise<void>;
+    startCheck(repository: string, input: StartCheckInput): Promise<{
+        checkId: string;
+    }>;
+    completeCheck(repository: string, input: CompleteCheckInput): Promise<void>;
+}
+export type ReviewHostErrorCode = "host_not_installed" | "host_permission_missing" | "host_api_error" | "host_invalid_response";
+export declare class ReviewHostError extends Error {
+    readonly code: ReviewHostErrorCode;
+    constructor(code: ReviewHostErrorCode, message?: string);
+}
+export type ReviewHostRegistry = Partial<Record<ReviewHostProvider, CodeReviewHost>>;
+/**
+ * A host's user-authorization (OAuth web) flow, used only to learn who a
+ * wardby principal is on the host. Implementations never store or return the
+ * user token: `complete` reads the user and revokes the token at once.
+ */
+export interface HostUserAuthorizer {
+    readonly provider: ReviewHostProvider;
+    authorizeUrl(input: {
+        state: string;
+        codeChallenge: string;
+        redirectUri: string;
+    }): string;
+    complete(input: {
+        code: string;
+        codeVerifier: string;
+        redirectUri: string;
+    }): Promise<{
+        hostUserId: string;
+        login: string;
+    }>;
+}
+export type HostUserAuthorizerRegistry = Partial<Record<ReviewHostProvider, HostUserAuthorizer>>;
+/**
+ * Host-neutral shape a webhook adapter (github-events.ts) normalises its
+ * provider payload into, for src/core/host-events.ts to route.
+ */
+export type HostEvent = {
+    kind: "push";
+    provider: ReviewHostProvider;
+    repository: string;
+    /** The branch pushed (without refs/heads/), always the repository's default branch. */
+    branch: string;
+    before: string;
+    after: string;
+    /** Union of added/modified/removed paths over the payload's commits, deduplicated, at most 1000. */
+    changedPaths: string[];
+    /** False when GitHub truncated the commit list (> 20 commits) or paths were capped: treat every concept as in scope. */
+    changedPathsComplete: boolean;
+} | {
+    kind: "pr_updated";
+    provider: ReviewHostProvider;
+    repository: string;
+    prNumber: number;
+    headSha: string;
+    isFork: boolean;
+} | {
+    /** The PR was merged or closed; only drives bookkeeping on issue/PR pairs wardby recorded. */
+    kind: "pr_closed";
+    provider: ReviewHostProvider;
+    repository: string;
+    prNumber: number;
+    merged: boolean;
+} | {
+    kind: "check_rerun";
+    provider: ReviewHostProvider;
+    repository: string;
+    prNumber: number;
+    headSha: string;
+    checkName: string;
+} | {
+    kind: "mention";
+    provider: ReviewHostProvider;
+    repository: string;
+    number: number;
+    isPullRequest: boolean;
+    comment: CommentRef;
+    /** Set when the mention is inside an inline review thread. */
+    replyToReviewCommentId?: string;
+    /** The comment text; for a "subject" mention, the issue/PR description. */
+    body: string;
+    author: string;
+    /** The author's immutable numeric host user id, as text; their permission is checked by it. */
+    authorId: string;
+    /** The issue or PR the mention is on, when the payload carries it. */
+    subject?: {
+        title: string;
+        body: string;
+    };
+    /** The run that opened this PR, when its description carries a valid run marker. */
+    priorRunId?: string;
+};

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

@@ -0,0 +1,24 @@
+/**
+ * Host-neutral code-review surface for native agents. GitHub is the first
+ * implementation (./github.ts); 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 HOST_PERMISSION_RANK = {
+    none: 0,
+    read: 1,
+    triage: 2,
+    write: 3,
+    maintain: 4,
+    admin: 5,
+};
+export class ReviewHostError extends Error {
+    code;
+    constructor(code, message = code) {
+        super(message);
+        this.code = code;
+        this.name = "ReviewHostError";
+    }
+}

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

@@ -1,5 +1,5 @@
-import { type GitHubRepositoryAccess } from "./github.js";
-import type { FinalizeChangesDetails, FinalizeChangesResult, PreparedWorkspace, VcsPrepareInput, VcsProvider } from "./types.js";
+import { type GitHubRepositoryAccess, type RepositoryFileInput } from "./github.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;
 export interface GitCommandOptions {
@@ -43,6 +43,18 @@ export interface GitVcsProviderOptions {
     /** 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
+ * baseline's exception (.wardby/services.yaml, which a builder may propose; it
+ * takes effect only after merge, docs/coding-services.md) is never protected;
+ * anything else under the baseline (.wardby/**) always is, whatever the agent's
+ * exceptions say; any other path is protected when it matches one of the
+ * agent's `patterns` and is not one of its exceptions (entries with a leading
+ * "!", each a literal path, so order does not matter). The baseline is applied
+ * here, at enforcement, rather than stored, so every existing agent and
+ * in-flight run gets it.
+ */
+export declare function protectedPathMatcher(patterns: readonly string[]): (path: string) => boolean;
 export declare class GitVcsProvider implements VcsProvider {
     private readonly options;
     private readonly rootDir;
@@ -74,10 +86,8 @@ export declare class GitVcsProvider implements VcsProvider {
      * github.ts). Safe to call more than once for the same run. Same
      * never-throw contract as notifyContinuationStarted.
      */
-    notifyContinuationFinished(workspace: PreparedWorkspace, outcome: "succeeded" | "failed", details?: {
-        summary?: string;
-        agentName?: string;
-    }): Promise<void>;
+    notifyContinuationFinished(workspace: PreparedWorkspace, outcome: ContinuationOutcome, details?: ContinuationFinishedDetails): Promise<void>;
+    readRepositoryFile(input: RepositoryFileInput): Promise<string | null>;
     private validateInput;
     private expectedPaths;
     private validatePrepared;

package/dist/providers/vcs/git.js

@@ -2,7 +2,10 @@ import { spawn } from "node:child_process";
 import { lstat, mkdir, opendir, readFile, readlink, realpath, rm } from "node:fs/promises";
 import { isAbsolute, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { gitExcludePathspecs, normalizeCollectExclusions } from "../../coding/collect-exclude.js";
+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 { isSafeGitHubInstallationToken } from "./github.js";
 export const DEFAULT_MAX_CHANGED_FILES = 1_000;
@@ -139,39 +142,40 @@ export class NodeGitCommandRunner {
         });
     }
 }
+/** Validates one protectedPaths entry; a leading "!" makes it an exception (see protectedPathMatcher). */
 function validateProtectedPath(value) {
     const path = value.trim();
-    if (!path ||
-        Buffer.byteLength(path, "utf8") > 512 ||
-        path.startsWith("/") ||
-        path.startsWith("./") ||
-        path.includes("\\") ||
-        path.split("/").some((part) => !part || part === "." || part === "..")) {
+    if (Buffer.byteLength(path, "utf8") > 512 || !isWellFormedProtectedPath(path)) {
         throw new Error("vcs_protected_path_invalid");
     }
     return path;
 }
-function globRegex(pattern) {
-    let source = "^";
-    for (let index = 0; index < pattern.length; index += 1) {
-        const character = pattern[index];
-        if (character === "*") {
-            if (pattern[index + 1] === "*") {
-                source += ".*";
-                index += 1;
-            }
-            else {
-                source += "[^/]*";
-            }
-        }
-        else if (character === "?") {
-            source += "[^/]";
-        }
-        else {
-            source += character.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
-        }
-    }
-    return new RegExp(`${source}$`);
+/** The fixed baseline, split once: its literal exceptions and its protected globs. */
+const WARDBY_UNPROTECTED = new Set(WARDBY_PROTECTED_PATHS.filter(isProtectedPathException).map(protectedPathBody));
+const WARDBY_PROTECTED = WARDBY_PROTECTED_PATHS.filter((pattern) => !isProtectedPathException(pattern)).map((pattern) => globRegex(pattern));
+/**
+ * Whether a changed path is protected, in this order: the WARDBY_PROTECTED_PATHS
+ * baseline's exception (.wardby/services.yaml, which a builder may propose; it
+ * takes effect only after merge, docs/coding-services.md) is never protected;
+ * anything else under the baseline (.wardby/**) always is, whatever the agent's
+ * exceptions say; any other path is protected when it matches one of the
+ * agent's `patterns` and is not one of its exceptions (entries with a leading
+ * "!", each a literal path, so order does not matter). The baseline is applied
+ * here, at enforcement, rather than stored, so every existing agent and
+ * in-flight run gets it.
+ */
+export function protectedPathMatcher(patterns) {
+    const exceptions = new Set(patterns.filter(isProtectedPathException).map(protectedPathBody));
+    const protectedPatterns = patterns
+        .filter((pattern) => !isProtectedPathException(pattern))
+        .map((pattern) => globRegex(pattern));
+    return (path) => {
+        if (WARDBY_UNPROTECTED.has(path))
+            return false;
+        if (WARDBY_PROTECTED.some((matcher) => matcher.test(path)))
+            return true;
+        return protectedPatterns.some((matcher) => matcher.test(path)) && !exceptions.has(path);
+    };
 }
 function validateChangedPath(path) {
     if (!path ||
@@ -352,7 +356,15 @@ export class GitVcsProvider {
         await this.inspectWorkspace(prepared.workspacePath);
         await this.assertRemote(prepared);
         await this.assertSafeLocalConfig(prepared.gitMetadataPath);
-        await this.gitFor(prepared, ["add", "--all", "--", ":/"]);
+        // Excluded paths (src/coding/collect-exclude.ts) are never collected from the worker, so
+        // they are also neither added nor deleted here: tracked files under them stay untouched.
+        await this.gitFor(prepared, [
+            "add",
+            "--all",
+            "--",
+            ":/",
+            ...gitExcludePathspecs(normalizeCollectExclusions(prepared.collectExclude)),
+        ]);
         const changed = nullSeparated((await this.gitFor(prepared, [
             "diff",
             "--cached",
@@ -364,8 +376,7 @@ export class GitVcsProvider {
         ])).stdout);
         if (changed.length > this.maxChangedFiles)
             throw new Error("vcs_changed_file_limit");
-        const protectedMatchers = prepared.protectedPaths.map((path) => ({ path, matcher: globRegex(path) }));
-        const protectedChange = changed.find((path) => protectedMatchers.some(({ matcher }) => matcher.test(path)));
+        const protectedChange = changed.find(protectedPathMatcher(prepared.protectedPaths));
         if (protectedChange)
             throw new Error(`vcs_protected_path:${protectedChange}`);
         let diff;
@@ -412,15 +423,21 @@ export class GitVcsProvider {
         // 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.
+        // 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 } : {}),
         });
         return {
             outcome: prepared.continuation ? "pull_request_updated" : "pull_request_opened",
@@ -498,14 +515,25 @@ export class GitVcsProvider {
             };
             const label = runLabel(details?.agentName, workspace.runId);
             const summarySuffix = details?.summary ? `\n\n${details.summary}` : "";
-            const body = outcome === "succeeded" ? `✅ ${label} finished.${summarySuffix}` : `❌ ${label} failed.${summarySuffix}`;
+            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: outcome === "succeeded" ? "succeeded" : "failed",
                 }),
             ]);
         }
@@ -513,6 +541,17 @@ export class GitVcsProvider {
             // 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,
+        });
+    }
     validateInput(input) {
         if (!SAFE_RUN_ID.test(input.runId))
             throw new Error("vcs_run_id_invalid");
@@ -540,7 +579,10 @@ export class GitVcsProvider {
         const protectedPaths = [...new Set(input.protectedPaths.map(validateProtectedPath))];
         if (protectedPaths.length === 0 || protectedPaths.length > 128)
             throw new Error("vcs_protected_paths_invalid");
-        return { runId: input.runId, repository, baseRef, headRef, protectedPaths, continuation };
+        if (!protectsSomePath(protectedPaths))
+            throw new Error("vcs_protected_paths_invalid");
+        const collectExclude = [...normalizeCollectExclusions(input.collectExclude ?? []).paths];
+        return { runId: input.runId, repository, baseRef, headRef, protectedPaths, collectExclude, continuation };
     }
     expectedPaths(runId) {
         if (!SAFE_RUN_ID.test(runId))
@@ -566,6 +608,8 @@ export class GitVcsProvider {
             workspace.gitMetadataPath !== expected.gitMetadataPath ||
             workspace.protectedPaths.length !== normalized.protectedPaths.length ||
             workspace.protectedPaths.some((path, index) => path !== normalized.protectedPaths[index]) ||
+            workspace.collectExclude.length !== normalized.collectExclude.length ||
+            workspace.collectExclude.some((path, index) => path !== normalized.collectExclude[index]) ||
             workspace.continuation?.rootRunId !== normalized.continuation?.rootRunId) {
             throw new Error("vcs_workspace_handle_invalid");
         }