@deftai/directive-core 0.108.0 → 0.109.0

package/dist/release/consumer-hard-stops.js

@@ -0,0 +1,140 @@
+/**
+ * Check 4 -- consumer hard-stop census (#3900 / #3713 / #3969).
+ *
+ * Enumerates open issues by privileged label only.
+ * BLOCKER is the sole permitted consumer title classification (inbound flare).
+ * The adoption-blocker label is never derived from a title.
+ * Issue bodies are not read into the verdict.
+ *
+ * parseClosesSet composes citation-grammar classifyPosition; do not add a
+ * third position classifier (#3969).
+ */
+import { classifyPosition } from "../design-critique/citation-grammar.js";
+export const CONSUMER_HARD_STOP_TITLE_RE = /^BLOCKER\b/i;
+export const ADOPTION_BLOCKER_LABEL = "adoption-blocker";
+export const BLOCKS_RELEASE_TAG_LABEL = "blocks-release-tag";
+/** Maintainer-applied labels that can block a cut. Titles cannot. */
+export const PRIVILEGED_HARD_STOP_LABELS = [
+    ADOPTION_BLOCKER_LABEL,
+    BLOCKS_RELEASE_TAG_LABEL,
+];
+const REMEDIATION = "Recovery: close those issues in this cut (or list them in the Unreleased Closes set). " +
+    "Census blocking classification is privileged labels (" +
+    PRIVILEGED_HARD_STOP_LABELS.join(", ") +
+    ") only; BLOCKER in a title is an inbound flare and does not by itself block a cut (#3713 / #3969).";
+function labelsOf(issue) {
+    return issue.labels.map((label) => label.trim()).filter((label) => label.length > 0);
+}
+function hasPrivilegedLabel(labels) {
+    return labels.some((label) => PRIVILEGED_HARD_STOP_LABELS.includes(label));
+}
+/** Privileged labels only. Title is recorded as a flare, never as a match. Never inspect a body field. */
+export function classifyHardStop(issue) {
+    const viaTitle = CONSUMER_HARD_STOP_TITLE_RE.test(issue.title.trim());
+    const viaLabel = hasPrivilegedLabel(labelsOf(issue));
+    if (!viaLabel) {
+        return null;
+    }
+    return { number: issue.number, title: issue.title, viaTitle, viaLabel };
+}
+export function enumerateConsumerHardStops(issues) {
+    const out = [];
+    for (const issue of issues) {
+        const match = classifyHardStop(issue);
+        if (match !== null) {
+            out.push(match);
+        }
+    }
+    return out.sort((a, b) => a.number - b.number);
+}
+/**
+ * Extract Closes/Fixes/Resolves #N from changelog Unreleased text.
+ * Never from issue bodies. Hits in refused markdown positions are not claims.
+ */
+export function parseClosesSet(changelogText) {
+    const after = changelogText.split(/^## \[Unreleased\]\s*$/m)[1] ?? "";
+    const unreleased = after.split(/^## \[/m)[0] ?? after;
+    const found = new Set();
+    const re = /\b(?:Closes|Fixes|Resolves)\s+#(\d+)/gi;
+    let match = re.exec(unreleased);
+    while (match !== null) {
+        const reason = classifyPosition(unreleased, match.index ?? 0);
+        if (reason === null) {
+            const n = Number(match[1]);
+            if (Number.isInteger(n) && n > 0) {
+                found.add(n);
+            }
+        }
+        match = re.exec(unreleased);
+    }
+    return found;
+}
+export function evaluateConsumerHardStopCensus(options) {
+    const matches = enumerateConsumerHardStops(options.issues);
+    const shipsPast = matches.filter((entry) => !options.closesSet.has(entry.number));
+    if (matches.length === 0) {
+        return {
+            code: 0,
+            message: "Consumer hard-stops: ok -- no open privileged hard-stop labels (" +
+                PRIVILEGED_HARD_STOP_LABELS.join(", ") +
+                ").",
+            stream: "stdout",
+            matches,
+            shipsPast,
+        };
+    }
+    if (shipsPast.length === 0) {
+        return {
+            code: 0,
+            message: "Consumer hard-stops: ok -- " +
+                String(matches.length) +
+                " open hard-stop(s) are in this cut Closes set.",
+            stream: "stdout",
+            matches,
+            shipsPast,
+        };
+    }
+    const sample = shipsPast
+        .slice(0, 8)
+        .map((entry) => "#" + String(entry.number))
+        .join(", ");
+    return {
+        code: 1,
+        message: "Consumer hard-stops: fail -- " +
+            String(shipsPast.length) +
+            " open hard-stop(s) not in this cut Closes set: " +
+            sample +
+            ". " +
+            REMEDIATION,
+        stream: "stderr",
+        matches,
+        shipsPast,
+    };
+}
+export function issueFromInventoryRow(row) {
+    const number = row.number;
+    const title = row.title;
+    if (typeof number !== "number" || !Number.isInteger(number) || typeof title !== "string") {
+        return null;
+    }
+    if ("pull_request" in row) {
+        return null;
+    }
+    const labelsRaw = row.labels;
+    const labels = [];
+    if (Array.isArray(labelsRaw)) {
+        for (const item of labelsRaw) {
+            if (typeof item === "string") {
+                labels.push(item);
+            }
+            else if (item !== null && typeof item === "object" && "name" in item) {
+                const name = item.name;
+                if (typeof name === "string") {
+                    labels.push(name);
+                }
+            }
+        }
+    }
+    return { number, title, labels };
+}
+//# sourceMappingURL=consumer-hard-stops.js.map

package/dist/release/consumer-readiness-disclosure.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Checks 5 and 6 -- operator disclosure at the release decision point (#3900).
+ *
+ * New-refusal census and net-posture are judgments. They are printed for the
+ * operator and never fail-closed, never dressed as a computed verdict.
+ */
+export interface RefusalHint {
+    readonly line: number;
+    readonly excerpt: string;
+}
+export interface ConsumerReadinessDisclosure {
+    readonly blocking: false;
+    readonly newRefusalHints: readonly RefusalHint[];
+    readonly text: string;
+}
+export declare function collectNewRefusalHints(changelogText: string): RefusalHint[];
+export declare function formatConsumerReadinessDisclosure(changelogText: string): ConsumerReadinessDisclosure;
+//# sourceMappingURL=consumer-readiness-disclosure.d.ts.map

package/dist/release/consumer-readiness-disclosure.js

@@ -0,0 +1,51 @@
+/**
+ * Checks 5 and 6 -- operator disclosure at the release decision point (#3900).
+ *
+ * New-refusal census and net-posture are judgments. They are printed for the
+ * operator and never fail-closed, never dressed as a computed verdict.
+ */
+const FAIL_CLOSED_HINT = /fail-closed|fail closed|refuses? to|MUST NOT|must not|blocks? (?:the )?(?:tag|cut|release)|new refusal/i;
+function unreleasedSection(changelogText) {
+    const rest = changelogText.split(/^## \[Unreleased\]\s*$/m)[1];
+    if (rest === undefined) {
+        return "";
+    }
+    const next = rest.split(/^## \[/m)[0] ?? rest;
+    return next;
+}
+export function collectNewRefusalHints(changelogText) {
+    const section = unreleasedSection(changelogText);
+    const hints = [];
+    const lines = section.split("\n");
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? "";
+        if (FAIL_CLOSED_HINT.test(line)) {
+            hints.push({ line: i + 1, excerpt: line.trim().slice(0, 160) });
+        }
+    }
+    return hints;
+}
+export function formatConsumerReadinessDisclosure(changelogText) {
+    const hints = collectNewRefusalHints(changelogText);
+    const lines = [
+        "Consumer-readiness disclosure (does not block the tag) -- #3900 checks 5 and 6.",
+        "",
+        "Check 5 -- new-refusal census (operator judgment):",
+    ];
+    if (hints.length === 0) {
+        lines.push("  No Unreleased lines matched fail-closed / new-refusal hints.");
+    }
+    else {
+        lines.push("  Unreleased lines that may introduce a consumer-visible refusal:");
+        for (const hint of hints.slice(0, 20)) {
+            lines.push("  - " + hint.excerpt);
+        }
+    }
+    lines.push("  Each new refusal needs remediation text and an escape hatch. This is not a computed verdict.");
+    lines.push("");
+    lines.push("Check 6 -- net-posture (operator judgment):");
+    lines.push("  Does this candidate fix more consumer-visible breakage than it introduces, and on which surfaces?");
+    lines.push("  Holding a release is only correct when that answer is negative. The operator decides.");
+    return { blocking: false, newRefusalHints: hints, text: lines.join("\n") };
+}
+//# sourceMappingURL=consumer-readiness-disclosure.js.map

package/dist/release/index.d.ts

@@ -3,6 +3,8 @@ export * from "./build-dist.js";
 export * from "./cli-drift-report.js";
 export * from "./closed-verb-gate.js";
 export * from "./constants.js";
+export * from "./consumer-hard-stops.js";
+export * from "./consumer-readiness-disclosure.js";
 export * from "./coverage-debt-ledger.js";
 export * from "./flags.js";
 export * from "./gh.js";

package/dist/release/index.js

@@ -4,6 +4,8 @@ export * from "./build-dist.js";
 export * from "./cli-drift-report.js";
 export * from "./closed-verb-gate.js";
 export * from "./constants.js";
+export * from "./consumer-hard-stops.js";
+export * from "./consumer-readiness-disclosure.js";
 export * from "./coverage-debt-ledger.js";
 export * from "./flags.js";
 export * from "./gh.js";

package/dist/release/pipeline.js

@@ -1,18 +1,21 @@
 import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { assertProjectionContained } from "../fs/projection-containment.js";
+import { restIssueListOpenInventory } from "../scm/gh-rest.js";
 import { readCoverageTotalsFromReport } from "../vitest-runner/coverage-debt.js";
 import { buildCoverageDebtIssueDraft, classifyStep5FailureWithFreshness, evaluateAutoHatch, formatAutoHatchBanner, parseExitCodeFromReason, reasonLooksLikeTimeout, } from "./auto-hatch.js";
 import { prependUpgradeBanner, promoteChangelog, sectionForVersion } from "./changelog.js";
 import { emitCliDriftReportBestEffort, shouldSkipRegistryPoll, } from "./cli-drift-report.js";
 import { assertTagPushClosedVerb } from "./closed-verb-gate.js";
 import { EXIT_CONFIG_ERROR, EXIT_OK, EXIT_VIOLATION, RELEASE_ARTIFACTS, RELEASE_CHECK_TIMEOUT_MINUTES, TOTAL_STEPS, VERIFY_DRAFT_INTERVAL_SECONDS, VERIFY_DRAFT_MAX_ATTEMPTS, } from "./constants.js";
+import { formatConsumerReadinessDisclosure } from "./consumer-readiness-disclosure.js";
 import { createCoverageDebtIssue, probeOpenCoverageDebtLedger } from "./coverage-debt-ledger.js";
 import { checkTagAvailable, createGithubRelease, readTextFile, verifyReleaseDraft } from "./gh.js";
 import { checkGitClean, commitReleaseArtifacts, createTag, currentBranch, pushRelease, releaseCommitSubject, runGit, } from "./git.js";
 import { checkVbriefLifecycleSyncNative, refreshRoadmapNative, runBuildNative, } from "./native-steps.js";
 import { todayIso } from "./paths.js";
 import { runReleaseCheck } from "./preflight.js";
+import { evaluateReleaseConsumerReadiness, issuesFromInventory } from "./run-consumer-readiness.js";
 import { formatSkipCiIncidentWarning } from "./skip-ci-incident.js";
 import { evaluateSuiteStamp, writeSuiteStamp } from "./suite-stamp.js";
 import { isPrereleaseTag } from "./version.js";
@@ -290,6 +293,58 @@ export function runPipeline(config, seams = {}) {
             }
         }
     }
+    // #3900: check 4 fail-closed (title/label census); checks 5-6 disclosure never block.
+    {
+        const crLabel = "Consumer-readiness census";
+        let changelogText = "";
+        try {
+            changelogText = readFile(changelogPath);
+        }
+        catch {
+            changelogText = "";
+        }
+        const disclosure = formatConsumerReadinessDisclosure(changelogText);
+        if (config.dryRun) {
+            emit(5, crLabel, "DRYRUN (would enumerate open privileged hard-stop labels; disclosure does not block)");
+            process.stderr.write(disclosure.text + "\n");
+        }
+        else if (seams.consumerHardStops) {
+            const [ok, msg] = seams.consumerHardStops(config.repo, projectRoot);
+            if (!ok) {
+                emit(5, crLabel, "FAIL (" + msg + ")");
+                process.stderr.write(disclosure.text + "\n");
+                return EXIT_VIOLATION;
+            }
+            emit(5, crLabel, "OK (" + msg + ")");
+            process.stderr.write(disclosure.text + "\n");
+        }
+        else if (seams.runCi !== undefined || seams.spawnText !== undefined) {
+            emit(5, crLabel, "SKIP (injected seam; run task verify:consumer-hard-stops at a real cut)");
+            process.stderr.write(disclosure.text + "\n");
+        }
+        else {
+            try {
+                const rows = restIssueListOpenInventory(config.repo);
+                const result = evaluateReleaseConsumerReadiness({
+                    changelogText,
+                    issues: issuesFromInventory(rows),
+                });
+                process.stderr.write(result.disclosure.text + "\n");
+                if (result.hardStops.code !== 0) {
+                    emit(5, crLabel, "FAIL (" + result.hardStops.message + ")");
+                    return result.hardStops.code === 2 ? EXIT_CONFIG_ERROR : EXIT_VIOLATION;
+                }
+                emit(5, crLabel, "OK (" + result.hardStops.message + ")");
+            }
+            catch (err) {
+                const reason = err instanceof Error ? err.message : String(err);
+                emit(5, crLabel, "FAIL (could not list open issues. Recovery: check gh auth and REST quota. " +
+                    reason +
+                    ")");
+                return EXIT_CONFIG_ERROR;
+            }
+        }
+    }
     // Step 6: CHANGELOG promotion.
     label = "CHANGELOG promotion";
     if (!fileExists(changelogPath)) {

package/dist/release/run-consumer-readiness.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Release pre-flight consumer-readiness: check 4 fail-closed, checks 5-6 disclosure (#3900).
+ */
+import { evaluateConsumerHardStopCensus, type HardStopIssue } from "./consumer-hard-stops.js";
+import { formatConsumerReadinessDisclosure } from "./consumer-readiness-disclosure.js";
+export interface ConsumerReadinessInput {
+    readonly changelogText: string;
+    readonly issues: readonly HardStopIssue[];
+}
+export declare function evaluateReleaseConsumerReadiness(input: ConsumerReadinessInput): {
+    readonly hardStops: ReturnType<typeof evaluateConsumerHardStopCensus>;
+    readonly disclosure: ReturnType<typeof formatConsumerReadinessDisclosure>;
+};
+export declare function issuesFromInventory(rows: readonly Record<string, unknown>[]): HardStopIssue[];
+//# sourceMappingURL=run-consumer-readiness.d.ts.map

package/dist/release/run-consumer-readiness.js

@@ -0,0 +1,24 @@
+/**
+ * Release pre-flight consumer-readiness: check 4 fail-closed, checks 5-6 disclosure (#3900).
+ */
+import { evaluateConsumerHardStopCensus, issueFromInventoryRow, parseClosesSet, } from "./consumer-hard-stops.js";
+import { formatConsumerReadinessDisclosure } from "./consumer-readiness-disclosure.js";
+export function evaluateReleaseConsumerReadiness(input) {
+    return {
+        hardStops: evaluateConsumerHardStopCensus({
+            issues: input.issues,
+            closesSet: parseClosesSet(input.changelogText),
+        }),
+        disclosure: formatConsumerReadinessDisclosure(input.changelogText),
+    };
+}
+export function issuesFromInventory(rows) {
+    const issues = [];
+    for (const row of rows) {
+        const issue = issueFromInventoryRow(row);
+        if (issue !== null)
+            issues.push(issue);
+    }
+    return issues;
+}
+//# sourceMappingURL=run-consumer-readiness.js.map

package/dist/release/types.d.ts

@@ -54,6 +54,12 @@ export interface ReleaseSeams {
     readonly writeFile?: (path: string, content: string) => void;
     readonly readFile?: (path: string) => string;
     readonly fileExists?: (path: string) => boolean;
+    /**
+     * #3900 check 4 -- consumer hard-stop census. When omitted, production lists
+     * open issues via REST. Tests inject a [ok, message] tuple so they do not
+     * hit GitHub.
+     */
+    readonly consumerHardStops?: (repo: string, projectRoot: string) => [boolean, string];
     readonly runCi?: (projectRoot: string, allowCoverageDebtIssue: number | null) => [boolean, string];
     readonly refreshRoadmap?: (projectRoot: string) => [boolean, string];
     readonly checkVbriefLifecycleSync?: (projectRoot: string, repo: string) => [boolean, number, string];

package/dist/review-monitor/github-lease.js

@@ -1,14 +1,15 @@
 import { spawnSync } from "node:child_process";
-import { resolveBinary } from "../scm/binary.js";
+import { resolveBinaryForArgv } from "../scm/call-shape.js";
 import { DEFAULT_TIMEOUT_S, restDeleteComment, restGetUser, restPostComment, restUpdateComment, } from "../scm/gh-rest.js";
 import { SUBPROCESS_MAX_BUFFER } from "../subprocess/max-buffer.js";
 import { isMaintainerAuthored, parseCommentsFromGhStdout, } from "../umbrella-current-shape/index.js";
 import { DEFAULT_PASS_STALE_MINUTES, PASS_MARKER_KIND } from "./constants.js";
 import { computeExpiresAt, findActivePassComment, mapCommentEntry, mapPassCommentEntry, renderPassOpenComment, } from "./lease-comment.js";
 function defaultFetchComments(repo, pr, seams) {
-    const binary = resolveBinary(seams.whichFn);
     const path = `repos/${repo}/issues/${pr}/comments?per_page=100`;
-    const proc = spawnSync(binary, ["api", "--paginate", path], {
+    const apiArgs = ["--paginate", path];
+    const binary = resolveBinaryForArgv("api", apiArgs, seams.whichFn);
+    const proc = spawnSync(binary, ["api", ...apiArgs], {
         encoding: "utf8",
         maxBuffer: SUBPROCESS_MAX_BUFFER,
         timeout: DEFAULT_TIMEOUT_S * 1000,

package/dist/run-summary/types.d.ts

@@ -126,8 +126,8 @@ export interface AcceptanceRunSummaryPayload {
     readonly none_stated?: boolean;
     readonly clause_count?: number;
     readonly clause_outcomes?: readonly AcceptanceClauseOutcomeRow[];
-    /** bank | cache | executed — how verify:ac obtained this result (#3387). */
-    readonly served_from?: "bank" | "cache" | "executed";
+    /** bank | cache | executed | refused — how verify:ac obtained this result (#3387 / #3615). */
+    readonly served_from?: "bank" | "cache" | "executed" | "refused";
     /** Config-error cause when outcome is config-error (#3559). */
     readonly cause?: string;
     /** Reuse-gate miss cause when served_from is executed (#3558). */

package/dist/scm/build-command.d.ts

@@ -1,7 +1,7 @@
-import { resolveBinary } from "./binary.js";
+import { resolveBinaryForArgv } from "./call-shape.js";
 export interface BuildCommandOptions {
     readonly binary?: string;
-    readonly whichFn?: Parameters<typeof resolveBinary>[0];
+    readonly whichFn?: Parameters<typeof resolveBinaryForArgv>[2];
 }
 /**
  * Construct the underlying `[binary, namespace, verb, *extra]` argv.

package/dist/scm/build-command.js

@@ -1,4 +1,4 @@
-import { resolveBinary } from "./binary.js";
+import { resolveBinaryForArgv } from "./call-shape.js";
 import { ALLOWED_ISSUE_VERBS, ALLOWED_NAMESPACES } from "./constants.js";
 import { ScmStubError } from "./errors.js";
 import { pyRepr, pyTuple } from "./py-format.js";
@@ -17,7 +17,7 @@ export function buildCommand(namespace, verb, extra, options = {}) {
             `${pyTuple(ALLOWED_ISSUE_VERBS)}. The v1 stub only exposes these four; ` +
             "additional scm:issue:* commands belong on #881.");
     }
-    const resolved = options.binary ?? resolveBinary(options.whichFn ?? undefined);
+    const resolved = options.binary ?? resolveBinaryForArgv(namespace, [verb, ...extra], options.whichFn);
     return [resolved, namespace, verb, ...extra];
 }
 //# sourceMappingURL=build-command.js.map

package/dist/scm/call-shape.d.ts

@@ -0,0 +1,25 @@
+import { type WhichFn } from "./binary.js";
+/** Surfaces ghx may serve versus surfaces that must use live gh (#3737). */
+export type ScmBinaryRole = "cached-get" | "live-gh";
+/**
+ * Classify an SCM argv for ghx eligibility.
+ *
+ * ghx is a cached read-only GET proxy that accepts a single positional path.
+ * Extra positionals are rejected (`accepts 1 arg(s), received 2`). Flags
+ * (`--method`, `--paginate`, `--jq`, `--input`, `-X`, ...) are not the cache
+ * shape. Non-`api` verbs are live `gh`.
+ */
+export declare function classifyScmArgv(verb: string, args?: readonly string[]): ScmBinaryRole;
+/**
+ * Resolve a binary for a classified role.
+ *
+ * cached-get uses the PATH ladder (`resolveBinary`, ghx then gh).
+ * live-gh pins `gh` — the same preference as `resolveLiveGh`,
+ * `resolveAuthProbeBinary`, and `GH_ONLY_WHICH`. If `gh` is absent, throw
+ * rather than fall through to ghx (a mutation or flag-rich GET is not a
+ * cache-proxy shape).
+ */
+export declare function resolveBinaryForRole(role: ScmBinaryRole, whichFn?: WhichFn): string;
+/** Classify argv then resolve. Compose with `resolveBinary`; do not probe health. */
+export declare function resolveBinaryForArgv(verb: string, args?: readonly string[], whichFn?: WhichFn): string;
+//# sourceMappingURL=call-shape.d.ts.map

package/dist/scm/call-shape.js

@@ -0,0 +1,59 @@
+import { defaultWhich, resolveBinary } from "./binary.js";
+import { ScmStubError } from "./errors.js";
+/**
+ * Classify an SCM argv for ghx eligibility.
+ *
+ * ghx is a cached read-only GET proxy that accepts a single positional path.
+ * Extra positionals are rejected (`accepts 1 arg(s), received 2`). Flags
+ * (`--method`, `--paginate`, `--jq`, `--input`, `-X`, ...) are not the cache
+ * shape. Non-`api` verbs are live `gh`.
+ */
+export function classifyScmArgv(verb, args = []) {
+    if (verb !== "api") {
+        return "live-gh";
+    }
+    const positionals = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const token = args[i];
+        if (token === undefined) {
+            continue;
+        }
+        if (token === "--") {
+            positionals.push(...args.slice(i + 1));
+            break;
+        }
+        if (token.startsWith("-")) {
+            return "live-gh";
+        }
+        positionals.push(token);
+    }
+    if (positionals.length !== 1) {
+        return "live-gh";
+    }
+    return "cached-get";
+}
+/**
+ * Resolve a binary for a classified role.
+ *
+ * cached-get uses the PATH ladder (`resolveBinary`, ghx then gh).
+ * live-gh pins `gh` — the same preference as `resolveLiveGh`,
+ * `resolveAuthProbeBinary`, and `GH_ONLY_WHICH`. If `gh` is absent, throw
+ * rather than fall through to ghx (a mutation or flag-rich GET is not a
+ * cache-proxy shape).
+ */
+export function resolveBinaryForRole(role, whichFn = defaultWhich) {
+    if (role === "live-gh") {
+        if (whichFn("gh") !== null) {
+            return "gh";
+        }
+        throw new ScmStubError("gh not found on PATH; this call shape requires live gh, not the ghx cache proxy. " +
+            "install GitHub CLI (https://cli.github.com/) or pass GH_TOKEN into a matched env and re-run. " +
+            "Refs #3737 / #2275.");
+    }
+    return resolveBinary(whichFn);
+}
+/** Classify argv then resolve. Compose with `resolveBinary`; do not probe health. */
+export function resolveBinaryForArgv(verb, args = [], whichFn = defaultWhich) {
+    return resolveBinaryForRole(classifyScmArgv(verb, args), whichFn);
+}
+//# sourceMappingURL=call-shape.js.map

package/dist/scm/call.d.ts

@@ -1,4 +1,4 @@
-import { resolveBinary } from "./binary.js";
+import { type WhichFn } from "./binary.js";
 /** Mirrors Python `subprocess.CompletedProcess`. */
 export interface CompletedProcess {
     readonly args: readonly string[];
@@ -13,7 +13,7 @@ export interface CallOptions {
     readonly timeout?: number;
     readonly cwd?: string;
     readonly binary?: string;
-    readonly whichFn?: Parameters<typeof resolveBinary>[0];
+    readonly whichFn?: WhichFn;
     readonly env?: NodeJS.ProcessEnv;
     readonly input?: string;
 }
@@ -21,10 +21,13 @@ export interface CallOptions {
  * Source-aware SCM invocation -- partial down-payment on #445 / #935 Workstream 6.
  * Mirrors `scripts/scm.py::call`.
  *
- * Binary absence still throws ScmStubError via resolveBinary with the #2275
- * diagnostic. Full auth readiness is enforced at SCM CLI entry points
+ * Binary absence still throws ScmStubError via resolveBinaryForRole with the
+ * #2275 diagnostic. Full auth readiness is enforced at SCM CLI entry points
  * (`scm/main`, issue-ingest, reconcile-issues) via requireScmReady — not on
  * every call() — so unit tests that inject binary/seams stay hermetic.
+ *
+ * Call-shape selection (#3737): ghx only for single-path GET. An explicit
+ * `binary` override skips selection and spawn-failure fallback.
  */
 export declare function call(source: string, verb: string, args?: readonly string[] | null, options?: CallOptions): CompletedProcess;
 //# sourceMappingURL=call.d.ts.map

package/dist/scm/call.js

@@ -1,27 +1,35 @@
 import { spawnSync } from "node:child_process";
 import { resolveCaptureFailureStderr, SUBPROCESS_MAX_BUFFER } from "../subprocess/max-buffer.js";
-import { resolveBinary } from "./binary.js";
+import { defaultWhich } from "./binary.js";
+import { classifyScmArgv, resolveBinaryForRole } from "./call-shape.js";
 import { SUPPORTED_CALL_SOURCES } from "./constants.js";
 import { pyRepr } from "./py-format.js";
+import { formatScmSpawnDiagnostic, isAvailabilitySpawnFailure } from "./spawn-status.js";
 /**
  * Source-aware SCM invocation -- partial down-payment on #445 / #935 Workstream 6.
  * Mirrors `scripts/scm.py::call`.
  *
- * Binary absence still throws ScmStubError via resolveBinary with the #2275
- * diagnostic. Full auth readiness is enforced at SCM CLI entry points
+ * Binary absence still throws ScmStubError via resolveBinaryForRole with the
+ * #2275 diagnostic. Full auth readiness is enforced at SCM CLI entry points
  * (`scm/main`, issue-ingest, reconcile-issues) via requireScmReady — not on
  * every call() — so unit tests that inject binary/seams stay hermetic.
+ *
+ * Call-shape selection (#3737): ghx only for single-path GET. An explicit
+ * `binary` override skips selection and spawn-failure fallback.
  */
 export function call(source, verb, args = null, options = {}) {
     if (!SUPPORTED_CALL_SOURCES.includes(source)) {
         throw new Error(`source=${pyRepr(source)} not yet supported; ` +
             "see #445 / #935 Workstream 6 for the abstraction.");
     }
-    const resolved = options.binary ?? resolveBinary(options.whichFn);
-    const argv = [resolved, verb, ...(args ?? [])];
+    const whichFn = options.whichFn ?? defaultWhich;
+    const role = classifyScmArgv(verb, args ?? []);
+    const explicitBinary = options.binary;
+    let resolved = explicitBinary ?? resolveBinaryForRole(role, whichFn);
+    const extra = args ?? [];
     const captureOutput = options.captureOutput ?? true;
     const timeoutMs = options.timeout !== undefined ? Math.round(options.timeout * 1000) : undefined;
-    const result = spawnSync(resolved, [verb, ...(args ?? [])], {
+    const spawnOnce = (bin) => spawnSync(bin, [verb, ...extra], {
         cwd: options.cwd,
         env: options.env ?? process.env,
         input: options.input,
@@ -30,14 +38,36 @@ export function call(source, verb, args = null, options = {}) {
         maxBuffer: SUBPROCESS_MAX_BUFFER,
         stdio: captureOutput ? ["pipe", "pipe", "pipe"] : "inherit",
     });
-    // A spawn-level failure (ENOBUFS past maxBuffer, timeout kill) yields a null
-    // status and empty stderr; surface error.message so callers never report a
-    // bare exit 1 with no reason (#1867 / #3903).
-    const stderr = resolveCaptureFailureStderr({
-        captured: typeof result.stderr === "string" ? result.stderr : "",
+    let result = spawnOnce(resolved);
+    if (explicitBinary === undefined &&
+        role === "cached-get" &&
+        resolved === "ghx" &&
+        isAvailabilitySpawnFailure({
+            status: result.status,
+            error: result.error,
+            stdout: typeof result.stdout === "string" ? result.stdout : "",
+            stderr: typeof result.stderr === "string" ? result.stderr : "",
+        }) &&
+        whichFn("gh") !== null) {
+        resolved = "gh";
+        result = spawnOnce(resolved);
+    }
+    const argv = [resolved, verb, ...extra];
+    const captured = typeof result.stderr === "string" ? result.stderr : "";
+    let stderr = resolveCaptureFailureStderr({
+        captured,
         status: result.status,
         message: result.error?.message,
     });
+    if (isAvailabilitySpawnFailure({
+        status: result.status,
+        error: result.error,
+        stdout: typeof result.stdout === "string" ? result.stdout : "",
+        stderr: captured,
+    }) &&
+        stderr.trim().length === 0) {
+        stderr = formatScmSpawnDiagnostic(resolved, result.status, stderr, result.error);
+    }
     if (options.check && result.status !== 0) {
         const error = new Error(stderr || `Process exited with code ${result.status}`);
         throw error;