session-orchestrator 3.19.0 → 3.21.0

package/scripts/lib/memory-cleanup-stamp.mjs

@@ -1,20 +1,41 @@
 /**
- * memory-cleanup-stamp.mjs — Pure helper: stamp `memory_cleanup_at` on a
- * session record when `/memory-cleanup` ran this session.
+ * memory-cleanup-stamp.mjs — stamp `memory_cleanup_at` on a session record when
+ * `/memory-cleanup` ran this session, and DERIVE that fact from the event log
+ * instead of from coordinator recall.
  *
  * Issue #699 fix: a healthy no-op run of `/memory-cleanup` previously left
  * `memory_cleanup_at` unstamped, so `auto-dream.mjs` `readDreamSignals`
  * never advanced `lastCleanupAt` and `shouldDispatchAutoDream` kept firing a
- * false nudge. This helper stamps the field unconditionally whenever the
- * cleanup ran — including a healthy no-op where no memory files were mutated.
+ * false nudge. `stampMemoryCleanup()` stamps the field unconditionally whenever
+ * the cleanup ran — including a healthy no-op where no memory files were mutated.
+ *
+ * #699 follow-up (Disziplin statt Mechanik): the `ranCleanup` boolean itself used
+ * to come from the coordinator-LLM remembering a prose step at session-end. It
+ * measurably failed — a `/memory-cleanup` ran on 2026-08-14 and all three session
+ * records of that day read `memory_cleanup_at: null`, so the session-start banner
+ * reported "29 days ago" while the operator's own notes said 3. Since then
+ * `/memory-cleanup` emits `orchestrator.memory.cleanup_completed` and
+ * `deriveMemoryCleanupSignal()` reads that event back out of
+ * `.orchestrator/metrics/events.jsonl`, which is what `scripts/emit-session.mjs`
+ * calls at write time. Nothing depends on recall any more.
  *
  * Design constraints:
- *   - Pure function — no I/O, no side-effects.
- *   - No-throw — invalid inputs return the record unchanged (defensive).
- *   - Testable seam — the Quality wave (Q2) unit-tests this function directly.
- *   - No external deps — Node 20+ stdlib only (none needed here).
+ *   - `stampMemoryCleanup()` stays pure — no I/O, no side-effects.
+ *   - No-throw — invalid inputs / unreadable-or-corrupt event log return the
+ *     "no cleanup" answer rather than blocking a session close.
+ *   - Testable seam — both functions are unit-tested directly.
+ *   - No external deps — Node stdlib only.
  */
 
