@deftai/directive-core 0.105.0 → 0.107.0

package/dist/intake/github-auth-modes.js

@@ -7,12 +7,18 @@ export const KNOWN_GITHUB_AUTH_MODES = new Set([
     GITHUB_AUTH_MODE_INJECTED_TOKEN,
     GITHUB_AUTH_MODE_HOST_GH,
 ]);
-export const DEFAULT_VALIDATION_REPO = "deftai/directive";
+export const PRINCIPAL_KIND_USER = "user";
 export const FAILURE_MISSING_INJECTED_TOKEN = "missing_injected_token";
 export const FAILURE_GH_AUTH = "gh_auth_failed";
 export const FAILURE_API_UNREACHABLE = "api_unreachable";
 export const FAILURE_REPO_ACCESS = "repo_access_denied";
 export const FAILURE_INVALID_MODE = "invalid_auth_mode";
+export const FAILURE_MISSING_EXPECTED_PRINCIPAL = "missing_expected_principal";
+export const FAILURE_PRINCIPAL_MISMATCH = "principal_mismatch";
+export const FAILURE_MISSING_TARGET_REPO = "missing_target_repo";
+export const FAILURE_INSTALLATION_IDENTITY_UNVERIFIABLE = "installation_identity_unverifiable";
+export const ENV_EXPECTED_GITHUB_LOGIN = "DEFT_EXPECTED_GITHUB_LOGIN";
+export const INSTALLATION_IDENTITY_ISSUE_URL = "https://github.com/deftai/directive/issues/3693";
 const INJECTED_TOKEN_ENV_VARS = ["GH_TOKEN", "GITHUB_TOKEN", "GH_ENTERPRISE_TOKEN"];
 const SANDBOX_REMEDIATION = "Remediation options for worker sandbox GitHub auth failures:\n" +
     "  - Run the GitHub step with full-access execution\n" +
@@ -22,6 +28,15 @@ const REPO_ACCESS_REMEDIATION = "Remediation options for repo-access failures:\n
     "  - Confirm the worker credential can read the target repository\n" +
     "  - Run the GitHub step with full-access execution if host gh has access\n" +
     "  - Use injected-token handoff scoped to the required repository";
