run402 4.38.1 → 4.39.0

package/git-remote-run402.mjs

@@ -68,12 +68,29 @@
  *     no per-ref object selection, so one batch = one full restore. That is a
  *     superset of what git asked for (git writes the refs itself from `list`),
  *     never a subset — but it is not incremental.
- *   - `push` never changes the vault's HEAD target; the SDK carries it forward.
- *     A fresh vault defaults to `refs/heads/main`, so a first push of some
- *     other branch leaves HEAD naming a ref that does not exist yet. Use
- *     `run402 gitvault push`, which sets the HEAD target from the local HEAD.
- *   - `option dry-run` is `unsupported`: this helper cannot rehearse a
- *     publication, and reporting a fake success would be worse than refusing.
+ *   - `push` REPAIRS a DANGLING vault HEAD and otherwise never moves it
+ *     (kychee-com/run402#568). A fresh vault defaults its HEAD symref to
+ *     `refs/heads/main`; before this fix, a first push of any OTHER branch
+ *     left that symref naming a ref that would never exist, and the first
+ *     `git clone` warned "remote HEAD refers to nonexistent ref" and checked
+ *     out an EMPTY tree — publishing landed, but nothing was reachable from
+ *     it. Now: when the vault's current HEAD target is unset, or is a
+ *     symref naming a ref this push's own batch does not leave present, the
+ *     helper points it at one of the branches THIS push is publishing — the
+ *     local repository's own HEAD branch when it is among them, else the
+ *     first branch in the batch — and prints a one-line stderr note saying
+ *     which and why (see `chooseGitvaultHeadTargetForPush`). A HEALTHY HEAD
+ *     (one that already names a ref this push leaves present) is NEVER
+ *     touched — push moving history never means push moving HEAD.
+ *   - `option dry-run true` (kychee-com/run402#565) runs the REAL local
+ *     pipeline — pack building, encryption sizing, via `vault.planPush` — and
+ *     reports the per-ref `ok` lines a real push would, plus a stderr summary
+ *     (objects, encrypted bytes, refs, the generation it would admit as,
+ *     whether allocation would be needed). It never uploads or admits, and a
+ *     push-to-create dry run never allocates. Still honestly refuses
+ *     anything git's own dry-run negotiation would also refuse (e.g. a
+ *     non-fast-forward update) — reporting a fake `ok` would be worse than
+ *     refusing, which is why this was `unsupported` until it could be real.
  *   - `fetch` and `push` REQUIRE the `GIT_DIR` git sets when it drives a
  *     helper against a repository, so running this binary by hand from a shell
  *     is refused rather than silently pointed at the current directory. Only
@@ -82,6 +99,7 @@
  */
 
 import { createInterface } from "node:readline";
+import { pathToFileURL } from "node:url";
 import { getSdk } from "./lib/sdk.mjs";
 import { resolveWalletCore, enforceWalletExistsCore, WalletSelectionError } from "./lib/wallet-context.mjs";
 import { gitvaultRemoteAddressForm, gitvaultSlugReleasedInfo, parseGitvaultRemoteUrl } from "#sdk";
@@ -214,6 +232,62 @@ function parsePushSpec(spec) {
   return { src: body.slice(0, colon), dst: body.slice(colon + 1), force: forced };
 }
 
+/**
+ * Decide whether THIS push must repair a DANGLING vault HEAD, and to what
+ * (kychee-com/run402#568 — the first-clone empty-tree hazard). The rule:
+ *
+ *   WHEN the vault's current materialized HEAD target is absent, OR is a
+ *   symref naming a ref this push's own batch does not leave present, set
+ *   `head_target` to one of the branches THIS push is publishing — this
+ *   repository's own HEAD branch when it is among them, else the first
+ *   branch in the batch (git's own order) — and say which, and why, in a
+ *   one-line note. No silent magic.
+ *
+ *   WHEN HEAD is already set and healthy (a symref naming a ref this push
+ *   leaves present, or a detached target), it is NEVER touched — push
+ *   moving history never means push moving HEAD. That stays the documented
+ *   rule (`vault.push`'s own `head_target ?? base.head_target` carry-forward
+ *   already guarantees this at the SDK layer; this function just decides
+ *   WHEN to override that default).
+ *
+ * Pure — no I/O, no git, no network — so it is unit-testable directly.
+ * `updates` is this push's own ref-transaction updates (`{ ref, new_oid }`,
+ * `new_oid: null` for a deletion); `baseRefs`/`baseHeadTarget` are what the
+ * vault materialized BEFORE this push; `localHeadRef` is this repository's
+ * own HEAD branch (`refs/heads/<name>`), or `null` when detached/unknown.
+ *
+ * Returns `{ head_target: undefined }` (never publish an override — the SDK
+ * carries the base forward) when HEAD needs no repair, or when this batch
+ * has no branch update to repair it WITH (a tags-only or deletion-only
+ * batch cannot fix a dangling HEAD by itself).
+ */
+export function chooseGitvaultHeadTargetForPush({ baseHeadTarget, baseRefs, updates, localHeadRef }) {
+  const postPushRefs = { ...(baseRefs ?? {}) };
+  for (const u of updates) {
+    if (u.new_oid === null) delete postPushRefs[u.ref];
+    else postPushRefs[u.ref] = u.new_oid;
+  }
+
+  const dangling =
+    !baseHeadTarget ||
+    (baseHeadTarget.kind === "symref" && !Object.prototype.hasOwnProperty.call(postPushRefs, baseHeadTarget.ref));
+  if (!dangling) return { head_target: undefined, note: null };
+
+  const pushedBranches = updates.filter((u) => u.new_oid !== null && u.ref.startsWith("refs/heads/")).map((u) => u.ref);
+  if (pushedBranches.length === 0) return { head_target: undefined, note: null };
+
+  const localIsPushed = Boolean(localHeadRef) && pushedBranches.includes(localHeadRef);
+  const chosen = localIsPushed ? localHeadRef : pushedBranches[0];
+  const why = localIsPushed
+    ? "this repository's own HEAD branch"
+    : pushedBranches.length > 1
+      ? `the first of ${pushedBranches.length} branches pushed in this batch`
+      : "the branch this push publishes";
+  const priorState = baseHeadTarget ? `dangling (named '${baseHeadTarget.ref}', which this push does not publish)` : "unset";
+  const note = `vault HEAD was ${priorState} — setting it to '${chosen}' (${why}). A healthy HEAD is never moved by push.`;
+  return { head_target: { kind: "symref", ref: chosen }, note };
+}
+
 async function main(argv) {
   const address = resolveRemoteAddress(argv);
   if (!address) {
@@ -230,6 +304,11 @@ async function main(argv) {
   const addressForm = gitvaultRemoteAddressForm(address);
   const target = { project_id: address.project_id, org_id: address.org_id };
   let verbosity = 1;
+  // kychee-com/run402#565: `option dry-run true` used to be honestly
+  // `unsupported` (this helper could not rehearse a publication, and
+  // reporting a fake success would be worse than refusing). It now IS
+  // real — see `handleOption`'s `dry-run` case and `runPush` below.
+  let dryRun = false;
 
   /**
    * The repository git invoked us for, resolved once and PROVEN.
@@ -245,6 +324,16 @@ async function main(argv) {
     return resolvedRepo.repo_dir;
   }
 
+  /** This repository's own HEAD branch (`refs/heads/<name>`), or `null` when detached, unborn, or unreadable — never a failure by itself. */
+  async function localHeadBranchRef(repoDir) {
+    try {
+      const out = (await hardenedGit(repoDir, ["symbolic-ref", "--quiet", "HEAD"])).text().trim();
+      return out.length > 0 ? out : null;
+    } catch {
+      return null;
+    }
+  }
+
   /**
    * What to tell a human when we refuse. `git clone` is the case that used to
    * fail; naming the working alternative beats a bare error.
@@ -380,6 +469,52 @@ async function main(argv) {
           ? null
           : (await hardenedGit(repoDir, ["rev-parse", "--verify", "--end-of-options", spec.src])).text().trim());
       }
+
+      if (dryRun) {
+        // kychee-com/run402#565: READ-ONLY resolution — `openVault`, never
+        // `openOrCreateVault` — so a push-to-create dry run allocates
+        // NOTHING. An unresolved vault means there is nothing to preview a
+        // push against yet (no repo_id ⇒ no encryption key ⇒ sizing is
+        // genuinely unknowable, not merely unreported); still report success
+        // per-ref, since a real push here WOULD succeed (it would allocate
+        // first) — only the sizing is unavailable.
+        let vault;
+        try {
+          vault = await openVault(repoDir);
+        } catch (err) {
+          if (!isVaultNotFound(err)) throw err;
+          note("dry-run: no vault allocated for this project yet — a real push would allocate one (push-to-create) before publishing; object/byte sizing is not knowable until then");
+          for (const spec of specs) out(`ok ${spec.dst}`);
+          endBlock();
+          return 0;
+        }
+        const base = await vault.materialize();
+        const updates = [];
+        for (const spec of specs) {
+          const expectedOld = base.refs?.[spec.dst] ?? null;
+          updates.push({
+            ref: spec.dst,
+            expected_old_oid: expectedOld,
+            new_oid: newOids.get(spec),
+            force: spec.force && expectedOld !== null,
+          });
+        }
+        // Same evaluation, pack building, and sealing/encryption a real push
+        // runs — stops before the two network mutations (upload, admit). A
+        // refusal here (non-fast-forward, tag immutability, ...) throws the
+        // SAME way a real push's would, caught below and reported as
+        // `error`, never a fake `ok`.
+        const plan = await vault.planPush({ transaction: { updates } });
+        note(
+          `dry-run: would publish generation ${plan.would_admit_generation} (${plan.would_admit_generation_decimal}, ${plan.form}) — ` +
+          `${plan.object_count} object(s), ${plan.encrypted_bytes} encrypted byte(s) (${plan.raw_bytes} raw), ` +
+          `${Object.keys(plan.refs).length} ref(s); no allocation needed`,
+        );
+        for (const spec of specs) out(`ok ${spec.dst}`);
+        endBlock();
+        return 0;
+      }
+
       const vault = await openOrCreateVault(repoDir);
       const base = await vault.materialize();
       const updates = [];
@@ -394,10 +529,26 @@ async function main(argv) {
           force: spec.force && expectedOld !== null,
         });
       }
+      // Repair a DANGLING HEAD from this batch's own branches (#568) — see
+      // `chooseGitvaultHeadTargetForPush`'s own doc comment for the exact
+      // rule. `localHeadRef` is read from THIS repository (never cwd, same
+      // fail-closed resolution as everything else in this function).
+      const headFix = chooseGitvaultHeadTargetForPush({
+        baseHeadTarget: base.head_target,
+        baseRefs: base.refs,
+        updates,
+        localHeadRef: await localHeadBranchRef(repoDir),
+      });
+      if (headFix.note) note(headFix.note);
       // ONE transaction for the whole batch: the SDK evaluates fast-forward,
       // tag immutability, protocol-ref refusal and retention roots, builds the
-      // packs, and publishes — all or nothing.
-      const published = await vault.push({ transaction: { updates } });
+      // packs, and publishes — all or nothing. `head_target` is included ONLY
+      // when a repair is called for; omitted, `vault.push` carries the base
+      // forward unchanged — a healthy HEAD is never moved.
+      const published = await vault.push({
+        transaction: { updates },
+        ...(headFix.head_target ? { head_target: headFix.head_target } : {}),
+      });
       if (verbosity >= 1) note(`published generation ${published.generation} (${published.form})`);
       for (const spec of specs) out(`ok ${spec.dst}`);
     } catch (err) {
@@ -429,8 +580,17 @@ async function main(argv) {
         // whichever way git asked for it.
         out("ok");
         return;
+      case "dry-run":
+        // kychee-com/run402#565: a REAL dry run — `runPush` runs the actual
+        // local pipeline (pack building, encryption sizing) and stops before
+        // the two network mutations. `value` is git's own boolean spelling
+        // ("true"/"false"); anything else is refused rather than guessed.
+        if (value === "true") { dryRun = true; out("ok"); return; }
+        if (value === "false") { dryRun = false; out("ok"); return; }
+        out("unsupported");
+        return;
       default:
-        // Includes dry-run, object-format, depth, cloning, check-connectivity,
+        // Includes object-format, depth, cloning, check-connectivity,
         // followtags, pushcert: honestly unsupported rather than acknowledged.
         out("unsupported");
     }
@@ -501,10 +661,23 @@ async function main(argv) {
   }
 }
 
+// Only run the protocol loop when git (or a human) actually invoked this file
+// as a binary — never on `import` (tests import `chooseGitvaultHeadTargetForPush`
+// directly; without this guard that import would block on stdin forever).
+const invokedDirectly = (() => {
+  try {
+    return process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+  } catch {
+    return false;
+  }
+})();
+
 // Never `process.exit()` mid-stream: that can truncate a pending stdout write
 // on a pipe, which git reads as a protocol violation. Set the code and let Node
 // flush and exit on its own.
-main(process.argv.slice(2)).then(
-  (code) => { process.exitCode = code; },
-  (err) => { note(describeError(err)); process.exitCode = 1; },
-);
+if (invokedDirectly) {
+  main(process.argv.slice(2)).then(
+    (code) => { process.exitCode = code; },
+    (err) => { note(describeError(err)); process.exitCode = 1; },
+  );
+}

package/lib/command-manifest.mjs

@@ -433,7 +433,11 @@ export const COMMAND_MANIFEST = [
   { path: ["service", "health"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
   { path: ["cache", "inspect"], positionals: [p("url")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["https://example.com/"] },
   { path: ["cache", "invalidate"], positionals: [p("url", { required: false })], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["--all", "--host", "example.com"] },
-  { path: ["doctor"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["--no-scan"], runStyle: "merged" },
+  // projectScoped (kychee-com/run402#566): --project targets the gitvault
+  // check only (see doctor.mjs's own HELP) — every other check stays
+  // wallet/machine-wide, but the gate's contract is "accepts --project
+  // without rejecting it," which this satisfies.
+  { path: ["doctor"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["--no-scan"], runStyle: "merged" },
   { path: ["webhook-secret", "rotate"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
   { path: ["logs"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["--request-id", "req_gate123"], runStyle: "merged" },
 ];

package/lib/doctor.mjs

@@ -24,11 +24,56 @@ import { doctorUpdateCheck } from "./update-check.mjs";
 import { buildBuzzDoctorReport, parseBuzzDoctorArgs } from "./buzz-doctor.mjs";
 import { queueBuzzDoctorTelemetry } from "./diagnostic-telemetry.mjs";
 import { fail } from "./sdk-errors.mjs";
+import { normalizeArgv, assertKnownFlags, flagValue } from "./argparse.mjs";
+
+/** Value-taking flags (kychee-com/run402#566 — the flag set doctor actually parses; anything else is BAD_USAGE via assertKnownFlags, never silently ignored). */
+const DOCTOR_VALUE_FLAGS = ["--scan-dir", "--buzz-agent", "--project", "--only"];
+
+/**
+ * The stable, complete registry of ordinary-mode check names (kychee-com/run402#566,
+ * the remaining half). One entry per `checks.push({ name: ... })` call below,
+ * in the order each check normally runs. This is the ONE place `--only`
+ * validates its argument against and the ONE place its help text is derived
+ * from, so a check can never be selectable-but-undocumented or
+ * documented-but-unselectable.
+ *
+ * Deliberately excludes buzz mode's own check names (`session_shell`,
+ * `node_runtime`, …) — buzz mode is a wholly separate report shape that
+ * returns before this array is ever consulted; see the `--only`/`--buzz`
+ * mutual-exclusion check in `run()`.
+ */
+const DOCTOR_CHECK_NAMES = [
+  "config_dir",
+  "cli_update",
+  "allowance",
+  "projects",
+  "api_reachable",
+  "tier",
+  "operator_health",
+  "runtime_staleness",
+  "gitvault",
+  "source_scan",
+];
+
+/** Every value passed to a repeatable flag, in argv order (mirrors the pattern in buzz-notifications.mjs). */
+function collectRepeatableFlag(args, flag) {
+  const values = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] !== flag) continue;
+    if (i + 1 >= args.length || (typeof args[i + 1] === "string" && args[i + 1].startsWith("--"))) {
+      fail({ code: "BAD_FLAG", message: `${flag} requires a value`, details: { flag } });
+    }
+    values.push(args[i + 1]);
+    i += 1;
+  }
+  return values;
+}
 
 const HELP = `run402 doctor — Health and config diagnostics
 
 Usage:
-  run402 doctor [--verbose] [--refresh] [--no-scan] [--scan-dir <D>]
+  run402 doctor [--verbose] [--refresh] [--no-scan] [--scan-dir <D>] [--project <id>]
+                [--only <check> ...]
   run402 --wallet <profile> doctor --buzz --buzz-agent <npub-or-hex>
 
 Output:
@@ -38,12 +83,40 @@ Output:
 
 Options:
   --verbose      Include extra detail (timing, error messages)
-  --refresh      Wait for a bounded live npm version check for the run402 CLI
-  --no-scan      Skip the source-tree scan (config / health checks only)
+  --refresh      Force a bounded live npm version check for the run402 CLI, even
+                 if the cache is still within its 24h TTL. The cache self-heals
+                 without this flag too: a MISSING or EXPIRED cache gets exactly
+                 one bounded live attempt automatically on a plain \`doctor\` call.
+                 A failed live check (offline) falls back to the last known-good
+                 value, clearly labeled with its age — never a silent weeks-old
+                 "latest" (kychee-com/run402#561). cli_update.value.cache always
+                 reports fresh/age_ms/refresh_attempted/refresh_failed.
+  --no-scan      Skip the source-tree scan (config / health checks only). Implied
+                 by any --only that omits source_scan.
   --scan-dir D   Scan a custom directory instead of \`<cwd>/src\`
+  --project <id> Target THIS project's gitvault check instead of the repo-standing
+                 default (the 4.38.0 pin / run402 remote / RUN402_PROJECT_ID / active
+                 project, in that order — see \`gitvault-target.mjs\`). Scoped to the
+                 gitvault check only; every other check is wallet/machine-wide, not
+                 per-project, and is unaffected by this flag. Composes with --only.
+  --only <check> Run ONLY the named check (repeatable — pass it more than once
+                 to run several). Every other check, INCLUDING the monorepo
+                 source-tree scan, is suppressed rather than merely hidden: a
+                 skipped check's network/filesystem work never runs at all, so
+                 \`doctor --only gitvault\` costs one gitvault read, not a
+                 config/tier/operator/scan sweep. An unknown check name is
+                 BAD_USAGE listing the valid names below. Not used with --buzz
+                 (buzz mode is its own separate, always-complete check set).
   --buzz         Run only the zero-mutation Buzz setup preflight
   --buzz-agent P Bind Buzz mode to the intended public agent npub or hex key
 
+--only check names (ordinary mode; see "Checks performed" below for what each
+one reports):
+  ${DOCTOR_CHECK_NAMES.join(", ")}
+
+Any flag not listed above is rejected (BAD_USAGE / UNKNOWN_FLAG), never
+silently ignored.
+
 Telemetry:
   Buzz preflight sends only anonymous allowlisted start/pass/block counters.
   No identity, wallet, relay, domain, path, command output, or installation id
@@ -109,16 +182,57 @@ function describeCheckFailure(label, err) {
 }
 
 export async function run(sub, args = []) {
-  const all = [sub, ...args].filter(Boolean);
+  const all = normalizeArgv([sub, ...args].filter(Boolean));
   if (all.includes("--help") || all.includes("-h")) {
     console.log(HELP);
     return;
   }
+  // kychee-com/run402#566 (--project half): doctor used to accept ANY flag
+  // silently — an unrecognized one (a typo, or --project before this fix)
+  // was simply never looked at. Any flag doctor actually parses is listed
+  // here; anything else is now a structured BAD_USAGE/UNKNOWN_FLAG rejection
+  // instead of quietly doing nothing.
+  assertKnownFlags(all, ["--verbose", "--refresh", "--no-scan", "--buzz", ...DOCTOR_VALUE_FLAGS], DOCTOR_VALUE_FLAGS);
   const verbose = all.includes("--verbose");
   const refresh = all.includes("--refresh");
   const skipScan = all.includes("--no-scan");
   const scanDirArgIdx = all.indexOf("--scan-dir");
   const scanDirOverride = scanDirArgIdx >= 0 ? all[scanDirArgIdx + 1] : null;
+  // Scoped to the gitvault check (see HELP): every other check is
+  // wallet/machine-wide, not per-project.
+  const projectOverride = flagValue(all, "--project");
+
+  // kychee-com/run402#566 (the remaining half): --only <check>, repeatable.
+  // Validated against the stable registry ABOVE the buzz early-return, so an
+  // unknown name is BAD_USAGE regardless of which mode was also requested —
+  // the same "every accepted flag must work or BAD_USAGE" bar #569 named for
+  // doctor's own --human bug.
+  const onlyChecks = collectRepeatableFlag(all, "--only");
+  for (const name of onlyChecks) {
+    if (!DOCTOR_CHECK_NAMES.includes(name)) {
+      fail({
+        code: "BAD_USAGE",
+        message: `Unknown doctor check: '${name}'.`,
+        hint: `Valid check names: ${DOCTOR_CHECK_NAMES.join(", ")}.`,
+        details: { check: name, known_checks: DOCTOR_CHECK_NAMES },
+      });
+    }
+  }
+  // Buzz mode is a wholly separate, always-complete report shape — an --only
+  // that named ordinary-mode checks would be silently ignored under --buzz,
+  // exactly the class of bug #569 flagged for --human. Reject the
+  // combination instead.
+  if (onlyChecks.length > 0 && all.includes("--buzz")) {
+    fail({
+      code: "BAD_USAGE",
+      message: "--only is not used with --buzz — buzz mode runs its own fixed, always-complete check set.",
+      hint: "Drop --buzz to scope the ordinary check set with --only, or drop --only to run every buzz check.",
+      details: { only: onlyChecks },
+    });
+  }
+  const only = new Set(onlyChecks);
+  /** `true` when `name` should run — every check when --only was not passed, otherwise exactly the named ones. */
+  const wanted = (name) => only.size === 0 || only.has(name);
 
   const buzzArgs = parseBuzzDoctorArgs(all);
   if (buzzArgs.error) fail(buzzArgs.error);
@@ -135,7 +249,7 @@ export async function run(sub, args = []) {
   const CONFIG_DIR = configDir();
 
   // 1. Config directory.
-  try {
+  if (wanted("config_dir")) try {
     if (existsSync(CONFIG_DIR) && statSync(CONFIG_DIR).isDirectory()) {
       checks.push({ name: "config_dir", status: "ok", value: CONFIG_DIR });
     } else {
@@ -156,7 +270,7 @@ export async function run(sub, args = []) {
 
   // 1b. CLI version/update state. This is advisory: stale or unknown version
   // state should help the user, not hide the rest of doctor.
-  try {
+  if (wanted("cli_update")) try {
     checks.push(await doctorUpdateCheck({ refresh }));
   } catch (err) {
     checks.push({
@@ -168,7 +282,7 @@ export async function run(sub, args = []) {
 
   // 2. Allowance.
   let allowanceConfigured = false;
-  try {
+  if (wanted("allowance")) try {
     const allowance = readAllowance();
     if (allowance) {
       allowanceConfigured = true;
@@ -203,7 +317,7 @@ export async function run(sub, args = []) {
   // service_key) that `run402 projects provision` writes. An empty store is
   // normal for fresh installs that haven't provisioned a project yet, so
   // report informationally as `ok` rather than warning.
-  try {
+  if (wanted("projects")) try {
     const keystore = loadKeyStore();
     const projectCount = Object.keys(keystore?.projects ?? {}).length;
     checks.push({
@@ -228,7 +342,7 @@ export async function run(sub, args = []) {
   }
 
   // 4. API base reachability.
-  try {
+  if (wanted("api_reachable")) try {
     const sdk = getSdk();
     // Use the service.status endpoint (read-only, unauthenticated).
     const t0 = Date.now();
@@ -249,7 +363,7 @@ export async function run(sub, args = []) {
   }
 
   // 5. Active tier.
-  try {
+  if (wanted("tier")) try {
     const sdk = getSdk();
     const tier = await sdk.tier.status();
     const tierName = tier?.tier ?? null;
@@ -292,7 +406,12 @@ export async function run(sub, args = []) {
   }
 
   // 6. Operator health snapshot (v1.55 + v1.56 verification attempt detail).
-  try {
+  // Both checks below ride the SAME operator-status read (runtime_staleness
+  // reuses the response operator_health already pulled), so the whole block
+  // is gated on wanting EITHER — --only runtime_staleness alone still needs
+  // this read, but --only-ing neither skips it entirely, same "don't do the work of a
+  // check nobody asked for" discipline the rest of --only follows.
+  if (wanted("operator_health") || wanted("runtime_staleness")) try {
     const sdk = getSdk();
     const status = await sdk.admin.getOperatorStatus();
     const gaps = [];
@@ -334,15 +453,17 @@ export async function run(sub, args = []) {
         gaps.push(`${item.kind}: ${item.detail}`);
       }
     }
-    if (gaps.length > 0) {
-      checks.push({
-        name: "operator_health",
-        status: "warning",
-        value: { gaps },
-        hint: "Address the above gaps; they're what 'run402 notifications' is designed to surface.",
-      });
-    } else {
-      checks.push({ name: "operator_health", status: "ok" });
+    if (wanted("operator_health")) {
+      if (gaps.length > 0) {
+        checks.push({
+          name: "operator_health",
+          status: "warning",
+          value: { gaps },
+          hint: "Address the above gaps; they're what 'run402 notifications' is designed to surface.",
+        });
+      } else {
+        checks.push({ name: "operator_health", status: "ok" });
+      }
     }
 
     // 6b. Function runtime staleness (v1.69, capability
@@ -352,45 +473,47 @@ export async function run(sub, args = []) {
     // NOT refresh it (apply's release diff keys on the source code_hash, not
     // the wrapper). Read-only signal; refreshing is strictly opt-in. Reuses
     // the operator status fetched above to avoid a second round-trip.
-    const runtime = status.runtime;
-    if (runtime && typeof runtime.stale_function_count === "number") {
-      if (runtime.stale_function_count > 0) {
-        checks.push({
-          name: "runtime_staleness",
-          status: "warning",
-          value: {
-            stale_function_count: runtime.stale_function_count,
-            stale_functions: runtime.stale_functions ?? [],
-          },
-          hint: `${runtime.stale_function_count} function(s) are running an older platform runtime. Run 'run402 functions rebuild --all' to refresh (re-bundles from your stored source; no source change).`,
-        });
+    if (wanted("runtime_staleness")) {
+      const runtime = status.runtime;
+      if (runtime && typeof runtime.stale_function_count === "number") {
+        if (runtime.stale_function_count > 0) {
+          checks.push({
+            name: "runtime_staleness",
+            status: "warning",
+            value: {
+              stale_function_count: runtime.stale_function_count,
+              stale_functions: runtime.stale_functions ?? [],
+            },
+            hint: `${runtime.stale_function_count} function(s) are running an older platform runtime. Run 'run402 functions rebuild --all' to refresh (re-bundles from your stored source; no source change).`,
+          });
+        } else {
+          checks.push({
+            name: "runtime_staleness",
+            status: "ok",
+            value: { stale_function_count: 0 },
+          });
+        }
       } else {
+        // Gateway older than v1.69 doesn't surface the runtime block.
         checks.push({
           name: "runtime_staleness",
-          status: "ok",
-          value: { stale_function_count: 0 },
+          status: "skipped",
+          ...(verbose && { hint: "operator status has no 'runtime' block; requires v1.69+ gateway." }),
         });
       }
-    } else {
-      // Gateway older than v1.69 doesn't surface the runtime block.
-      checks.push({
-        name: "runtime_staleness",
-        status: "skipped",
-        ...(verbose && { hint: "operator status has no 'runtime' block; requires v1.69+ gateway." }),
-      });
     }
   } catch (err) {
     // Operator status endpoint may not be reachable if the operator-binding
     // substrate isn't deployed yet on the target API. Don't fail the whole
     // doctor over it — emit as a soft warning. The runtime-staleness check
     // rides on the same fetch, so skip it for the same reason.
-    checks.push({
+    if (wanted("operator_health")) checks.push({
       name: "operator_health",
       status: "skipped",
       message: describeCheckFailure("operator status check", err),
       ...(verbose && { hint: "GET /agent/v1/operator/status not reachable; requires v1.55+ gateway." }),
     });
-    checks.push({
+    if (wanted("runtime_staleness")) checks.push({
       name: "runtime_staleness",
       status: "skipped",
       message: describeCheckFailure("operator status check", err),
@@ -410,14 +533,16 @@ export async function run(sub, args = []) {
   // deployed is a first-class shape (protocol D183), so its mere absence of a
   // deploy raises nothing.
   //
-  // TARGETING (repo-first-onramp follow-up, kychee-com/run402#559d): when
-  // cwd is a repository with its own pinned repo id or run402/origin remote,
-  // doctor now checks THAT vault, not the profile's active project — the
-  // same pin > remote > RUN402_PROJECT_ID env > active-project order every
-  // other gitvault verb follows (`gitvault-target.mjs`). Doctor has no
-  // `--project`/`--repo` flag of its own, so there is no explicit tier here.
-  {
-    const target = await resolveGitvaultTarget({ repoDir: process.cwd() });
+  // TARGETING (repo-first-onramp follow-up, kychee-com/run402#559d, extended
+  // by kychee-com/run402#566's --project half): when cwd is a repository
+  // with its own pinned repo id or run402/origin remote, doctor checks THAT
+  // vault, not the profile's active project — the same pin > remote >
+  // RUN402_PROJECT_ID env > active-project order every other gitvault verb
+  // follows (`gitvault-target.mjs`). An explicit `--project <id>` outranks
+  // all of that (the resolver's own top tier), same as every other gitvault
+  // verb's `--project`.
+  if (wanted("gitvault")) {
+    const target = await resolveGitvaultTarget({ repoDir: process.cwd(), explicitProjectId: projectOverride ?? undefined });
     const projectId = target.project_id ?? null;
     const repoId = target.repo_id ?? null;
     if (!projectId && !repoId) {
@@ -458,7 +583,11 @@ export async function run(sub, args = []) {
         if (gv.pending_overrides > 0) {
           gaps.push(`${gv.pending_overrides} unvaulted-override journal(s) are still open — run 'run402 gitvault push' to drain them`);
         }
-        if (gv.remote && !gv.remote.matches) {
+        // `matches` is a TRI-STATE (kychee-com/run402#562): `false` alone is
+        // a real mismatch. `null` (a slug-form remote not yet resolved on
+        // this machine) is not evidence of anything wrong — `!gv.remote.matches`
+        // used to treat null the same as false and would have warned here.
+        if (gv.remote && gv.remote.matches === false) {
           gaps.push(`the '${gv.remote.name}' git remote points at a different project than ${value.project_id} (${gv.remote.url})`);
         }
         // Echoed exactly as the SDK reported them — including the
@@ -488,8 +617,10 @@ export async function run(sub, args = []) {
   // SDK names, state-changing GETs, auth.* in prerendered pages, and
   // direct mutation of internal.sessions.authz_version. Hits with severity
   // `error` block deploy (`run402 deploy` wraps doctor and respects exit
-  // code). Skipped via --no-scan when the user wants config-only checks.
-  if (!skipScan) {
+  // code). Skipped via --no-scan when the user wants config-only checks, and
+  // by any --only that omits it (kychee-com/run402#566 — this is the check
+  // that used to bury the gitvault diagnosis under ~1,800 monorepo findings).
+  if (!skipScan && wanted("source_scan")) {
     try {
       const scanRoot = scanDirOverride ?? resolveScanRoot(process.cwd());
       const findings = scanSourceTree(scanRoot, { cwd: process.cwd() });