run402 4.61.0 → 4.62.0

package/cli.mjs

@@ -526,18 +526,23 @@ switch (cmd) {
     // cli-conventions gate keeps them in lockstep), so no second list.
     const { COMMAND_MANIFEST, SKIPPED_FAMILIES } = await import("./lib/command-manifest.mjs");
     const { closestWord } = await import("./lib/argparse.mjs");
+    const { describeRejectedValue } = await import("./core-dist/redact.js");
     const families = new Set([
       ...COMMAND_MANIFEST.map((entry) => entry.path[0]),
       ...Object.keys(SKIPPED_FAMILIES),
     ]);
     const closest = typeof cmd === "string" ? closestWord(cmd, [...families]) : null;
+    // `cmd` is the first bare positional — could be anything a script passes
+    // by mistake (kychee-com/run402-private#640 is the demonstrated risk for
+    // this shape of value), so it must not be echoed verbatim.
+    const shownCmd = describeRejectedValue(cmd);
     fail({
       code: "UNKNOWN_COMMAND",
       message: closest
-        ? `Unknown command: ${cmd}. Did you mean ${closest}?`
-        : `Unknown command: ${cmd}`,
+        ? `Unknown command: ${shownCmd}. Did you mean ${closest}?`
+        : `Unknown command: ${shownCmd}`,
       hint: "Run `run402 --help` for the command list.",
-      details: { command: cmd, closest: closest ? [closest] : [] },
+      details: { command: shownCmd, closest: closest ? [closest] : [] },
     });
   }
 }

package/core-dist/config.js