+import { readFileSync } from 'node:fs';
+
+/**
+ * Event `/memory-cleanup` emits when a run completes (any mode, any outcome —
+ * including a healthy no-op). Emitted via `scripts/emit-event.mjs` → the
+ * canonical `emitEvent()` path; see `skills/memory-cleanup/SKILL.md` § Output.
+ */
+export const MEMORY_CLEANUP_EVENT = 'orchestrator.memory.cleanup_completed';
+
 /**
  * Stamp `memory_cleanup_at` on a session record when `/memory-cleanup` ran.
  *
@@ -54,3 +75,106 @@ export function stampMemoryCleanup(record, { ranCleanup, completedAt } = {}) {
   // Return a shallow clone with the stamp applied — never mutate the input.
   return { ...record, memory_cleanup_at: completedAt };
 }
+
+/**
+ * Derive "did `/memory-cleanup` run in THIS session?" from the event log.
+ *
+ * Reads `eventsFile` and looks for `orchestrator.memory.cleanup_completed`
+ * records that fall inside the session's own `[startedAt, completedAt]` window.
+ * This is the mechanical replacement for the coordinator-supplied boolean.
+ *
+ * Matching rule (two clauses, both mechanical):
+ *   1. the event's `timestamp` lies within `[startedAt, completedAt]` inclusive;
+ *   2. IF the event carries a non-empty `semantic_session_id`, it must equal
+ *      `sessionId` (sessions.jsonl `session_id` is the SEMANTIC id — the UUID
+ *      `session_id` some events carry lives in a different id space and is
+ *      deliberately NOT used for matching).
+ *
+ * Named ceiling (deliberate simplification): an event with NO attribution is
+ * claimed on the window alone, so two parallel sessions in one repo with
+ * overlapping windows both derive `ranCleanup: true`. The consequence is a
+ * marginally generous cadence marker on the peer's record — never a MISSED
+ * cleanup, which is the failure this whole path exists to prevent. Revisit
+ * trigger: if per-session cleanup accounting is ever needed, attach
+ * `semantic_session_id` to the emitted event and clause 2 makes it exact.
+ * Scan cost is a single linear pass over `events.jsonl` (~23k lines,
+ * size-rotated at SessionStart by `events-rotation.mjs`) — revisit if rotation
+ * is ever removed.
+ *
+ * No-throw: a missing, unreadable, or partly-corrupt event log yields
+ * `{ ranCleanup: false, ... }`. A session close must never fail because
+ * telemetry is damaged.
+ *
+ * @param {object} opts
+ * @param {string} opts.eventsFile  Absolute or CWD-relative path to events.jsonl.
+ * @param {string} [opts.sessionId] The record's `session_id` (semantic form).
+ * @param {string} opts.startedAt   Session `started_at` (ISO-8601).
+ * @param {string} opts.completedAt Session `completed_at` (ISO-8601).
+ * @returns {{ranCleanup: boolean, at: string|null, matches: number}}
+ *   `at` is the LATEST matching event timestamp (null when none matched);
+ *   `matches` is how many events matched (a run can emit more than one).
+ */
+export function deriveMemoryCleanupSignal({
+  eventsFile,
+  sessionId,
+  startedAt,
+  completedAt,
+} = {}) {
+  const none = { ranCleanup: false, at: null, matches: 0 };
+
+  if (typeof eventsFile !== 'string' || eventsFile.length === 0) return none;
+
+  const startMs = Date.parse(startedAt);
+  const endMs = Date.parse(completedAt);
+  if (!Number.isFinite(startMs) || !Number.isFinite(endMs) || endMs < startMs) {
+    return none;
+  }
+
+  let raw;
+  try {
+    raw = readFileSync(eventsFile, 'utf8');
+  } catch {
+    // Missing / unreadable event log — no signal, never an error.
+    return none;
+  }
+
+  const wantSession = typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : null;
+  let matches = 0;
+  let latestMs = -Infinity;
+  let latestTs = null;
+
+  for (const line of raw.split('\n')) {
+    // Cheap substring prefilter before the JSON.parse cost.
+    if (line.length === 0 || !line.includes(MEMORY_CLEANUP_EVENT)) continue;
+
+    let rec;
+    try {
+      rec = JSON.parse(line);
+    } catch {
+      continue; // corrupt line — skip, best-effort reader
+    }
+    if (rec === null || typeof rec !== 'object' || Array.isArray(rec)) continue;
+    if (rec.event !== MEMORY_CLEANUP_EVENT) continue;
+
+    const tsMs = Date.parse(rec.timestamp);
+    if (!Number.isFinite(tsMs) || tsMs < startMs || tsMs > endMs) continue;
+
+    const semantic = rec.semantic_session_id;
+    if (
+      wantSession !== null &&
+      typeof semantic === 'string' &&
+      semantic.length > 0 &&
+      semantic !== wantSession
+    ) {
+      continue; // attributed to a DIFFERENT session — not ours
+    }
+
+    matches += 1;
+    if (tsMs > latestMs) {
+      latestMs = tsMs;
+      latestTs = rec.timestamp;
+    }
+  }
+
+  return { ranCleanup: matches > 0, at: latestTs, matches };
+}

package/scripts/lib/mirror-issues-banner.mjs

