@deftai/directive-core 0.106.0 → 0.108.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/intake/issue-ingest.js

@@ -2,6 +2,7 @@ import { lstatSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSyn
 import { basename, dirname, join, resolve } from "node:path";
 import { cacheGet } from "../cache/operations.js";
 import { scan } from "../cache/scanner.js";
+import { assertCompletedArcAllowsIngest, DesignCritiqueIngestBlockedError, } from "../design-critique/completed-arc-record.js";
 import { assertWriteTargetSafe, ProjectionContainmentError } from "../fs/projection-containment.js";
 import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
 import { captureAndAttachLiteralAcceptance } from "../literal-acceptance/index.js";
@@ -703,6 +704,41 @@ function resolveIngestProjectRoot(vbriefDir, cwd) {
     }
     return null;
 }
+function issueLabelNames(issue) {
+    const labels = issue.labels;
+    if (!Array.isArray(labels))
+        return [];
+    const names = [];
+    for (const lbl of labels) {
+        if (typeof lbl === "string") {
+            names.push(lbl);
+            continue;
+        }
+        if (lbl !== null && typeof lbl === "object" && !Array.isArray(lbl)) {
+            const name = lbl.name;
+            if (typeof name === "string")
+                names.push(name);
+        }
+    }
+    return names;
+}
+function threadCommentsFromIssue(issue) {
+    const raw = issue[ISSUE_COMMENT_THREAD_KEY];
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const entry of raw) {
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry))
+            continue;
+        const rec = entry;
+        const id = Number(rec.id);
+        if (!Number.isSafeInteger(id) || id <= 0)
+            continue;
+        const body = typeof rec.body === "string" ? rec.body : "";
+        out.push({ id, body });
+    }
+    return out;
+}
 export function ingestOne(issue, options) {
     const number = Number(issue.number);
     const refs = options.existingRefs ?? scanProvenanceRefs(options.vbriefDir);
@@ -719,6 +755,11 @@ export function ingestOne(issue, options) {
         cwd: options.cwd,
         cacheRoot: options.cacheRoot,
     });
+    assertCompletedArcAllowsIngest({
+        issueNumber: number,
+        labels: issueLabelNames(enriched),
+        comments: threadCommentsFromIssue(enriched),
+    });
     const emissionLayout = resolveIngestEmissionLayout(options.vbriefDir);
     const [vbrief, folder] = buildIssueVbrief(enriched, options.status, options.repoUrl, {
         infoRootKey: emissionLayout.infoRootKey,
@@ -774,6 +815,7 @@ export function ingestBulk(issues, options) {
         duplicate: [],
         dryrun: [],
         failed: [],
+        blocked: [],
         notices: [],
     };
     for (const issue of filtered) {
@@ -790,6 +832,11 @@ export function ingestBulk(issues, options) {
                 process.stderr.write(`${exc.message}\n`);
                 continue;
             }
+            if (exc instanceof DesignCritiqueIngestBlockedError) {
+                summary.blocked.push(`#${exc.issueNumber}`);
+                process.stderr.write(`${exc.message}\n`);
+                continue;
+            }
             throw exc;
         }
         const [result, path, msg] = ingested;
@@ -861,7 +908,8 @@ export function issueIngestMain(args) {
         const duplicate = summary.duplicate;
         const dryrun = summary.dryrun;
         const failed = summary.failed ?? [];
-        process.stdout.write(`issue:ingest bulk summary: ${created.length} created, ${duplicate.length} duplicate, ${dryrun.length} dry-run, ${failed.length} refused (total considered: ${summary.total})\n`);
+        const blocked = summary.blocked ?? [];
+        process.stdout.write(`issue:ingest bulk summary: ${created.length} created, ${duplicate.length} duplicate, ${dryrun.length} dry-run, ${failed.length} refused, ${blocked.length} blocked (total considered: ${summary.total})\n`);
         for (const entry of created) {
             process.stdout.write(`  CREATED ${entry}\n`);
         }
@@ -877,8 +925,16 @@ export function issueIngestMain(args) {
         for (const entry of failed) {
             process.stdout.write(`  REFUSED ${entry} (quarantine scanner hard-fail; nothing written)\n`);
         }
+        for (const entry of blocked) {
+            process.stdout.write(`  BLOCKED ${entry} (design-critique completed-arc record; nothing written)\n`);
+        }
         // #2306: fail closed on any quarantine hard-fail in the batch.
-        return failed.length > 0 ? 2 : 0;
+        // Design-critique protocol holds are exit 1, not the scanner fatal path.
+        if (failed.length > 0)
+            return 2;
+        if (blocked.length > 0)
+            return 1;
+        return 0;
     }
     const issue = fetchIssue(repo, args.number, { cwd: projectRoot });
     if (issue === null) {
@@ -901,6 +957,10 @@ export function issueIngestMain(args) {
             process.stderr.write(`${exc.message}\n`);
             return 2;
         }
+        if (exc instanceof DesignCritiqueIngestBlockedError) {
+            process.stderr.write(`${exc.message}\n`);
+            return 1;
+        }
         throw exc;
     }
     process.stdout.write(`${msg}\n`);

package/dist/intake/platform-capabilities.d.ts

@@ -1,11 +1,18 @@
 /** Minimal runtime capability probe for github_auth_modes (#1557a / #1784). */
+import { type ManagedRuntimeProbe } from "../platform/cursor-managed-runtime.js";
 export declare const RUNTIME_MODE_LOCAL_UNSANDBOXED = "local-unsandboxed";
 export declare const RUNTIME_MODE_CURSOR_NATIVE_SANDBOX = "cursor-native-sandbox";
 export declare const RUNTIME_MODE_CLOUD_HEADLESS = "cloud-headless";
 export declare const KNOWN_RUNTIME_MODES: Set<string>;
 export interface RuntimeCapabilityReport {
     readonly runtimeMode: string;
+    /** Stable id naming why `runtimeMode` was chosen; surfaced by scm:status (#3859). */
+    readonly runtimeModeReason?: string;
 }
-export declare function probeRuntimeCapabilities(environ?: NodeJS.ProcessEnv): RuntimeCapabilityReport;
-export declare function getPlatformCapabilities(): RuntimeCapabilityReport;
+export interface ProbeRuntimeCapabilityOptions {
+    /** Injectable managed-runtime probe (#3859). Defaults to the metadata read. */
+    readonly managedRuntimeProbe?: ManagedRuntimeProbe;
+}
+export declare function probeRuntimeCapabilities(environ?: NodeJS.ProcessEnv, options?: ProbeRuntimeCapabilityOptions): RuntimeCapabilityReport;
+export declare function getPlatformCapabilities(options?: ProbeRuntimeCapabilityOptions): RuntimeCapabilityReport;
 //# sourceMappingURL=platform-capabilities.d.ts.map