@@ -2,6 +2,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { existsSync, renameSync, mkdirSync, chmodSync, readFileSync, writeFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
+import { describeRejectedValue } from "./redact.js";
 export const DEFAULT_API_BASE = "https://api.run402.com";
 /**
  * Validate a user-supplied API base URL. Throws a clear error message that
@@ -25,10 +26,10 @@ function validateApiBase(envVar, raw, fallback) {
         u = new URL(raw);
     }
     catch {
-        throw new Error(`${envVar} is not a valid URL: ${JSON.stringify(raw)}. Expected an http(s) URL like https://api.run402.com.`);
+        throw new Error(`${envVar} is not a valid URL: ${JSON.stringify(describeRejectedValue(raw))}. Expected an http(s) URL like https://api.run402.com.`);
     }
     if (u.protocol !== "https:" && u.protocol !== "http:") {
-        throw new Error(`${envVar} must use http(s):, got ${u.protocol} (full value: ${JSON.stringify(raw)}).`);
+        throw new Error(`${envVar} must use http(s):, got ${u.protocol} (full value: ${JSON.stringify(describeRejectedValue(raw))}).`);
     }
     return raw;
 }
@@ -81,7 +82,15 @@ function assertSafeProfileName(name) {
     if (name === DEFAULT_PROFILE)
         return;
     if (!isValidProfileName(name)) {
-        throw new Error(`Invalid wallet/profile name ${JSON.stringify(name)}. ` +
+        // A value that failed this check is a value we know nothing about — the
+        // most likely mistake is a typo, but kychee-com/run402-private#640 was a
+        // Base-mainnet private key pasted into RUN402_WALLET (a NAME field), and
+        // the raw value used to be echoed straight into this message and
+        // wherever it propagated (terminal, logs, session transcripts).
+        // describeRejectedValue() shows short/plain values in full (useful for
+        // an actual typo) and redacts anything long or hex-shaped enough to be
+        // a secret instead of a name.
+        throw new Error(`Invalid wallet/profile name ${JSON.stringify(describeRejectedValue(name))}. ` +
             "Names must match /^[a-z0-9][a-z0-9_-]{0,63}$/ (lowercase letters, digits, '_' and '-'). " +
             "Check the RUN402_WALLET / RUN402_PROFILE env var.");
     }

package/core-dist/profiles.js

@@ -18,6 +18,7 @@ import { readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync, existsSy
 import { dirname, join } from "node:path";
 import { randomBytes } from "node:crypto";
 import { getConfigBaseDir, getProfilesDir, DEFAULT_PROFILE, isValidProfileName, } from "./config.js";
+import { describeRejectedValue } from "./redact.js";
 function atomicWrite(p, content, mode) {
     const dir = dirname(p);
     mkdirSync(dir, { recursive: true });
@@ -153,7 +154,10 @@ export function removeProfile(name) {
  */
 export function renameProfile(oldName, newName) {
     if (!isValidProfileName(newName)) {
-        throw new Error(`Invalid wallet name ${JSON.stringify(newName)}.`);
+        // See describeRejectedValue()'s doc comment (kychee-com/run402-private#640):
+        // a rejected value may be a secret pasted into a name field, so it is
+        // never safe to echo verbatim here.
+        throw new Error(`Invalid wallet name ${JSON.stringify(describeRejectedValue(newName))}.`);
     }
     if (newName === oldName)
         return;

package/core-dist/redact.js

@@ -0,0 +1,64 @@
+/**
+ * Safe-echo policy for values that failed local (client-side) validation.
+ *
+ * A value rejected by a format/existence check is a value we know nothing
+ * about — the CLI has only established what it is NOT. The likeliest
+ * failure is an ordinary typo, but the second likeliest, demonstrated in
+ * practice, is a credential pasted into the wrong slot:
+ * kychee-com/run402-private#640 — a Base-mainnet private key holding real
+ * funds landed in `RUN402_WALLET` (which takes a wallet NAME, not a key),
+ * failed the name check, and was printed verbatim to a terminal, a log, and
+ * a session transcript.
+ *
+ * `describeRejectedValue` is the one place that decides what a rejected
+ * value is safe to show, so every call site — wallet names, org ids, room
+ * keys, unknown commands/subcommands, "not found" lookups — gets the same
+ * answer instead of each reinventing (or forgetting) the judgment call.
+ *
+ * Short, low-entropy values (ordinary typos) are returned unchanged — that
+ * is what makes the resulting error message useful. Long or
+ * high-entropy-looking values are replaced with a shape-only description
+ * (character count only), never a substring or prefix of the original:
+ * even a short prefix of a private key is more than a debugging aid needs
+ * and more than a leak should give up.
+ *
+ * This is a heuristic, not a content-aware secret scanner: treat "returned
+ * unchanged" as "short and plain enough to be a typo," not as proof the
+ * value holds no secret. Callers with a value that is never supposed to be
+ * secret-shaped in the first place (a service key, an admin key) should
+ * still never echo it at all, redacted or not — this helper is for slots
+ * that normally hold a plain identifier and occasionally, by mistake,
+ * don't.
+ */
+// Real hand-typed identifiers (wallet names, room keys, command names) top
+// out well under this, and it comfortably clears a UUID (36 chars — the
+// canonical shape of an org id, and *itself* a public, harmless-to-echo
+// identifier even when it's the "wrong" one in a conflict, not a secret).
+// Secrets that land in the wrong slot (private keys, API tokens, JWTs) are
+// almost always well past it — the private key in #640 was 64-66 characters.
+const MAX_SAFE_ECHO_LENGTH = 40;
+// A contiguous hex run (with or without a `0x` prefix) reads as key
+// material or a hash rather than a human-typed identifier, even when short
+// enough to pass the length check above — the exact shape of #640.
+const HEX_RUN_RE = /^(0x)?[0-9a-fA-F]{16,}$/;
+function looksSecretShaped(str) {
+    return str.length > MAX_SAFE_ECHO_LENGTH || HEX_RUN_RE.test(str);
+}
+/**
+ * Return `value` unchanged when it is short and plain enough to be a
+ * harmless typo; otherwise return a shape-only placeholder (character count
+ * only — never a substring) that is still safe to embed in a message or a
+ * structured `details` field.
+ *
+ * Never throws. Coerces non-string input the same way template-literal
+ * interpolation would, so a caller can pass whatever it already has without
+ * a separate type check.
+ */
+export function describeRejectedValue(value) {
+    const str = typeof value === "string" ? value : String(value ?? "");
+    if (looksSecretShaped(str)) {
+        return `${str.length} chars, not shown — too long or hex-shaped to be a typo (may be a credential that landed in the wrong place)`;
+    }
+    return str;
+}
+//# sourceMappingURL=redact.js.map

package/gitvault-surface.json

@@ -1,5 +1,5 @@
 {
-  "surface_version": "4.61.0",
+  "surface_version": "4.62.0",
   "verbs": [
     "repos create",
     "repos list",

package/lib/argparse.mjs

@@ -2,6 +2,7 @@ import { existsSync, statSync } from "node:fs";
 import { fail } from "./sdk-errors.mjs";
 import { resolveProjectId } from "./config.mjs";
 import { COMMAND_MANIFEST } from "./command-manifest.mjs";
+import { describeRejectedValue } from "../core-dist/redact.js";
 
 export function normalizeArgv(argv = []) {
   const out = [];
@@ -140,12 +141,15 @@ export function validateEvmAddress(value, fieldName = "address") {
   }
 }
 
+// A rejected positional could be anything the caller typed or piped in — see
+// core-dist/redact.js's doc comment (kychee-com/run402-private#640) — so it
+// is never safe to echo verbatim.
 export function failBadProjectId(value) {
   fail({
     code: "BAD_PROJECT_ID",
-    message: `Argument '${value}' is not a project id. Project IDs must start with 'prj_'.`,
+    message: `Argument '${describeRejectedValue(value)}' is not a project id. Project IDs must start with 'prj_'.`,
     hint: "Omit the project id to use the active project, or pass the full prj_... id.",
-    details: { value, expected_prefix: "prj_" },
+    details: { value: describeRejectedValue(value), expected_prefix: "prj_" },
   });
 }
 
@@ -433,16 +437,22 @@ export function knownSubcommands(family) {
 export function failUnknownSubcommand(family, sub, { hint, label, extraSubcommands = [], next_actions } = {}) {
   const displayLabel = label ?? family;
   const known = [...new Set([...knownSubcommands(family), ...extraSubcommands])].sort();
+  // closestWord() itself never echoes — it only ever returns one of the
+  // known, safe `known` candidates — but `sub` is an arbitrary positional
+  // (could be anything piped or mistyped in; kychee-com/run402-private#640
+  // is the demonstrated risk), so the ECHO of `sub` below still needs
+  // redaction even though the matching runs on the raw value.
   const closest = typeof sub === "string" ? closestWord(sub, known) : null;
+  const shownSub = describeRejectedValue(sub);
   fail({
     code: "UNKNOWN_SUBCOMMAND",
     message: closest
-      ? `Unknown ${displayLabel} subcommand: ${sub}. Did you mean ${closest}?`
-      : `Unknown ${displayLabel} subcommand: ${sub}`,
+      ? `Unknown ${displayLabel} subcommand: ${shownSub}. Did you mean ${closest}?`
+      : `Unknown ${displayLabel} subcommand: ${shownSub}`,
     hint: hint ?? `Run \`run402 ${displayLabel} --help\` for usage.`,
     details: {
       command: displayLabel,
-      subcommand: sub,
+      subcommand: shownSub,
       closest: closest ? [closest] : [],
       known_subcommands: known,
     },

package/lib/email.mjs

@@ -4,6 +4,7 @@ import { resolveProjectId } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail, parseFlagJson } from "./sdk-errors.mjs";
 import { assertKnownFlags, flagValue, normalizeArgv, parseIntegerFlag, positionalArgs, failUnknownSubcommand } from "./argparse.mjs";
+import { describeRejectedValue } from "../core-dist/redact.js";
 
 // Extension → content-type for `--attach <path>` without an explicit `:type`.
 const ATTACH_EXT_CONTENT_TYPES = {
@@ -365,11 +366,14 @@ function mailboxIdFromSelector(envelope, selector, flag) {
   if (/^mbx_/.test(selector)) return selector;
   const hit = (envelope.mailboxes ?? []).find((m) => m.mailbox_id === selector || m.slug === selector);
   if (!hit) {
+    // A selector that matches nothing is a value we know nothing about — see
+    // core-dist/redact.js's doc comment (kychee-com/run402-private#640) —
+    // so it must not be echoed verbatim.
     fail({
       code: "MAILBOX_NOT_FOUND",
-      message: `No mailbox matching ${JSON.stringify(selector)} for ${flag}.`,
+      message: `No mailbox matching ${JSON.stringify(describeRejectedValue(selector))} for ${flag}.`,
       details: {
-        selector,
+        selector: describeRejectedValue(selector),
         flag,
         candidates: (envelope.mailboxes ?? []).map(summarizeMailboxForDefaults),
       },

package/lib/gitvault-daemon.mjs

@@ -89,7 +89,7 @@ export async function runDaemon() {
     socket.setNoDelay(true);
     armIdle();
     let buf = "";
-    let session = null; // { stdin, restoreEnv, restoreCwd, restoreWrites }
+    let session = null; // { stdin, restoreEnv, restoreCwd, restoreWrites, backgroundWork }
 
     const send = (obj) => {
       try {
@@ -99,22 +99,47 @@ export async function runDaemon() {
       }
     };
 
-    const teardown = () => {
+    /**
+     * gitvault-checkpoint-cadence design D2: `session.backgroundWork` — set
+     * by `onBackgroundWork` below when a push's auto-gc cycle was handed
+     * off — is a promise this daemon keeps itself alive for BEFORE
+     * restoring env/cwd/`busy`, even though the CLIENT already got its
+     * `exit` and the socket is already ending. `session` is cleared and
+     * write-redirection restored immediately and SYNCHRONOUSLY (so a stray
+     * log line from the background cycle lands on the daemon's own
+     * stdout/stderr, never an attempt to write into an already-closing
+     * socket) — only `busy`/env/cwd/idle-arming wait on the promise. This
+     * is what "keep the daemon alive through it" means structurally:
+     * `busy` stays `true` (refusing a new `hello`, and holding off
+     * idle-exit) for the ENTIRE compaction, not just the git protocol
+     * exchange that preceded it — the single-session invariant this
+     * module's whole design rests on would otherwise race a NEW session's
+     * env/cwd swap against the still-running compaction's own SDK calls.
+     * `backgroundWork` itself never rejects (`maybeRunAutoGc` swallows the
+     * cycle's own failure before handing the promise off) — the `catch`
+     * here is belt-and-suspenders, not a real error path.
+     */
+    const teardown = async () => {
       if (!session) return;
       const s = session;
       session = null;
-      busy = false;
       try {
         s.stdin.end();
       } catch {
         /* already ended */
       }
       s.restoreWrites();
+      if (s.backgroundWork) {
+        await s.backgroundWork.catch(() => undefined);
+      }
+      busy = false;
       s.restoreEnv();
       s.restoreCwd();
       armIdle();
     };
-    socket.on("close", teardown);
+    socket.on("close", () => {
+      void teardown();
+    });
     socket.on("error", () => socket.destroy());
 
     socket.on("data", (chunk) => {
@@ -186,18 +211,30 @@ export async function runDaemon() {
             process.stdout.write = realOut;
             process.stderr.write = realErr;
           };
-          session = { stdin, restoreEnv, restoreCwd, restoreWrites };
+          session = { stdin, restoreEnv, restoreCwd, restoreWrites, backgroundWork: null };
           send({ t: "ready" });
-          runHelperSession(Array.isArray(msg.argv) ? msg.argv : [], { stdin })
+          // gitvault-checkpoint-cadence design D2: a push's auto-gc cycle
+          // (if triggered) hands its ALREADY-STARTED promise here instead
+          // of being awaited inline — `runHelperSession` itself still
+          // resolves at push speed, so `exit`/`socket.end()` below reach
+          // the client immediately; `teardown()` is what actually waits on
+          // it (see its own doc comment) before this daemon looks idle or
+          // accepts a new session.
+          runHelperSession(Array.isArray(msg.argv) ? msg.argv : [], {
+            stdin,
+            onBackgroundWork: (promise) => {
+              if (session) session.backgroundWork = promise;
+            },
+          })
             .then((code) => {
-              teardown();
               send({ t: "exit", code });
               socket.end();
+              void teardown();
             })
             .catch(() => {
-              teardown();
               send({ t: "exit", code: 1 });
               socket.end();
+              void teardown();
             });
         } else if (msg.t === "in") {
           session?.stdin.write(Buffer.from(msg.d, "base64"));

package/lib/org-context.mjs

@@ -43,6 +43,7 @@ import { flagValue } from "./argparse.mjs";
 import { findBindingKey } from "./wallet-context.mjs";
 import { fail } from "./sdk-errors.mjs";
 import { nextAction } from "./next-actions.mjs";
+import { describeRejectedValue } from "../core-dist/redact.js";
 import {
   getActiveOrgId as coreGetActiveOrgId,
   setActiveOrgId as coreSetActiveOrgId,
@@ -66,14 +67,19 @@ const trimmed = (v) => (typeof v === "string" && v.trim() ? v.trim() : null);
 /**
  * Shape-validate an organization id supplied by a local source. Membership is
  * NEVER checked here — only that the value could be an org id at all.
+ *
+ * A rejected value is a value we know nothing about — see
+ * core-dist/redact.js's doc comment (kychee-com/run402-private#640): the
+ * same class of mistake that put a private key into RUN402_WALLET can put
+ * one into RUN402_ORG / --org, so this must never echo the raw value.
  */
 function assertOrgIdShape(orgId, origin) {
   if (ORG_ID_RE.test(orgId)) return orgId;
   fail({
     code: "BAD_ORG_ID",
-    message: `Invalid organization id ${JSON.stringify(orgId)} (from ${origin}).`,
+    message: `Invalid organization id ${JSON.stringify(describeRejectedValue(orgId))} (from ${origin}).`,
     hint: "An org_id is a UUID. Run 'run402 org list' to see the organizations you belong to.",
-    details: { org_id: orgId, origin },
+    details: { org_id: describeRejectedValue(orgId), origin },
     next_actions: [listOrgsAction()],
   });
 }

package/lib/remote-helper-session.mjs

@@ -126,7 +126,7 @@ const nodeModP = import("#sdk/node");
 const { getSdk } = await sdkModP;
 const { resolveWalletCore, enforceWalletExistsCore, WalletSelectionError } = await walletModP;
 const { gitvaultRemoteAddressForm, gitvaultSlugReleasedInfo, parseGitvaultRemoteUrl } = await isoModP;
-const { GITVAULT_R402_REF_NAMESPACE, hardenedGit, resolveGitInvocationRepo, readPinnedGitvaultRepo, pinGitvaultRepo } = await nodeModP;
+const { GITVAULT_R402_REF_NAMESPACE, hardenedGit, resolveGitInvocationRepo, readPinnedGitvaultRepo, pinGitvaultRepo, readGitvaultRestoreMarker, readGitvaultAutoGcThreshold } = await nodeModP;
 
 /** The session's input stream — injected per session (daemon: the socket's forwarded stdin). */
 let sessionStdin = process.stdin;
@@ -339,7 +339,20 @@ export function chooseGitvaultHeadTargetForPush({ baseHeadTarget, baseRefs, upda
   return { head_target: { kind: "symref", ref: chosen }, note };
 }
 
-async function main(argv) {
+/**
+ * gitvault-checkpoint-cadence design D1 — the pure post-push auto-gc
+ * threshold decision, exported standalone so the threshold matrix (below /
+ * at / disabled) is directly unit-testable without the session's heavier
+ * closures (network, git, daemon plumbing). `0` (or anything not a
+ * positive finite number — a corrupt local config value) means disabled;
+ * `generationsSinceCheckpoint >= threshold` is the trigger (matches
+ * `gitvaultCheckpointStaleness`'s own `since >= THRESHOLD` shape).
+ */
+export function shouldRunAutoGc(threshold, generationsSinceCheckpoint) {
+  return Number.isFinite(threshold) && threshold > 0 && Number.isFinite(generationsSinceCheckpoint) && generationsSinceCheckpoint >= threshold;
+}
+
+async function main(argv, { onBackgroundWork } = {}) {
   // gitvault-connection-amortization (bench P5) note: the prewarm now fires
   // at the module TOP, before the SDK graph loads (gitvault-startup-
   // amortization D1) — connection dial and signer warmup both race module
@@ -511,13 +524,29 @@ async function main(argv) {
       // checkout) — `list` still works, and there is nothing for `push` to
       // share later in that case.
     }
+    // gitvault-session-state-reuse design D2: read the restore MARKER —
+    // NEVER the chain-trust pin (see `tryStateFastPath`'s own doc comment on
+    // why the pin is the wrong `since` for a standing clone that is
+    // generations behind) — once, here, and thread it to the materialize
+    // call below AND to `fetch`'s reuse below. Best-effort: a marker-read
+    // failure (no repository, no prior restore) just means no `since` is
+    // sent, exactly today's behavior.
+    let fetchMarker = null;
+    if (repoDir) {
+      try {
+        fetchMarker = await readGitvaultRestoreMarker(repoDir);
+      } catch {
+        fetchMarker = null;
+      }
+    }
+    const materializeOpts = fetchMarker ? { deltaSince: fetchMarker.generation } : {};
     let vault;
     let state;
     try {
       const opened = await openVault(repoDir ?? undefined);
       vault = opened.vault;
       try {
-        state = await vault.materialize();
+        state = await vault.materialize(materializeOpts);
       } catch (err) {
         // An OFFLINE (id-carrying pin) resolution discovers a stale pin on
         // its FIRST repo-scoped read (client-surface spec, id-pinning
@@ -532,7 +561,7 @@ async function main(argv) {
         if (!recovered) throw err;
         note(`pinned vault ${opened.resolution.repo_id} no longer resolves — re-resolved to ${recovered.resolution.repo_id}, retrying`);
         vault = recovered.handle.vault;
-        state = await vault.materialize();
+        state = await vault.materialize(materializeOpts);
       }
     } catch (err) {
       // An unallocated vault is not an error here: `list` is the read half of
@@ -549,7 +578,12 @@ async function main(argv) {
       }
       throw err;
     }
-    if (repoDir) sharedListSession = { repoDir, walletName: resolvedWallet?.name ?? null, vault, base: state };
+    // gitvault-session-state-reuse design D1: `fetchState`/`fetchMarker`
+    // extend the SAME session-scoped handoff `push` already reuses (`base`)
+    // — the `fetch` phase of THIS session reuses this response instead of
+    // issuing its own state read. Session-scoped only: dropped the moment a
+    // push admits in this same session (see `runPush`'s reset below).
+    if (repoDir) sharedListSession = { repoDir, walletName: resolvedWallet?.name ?? null, vault, base: state, fetchMarker, fetchState: state };
     const refs = state.refs ?? {};
     for (const ref of Object.keys(refs).sort()) out(`${refs[ref]} ${ref}`);
     // A snapshot-only vault holds protocol refs but no branch heads, so a
@@ -586,7 +620,17 @@ async function main(argv) {
     // wherever clone was run FROM, unrelated to the target repository).
     applyWalletForDir(repoDir);
     if (verbosity >= 1) note(`restoring the vault object database for ${batch.length} ref(s) into ${repoDir}`);
-    const restored = await getSdk().gitvault.restore({ ...target, repo_dir: repoDir, target_dir: repoDir });
+    // gitvault-session-state-reuse design D1/D4: reuse THIS session's `list`
+    // phase state — same resolved repository AND wallet, exactly the same
+    // matching rule `push`'s own reuse uses above — instead of a second
+    // network state read. Any mismatch (no prior `list`, a failed list, a
+    // different repository/wallet, or a push that already admitted in this
+    // same session — see `runPush`'s reset) falls back to the vault's own
+    // read, unchanged.
+    const shared = sharedListSession && sharedListSession.repoDir === repoDir && sharedListSession.walletName === (resolvedWallet?.name ?? null) ? sharedListSession : null;
+    const restored = shared
+      ? await shared.vault.restoreObjectsInto(repoDir, { marker: shared.fetchMarker, state: shared.fetchState })
+      : await getSdk().gitvault.restore({ ...target, repo_dir: repoDir, target_dir: repoDir });
     if (verbosity >= 1) note(`restored generation ${restored.generation}`);
     // clone-installs-retained-refs D3: a bookkeeping failure here degrades to
     // exactly today's (pre-change) behavior — one stderr note, fetch still
@@ -600,8 +644,81 @@ async function main(argv) {
     return 0;
   }
 
+  /**
+   * gitvault-checkpoint-cadence (design D1/D2) — the post-push auto-gc
+   * cadence, `git gc --auto`'s shape: a cheap local threshold check after
+   * every successful push, maintenance only past it.
+   *
+   * MUST be called strictly AFTER the push's own `ok`/`error` lines and
+   * `endBlock()` have already been written — auto-gc can never fail, slow,
+   * or reorder the push it follows (this function itself never throws).
+   * `generationsSinceCheckpoint` comes from `published.checkpoint_staleness`
+   * (the push's own already-materialized chain) — zero extra reads to learn
+   * it.
+   *
+   * Threshold: `repoDir`'s local `auto_gc_generations` (default 32, `0`
+   * disables — `readGitvaultAutoGcThreshold`, design D1's "rides the
+   * existing vault policy surface" as a per-checkout `repos policy` knob).
+   *
+   * Dispatch: with a daemon-supplied `onBackgroundWork`, the compaction is
+   * STARTED immediately and handed off as a promise — the daemon keeps
+   * itself alive until it settles, but THIS call returns immediately so the
+   * client-visible session (and the user's prompt) is not held up. Without
+   * one (the in-process fallback), the SAME cycle is awaited right here,
+   * with one stderr advisory line naming the wait.
+   *
+   * `compact()` (namespace, `sdk/src/namespaces/gitvault.ts`) already owns
+   * the compaction headroom grant's open/close and single-flight refusal
+   * (`GITVAULT_COMPACTION_IN_PROGRESS`) — this function only decides WHETHER
+   * and HOW to run the cycle, never re-implements those. `--force-headroom`
+   * is NEVER passed on this path (design D5) — an insufficient-headroom
+   * refusal, a conflicting in-flight compaction, or any other failure all
+   * degrade identically: one advisory line naming `run402 repos gc`, never
+   * a thrown error, never a retry loop.
+   */
+  async function maybeRunAutoGc({ repoDir, generationsSinceCheckpoint }) {
+    let threshold;
+    try {
+      threshold = await readGitvaultAutoGcThreshold(repoDir);
+    } catch {
+      return; // never let a local-config read failure touch the push it follows
+    }
+    if (!shouldRunAutoGc(threshold, generationsSinceCheckpoint)) return;
+
+    const runCycle = async () => {
+      const sdk = getSdk();
+      const checkpoint = await sdk.gitvault.compact({ ...target });
+      const prune = await sdk.gitvault.prune(target); // PLAN only — never `submit`; see compact()'s own grant-close doc comment for why prune needs no headroom of its own
+      return { checkpoint, prune };
+    };
+
+    if (typeof onBackgroundWork === "function") {
+      // Daemon host: start it now, hand the PROMISE off, return immediately.
+      // Failures are swallowed here (best-effort, matching the fallback
+      // branch's degrade contract) — there is no live client to advise by
+      // the time this settles, and the daemon's own teardown does not
+      // depend on the outcome, only on the promise SETTLING.
+      const cyclePromise = runCycle().catch(() => undefined);
+      onBackgroundWork(cyclePromise);
+      return;
+    }
+
+    // In-process fallback: the extra wall time is real, so name it.
+    note(`gitvault: compacting (${generationsSinceCheckpoint} generations since checkpoint)…`);
+    try {
+      await runCycle();
+    } catch (err) {
+      note(`gitvault: auto-compaction stopped short — ${describeError(err)} — run \`run402 repos gc\` to finish it by hand.`);
+    }
+  }
+
   async function runPush(batch) {
     const specs = batch.map(parsePushSpec);
+    // gitvault-checkpoint-cadence: set ONLY after a successful admission
+    // (never in the catch block) — `null` means "auto-gc has nothing to
+    // do", which is also the correct value for every early-return path
+    // above (nothing pushed, nothing refused-only, dry-run).
+    let autoGcCandidate = null;
     // D4: `refs/r402/*` is client-local — refuse it per-ref, BEFORE any
     // repository/wallet/network work, while unrelated branch updates in the
     // SAME push proceed normally (client-surface spec's own scenario).
@@ -721,14 +838,26 @@ async function main(argv) {
         base,
         ...(headFix.head_target ? { head_target: headFix.head_target } : {}),
       });
+      // gitvault-session-state-reuse design D4: this admission just advanced
+      // the vault, so the `list` phase's handoff (if any) is now stale —
+      // drop it. A `fetch` later in this SAME session (an unusual ordering
+      // git's own protocol does not normally produce) reads fresh rather
+      // than reusing pre-admission state.
+      sharedListSession = null;
       if (verbosity >= 1) note(`published generation ${published.generation} (${published.form})`);
-      // gitvault-clone-scaling (P3): advisory only — never blocks, never
-      // auto-runs compaction, and never fires on a failed push (this line is
-      // unreachable from the catch). Unknown coverage reads as not-advised.
+      // gitvault-clone-scaling (P3): advisory only — informational, always
+      // fires at 25 generations regardless of the SEPARATE auto-gc
+      // threshold below (design D1's `auto_gc_generations`, default 32) —
+      // the two are deliberately different numbers for different purposes.
       if (published.checkpoint_staleness?.advised) {
         note(`${published.checkpoint_staleness.generations_since_checkpoint} generations since the last checkpoint — cold clones re-verify each one; run402 repos gc compacts them`);
       }
       for (const spec of allowed) out(`ok ${spec.dst}`);
+      // gitvault-checkpoint-cadence: captured here (never in the catch
+      // block below — auto-gc must never fire on a failed push) and acted
+      // on AFTER this function's own `endBlock()`, so the auto-gc check
+      // itself can never delay, alter, or reorder the push's own report.
+      autoGcCandidate = { repoDir, generationsSinceCheckpoint: published.checkpoint_staleness?.generations_since_checkpoint ?? 0 };
     } catch (err) {
       // The transaction is atomic, so a failure failed every ref in it. Report
       // it against each one rather than letting some look like they landed.
@@ -742,6 +871,10 @@ async function main(argv) {
       for (const spec of allowed) out(`error ${spec.dst} ${reason}`);
     }
     endBlock();
+    // gitvault-checkpoint-cadence design D1/D2: strictly AFTER the push's
+    // own report — `null` (a failed push, a refused-only batch, dry-run)
+    // is a silent no-op. `maybeRunAutoGc` itself never throws.
+    if (autoGcCandidate) await maybeRunAutoGc(autoGcCandidate);
     return 0;
   }
 
@@ -852,12 +985,21 @@ async function main(argv) {
  * serving sequential sessions never leaks one invocation's resolution into
  * the next (D2). Never throws — the error path is the same
  * note-and-exit-1 the standalone binary always had.
+ *
+ * `onBackgroundWork` (gitvault-checkpoint-cadence design D2): when supplied
+ * (the DAEMON host only — see `gitvault-daemon.mjs`), a successful push's
+ * auto-gc cycle is handed to it as an ALREADY-STARTED promise instead of
+ * being awaited inline, so this call resolves (and the client-visible
+ * session ends) at push speed. The caller is responsible for keeping
+ * whatever this promise needs alive (its own connections, its own process)
+ * until the promise settles. Absent (the in-process fallback host), the
+ * SAME cycle is awaited inline instead — see `maybeRunAutoGc` below.
  */
-export async function runHelperSession(argv, { stdin } = {}) {
+export async function runHelperSession(argv, { stdin, onBackgroundWork } = {}) {
   sessionStdin = stdin ?? process.stdin;
   resolvedWallet = null;
   try {
-    return await main(argv);
+    return await main(argv, { onBackgroundWork });
   } catch (err) {
     note(describeError(err));
     return 1;