session-orchestrator 3.17.0 → 3.20.0

package/scripts/lib/backlog-scan.mjs

@@ -19,6 +19,9 @@
 
 import { spawnSync } from 'node:child_process';
 
+import { normalizeLabel } from './label-scope.mjs';
+import { resolveRepoSpec } from './vcs-repo-spec.mjs';
+
 export const STALE_THRESHOLD_DAYS = 30;
 
 /** Module-level cache. Keyed by JSON.stringify({vcs, limit}). */
@@ -108,8 +111,12 @@ export function summarizeIssues(issues, nowMs = Date.now()) {
 
     for (const name of labelNames) {
       byLabel[name] = (byLabel[name] || 0) + 1;
-      if (name === 'priority:critical') criticalCount += 1;
-      else if (name === 'priority:high') highCount += 1;
+      // Scope-tolerant: the canonical spelling is the scoped `priority::<level>`,
+      // but the label-data migration trails the producer migration, so issues
+      // carrying the legacy `priority:<level>` must keep counting.
+      const key = normalizeLabel(name);
+      if (key === 'priority:critical') criticalCount += 1;
+      else if (key === 'priority:high') highCount += 1;
     }
 
     const updated = issue.updated_at || issue.updatedAt || null;
@@ -127,7 +134,10 @@ export function summarizeIssues(issues, nowMs = Date.now()) {
 
 /**
  * Scan the project's open backlog and return a structural summary suitable for
- * `signals.backlog`. Caches the result per (vcs, limit) within the running process.
+ * `signals.backlog`. Caches the result per (vcs, limit, spec) within the
+ * running process — `spec` (the resolved `-R`/`--repo` host-pinning value,
+ * #872) is part of the cache key so two different repos scanning the SAME
+ * (vcs, limit) pair never collide on a shared cache entry.
  *
  * Returns null on any of:
  *  - VCS cannot be detected (no git origin)
@@ -136,7 +146,20 @@ export function summarizeIssues(issues, nowMs = Date.now()) {
  *
  * Never throws.
  *
- * @param {{limit?: number, vcs?: 'github'|'gitlab'|null, nowMs?: number}} [opts]
+ * @param {{
+ *   limit?: number,
+ *   vcs?: 'github'|'gitlab'|null,
+ *   nowMs?: number,
+ *   repoRoot?: string,
+ *   resolveRepoSpecFn?: (opts: { repoRoot: string, vcs: 'gitlab'|'github' }) => string | undefined,
+ *   runJsonFn?: (bin: string, args: string[]) => Array | null
+ * }} [opts]
+ *   `repoRoot` defaults to `process.cwd()`. `resolveRepoSpecFn` is the
+ *   injectable seam for the `-R`/`--repo` host-pinning resolution (#872) —
+ *   defaults to the real `resolveRepoSpec` (shells out to `git remote
+ *   get-url`); tests inject a stub instead of shelling out. `runJsonFn` is
+ *   the injectable seam for the CLI runner — defaults to the real `runJson`
+ *   (shells out to `glab`/`gh`).
  * @returns {Promise<null | {criticalCount: number, highCount: number, staleCount: number, byLabel: Record<string, number>, total: number, vcs: string, limit: number}>}
  */
 export async function scanBacklog(opts = {}) {
@@ -149,7 +172,16 @@ export async function scanBacklog(opts = {}) {
 
   if (vcs !== 'github' && vcs !== 'gitlab') return null;
 
-  const cacheKey = JSON.stringify({ vcs, limit });
+  const repoRoot = typeof opts.repoRoot === 'string' ? opts.repoRoot : process.cwd();
+  const resolveRepoSpecFn =
+    typeof opts.resolveRepoSpecFn === 'function' ? opts.resolveRepoSpecFn : resolveRepoSpec;
+  const runJsonFn = typeof opts.runJsonFn === 'function' ? opts.runJsonFn : runJson;
+
+  // Resolve the -R/--repo host-pinning spec ONCE (#872), mirroring the
+  // #839 idiom in spiral-carryover.mjs / issue-close-strip-labels.mjs.
+  const spec = resolveRepoSpecFn({ repoRoot, vcs });
+
+  const cacheKey = JSON.stringify({ vcs, limit, spec });
   if (_cache.has(cacheKey)) return _cache.get(cacheKey);
 
   const bin = vcs === 'github' ? 'gh' : 'glab';
@@ -157,8 +189,9 @@ export async function scanBacklog(opts = {}) {
     vcs === 'github'
       ? ['issue', 'list', '--limit', String(limit), '--json', 'number,labels,updatedAt,state']
       : ['issue', 'list', '--per-page', String(limit), '--output', 'json'];
+  if (spec) args.push('-R', spec);
 
-  const issues = runJson(bin, args);
+  const issues = runJsonFn(bin, args);
   if (issues === null) {
     _cache.set(cacheKey, null);
     return null;

package/scripts/lib/blocked-commands-policy.mjs

@@ -0,0 +1,340 @@
+/**
+ * scripts/lib/blocked-commands-policy.mjs — policy-floor merge for the
+ * destructive-command guard (#972).
+ *
+ * Before #972 the guard's policy loader was first-hit-wins over
+ * [cwd, projectDir, pluginRoot]/.orchestrator/policy/blocked-commands.json.
+ * Consequence: an empty (or hostile) consumer policy in cwd SILENTLY disarmed
+ * the plugin's own policy — `{"version":1,"rules":[]}` switched the guard off.
+ *
+ * This module replaces first-hit-wins with a FLOOR/OVERLAY merge:
+ *   - FLOOR   = the plugin-root policy (the plugin's own blocklist).
+ *   - OVERLAY = the first existing policy from [cwd, projectDir] (a consumer
+ *               repo's local policy).
+ *   - The overlay can only ADD rules or ESCALATE severity — never remove a
+ *     floor rule, never downgrade a floor `block`, never swap a floor rule's
+ *     pattern/path-allowlist for its own (field-merge would be the backdoor).
+ *
+ * Invariant: merged.rules ⊇ floor.rules for EVERY overlay input (including
+ * `{}`, `{"rules":[]}`, malformed JSON, and a missing file) — every overlay
+ * failure mode fails TO THE FLOOR, not open.
+ *
+ * All exported functions are TOTAL: they never throw. The consuming hook keeps
+ * its documented `main().catch → exit 0` fail-open for internal errors, so any
+ * throw here would silently disarm the guard — totality is load-bearing.
+ */
+
+import { existsSync, promises as fsp } from 'node:fs';
+import path from 'node:path';
+
+const POLICY_REL = path.join('.orchestrator', 'policy', 'blocked-commands.json');
+
+/** Severity ordering for the escalate-only merge: warn < block. */
+const SEVERITY_RANK = { warn: 0, block: 1 };
+
+/** Module-level default per-path cache (each hook invocation is an isolated
+ * Node subprocess, so this is fresh per process — issue #250 contract). */
+const _defaultCache = new Map();
+
+// ---------------------------------------------------------------------------
+// Path resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the floor and overlay policy paths from the three injected roots.
+ *
+ * Roles are purely PATH-based (no schema marker): the plugin root supplies the
+ * floor; the first existing policy among [cwd, projectDir] is the overlay.
+ * When both roles resolve to the SAME file (the common case inside the plugin
+ * repo itself, where cwd == pluginRoot), callers must treat it as ONE policy
+ * (identity merge) — `loadEffectivePolicy` does exactly that.
+ *
+ * @param {{cwd?: string, projectDir?: string, pluginRoot?: string}} [roots]
+ * @returns {{floorPath: string|null, overlayPath: string|null}} existing paths only
+ */
+export function resolvePolicyPaths({ cwd, projectDir, pluginRoot } = {}) {
+  const candidate = (root) => {
+    if (typeof root !== 'string' || root.length === 0) return null;
+    try {
+      const p = path.join(root, POLICY_REL);
+      return existsSync(p) ? p : null;
+    } catch {
+      return null;
+    }
+  };
+
+  const floorPath = candidate(pluginRoot);
+
+  let overlayPath = null;
+  for (const root of [cwd, projectDir]) {
+    const p = candidate(root);
+    if (p) { overlayPath = p; break; }
+  }
+
+  return { floorPath, overlayPath };
+}
+
+// ---------------------------------------------------------------------------
+// Rule sanitation (per-file)
+// ---------------------------------------------------------------------------
+
+/**
+ * Sanitize one file's rules array: drop broken individual rules (missing
+ * string id/pattern/severity) and duplicate ids (first occurrence wins), each
+ * with a warning — never kill the whole list for one bad entry.
+ *
+ * Valid rules pass through UNCHANGED (extra fields like `path-allowlist` and
+ * `allow-override-flag` are preserved verbatim).
+ *
+ * @param {unknown} rules
+ * @param {string} label - 'floor' | 'overlay' | 'policy' (for warning text)
+ * @param {string[]} warnings - appended to in place
+ * @returns {object[]}
+ */
+function sanitizeRules(rules, label, warnings) {
+  const out = [];
+  const seen = new Set();
+  if (!Array.isArray(rules)) return out;
+
+  for (let i = 0; i < rules.length; i++) {
+    const rule = rules[i];
+    const broken =
+      rule === null ||
+      typeof rule !== 'object' ||
+      typeof rule.id !== 'string' || rule.id.length === 0 ||
+      typeof rule.pattern !== 'string' || rule.pattern.length === 0 ||
+      typeof rule.severity !== 'string';
+    if (broken) {
+      const ident = rule && typeof rule === 'object' && typeof rule.id === 'string'
+        ? `'${rule.id}'`
+        : `at index ${i}`;
+      warnings.push(`${label} rule ${ident} skipped (missing/invalid id, pattern, or severity)`);
+      continue;
+    }
+    if (seen.has(rule.id)) {
+      warnings.push(`${label} rule '${rule.id}' duplicated within one file — first occurrence wins`);
+      continue;
+    }
+    seen.add(rule.id);
+    out.push(rule);
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Merge
+// ---------------------------------------------------------------------------
+
+/**
+ * Merge a floor policy with an overlay policy — union by rule id, floor rules
+ * first, escalate-only semantics:
+ *
+ *   (a) overlay-only id                  → appended (additive).
+ *   (b) id collision, floor `block`      → the WHOLE floor rule wins (no field
+ *       merge — an overlay path-allowlist/pattern would be the backdoor);
+ *       overlay definition dropped + warning.
+ *   (c) id collision, floor `warn`       → max(floor, overlay) severity with
+ *       warn < block, on the FLOOR rule's fields; unknown/missing overlay
+ *       severity → floor wins + warning.
+ *   (d) duplicate ids WITHIN one file    → first occurrence wins + warning.
+ *   (e) broken individual rule           → skipped with warning, list survives.
+ *
+ * Total function: any non-policy input is treated as an empty rules list.
+ *
+ * @param {{rules?: unknown}|null|undefined} floor
+ * @param {{rules?: unknown}|null|undefined} overlay
+ * @returns {{rules: object[], warnings: string[]}}
+ */
+export function mergePolicies(floor, overlay) {
+  const warnings = [];
+  const floorRules = sanitizeRules(floor?.rules, 'floor', warnings);
+  const overlayRules = sanitizeRules(overlay?.rules, 'overlay', warnings);
+
+  const merged = [...floorRules];
+  const indexById = new Map(merged.map((r, i) => [r.id, i]));
+
+  for (const rule of overlayRules) {
+    const idx = indexById.get(rule.id);
+    if (idx === undefined) {
+      // (a) additive overlay-only rule
+      indexById.set(rule.id, merged.length);
+      merged.push(rule);
+      continue;
+    }
+
+    const floorRule = merged[idx];
+    if (floorRule.severity === 'block') {
+      // (b) floor block is immutable — whole floor rule wins
+      warnings.push(
+        `overlay rule '${rule.id}' shadowed by floor block rule — overlay definition ignored`
+      );
+      continue;
+    }
+
+    if (floorRule.severity === 'warn') {
+      // (c) escalate-only on the floor rule's fields.
+      // Object.hasOwn, not `in`: `in` walks the prototype chain, so an
+      // inherited key like severity:'toString' passed as "known" and silently
+      // swallowed the unknown-severity warning (W4 F4).
+      if (!Object.hasOwn(SEVERITY_RANK, rule.severity)) {
+        warnings.push(
+          `overlay rule '${rule.id}' has unknown severity '${rule.severity}' — floor severity kept`
+        );
+        continue;
+      }
+      if (SEVERITY_RANK[rule.severity] > SEVERITY_RANK[floorRule.severity]) {
+        merged[idx] = { ...floorRule, severity: rule.severity };
+      }
+      continue;
+    }
+
+    // Floor rule carries an unknown severity string — conservative: keep it.
+    warnings.push(
+      `overlay rule '${rule.id}' collides with floor rule of unknown severity ` +
+      `'${floorRule.severity}' — floor rule kept`
+    );
+  }
+
+  return { rules: merged, warnings };
+}
+
+// ---------------------------------------------------------------------------
+// Load (with per-path mtime cache)
+// ---------------------------------------------------------------------------
+
+/**
+ * Read + parse one policy file with a per-path mtime cache.
+ *
+ * @param {string|null} policyPath
+ * @param {Map<string, {mtimeMs: number, policy: object}>} cache
+ * @returns {Promise<{status: 'valid', policy: object}
+ *   | {status: 'invalid', reason: string}
+ *   | {status: 'missing'}>}
+ */
+async function readPolicyFile(policyPath, cache) {
+  if (!policyPath) return { status: 'missing' };
+
+  let mtimeMs;
+  try {
+    mtimeMs = (await fsp.stat(policyPath)).mtimeMs;
+    const cached = cache.get(policyPath);
+    if (cached && cached.mtimeMs === mtimeMs) {
+      return { status: 'valid', policy: cached.policy };
+    }
+  } catch {
+    // stat failure → fall through to an uncached read attempt (fail-safe;
+    // mirrors the pre-#972 loadPolicyCached contract).
+    mtimeMs = null;
+  }
+
+  let policy;
+  try {
+    policy = JSON.parse(await fsp.readFile(policyPath, 'utf8'));
+  } catch (err) {
+    if (err?.code === 'ENOENT') return { status: 'missing' };
+    return { status: 'invalid', reason: 'malformed (invalid JSON)' };
+  }
+  if (!policy || typeof policy !== 'object' || !Array.isArray(policy.rules)) {
+    return { status: 'invalid', reason: 'missing .rules array' };
+  }
+  if (mtimeMs !== null) cache.set(policyPath, { mtimeMs, policy });
+  return { status: 'valid', policy };
+}
+
+/**
+ * Load the EFFECTIVE policy: floor + overlay, merged escalate-only.
+ *
+ * Failure modes (all fail-to-floor, never fail-open where a floor exists):
+ *   - overlay malformed / missing .rules / EMPTY rules → floor alone + warning
+ *     (`rules: []` is explicitly a warning, not a legitimate empty policy —
+ *     an empty overlay must not disarm the floor).
+ *   - floor unavailable (plugin root unresolvable or file missing) → overlay
+ *     alone + warning.
+ *   - floor malformed + valid overlay → overlay alone + loud warning.
+ *   - both unavailable → `{ rules: null, warnings: [...] }` — the hook keeps
+ *     its documented fail-open + stderr warning for this case.
+ *   - floorPath === overlayPath (degenerate, e.g. cwd == pluginRoot) → the one
+ *     file IS the policy (identity merge; no shadow warnings against itself).
+ *
+ * Total function: never throws.
+ *
+ * @param {{cwd?: string, projectDir?: string, pluginRoot?: string,
+ *          cache?: Map<string, {mtimeMs: number, policy: object}>}} [opts]
+ * @returns {Promise<{rules: object[]|null, warnings: string[]}>}
+ */
+export async function loadEffectivePolicy({ cwd, projectDir, pluginRoot, cache = _defaultCache } = {}) {
+  const warnings = [];
+  try {
+    const { floorPath, overlayPath } = resolvePolicyPaths({ cwd, projectDir, pluginRoot });
+
+    // Degenerate case: both roles are the same file → ONE policy.
+    if (floorPath !== null && floorPath === overlayPath) {
+      const res = await readPolicyFile(floorPath, cache);
+      if (res.status === 'valid') {
+        return { rules: sanitizeRules(res.policy.rules, 'policy', warnings), warnings };
+      }
+      warnings.push(
+        res.status === 'invalid' && res.reason === 'missing .rules array'
+          ? 'policy file missing .rules array — skipping guard'
+          : 'policy file is malformed (invalid JSON) — skipping guard'
+      );
+      return { rules: null, warnings };
+    }
+
+    const floorRes = await readPolicyFile(floorPath, cache);
+    const overlayRes = await readPolicyFile(overlayPath, cache);
+
+    const floorValid = floorRes.status === 'valid';
+    const overlayValid = overlayRes.status === 'valid';
+    const overlayEmpty = overlayValid && overlayRes.policy.rules.length === 0;
+
+    if (floorValid && overlayValid && !overlayEmpty) {
+      const merge = mergePolicies(floorRes.policy, overlayRes.policy);
+      return { rules: merge.rules, warnings: [...warnings, ...merge.warnings] };
+    }
+
+    if (floorValid) {
+      // fail-to-floor: overlay missing is the normal no-overlay case (silent);
+      // overlay invalid or empty is a warning — it can never disarm the floor.
+      if (overlayRes.status === 'invalid') {
+        warnings.push(`overlay policy ignored (${overlayRes.reason}) — floor policy enforced alone`);
+      } else if (overlayEmpty) {
+        warnings.push(
+          'overlay policy ignored (empty rules array — an empty overlay cannot disarm the floor) ' +
+          '— floor policy enforced alone'
+        );
+      }
+      return { rules: sanitizeRules(floorRes.policy.rules, 'floor', warnings), warnings };
+    }
+
+    if (overlayValid) {
+      warnings.push(
+        floorRes.status === 'invalid'
+          ? `floor policy is ${floorRes.reason} — enforcing overlay policy alone`
+          : 'floor policy unavailable (plugin root unresolvable or file missing) — enforcing overlay policy alone'
+      );
+      if (overlayEmpty) {
+        warnings.push('overlay policy has an empty rules array — guard has no rules to enforce');
+      }
+      return { rules: sanitizeRules(overlayRes.policy.rules, 'overlay', warnings), warnings };
+    }
+
+    // Neither side usable.
+    if (floorRes.status === 'missing' && overlayRes.status === 'missing') {
+      warnings.push(
+        'policy file not found (.orchestrator/policy/blocked-commands.json) — skipping guard'
+      );
+    } else {
+      const describe = (res) =>
+        res.status === 'missing' ? 'missing' : res.reason;
+      warnings.push(
+        `no usable policy (floor: ${describe(floorRes)}; overlay: ${describe(overlayRes)}) — skipping guard`
+      );
+    }
+    return { rules: null, warnings };
+  } catch (err) {
+    // Totality backstop — never throw into the hook's fail-open catch.
+    warnings.push(`policy load failed unexpectedly (${err?.message || err}) — skipping guard`);
+    return { rules: null, warnings };
+  }
+}

package/scripts/lib/ci-status-banner.mjs

@@ -12,6 +12,7 @@
 
 import { execFile as _execFile } from 'node:child_process';
 import { promisify } from 'node:util';
+import { resolveRepoSpec, resolveRepoHost } from './vcs-repo-spec.mjs';
 
 const execFileAsync = promisify(_execFile);
 
@@ -77,14 +78,19 @@ async function getHeadSha(repoRoot, deps = {}) {
 /**
  * Get GitLab project ID via glab.
  *
+ * #872: pins to `deps.repoSpec` via `-R` when resolved (host-pinning —
+ * `glab repo view` otherwise falls back to the ambient `GITLAB_HOST`).
+ *
  * @param {string} repoRoot
- * @param {{ execFile?: Function, timeoutMs?: number }} deps
+ * @param {{ execFile?: Function, timeoutMs?: number, repoSpec?: string }} deps
  * @returns {Promise<number>}
  */
 async function getGlabProjectId(repoRoot, deps = {}) {
+  const args = ['repo', 'view', '--output', 'json'];
+  if (deps.repoSpec) args.push('-R', deps.repoSpec);
   const result = await execWithTimeout(
     'glab',
-    ['repo', 'view', '--output', 'json'],
+    args,
     { cwd: repoRoot, timeoutMs: deps.timeoutMs ?? DEFAULT_TIMEOUT_MS, execFile: deps.execFile },
   );
   const parsed = JSON.parse(result.stdout);
@@ -94,15 +100,21 @@ async function getGlabProjectId(repoRoot, deps = {}) {
 /**
  * Run `glab api <path>` and return parsed JSON.
  *
+ * #872: `glab api` has no repo/`-R` concept — it accepts only `--hostname`
+ * to pin which GitLab instance the request targets. Pinned via
+ * `deps.repoHost` when resolved.
+ *
  * @param {string} apiPath
  * @param {string} repoRoot
- * @param {{ execFile?: Function, timeoutMs?: number }} deps
+ * @param {{ execFile?: Function, timeoutMs?: number, repoHost?: string }} deps
  * @returns {Promise<unknown>}
  */
 async function glabApi(apiPath, repoRoot, deps = {}) {
+  const args = ['api', apiPath];
+  if (deps.repoHost) args.push('--hostname', deps.repoHost);
   const result = await execWithTimeout(
     'glab',
-    ['api', apiPath],
+    args,
     { cwd: repoRoot, timeoutMs: deps.timeoutMs ?? DEFAULT_TIMEOUT_MS, execFile: deps.execFile },
   );
   return JSON.parse(result.stdout);
@@ -111,15 +123,20 @@ async function glabApi(apiPath, repoRoot, deps = {}) {
 /**
  * Run `gh api <path>` and return parsed JSON.
  *
+ * #872: `gh api` has no repo/`-R` concept either — pinned via `--hostname`
+ * from `deps.repoHost` when resolved.
+ *
  * @param {string} apiPath
  * @param {string} repoRoot
- * @param {{ execFile?: Function, timeoutMs?: number }} deps
+ * @param {{ execFile?: Function, timeoutMs?: number, repoHost?: string }} deps
  * @returns {Promise<unknown>}
  */
 async function ghApi(apiPath, repoRoot, deps = {}) {
+  const args = ['api', apiPath];
+  if (deps.repoHost) args.push('--hostname', deps.repoHost);
   const result = await execWithTimeout(
     'gh',
-    ['api', apiPath],
+    args,
     { cwd: repoRoot, timeoutMs: deps.timeoutMs ?? DEFAULT_TIMEOUT_MS, execFile: deps.execFile },
   );
   return JSON.parse(result.stdout);
@@ -144,7 +161,7 @@ function ageDaysFrom(isoDate, now) {
  *
  * @param {string} repoRoot
  * @param {number} now
- * @param {{ execFile?: Function, timeoutMs?: number }} deps
+ * @param {{ execFile?: Function, timeoutMs?: number, repoSpec?: string, repoHost?: string }} deps
  * @returns {Promise<object|null>}
  */
 async function checkGitlab(repoRoot, now, deps = {}) {
@@ -176,9 +193,32 @@ async function checkGitlab(repoRoot, now, deps = {}) {
   const pipelineStatus = currentPipeline.status;
 
   if (pipelineStatus === 'success') {
+    // A pipeline reports `success` even when jobs marked `allow_failure: true`
+    // failed. Those jobs are invisible at the pipeline level, so a permanently
+    // red allow-failure job (observed: 4/4 consecutive pipelines) would never
+    // surface. Inspect the job list to name them. Non-fatal: a failed job query
+    // still yields a plain green result.
+    let allowFailureJobs;
+    try {
+      const jobs = await glabApi(
+        `projects/${projectId}/pipelines/${currentPipeline.id}/jobs`,
+        repoRoot,
+        deps,
+      );
+      if (Array.isArray(jobs)) {
+        const softFailed = jobs
+          .filter((j) => j.status === 'failed' && j.allow_failure === true)
+          .map((j) => j.name);
+        if (softFailed.length > 0) allowFailureJobs = softFailed;
+      }
+    } catch {
+      // Non-fatal — report green without the allow-failure detail.
+    }
+
     return {
       status: 'green',
       ok: true,
+      ...(allowFailureJobs ? { allowFailureJobs } : {}),
       details: {
         currentPipelineId: currentPipeline.id,
         cliUsed: 'glab',
@@ -268,15 +308,21 @@ async function checkGitlab(repoRoot, now, deps = {}) {
 /**
  * GitHub CI status check (v1 — red/green only; lastGreen not implemented).
  *
+ * #872: pins the `gh repo view` lookup to `deps.repoSpec` via `-R` when
+ * resolved (host-pinning — `gh repo view` otherwise falls back to the
+ * ambient `GH_HOST`).
+ *
  * @param {string} repoRoot
- * @param {{ execFile?: Function, timeoutMs?: number }} deps
+ * @param {{ execFile?: Function, timeoutMs?: number, repoSpec?: string, repoHost?: string }} deps
  * @returns {Promise<object|null>}
  */
 async function checkGithub(repoRoot, deps = {}) {
   // Resolve owner/repo from gh to keep the API path generic.
+  const repoViewArgs = ['repo', 'view', '--json', 'nameWithOwner'];
+  if (deps.repoSpec) repoViewArgs.push('-R', deps.repoSpec);
   const repoViewResult = await execWithTimeout(
     'gh',
-    ['repo', 'view', '--json', 'nameWithOwner'],
+    repoViewArgs,
     { cwd: repoRoot, timeoutMs: deps.timeoutMs ?? DEFAULT_TIMEOUT_MS, execFile: deps.execFile },
   );
   const { nameWithOwner } = JSON.parse(repoViewResult.stdout);
@@ -354,7 +400,12 @@ async function checkGithub(repoRoot, deps = {}) {
  * }} opts
  * @param {{
  *   execFile?: Function,
- * }} deps  Dependency-injection seam for testing.
+ *   resolveRepoSpec?: (opts: { repoRoot: string, vcs: 'gitlab'|'github' }) => string|undefined,
+ *   resolveRepoHost?: (opts: { repoRoot: string, vcs: 'gitlab'|'github' }) => string|undefined,
+ * }} deps  Dependency-injection seam for testing. `resolveRepoSpec`/
+ *   `resolveRepoHost` default to the real `vcs-repo-spec.mjs` exports
+ *   (#872 host-pinning — see that module for the `-R` vs `--hostname`
+ *   contract).
  * @returns {Promise<null | {
  *   status: 'green'|'red'|'unknown',
  *   ok: boolean,
@@ -381,6 +432,9 @@ export async function checkCiStatus(opts = {}, deps = {}) {
     ? promisify(deps.execFile)
     : execFileAsync;
 
+  const resolveRepoSpecDep = deps.resolveRepoSpec ?? resolveRepoSpec;
+  const resolveRepoHostDep = deps.resolveRepoHost ?? resolveRepoHost;
+
   const depsWithExec = { execFile: execFileDep, timeoutMs };
 
   try {
@@ -395,13 +449,22 @@ export async function checkCiStatus(opts = {}, deps = {}) {
       }
     }
 
+    // Step 1b (#872): resolve the -R/--hostname host-pinning spec ONCE per
+    // checkCiStatus call — a bare glab/gh spawn falls back to the ambient
+    // GITLAB_HOST/GH_HOST env var, which can silently target the wrong
+    // instance on a multi-instance host. `cwd: repoRoot` alone does not fix
+    // this (ambient env still wins over cwd).
+    const repoSpec = resolveRepoSpecDep({ repoRoot, vcs });
+    const repoHost = resolveRepoHostDep({ repoRoot, vcs });
+    const depsWithPinning = { ...depsWithExec, repoSpec, repoHost };
+
     // Step 2: dispatch to VCS-specific implementation.
     if (vcs === 'gitlab') {
-      return await checkGitlab(repoRoot, now, depsWithExec);
+      return await checkGitlab(repoRoot, now, depsWithPinning);
     }
 
     if (vcs === 'github') {
-      return await checkGithub(repoRoot, depsWithExec);
+      return await checkGithub(repoRoot, depsWithPinning);
     }
 
     // Unknown VCS value — silent no-op.