+const PRINCIPAL_REMEDIATION = "Remediation for GitHub worker-principal failures:\n" +
+    "  - User-bearing credential: pass expectedPrincipal.login or set DEFT_EXPECTED_GITHUB_LOGIN\n" +
+    "  - Do not treat a /user 403 on an installation token as API unreachability\n" +
+    "  - GitHub App installation identity cannot be verified from the token; see #3693";
+const INSTALLATION_IDENTITY_REMEDIATION = "A GitHub App installation token cannot prove which App it belongs to.\n" +
+    `Tracked in ${INSTALLATION_IDENTITY_ISSUE_URL}. Do not treat a /user 403 as API unreachability.`;
+const TARGET_REPO_REMEDIATION = "Remediation for missing target repository:\n" +
+    "  - Pass repo as owner/repo, or set GH_REPO / GITHUB_REPOSITORY, or run inside a git checkout with origin\n" +
+    "  - Do not fall back to a hard-coded public default";
 export function findInjectedToken(environ) {
     for (const name of INJECTED_TOKEN_ENV_VARS) {
         const value = environ[name]?.trim() ?? "";
@@ -63,6 +78,113 @@ function defaultRunGh(args, environ) {
         return { args: [binary, ...args], returncode: 1, stdout: "", stderr: message };
     }
 }
+export function defaultReadGitOriginUrl(cwd) {
+    try {
+        const result = spawnSync("git", ["remote", "get-url", "origin"], {
+            cwd,
+            encoding: "utf8",
+            timeout: 10_000,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        if ((result.status ?? 1) !== 0) {
+            return null;
+        }
+        const url = (typeof result.stdout === "string" ? result.stdout : "").trim();
+        return url.length > 0 ? url : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function parseOwnerRepoSlug(input) {
+    const raw = input.trim();
+    if (raw.length === 0) {
+        return null;
+    }
+    const direct = raw.match(/^([A-Za-z0-9._-]+)\/([A-Za-z0-9._-]+)$/);
+    if (direct) {
+        return `${direct[1]}/${direct[2]}`;
+    }
+    const stripped = raw.replace(/\.git$/i, "");
+    // SCP form including GitHub Enterprise: git@host:owner/repo
+    if (!stripped.includes("://")) {
+        const scp = stripped.match(/:([A-Za-z0-9._-]+)\/([A-Za-z0-9._-]+)$/);
+        if (scp) {
+            return `${scp[1]}/${scp[2]}`;
+        }
+    }
+    const fromUrl = stripped.match(/[:/]([A-Za-z0-9._-]+)\/([A-Za-z0-9._-]+)$/);
+    if (fromUrl) {
+        return `${fromUrl[1]}/${fromUrl[2]}`;
+    }
+    return null;
+}
+export function deriveValidationRepo(options) {
+    if (options.repo !== undefined && options.repo !== null) {
+        const parsed = parseOwnerRepoSlug(options.repo);
+        if (parsed === null) {
+            return {
+                ok: false,
+                detail: `invalid repository slug: ${JSON.stringify(options.repo)} (expected owner/repo)`,
+            };
+        }
+        return { ok: true, repo: parsed };
+    }
+    const env = options.environ ?? {};
+    const fromEnv = (env.GH_REPO ?? env.GITHUB_REPOSITORY ?? "").trim();
+    if (fromEnv.length > 0) {
+        const parsed = parseOwnerRepoSlug(fromEnv);
+        if (parsed === null) {
+            return {
+                ok: false,
+                detail: `invalid repository slug from GH_REPO/GITHUB_REPOSITORY: ${JSON.stringify(fromEnv)}`,
+            };
+        }
+        return { ok: true, repo: parsed };
+    }
+    const remote = options.gitRemoteUrl !== undefined && options.gitRemoteUrl !== null
+        ? options.gitRemoteUrl
+        : (options.readGitRemote ?? defaultReadGitOriginUrl)(options.cwd);
+    if (typeof remote === "string" && remote.trim().length > 0) {
+        const parsed = parseOwnerRepoSlug(remote);
+        if (parsed === null) {
+            return {
+                ok: false,
+                detail: `invalid git origin URL for repository derivation: ${JSON.stringify(remote.trim())}`,
+            };
+        }
+        return { ok: true, repo: parsed };
+    }
+    return {
+        ok: false,
+        detail: "cannot derive target repository; pass repo as owner/repo, set GH_REPO or GITHUB_REPOSITORY, or run inside a git checkout with origin",
+    };
+}
+export function resolveExpectedGithubWorkerPrincipal(environ, explicit) {
+    if (explicit === null) {
+        return null;
+    }
+    if (explicit !== undefined) {
+        return normalizeExpectedPrincipal(explicit);
+    }
+    const login = environ[ENV_EXPECTED_GITHUB_LOGIN]?.trim() ?? "";
+    if (login.length > 0) {
+        return { kind: PRINCIPAL_KIND_USER, login };
+    }
+    return null;
+}
+function normalizeExpectedPrincipal(principal) {
+    if (principal.kind !== PRINCIPAL_KIND_USER) {
+        return {
+            error: `unknown expected principal kind ${pyRepr(principal.kind)}`,
+        };
+    }
+    const login = principal.login.trim();
+    if (login.length === 0) {
+        return { error: "user principal requires a non-empty login" };
+    }
+    return { kind: PRINCIPAL_KIND_USER, login };
+}
 function splitRepo(repo) {
     const idx = repo.indexOf("/");
     if (idx <= 0 || idx >= repo.length - 1) {
@@ -76,13 +198,30 @@ function sandboxRemediation(runtimeMode, failureKind) {
     }
     if (failureKind === FAILURE_GH_AUTH ||
         failureKind === FAILURE_API_UNREACHABLE ||
-        failureKind === FAILURE_REPO_ACCESS) {
+        failureKind === FAILURE_REPO_ACCESS ||
+        failureKind === FAILURE_MISSING_EXPECTED_PRINCIPAL ||
+        failureKind === FAILURE_PRINCIPAL_MISMATCH ||
+        failureKind === FAILURE_MISSING_TARGET_REPO ||
+        failureKind === FAILURE_INSTALLATION_IDENTITY_UNVERIFIABLE) {
         return SANDBOX_REMEDIATION;
     }
     return null;
 }
-function repoAccessRemediation(failureKind) {
-    return failureKind === FAILURE_REPO_ACCESS ? REPO_ACCESS_REMEDIATION : null;
+function extraRemediation(failureKind) {
+    if (failureKind === FAILURE_REPO_ACCESS) {
+        return REPO_ACCESS_REMEDIATION;
+    }
+    if (failureKind === FAILURE_INSTALLATION_IDENTITY_UNVERIFIABLE) {
+        return INSTALLATION_IDENTITY_REMEDIATION;
+    }
+    if (failureKind === FAILURE_MISSING_EXPECTED_PRINCIPAL ||
+        failureKind === FAILURE_PRINCIPAL_MISMATCH) {
+        return PRINCIPAL_REMEDIATION;
+    }
+    if (failureKind === FAILURE_MISSING_TARGET_REPO) {
+        return TARGET_REPO_REMEDIATION;
+    }
+    return null;
 }
 function mergeRemediation(runtimeMode, failureKind) {
     const parts = [];
@@ -90,9 +229,9 @@ function mergeRemediation(runtimeMode, failureKind) {
     if (sandbox !== null) {
         parts.push(sandbox);
     }
-    const repo = repoAccessRemediation(failureKind);
-    if (repo !== null && !parts.includes(repo)) {
-        parts.push(repo);
+    const extra = extraRemediation(failureKind);
+    if (extra !== null && !parts.includes(extra)) {
+        parts.push(extra);
     }
     return parts.length > 0 ? parts.join("\n\n") : null;
 }
@@ -118,147 +257,193 @@ function parseLogin(stdout) {
     }
     return null;
 }
-export function validateInjectedTokenMode(environ, options = {}) {
-    const runner = options.runGh ?? defaultRunGh;
-    const repo = options.repo ?? DEFAULT_VALIDATION_REPO;
-    const runtimeMode = options.runtimeMode ?? null;
-    const token = findInjectedToken(environ);
-    if (token === null) {
-        return {
-            ok: false,
-            githubAuthMode: GITHUB_AUTH_MODE_INJECTED_TOKEN,
-            runtimeMode,
-            failureKind: FAILURE_MISSING_INJECTED_TOKEN,
-            detail: "injected-token mode requires GH_TOKEN, GITHUB_TOKEN, or GH_ENTERPRISE_TOKEN; host gh credential store is not used",
-            remediation: null,
-            login: null,
-        };
+function combinedGhText(proc) {
+    return `${proc.stdout}\n${proc.stderr}`;
+}
+export function isInstallationUserEndpointInapplicable(proc) {
+    const blob = combinedGhText(proc).toLowerCase();
+    return (blob.includes("resource not accessible by integration") ||
+        blob.includes("not accessible by integration"));
+}
+function clipFailureText(text, max = 240) {
+    const compact = text.replace(/\s+/g, " ").trim();
+    if (compact.length === 0) {
+        return "";
     }
-    const authStatus = runner(["auth", "status"], environ);
-    if (authStatus.returncode !== 0) {
-        return {
-            ok: false,
-            githubAuthMode: GITHUB_AUTH_MODE_INJECTED_TOKEN,
-            runtimeMode,
-            failureKind: FAILURE_GH_AUTH,
-            detail: "injected token present but gh auth status failed in worker",
-            remediation: mergeRemediation(runtimeMode, FAILURE_GH_AUTH),
-            login: null,
-        };
+    if (compact.length <= max) {
+        return compact;
     }
-    const userApi = runner(["api", "user", "--jq", ".login"], environ);
-    if (userApi.returncode !== 0) {
-        return {
-            ok: false,
-            githubAuthMode: GITHUB_AUTH_MODE_INJECTED_TOKEN,
-            runtimeMode,
-            failureKind: FAILURE_API_UNREACHABLE,
-            detail: "injected token present but GitHub API is unreachable",
-            remediation: mergeRemediation(runtimeMode, FAILURE_API_UNREACHABLE),
-            login: null,
-        };
+    return `${compact.slice(0, max - 3)}...`;
+}
+function parseGhApiMessage(proc) {
+    for (const chunk of [proc.stdout, proc.stderr]) {
+        const text = chunk.trim();
+        if (text.length === 0) {
+            continue;
+        }
+        try {
+            const payload = JSON.parse(text);
+            if (payload !== null && typeof payload === "object" && !Array.isArray(payload)) {
+                const message = payload.message;
+                if (typeof message === "string" && message.length > 0) {
+                    const status = payload.status;
+                    if (typeof status === "string" || typeof status === "number") {
+                        return `${message} (HTTP ${status})`;
+                    }
+                    return message;
+                }
+            }
+        }
+        catch {
+            // fall through to raw text
+        }
     }
-    const login = parseLogin(userApi.stdout);
+    return null;
+}
+function isNetworkUnreachableText(text) {
+    return /timed out|timeout|econnrefused|enotfound|eai_again|network is unreachable|could not resolve host/i.test(text);
+}
+export function formatUserApiFailureDetail(mode, proc) {
+    const parsed = parseGhApiMessage(proc);
+    const raw = clipFailureText(combinedGhText(proc));
+    const cause = parsed ?? (raw.length > 0 ? raw : `exit ${proc.returncode}`);
+    const prefix = mode === GITHUB_AUTH_MODE_INJECTED_TOKEN
+        ? "injected token present but GitHub /user failed"
+        : "gh auth status passed but GitHub /user failed";
+    if (isNetworkUnreachableText(cause) || isNetworkUnreachableText(raw)) {
+        return `${prefix}: GitHub API is unreachable (${cause})`;
+    }
+    return `${prefix}: ${cause}`;
+}
+function emptyResult(mode, runtimeMode, failureKind, detail, options = {}) {
+    const ok = options.ok ?? false;
+    return {
+        ok,
+        githubAuthMode: mode,
+        runtimeMode,
+        failureKind: ok ? null : failureKind,
+        detail,
+        remediation: ok ? null : mergeRemediation(runtimeMode, failureKind ?? ""),
+        login: options.login ?? null,
+        principal: options.principal ?? null,
+        validationRepo: options.validationRepo ?? null,
+    };
+}
+function loginsMatch(expected, observed) {
+    return expected.localeCompare(observed, undefined, { sensitivity: "accent" }) === 0;
+}
+function failClosedInstallationCredential(mode, runtimeMode, repo) {
+    return emptyResult(mode, runtimeMode, FAILURE_INSTALLATION_IDENTITY_UNVERIFIABLE, "GitHub /user is inapplicable to a GitHub App installation credential (no authenticated user). " +
+        "The API is reachable. An installation token cannot disclose which App it belongs to, " +
+        `so identity cannot be verified. Deferred to ${INSTALLATION_IDENTITY_ISSUE_URL}.`, { validationRepo: repo });
+}
+function checkTargetRepoAccess(mode, runtimeMode, runner, environ, repo, login, principal) {
     const [owner, name] = splitRepo(repo);
     const repoApi = runner(["api", `repos/${owner}/${name}`], environ);
     if (repoApi.returncode !== 0) {
-        return {
-            ok: false,
-            githubAuthMode: GITHUB_AUTH_MODE_INJECTED_TOKEN,
-            runtimeMode,
-            failureKind: FAILURE_REPO_ACCESS,
-            detail: `injected token can reach GitHub API but cannot access ${repo}`,
-            remediation: mergeRemediation(runtimeMode, FAILURE_REPO_ACCESS),
+        const detail = mode === GITHUB_AUTH_MODE_INJECTED_TOKEN
+            ? `injected token can reach GitHub API but cannot access ${repo}`
+            : `GitHub API reachable but repository access failed for ${repo}`;
+        return emptyResult(mode, runtimeMode, FAILURE_REPO_ACCESS, detail, {
             login,
-        };
+            principal,
+            validationRepo: repo,
+        });
     }
-    return {
+    const okDetail = mode === GITHUB_AUTH_MODE_INJECTED_TOKEN
+        ? "injected-token mode validated in worker environment"
+        : "host-gh mode validated in worker environment";
+    return emptyResult(mode, runtimeMode, null, okDetail, {
         ok: true,
-        githubAuthMode: GITHUB_AUTH_MODE_INJECTED_TOKEN,
-        runtimeMode,
-        failureKind: null,
-        detail: "injected-token mode validated in worker environment",
-        remediation: null,
         login,
-    };
+        principal,
+        validationRepo: repo,
+    });
 }
-export function validateHostGhMode(environ, options = {}) {
+function validateAfterAuth(mode, environ, options, runtimeMode, runner) {
+    const derived = deriveValidationRepo({
+        repo: options.repo,
+        environ,
+        gitRemoteUrl: options.gitRemoteUrl,
+        readGitRemote: options.readGitRemote,
+        cwd: options.cwd,
+    });
+    if (!derived.ok) {
+        return emptyResult(mode, runtimeMode, FAILURE_MISSING_TARGET_REPO, derived.detail);
+    }
+    const repo = derived.repo;
+    const expectedPrincipal = resolveExpectedGithubWorkerPrincipal(environ, options.expectedPrincipal);
+    if (expectedPrincipal !== null && "error" in expectedPrincipal && options.expectedPrincipal) {
+        return emptyResult(mode, runtimeMode, FAILURE_MISSING_EXPECTED_PRINCIPAL, expectedPrincipal.error, {
+            validationRepo: repo,
+        });
+    }
+    const userApi = runner(["api", "user"], environ);
+    if (userApi.returncode !== 0) {
+        if (isInstallationUserEndpointInapplicable(userApi)) {
+            return failClosedInstallationCredential(mode, runtimeMode, repo);
+        }
+        return emptyResult(mode, runtimeMode, FAILURE_API_UNREACHABLE, formatUserApiFailureDetail(mode, userApi), { validationRepo: repo });
+    }
+    const login = parseLogin(userApi.stdout);
+    if (login === null) {
+        return emptyResult(mode, runtimeMode, FAILURE_PRINCIPAL_MISMATCH, "GitHub /user succeeded but returned no login", { validationRepo: repo });
+    }
+    if (expectedPrincipal !== null && "error" in expectedPrincipal) {
+        return emptyResult(mode, runtimeMode, FAILURE_MISSING_EXPECTED_PRINCIPAL, expectedPrincipal.error, {
+            login,
+            validationRepo: repo,
+        });
+    }
+    if (expectedPrincipal !== null) {
+        if (!loginsMatch(expectedPrincipal.login, login)) {
+            return emptyResult(mode, runtimeMode, FAILURE_PRINCIPAL_MISMATCH, `identity mismatch: expected ${expectedPrincipal.login}, observed ${login}`, { login, validationRepo: repo });
+        }
+    }
+    const principal = { kind: PRINCIPAL_KIND_USER, login };
+    return checkTargetRepoAccess(mode, runtimeMode, runner, environ, repo, login, principal);
+}
+export function validateInjectedTokenMode(environ, options = {}) {
     const runner = options.runGh ?? defaultRunGh;
-    const repo = options.repo ?? DEFAULT_VALIDATION_REPO;
     const runtimeMode = options.runtimeMode ?? null;
+    const tokenPresent = findInjectedToken(environ) !== null;
+    if (!tokenPresent) {
+        return emptyResult(GITHUB_AUTH_MODE_INJECTED_TOKEN, runtimeMode, FAILURE_MISSING_INJECTED_TOKEN, "injected-token mode requires GH_TOKEN, GITHUB_TOKEN, or GH_ENTERPRISE_TOKEN; host gh credential store is not used");
+    }
     const authStatus = runner(["auth", "status"], environ);
     if (authStatus.returncode !== 0) {
-        return {
-            ok: false,
-            githubAuthMode: GITHUB_AUTH_MODE_HOST_GH,
-            runtimeMode,
-            failureKind: FAILURE_GH_AUTH,
-            detail: "gh auth status failed in worker environment",
-            remediation: mergeRemediation(runtimeMode, FAILURE_GH_AUTH),
-            login: null,
-        };
-    }
-    const userApi = runner(["api", "user", "--jq", ".login"], environ);
-    if (userApi.returncode !== 0) {
-        return {
-            ok: false,
-            githubAuthMode: GITHUB_AUTH_MODE_HOST_GH,
-            runtimeMode,
-            failureKind: FAILURE_API_UNREACHABLE,
-            detail: "gh auth status passed but GitHub API is unreachable",
-            remediation: mergeRemediation(runtimeMode, FAILURE_API_UNREACHABLE),
-            login: null,
-        };
+        return emptyResult(GITHUB_AUTH_MODE_INJECTED_TOKEN, runtimeMode, FAILURE_GH_AUTH, "injected token present but gh auth status failed in worker");
     }
-    const [owner, name] = splitRepo(repo);
-    const repoApi = runner(["api", `repos/${owner}/${name}`], environ);
-    if (repoApi.returncode !== 0) {
-        return {
-            ok: false,
-            githubAuthMode: GITHUB_AUTH_MODE_HOST_GH,
-            runtimeMode,
-            failureKind: FAILURE_REPO_ACCESS,
-            detail: `GitHub API reachable but repository access failed for ${repo}`,
-            remediation: mergeRemediation(runtimeMode, FAILURE_REPO_ACCESS),
-            login: parseLogin(userApi.stdout),
-        };
+    return validateAfterAuth(GITHUB_AUTH_MODE_INJECTED_TOKEN, environ, options, runtimeMode, runner);
+}
+export function validateHostGhMode(environ, options = {}) {
+    const runner = options.runGh ?? defaultRunGh;
+    const runtimeMode = options.runtimeMode ?? null;
+    const authStatus = runner(["auth", "status"], environ);
+    if (authStatus.returncode !== 0) {
+        return emptyResult(GITHUB_AUTH_MODE_HOST_GH, runtimeMode, FAILURE_GH_AUTH, "gh auth status failed in worker environment");
     }
-    return {
-        ok: true,
-        githubAuthMode: GITHUB_AUTH_MODE_HOST_GH,
-        runtimeMode,
-        failureKind: null,
-        detail: "host-gh mode validated in worker environment",
-        remediation: null,
-        login: parseLogin(userApi.stdout),
-    };
+    return validateAfterAuth(GITHUB_AUTH_MODE_HOST_GH, environ, options, runtimeMode, runner);
 }
 export function validateGithubAuth(githubAuthMode, options = {}) {
     const env = options.environ ?? process.env;
     const runtimeMode = options.runtimeReport?.runtimeMode ?? null;
     if (!KNOWN_GITHUB_AUTH_MODES.has(githubAuthMode)) {
-        return {
-            ok: false,
-            githubAuthMode,
-            runtimeMode,
-            failureKind: FAILURE_INVALID_MODE,
-            detail: `unknown github_auth_mode ${pyRepr(githubAuthMode)}; expected one of ${pyRepr([...KNOWN_GITHUB_AUTH_MODES].sort())}`,
-            remediation: null,
-            login: null,
-        };
-    }
-    if (githubAuthMode === GITHUB_AUTH_MODE_INJECTED_TOKEN) {
-        return validateInjectedTokenMode(env, {
-            repo: options.repo,
-            runtimeMode,
-            runGh: options.runGh,
-        });
+        return emptyResult(githubAuthMode, runtimeMode, FAILURE_INVALID_MODE, `unknown github_auth_mode ${pyRepr(githubAuthMode)}; expected one of ${pyRepr([...KNOWN_GITHUB_AUTH_MODES].sort())}`);
     }
-    return validateHostGhMode(env, {
+    const shared = {
         repo: options.repo,
         runtimeMode,
         runGh: options.runGh,
-    });
+        expectedPrincipal: options.expectedPrincipal,
+        gitRemoteUrl: options.gitRemoteUrl,
+        readGitRemote: options.readGitRemote,
+        cwd: options.cwd,
+    };
+    if (githubAuthMode === GITHUB_AUTH_MODE_INJECTED_TOKEN) {
+        return validateInjectedTokenMode(env, shared);
+    }
+    return validateHostGhMode(env, shared);
 }
 export function validateGithubAuthForWorker(githubAuthMode = null, options = {}) {
     const report = options.runtimeReport ?? getPlatformCapabilities();
@@ -274,12 +459,30 @@ export function resultToDict(result) {
         detail: result.detail,
         remediation: result.remediation,
         login: result.login,
+        principal_kind: result.principal?.kind ?? null,
+        validation_repo: result.validationRepo,
     };
 }
+function expectedPrincipalFromCliArgs(args) {
+    if (args.expectedPrincipal !== undefined) {
+        return args.expectedPrincipal ?? undefined;
+    }
+    const login = args.expectedLogin?.trim() ?? "";
+    if (login.length > 0) {
+        return { kind: PRINCIPAL_KIND_USER, login };
+    }
+    return undefined;
+}
 export function githubAuthModesMain(args) {
+    const fromFlags = expectedPrincipalFromCliArgs(args);
+    if (fromFlags !== undefined && "error" in fromFlags) {
+        process.stderr.write(`${fromFlags.error}\n`);
+        return 2;
+    }
     const result = validateGithubAuthForWorker(args.githubAuthMode ?? null, {
-        repo: args.repo ?? DEFAULT_VALIDATION_REPO,
+        repo: args.repo,
         runGh: args.runGh,
+        expectedPrincipal: fromFlags,
     });
     if (args.json) {
         process.stdout.write(`${JSON.stringify(resultToDict(result), null, 2)}\n`);

package/dist/lifecycle/completed-tracked-on-delivery.d.ts

@@ -35,7 +35,33 @@ export interface EvaluateCompletedTrackedOptions {
     readonly runGit?: GitRunner;
     /** Test seam: override issue state resolution. */
     readonly resolveIssueState?: (ref: IssueRef) => "open" | "closed" | null;
+    /**
+     * Progress hook (#3673). Fired after tip listing and after the batch
+     * blob read so a CLI can announce an up-front count only when elapsed
+     * time crosses a measured threshold.
+     */
+    readonly onProgress?: (event: CompletedTrackedProgress) => void;
+    /** Test seam: override wall clock for progress elapsedMs. */
+    readonly now?: () => number;
+}
+/** Default silence window so a ~2s batch read does not emit progress noise. */
+export declare const COMPLETED_TRACKED_PROGRESS_THRESHOLD_MS = 3000;
+/**
+ * Up-front count floor (#3673 Greptile P2). Listing is cheap; the batch
+ * read is the remaining stall. Announce the blob count after listing
+ * (before `cat-file --batch`) when the corpus is large enough that a
+ * silent wait is the old DONE-path failure mode. Fixture-sized runs stay
+ * quiet unless the duration threshold is also crossed.
+ */
+export declare const COMPLETED_TRACKED_PROGRESS_MIN_BLOBS = 32;
+export interface CompletedTrackedProgress {
+    readonly phase: "listed" | "read";
+    readonly terminalCount: number;
+    readonly nonterminalCount: number;
+    readonly elapsedMs: number;
 }
+export declare function shouldAnnounceProgress(elapsedMs: number, thresholdMs?: number): boolean;
+export declare function shouldAnnounceUpFrontCount(terminalCount: number, nonterminalCount: number, minBlobs?: number): boolean;
 /**
  * Resolve the git tip to inspect for tracked completed/cancelled land.
  * Prefers origin/<deliveryBranch> when present.

package/dist/lifecycle/completed-tracked-on-delivery.js

@@ -16,7 +16,7 @@ import { hasArtifactSuffix, LEGACY_ARTIFACT_DIR, MIGRATED_ARTIFACT_DIR, resolveL
 import { collectGithubRefs } from "../orphan-active/refs.js";
 import { resolveDeliveryBranch } from "../policy/delivery-branch.js";
 import { defaultRunGh } from "../pr-protected-issues/gh.js";
-import { defaultGitRunner } from "../session/git.js";
+import { defaultGitRunner, showBlobsBatch } from "../session/git.js";
 import { CACHE_DIR_NAME, CACHE_SOURCE_GITHUB_ISSUE } from "../triage/queue/constants.js";
 import { resolveRepo } from "../triage/queue/repo.js";
 /** Lifecycle folders scanned for local "known origin" xBRIEFs. */
@@ -31,6 +31,22 @@ export const LOCAL_ORIGIN_FOLDERS = [
 export const TIP_NONTERMINAL_FOLDERS = ["proposed", "pending", "active"];
 /** Terminal tip folders that satisfy the land rule. */
 export const TIP_TERMINAL_FOLDERS = ["completed", "cancelled"];
+/** Default silence window so a ~2s batch read does not emit progress noise. */
+export const COMPLETED_TRACKED_PROGRESS_THRESHOLD_MS = 3_000;
+/**
+ * Up-front count floor (#3673 Greptile P2). Listing is cheap; the batch
+ * read is the remaining stall. Announce the blob count after listing
+ * (before `cat-file --batch`) when the corpus is large enough that a
+ * silent wait is the old DONE-path failure mode. Fixture-sized runs stay
+ * quiet unless the duration threshold is also crossed.
+ */
+export const COMPLETED_TRACKED_PROGRESS_MIN_BLOBS = 32;
+export function shouldAnnounceProgress(elapsedMs, thresholdMs = COMPLETED_TRACKED_PROGRESS_THRESHOLD_MS) {
+    return elapsedMs >= thresholdMs;
+}
+export function shouldAnnounceUpFrontCount(terminalCount, nonterminalCount, minBlobs = COMPLETED_TRACKED_PROGRESS_MIN_BLOBS) {
+    return terminalCount + nonterminalCount >= minBlobs;
+}
 function readJson(path) {
     try {
         const parsed = JSON.parse(readFileSync(path, "utf8"));
@@ -223,13 +239,6 @@ function listTreePaths(projectRoot, tip, prefixes, runGit) {
         .map((line) => line.trim().replace(/\\/g, "/"))
         .filter((line) => line.length > 0 && hasArtifactSuffix(line));
 }
-function showBlob(projectRoot, tip, path, runGit) {
-    const result = runGit(projectRoot, ["show", `${tip}:${path}`]);
-    if (result.code !== 0) {
-        return null;
-    }
-    return result.stdout;
-}
 function terminalPrefixes() {
     const out = [];
     for (const root of [MIGRATED_ARTIFACT_DIR, LEGACY_ARTIFACT_DIR]) {
@@ -248,11 +257,11 @@ function nonterminalPrefixes() {
     }
     return out;
 }
-function issuesFromBlobPaths(projectRoot, tip, paths, defaultRepo, runGit, originPrefix) {
+function issuesFromBlobBodies(paths, bodies, defaultRepo, originPrefix) {
     const hits = [];
     for (const path of paths) {
-        const body = showBlob(projectRoot, tip, path, runGit);
-        if (body === null) {
+        const body = bodies.get(path);
+        if (body === undefined || body === null) {
             continue;
         }
         let parsed;
@@ -375,17 +384,31 @@ export function evaluateCompletedTracked(projectRoot, options = {}) {
             tip: null,
         };
     }
+    const startedAt = (options.now ?? Date.now)();
+    const emitProgress = (phase, terminalCount, nonterminalCount) => {
+        options.onProgress?.({
+            phase,
+            terminalCount,
+            nonterminalCount,
+            elapsedMs: (options.now ?? Date.now)() - startedAt,
+        });
+    };
     const localHits = scanLocalOrigins(root, defaultRepo);
     const tipNonterminalPaths = listTreePaths(root, tip, nonterminalPrefixes(), runGit);
-    const tipNonterminalHits = issuesFromBlobPaths(root, tip, tipNonterminalPaths, defaultRepo, runGit, `tip:${tip}`);
-    let originMap = mergeOrigins([...localHits, ...tipNonterminalHits]);
     // Delivery tip only — the land invariant is post-merge tip truth (#3264 AC).
     // Lifecycle PRs that commit completed/ on a feature branch are not expected
     // to satisfy this gate until merge; run the verb with --tip HEAD when
     // validating an in-flight land PR. The gate is a standalone verify verb
     // (not wired into check:consumer) so product PRs are not deadlocked.
     const tipTerminalPaths = listTreePaths(root, tip, terminalPrefixes(), runGit);
-    const tipTerminalHits = issuesFromBlobPaths(root, tip, tipTerminalPaths, defaultRepo, runGit, `tip:${tip}`);
+    emitProgress("listed", tipTerminalPaths.length, tipNonterminalPaths.length);
+    // One process for every tip artifact. Issue identity still comes from
+    // parsed plan.references / plan.metadata["x-tracking"] — never the path.
+    const tipBodies = showBlobsBatch(root, tip, [...tipNonterminalPaths, ...tipTerminalPaths], runGit);
+    emitProgress("read", tipTerminalPaths.length, tipNonterminalPaths.length);
+    const tipNonterminalHits = issuesFromBlobBodies(tipNonterminalPaths, tipBodies, defaultRepo, `tip:${tip}`);
+    let originMap = mergeOrigins([...localHits, ...tipNonterminalHits]);
+    const tipTerminalHits = issuesFromBlobBodies(tipTerminalPaths, tipBodies, defaultRepo, `tip:${tip}`);
     const landedKeys = new Set(tipTerminalHits.map((h) => issueKey(h.issue)));
     const issueFilter = options.issue ?? null;
     if (issueFilter !== null) {