@@ -0,0 +1,266 @@
+/**
+ * mirror-issues-banner.mjs — the mirror blind spot (#1022 follow-up)
+ *
+ * `skills/gitlab-ops/SKILL.md` § VCS Auto-Detection picks EXACTLY ONE platform
+ * via if/else. In a repo whose `origin` is GitLab and whose `github` remote is
+ * a public mirror, no code path ever reads issues from the mirror — so issues
+ * filed by external reporters against the mirror are structurally invisible to
+ * every session. This probe is the counter-measure: it asks the OTHER side.
+ *
+ * The VCS family is therefore HARD-PINNED to `'github'`, never auto-detected.
+ * Auto-detection is the defect this module exists to compensate for; deriving
+ * the family here would reproduce it.
+ *
+ * No new Session Config key by design. `resolveRepoSpec({ vcs:'github' })`
+ * derives the `gh -R` spec straight from `git remote` (its `REMOTE_PREFERENCE`
+ * tries the remote literally named `github` first, and its `WRONG_FAMILY_HOST`
+ * guard discards a cross-family match). That makes the probe SELF-DISABLING: a
+ * repo without a GitHub mirror resolves to `undefined` → `null` → no spawn, no
+ * network call. A config key would be a second SSOT drifting against
+ * `git remote`.
+ *
+ * Plain-JS — no Zod dependency. Never throws.
+ *
+ * Mirrors the Phase 4 banner contract documented in
+ * `scripts/lib/loop-readiness-banner.mjs:23-26`: a single `checkXxx()` entry
+ * point returning `null` or `{ severity, message, ... }`.
+ *
+ * Cross-references:
+ *  - `scripts/lib/ci-status-banner.mjs` — the sibling project-facing probe
+ *    (whose `null`-collapsing this module deliberately does NOT copy, see below).
+ *  - `scripts/lib/reconcile-nudge-banner.mjs:183-186` — the same
+ *    absence-preserving discipline applied to a count.
+ *  - `skills/session-start/SKILL.md` Phase 4 — banner render site.
+ */
+
+import { execFile as _execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { resolveRepoSpec as _resolveRepoSpec } from './vcs-repo-spec.mjs';
+
+const execFileAsync = promisify(_execFile);
+
+/** Default timeout in ms for the `gh` invocation. Mirrors `ci-status-banner.mjs:20`. */
+export const DEFAULT_TIMEOUT_MS = 8000;
+
+/** Default `--limit` passed to `gh issue list`. */
+export const DEFAULT_LIMIT = 20;
+
+/**
+ * The VCS family this probe queries. Deliberately a module constant, not a
+ * parameter: querying the auto-detected platform would make this probe a no-op
+ * in exactly the repos it exists for.
+ */
+const MIRROR_VCS = 'github';
+
+/** How many issue numbers the banner message names before summarising. */
+const MESSAGE_ISSUE_CAP = 5;
+
+/**
+ * Closed set of `degraded` reasons. A degraded result means "the mirror was
+ * NOT successfully read" — never "the mirror is clean".
+ *
+ * `query-failed` is the residual bucket for a `gh` that ran and exited
+ * non-zero for a reason that is neither missing-CLI, timeout, nor auth
+ * (network down, repo renamed, rate limit). It is a deliberate fifth member
+ * beyond the four originally specified: folding those into `parse-error`
+ * would mislabel a network failure as malformed output, reintroducing the
+ * dishonest-state class this module was built to remove.
+ *
+ * @type {readonly ['cli-missing','timeout','parse-error','auth-error','query-failed']}
+ */
+export const DEGRADED_REASONS = Object.freeze([
+  'cli-missing',
+  'timeout',
+  'parse-error',
+  'auth-error',
+  'query-failed',
+]);
+
+/**
+ * Run `cmd` with a timeout race. Mirrors `ci-status-banner.mjs:30-38`.
+ *
+ * The timer is cleared and `unref`ed so a fast success does not hold the event
+ * loop open for the full budget (`.claude/rules/testing.md` § Async & Timeout
+ * Patterns). KNOWN LIMIT, inherited from the shared pattern and NOT fixed
+ * here: losing the race abandons the `gh` child process rather than killing
+ * it — a hung `gh` is left orphaned.
+ *
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {{ cwd?: string, timeoutMs?: number, execFile?: Function }} [opts]
+ * @returns {Promise<{ stdout?: string, stderr?: string }>}
+ */
+async function execWithTimeout(cmd, args, opts = {}) {
+  const { cwd, timeoutMs = DEFAULT_TIMEOUT_MS, execFile = execFileAsync } = opts;
+  /** @type {NodeJS.Timeout | undefined} */
+  let timer;
+  try {
+    return await Promise.race([
+      execFile(cmd, args, { cwd, env: process.env }),
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error('timeout')), timeoutMs);
+        if (typeof timer.unref === 'function') timer.unref();
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/**
+ * Map a failed `gh` invocation onto a {@link DEGRADED_REASONS} member.
+ *
+ * @param {unknown} err
+ * @returns {'cli-missing'|'timeout'|'auth-error'|'query-failed'}
+ */
+function classifyFailure(err) {
+  const code = err && typeof err === 'object' ? /** @type {any} */ (err).code : undefined;
+  if (code === 'ENOENT') return 'cli-missing';
+
+  const message = err instanceof Error ? err.message : String(err ?? '');
+  if (message === 'timeout') return 'timeout';
+
+  const stderr = err && typeof err === 'object' ? String(/** @type {any} */ (err).stderr ?? '') : '';
+  const haystack = `${message}\n${stderr}`.toLowerCase();
+  if (
+    haystack.includes('gh auth login') ||
+    haystack.includes('not logged in') ||
+    haystack.includes('authentication') ||
+    haystack.includes('http 401') ||
+    haystack.includes('http 403')
+  ) {
+    return 'auth-error';
+  }
+  return 'query-failed';
+}
+
+/**
+ * Build the degraded result. Distinct from `null` on purpose: `null` in the
+ * banner contract reads as "all clear", which a failed query has NOT
+ * established.
+ *
+ * @param {string} repoSpec
+ * @param {string} reason
+ * @returns {{ severity: 'warn', message: string, repoSpec: string, degraded: string }}
+ */
+function degradedResult(repoSpec, reason) {
+  return {
+    severity: 'warn',
+    message:
+      `⚠ mirror-issues: Mirror ${repoSpec} konnte nicht abgefragt werden (${reason}) ` +
+      `— Zustand unbekannt, nicht "sauber".`,
+    repoSpec,
+    degraded: reason,
+  };
+}
+
+/**
+ * Render the found-issues banner message, naming issue numbers up to
+ * {@link MESSAGE_ISSUE_CAP} and summarising any remainder.
+ *
+ * @param {string} repoSpec
+ * @param {Array<{ number: number, title: string }>} issues
+ * @returns {string}
+ */
+function formatMessage(repoSpec, issues) {
+  const named = issues.slice(0, MESSAGE_ISSUE_CAP).map((i) => `#${i.number}`).join(', ');
+  const rest = issues.length - Math.min(issues.length, MESSAGE_ISSUE_CAP);
+  const tail = rest > 0 ? ` (+${rest} weitere)` : '';
+  const plural = issues.length === 1 ? 'offenes Issue' : 'offene Issues';
+  return (
+    `⚠ mirror-issues: ${issues.length} ${plural} im Mirror ${repoSpec}: ${named}${tail} ` +
+    `— kein anderer Codepfad dieser Session liest sie.`
+  );
+}
+
+/**
+ * Check the GitHub mirror for open issues and produce a session-start banner.
+ *
+ * Return contract — three states, not two:
+ *  - `null` when the mirror remote does not resolve (repo genuinely has no
+ *    mirror; NO subprocess is spawned) or when the query SUCCEEDED and found
+ *    zero open issues (measured and clean).
+ *  - `{ severity:'warn', message, count, repoSpec, issues }` when N > 0.
+ *  - `{ severity:'warn', message, repoSpec, degraded }` when the query did not
+ *    succeed. `degraded` is present ONLY in this case, so its absence proves
+ *    the mirror was actually read — the distinction `ci-status-banner.mjs`
+ *    collapses (CLI-missing, bad JSON and no-remote all return `null` there,
+ *    which is why the mirror gap went unseen for months).
+ *
+ * Never throws.
+ *
+ * @param {{ repoRoot?: string, timeoutMs?: number, limit?: number }} [opts]
+ * @param {{ execFile?: Function, resolveRepoSpec?: Function }} [deps] DI for tests only.
+ * @returns {Promise<null | { severity: 'warn', message: string, repoSpec: string, count?: number, issues?: Array<{number:number,title:string}>, degraded?: string }>}
+ */
+export async function checkMirrorIssues(opts = {}, deps = {}) {
+  try {
+    const { repoRoot, timeoutMs = DEFAULT_TIMEOUT_MS, limit = DEFAULT_LIMIT } = opts ?? {};
+    if (!repoRoot || typeof repoRoot !== 'string') return null;
+
+    const { execFile = execFileAsync, resolveRepoSpec = _resolveRepoSpec } = deps ?? {};
+
+    // Step 1 — resolve the mirror spec from `git remote`. `undefined` here is
+    // the self-disabling path: no mirror, no spawn, no network cost.
+    let repoSpec;
+    try {
+      repoSpec = resolveRepoSpec({ repoRoot, vcs: MIRROR_VCS });
+    } catch {
+      return null;
+    }
+    if (!repoSpec || typeof repoSpec !== 'string') return null;
+
+    // Step 2 — query. Args array, never a shell string.
+    let stdout;
+    try {
+      const result = await execWithTimeout(
+        'gh',
+        [
+          'issue',
+          'list',
+          '-R',
+          repoSpec,
+          '--state',
+          'open',
+          '--limit',
+          String(limit),
+          '--json',
+          'number,title',
+        ],
+        { cwd: repoRoot, timeoutMs, execFile },
+      );
+      stdout = String(result?.stdout ?? '');
+    } catch (err) {
+      return degradedResult(repoSpec, classifyFailure(err));
+    }
+
+    // Step 3 — parse. A CLI that exited 0 with unusable output is degraded,
+    // NOT clean.
+    let issues;
+    try {
+      const parsed = JSON.parse(stdout);
+      if (!Array.isArray(parsed)) return degradedResult(repoSpec, 'parse-error');
+      issues = parsed
+        .filter((entry) => entry && typeof entry === 'object' && Number.isFinite(Number(entry.number)))
+        .map((entry) => ({ number: Number(entry.number), title: String(entry.title ?? '') }));
+    } catch {
+      return degradedResult(repoSpec, 'parse-error');
+    }
+
+    // Step 4 — measured and clean.
+    if (issues.length === 0) return null;
+
+    return {
+      severity: 'warn',
+      message: formatMessage(repoSpec, issues),
+      count: issues.length,
+      repoSpec,
+      issues,
+    };
+  } catch {
+    // Defensive catch-all: a banner must never break session-start.
+    return null;
+  }
+}
+
+export default checkMirrorIssues;

package/scripts/lib/named-vault-resolver.mjs

@@ -16,6 +16,29 @@
  * IO is fully injectable (existsSync, realpathSync, env, gitRemote) so every
  * branch is unit-testable without touching disk or git.
  *
+ * ── Remote resolution (#1039) ────────────────────────────────────────────────
+ *
+ * The default `gitRemote` reads the repo's remote through the shared core in
+ * `vcs-repo-spec.mjs` ({@link resolvePreferredRemote}), VCS-LESS. Two properties
+ * of that call are load-bearing here and must not be "tidied":
+ *
+ *   1. **`vcs` is deliberately omitted.** This module needs a URL, not a
+ *      platform family, and the vcs-less preference order is `origin` first.
+ *      That order is what keeps the derived slug STABLE: in a repo carrying both
+ *      `origin` (→ `<group>/<repo>`) and `gitlab`/`github` mirrors under other
+ *      namespaces, a `gitlab`-first order would re-namespace — i.e. silently
+ *      RENAME — every vault note already written under the origin namespace.
+ *   2. **Absence and query-failure are kept apart.** The former
+ *      `git remote get-url origin` implementation returned `''` for *both* "no
+ *      remote configured" and "git blew up / this is not a repo", and a falsy
+ *      URL skips the walk-up entirely. The vault then resolved to the
+ *      single-vault fallback with no trace of why — one `source:'fallback'`
+ *      label covering a benign repo state and a broken measurement. The
+ *      fallback result now carries an optional `remoteError` (a
+ *      `REMOTE_RESOLUTION_REASONS` value) so the two are separable BY VALUE, and
+ *      only a query failure ({@link isQueryFailure}) WARNs — an absence is
+ *      normal and stays silent.
+ *
  * ── Exports ──────────────────────────────────────────────────────────────────
  *
  *   parseNamedVaults(ownerConfig)
@@ -28,7 +51,7 @@
 
 import { join, dirname } from 'node:path';
 import { existsSync as nodeExistsSync, realpathSync as nodeRealpathSync } from 'node:fs';
-import { spawnSync } from 'node:child_process';
+import { resolvePreferredRemote, isQueryFailure } from './vcs-repo-spec.mjs';
 
 // ---------------------------------------------------------------------------
 // Internal helpers
@@ -289,12 +312,31 @@ export function findRepoRoot(cwd = process.cwd(), { existsSync = nodeExistsSync,
  * `gitRemote(repoRoot)` is called ONLY in the walk-up path — injecting a
  * stub that throws proves the explicit path never calls it.
  *
+ * `gitRemote` keeps its `(repoRoot) => string` contract verbatim; the optional
+ * second argument is an OUT-parameter the default implementation uses to report
+ * WHY it returned `''`. A one-arg stub ignores it and classifies as
+ * `'no-remotes'` on `''` / `'git-error'` on a throw — so every pre-existing
+ * injection still works unchanged.
+ *
+ * `gitRun` is injected into the DEFAULT `gitRemote` only, and is ignored when
+ * `gitRemote` is supplied (the caller has replaced the thing that would use it).
+ * It exists so the default remote-resolution path — preference order, reason
+ * propagation — is testable at all; a `gitRemote` stub answers that question
+ * before the code under test runs and can only ever confirm itself.
+ *
+ * `remoteError` is present ONLY on a `source:'fallback'` result that was reached
+ * because the remote query produced nothing; it is absent when the fallback was
+ * reached for any other reason (no vaults configured, no repo root, the repo IS
+ * a vault, no org-prefix match). Additive — pre-#1039 readers see the identical
+ * four fields.
+ *
  * @param {{
  *   vaultName?: string|null,
  *   cwd?: string,
  *   ownerConfig?: object,
  *   env?: Record<string, string|undefined>,
- *   gitRemote?: (repoRoot: string) => string,
+ *   gitRemote?: (repoRoot: string, out?: {reason?: string}) => string,
+ *   gitRun?: (args: string[]) => {ok: boolean, stdout: string, stderr: string, status?: number, code?: string},
  *   existsSync?: Function,
  *   realpathSync?: Function,
  * }} [opts]
@@ -302,7 +344,8 @@ export function findRepoRoot(cwd = process.cwd(), { existsSync = nodeExistsSync,
  *   root: string|null,
  *   suffix: string,
  *   name: string|null,
- *   source: 'explicit'|'walkup'|'fallback'
+ *   source: 'explicit'|'walkup'|'fallback',
+ *   remoteError?: string
  * }}
  */
 export function resolveNamedVault({
@@ -310,11 +353,14 @@ export function resolveNamedVault({
   cwd = process.cwd(),
   ownerConfig,
   env = process.env,
-  gitRemote = _defaultGitRemote,
+  gitRemote,
+  gitRun,
   existsSync = nodeExistsSync,
   realpathSync = nodeRealpathSync,
 } = {}) {
   const vaults = parseNamedVaults(ownerConfig);
+  const readRemote =
+    typeof gitRemote === 'function' ? gitRemote : (root, out) => _defaultGitRemote(root, out, gitRun);
 
   // ── Path 1: explicit vault-name ──────────────────────────────────────────
   const trimmedName = typeof vaultName === 'string' ? vaultName.trim() : '';
@@ -330,18 +376,39 @@ export function resolveNamedVault({
   }
 
   // ── Path 2: walk-up org-prefix match ────────────────────────────────────
+  /** @type {string|undefined} — set ONLY when the remote query is why we fall through */
+  let remoteError;
+
   if (vaults.length > 0) {
     const repoRoot = findRepoRoot(cwd, { existsSync, realpathSync });
     if (repoRoot !== null) {
-      // Get the git remote for origin
+      // Resolve the repo's preferred remote (vcs-less → origin-first; see the
+      // module docblock for why that order must not move).
+      /** @type {{reason?: string, stderr?: string}} */
+      const remoteOut = {};
       let remoteUrl;
       try {
-        remoteUrl = gitRemote(repoRoot);
-      } catch {
+        remoteUrl = readRemote(repoRoot, remoteOut);
+      } catch (err) {
+        // A throwing gitRemote could not answer the question — that is a query
+        // failure, never "this repo has no remote".
         remoteUrl = '';
+        remoteOut.reason = 'git-error';
+        remoteOut.stderr = err instanceof Error ? err.message : String(err);
       }
 
-      if (remoteUrl) {
+      if (!remoteUrl) {
+        // Falsy URL: keep the REASON instead of collapsing it into a bare
+        // `source:'fallback'`. A one-arg stub that reported nothing means the
+        // benign "no remote configured" case.
+        remoteError = remoteOut.reason ?? 'no-remotes';
+        if (isQueryFailure(remoteError)) {
+          const detail = remoteOut.stderr ? `: ${String(remoteOut.stderr).trim()}` : '';
+          process.stderr.write(
+            `WARN named-vault-resolver: could not read the git remote of "${repoRoot}" (${remoteError})${detail}; falling back to the single-vault default\n`,
+          );
+        }
+      } else {
         // Derive org/repo from the remote URL (strip suffix/.git/scheme)
         const repoSlug = _deriveSlugFromRemote(remoteUrl);
 
@@ -366,11 +433,14 @@ export function resolveNamedVault({
   }
 
   // ── Path 3: single-vault fallback ────────────────────────────────────────
+  // `remoteError` is spread in only when set, so a fallback reached for any
+  // other reason keeps the exact pre-#1039 four-field shape.
   return {
     root: null,
     suffix: _resolveEnvSuffix(env) ?? DEFAULT_SUFFIX,
     name: null,
     source: 'fallback',
+    ...(remoteError === undefined ? {} : { remoteError }),
   };
 }
 
@@ -420,14 +490,33 @@ function _deriveSlugFromRemote(url) {
 }
 
 /**
- * Default gitRemote implementation: runs `git -C <repoRoot> remote get-url origin`.
+ * Default gitRemote implementation (#1039).
+ *
+ * Delegates to the shared {@link resolvePreferredRemote} core VCS-LESS, which
+ * makes this resolver work in the repos the old hard-coded
+ * `git remote get-url origin` was blind in — a repo whose remotes are named
+ * `gitlab`/`github`, a fork whose sole remote is `upstream`. The vcs-less
+ * preference order still tries `origin` FIRST, so the slug derived for a repo
+ * that has an `origin` is byte-identical to the pre-#1039 value.
+ *
+ * Return type stays `string` (the `gitRemote` DI contract depends on it). The
+ * failure reason travels through the optional `out` OUT-parameter instead:
+ * folding it into the return value would have meant changing that contract for
+ * every injected stub.
+ *
  * @param {string} repoRoot
- * @returns {string}
+ * @param {{reason?: string, stderr?: string}} [out] — populated with the
+ *   {@link REMOTE_RESOLUTION_REASONS} reason when the resolution failed
+ * @param {Function} [gitRun] — injectable git runner; `undefined` uses the real one
+ * @returns {string} the remote URL, or `''` when none resolved
  */
-function _defaultGitRemote(repoRoot) {
-  const res = spawnSync('git', ['-C', repoRoot, 'remote', 'get-url', 'origin'], {
-    encoding: 'utf8',
-  });
-  if (res.status !== 0) return '';
-  return res.stdout.trim();
+function _defaultGitRemote(repoRoot, out, gitRun) {
+  // `vcs` deliberately omitted — see the module docblock (origin-first order).
+  const resolved = resolvePreferredRemote({ repoRoot, gitRun });
+  if (resolved.ok) return resolved.url;
+  if (isPlainObject(out)) {
+    out.reason = resolved.reason;
+    if (resolved.stderr) out.stderr = resolved.stderr;
+  }
+  return '';
 }

package/scripts/lib/peer-cards/schema.mjs

@@ -6,8 +6,12 @@
  * YAML frontmatter on read and before write.
  *
  * Design notes:
- *   - Follows the `mission-status-schema.mjs` convention (pure regex/checks)
- *     rather than `skills/vault-sync/validator.mjs` (zod). The repo root has
+ *   - Pure regex/checks rather than `skills/vault-sync/validator.mjs` (zod).
+ *     (This line used to cite `scripts/lib/mission-status-schema.mjs` as the
+ *     exemplar for that convention; that module was deleted on 2026-08-15 for
+ *     having zero production callers while three prose sites promised it ran.
+ *     The convention below stands on its own reason, stated next.)
+ *     The repo root has
  *     no `zod` dependency — only `skills/vault-sync/` does, scoped to that
  *     skill's own `node_modules`. Keeping this validator dependency-free lets
  *     callers from anywhere under `scripts/lib/` use it without extra setup.