run402 4.61.0 → 4.62.0

package/lib/repos.mjs

@@ -82,6 +82,7 @@ Maintenance:
   run402 repos access revoke-key <principal_id> [--project <id>] [--repo <repo_id>]
   run402 repos access declare-exposure [--project <id>] [--repo <repo_id>]
   run402 repos policy <required|grandfathered> [--project <id>] [--repo <repo_id>] [--reason <why>]
+  run402 repos policy auto-gc [<generations>|off]   (local, per-checkout — no --project/--repo)
 
 Every verb above also accepts -v/--verbose (a stderr summary line of request
 stats — round trips, wire time, bytes — coexists with --human) and always
@@ -268,6 +269,15 @@ Subcommands:
            step-up, audited. \`grandfathered\` is the documented way out of a
            deploy the vault gate refused, and needs \`--reason\`; returning to
            \`required\` does not. Allocating a repo never sets this.
+  policy auto-gc [<generations>|off]
+           A LOCAL, per-checkout setting (git config, like git's own
+           \`gc.auto\` — no network call, no --project/--repo/--reason): the
+           post-push compaction cadence (gitvault-checkpoint-cadence).
+           Default 32 — after a push, once this many generations have
+           accumulated since the vault's last checkpoint, \`gc\`'s
+           compact+prune-plan cycle runs automatically (one stderr advisory
+           without a resident daemon; silently in the background with one).
+           \`off\` (or \`0\`) disables it. No value prints the current setting.
 
 Options:
   --project <id>    Project whose repo to act on (defaults to the active project)
@@ -1359,20 +1369,84 @@ async function snapshot(args) {
 
 // ─── policy ─────────────────────────────────────────────────────────────────
 
+/**
+ * gitvault-checkpoint-cadence design D1: `auto-gc` is a LOCAL, per-checkout
+ * knob — the same local-git-config mechanism as the restore marker, and the
+ * same shape as git's own `gc.auto` — deliberately NOT a gateway call like
+ * `required`/`grandfathered` above (there is no server-side policy row for
+ * it; the gateway task list for this change never adds one). It rides
+ * `repos policy`'s NAMESPACE only, for the muscle-memory: `run402 repos
+ * policy auto-gc [<generations>|off]`. No value reads the current setting;
+ * `off` is sugar for `0` (disables auto-gc entirely).
+ */
+async function policyAutoGc(rawValue, a) {
+  const { hardenedGit, readGitvaultAutoGcThreshold, writeGitvaultAutoGcThreshold, GITVAULT_AUTO_GC_GENERATIONS_DEFAULT } = await import("#sdk/node");
+  const dir = process.cwd();
+  try {
+    await hardenedGit(dir, ["rev-parse", "--git-dir"]);
+  } catch {
+    fail({
+      code: "BAD_USAGE",
+      message: "run402 repos policy auto-gc must run inside a git checkout.",
+      hint: "cd into the repository this vault is checked out in, then re-run — auto-gc's threshold is per-checkout, like git's own `gc.auto`.",
+    });
+  }
+  const sdk = getSdk();
+  if (rawValue === undefined) {
+    const current = await readGitvaultAutoGcThreshold(dir);
+    printJson(sdk, { auto_gc_generations: current, default: GITVAULT_AUTO_GC_GENERATIONS_DEFAULT });
+    console.error(
+      current === 0
+        ? "auto-gc is disabled for this checkout"
+        : `auto-gc runs after a push once ${current} generation(s) have accumulated since the last checkpoint (default ${GITVAULT_AUTO_GC_GENERATIONS_DEFAULT})`,
+    );
+    printVerboseStats(a, sdk);
+    return;
+  }
+  let generations;
+  if (rawValue === "off") {
+    generations = 0;
+  } else if (/^\d+$/.test(rawValue)) {
+    generations = Number.parseInt(rawValue, 10);
+  } else {
+    fail({
+      code: "BAD_USAGE",
+      message: `Invalid auto-gc value: ${rawValue}.`,
+      hint: "Expected a non-negative integer (generations since checkpoint before auto-gc runs), or `off` to disable.",
+      details: { value: rawValue },
+    });
+  }
+  await writeGitvaultAutoGcThreshold(dir, generations);
+  printJson(sdk, { auto_gc_generations: generations });
+  console.error(
+    generations === 0
+      ? "auto-gc disabled for this checkout"
+      : `auto-gc will run after a push once ${generations} generation(s) have accumulated since the last checkpoint`,
+  );
+  printVerboseStats(a, sdk);
+}
+
 async function policy(args) {
   const a = normalizeArgv(args);
   const valueFlags = [...COMMON_VALUE_FLAGS, "--reason"];
   assertKnownFlags(a, [...valueFlags, "-v", "--verbose", "--help", "-h"], valueFlags);
-  const [requested] = requirePositionalCount(a, valueFlags, {
-    min: 1, max: 1, command: "run402 repos policy <required|grandfathered>",
-    missing: "Missing <policy>. Expected `required` or `grandfathered`.",
+  const positionals = requirePositionalCount(a, valueFlags, {
+    min: 1, max: 2, command: "run402 repos policy <required|grandfathered|auto-gc> [value]",
+    missing: "Missing <policy>. Expected `required`, `grandfathered`, or `auto-gc [<generations>|off]`.",
   });
+  const [requested, secondArg] = positionals;
+  if (requested === "auto-gc") {
+    return policyAutoGc(secondArg, a);
+  }
+  if (secondArg !== undefined) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for run402 repos policy ${requested}: ${secondArg}`, hint: "Only `auto-gc` takes a second argument." });
+  }
   if (requested !== "required" && requested !== "grandfathered") {
     fail({
       code: "BAD_USAGE",
       message: `Unknown policy: ${requested}.`,
-      hint: "Expected `required` (a deploy must present a vaulted capture) or `grandfathered` (it need not).",
-      details: { policy: requested, known_policies: ["required", "grandfathered"] },
+      hint: "Expected `required` (a deploy must present a vaulted capture), `grandfathered` (it need not), or `auto-gc [<generations>|off]` (the post-push compaction cadence).",
+      details: { policy: requested, known_policies: ["required", "grandfathered", "auto-gc"] },
     });
   }
   const reason = flagValue(a, "--reason");

package/lib/rooms-context.mjs

@@ -31,6 +31,7 @@ import { resolveOrg } from "./org-context.mjs";
 import { findBindingKey } from "./wallet-context.mjs";
 import { nextAction } from "./next-actions.mjs";
 import { resolveSessionKey } from "./harness-context.mjs";
+import { describeRejectedValue } from "../core-dist/redact.js";
 
 export const ROOM_ENV = "RUN402_ROOM";
 export const PRESENCE_ENV = "RUN402_PRESENCE_ID";
@@ -58,10 +59,12 @@ export async function resolveRoom({ org, room, project } = {}) {
   if (envRoom) {
     const slash = envRoom.indexOf("/");
     if (slash <= 0 || slash === envRoom.length - 1) {
+      // Same class as kychee-com/run402-private#640: a malformed RUN402_ROOM
+      // is a value we know nothing about, so it must not be echoed raw.
       fail({
         code: "BAD_USAGE",
         message: `${ROOM_ENV} must be "<org_id>/<room_key>".`,
-        details: { value: envRoom },
+        details: { value: describeRejectedValue(envRoom) },
       });
     }
     return {

package/lib/wallet-context.mjs

@@ -25,6 +25,7 @@ import { fail } from "./sdk-errors.mjs";
 import { isValidProfileName } from "../core-dist/config.js";
 import { getDefaultWallet, profileExists, readMeta, profileDir } from "../core-dist/profiles.js";
 import { readAllowance } from "../core-dist/allowance.js";
+import { describeRejectedValue } from "../core-dist/redact.js";
 // The binding file is a CHECKOUT-LEVEL CONTRACT read by more than one surface,
 // so its reader lives in core — `run402-mcp` ships core/dist but not cli/, and
 // two readers of one file format is exactly the drift worth not having.
@@ -131,13 +132,21 @@ export class WalletSelectionError extends Error {
   }
 }
 
+// A rejected name is a value we know nothing about — the most likely
+// mistake is a typo, but kychee-com/run402-private#640 was a live
+// Base-mainnet private key pasted into RUN402_WALLET (a NAME field, not a
+// key field), and the raw value used to be echoed straight into this error
+// — printed to a terminal, a log, and a session transcript. Route it
+// through describeRejectedValue() so a short/plain typo still shows in
+// full (that's what makes the error useful) while anything long or
+// hex-shaped enough to be a secret is redacted instead.
 function assertValidNameCore(name, origin) {
   if (name === DEFAULT || isValidProfileName(name)) return;
   throw new WalletSelectionError({
     code: "BAD_WALLET_NAME",
-    message: `Invalid wallet name ${JSON.stringify(name)} (from ${origin}).`,
-    hint: "Wallet names must match /^[a-z0-9][a-z0-9_-]{0,63}$/ (lowercase letters, digits, '_' and '-').",
-    details: { name, origin },
+    message: `Invalid wallet name ${JSON.stringify(describeRejectedValue(name))} (from ${origin}).`,
+    hint: "Wallet names must match /^[a-z0-9][a-z0-9_-]{0,63}$/ (lowercase letters, digits, '_' and '-'). If a private key or other secret ended up here, it does not belong in a NAME field — see `run402 wallets import` — and should be treated as compromised.",
+    details: { name: describeRejectedValue(name), origin },
   });
 }
 
@@ -187,11 +196,18 @@ export function resolveWalletCore({ walletFlag, env = {}, cwd = process.cwd(), c
   const binding = findBinding(cwd);
 
   if (envName && binding && envName !== binding.wallet && !CONFLICT_EXEMPT.has(cmd)) {
+    // This conflict check runs BEFORE assertValidNameCore below, so an
+    // unvalidated (possibly secret-shaped — kychee-com/run402-private#640)
+    // RUN402_WALLET reaches here first whenever a directory binding exists
+    // (routine per this repo's own fleet-coordination convention). Redact
+    // the env side the same way the format check would; `binding.wallet`
+    // comes from a committed .run402.json, which by convention never holds
+    // a secret (`wallets bind` validates the name before writing it).
     throw new WalletSelectionError({
       code: "WALLET_SELECTION_CONFLICT",
-      message: `Ambiguous wallet: RUN402_WALLET=${envName} but ${binding.file} selects '${binding.wallet}'.`,
+      message: `Ambiguous wallet: RUN402_WALLET=${describeRejectedValue(envName)} but ${binding.file} selects '${binding.wallet}'.`,
       hint: "Resolve with one of: pass --wallet <name>, unset RUN402_WALLET, or run402 wallets unbind.",
-      details: { env_wallet: envName, binding_wallet: binding.wallet, binding_file: binding.file },
+      details: { env_wallet: describeRejectedValue(envName), binding_wallet: binding.wallet, binding_file: binding.file },
     });
   }
 
@@ -232,14 +248,25 @@ export function enforceWalletExistsCore({ name, source }, cmd) {
   if (name === DEFAULT) return;
   if (EXISTENCE_EXEMPT.has(cmd)) return;
   if (profileExists(name)) return;
+  // `name` already passed the format check (assertValidNameCore), which
+  // constrains it to lowercase/digits/'_'/'-' — but a bare 64-hex private
+  // key with no "0x" prefix satisfies that charset too, so this "not found"
+  // path can still see raw key material. looksLikeAddress() is safe to echo
+  // (an address is public); anything else goes through describeRejectedValue(),
+  // which leaves a short/plain name untouched but redacts anything shaped
+  // like a secret — so only the untouched case gets a "create it" command
+  // that's actually safe (and sensible) to suggest re-typing.
+  const shown = describeRejectedValue(name);
   const hint = looksLikeAddress(name)
     ? `'${name}' looks like an address. For billing use: run402 billing ... --wallet-address ${name}`
-    : `Run 'run402 wallets list' to see wallets, or 'run402 wallets new ${name}' to create it.`;
+    : shown === name
+      ? `Run 'run402 wallets list' to see wallets, or 'run402 wallets new ${name}' to create it.`
+      : "Run 'run402 wallets list' to see wallets. This value was not shown because it looks like a secret rather than a wallet name — if a private key or other credential landed here, treat it as compromised.";
   throw new WalletSelectionError({
     code: "WALLET_NOT_FOUND",
-    message: `No local wallet named '${name}'.`,
+    message: `No local wallet named '${shown}'.`,
     hint,
-    details: { wallet: name, source },
+    details: { wallet: shown, source },
   });
 }
 

package/lib/wallet-context.test.mjs

@@ -27,12 +27,17 @@ afterEach(() => {
 });
 
 // Capture a fail() invocation: fail() does console.error(envelope) + process.exit.
+// `raw` is the exact string handed to console.error — the byte-for-byte
+// stderr line a real invocation would print — for tests that need to prove
+// something is absent from the actual output, not just from the re-parsed
+// object (key order/JSON-escaping could otherwise mask a leak).
 function captureFail(fn) {
   const origExit = process.exit;
   const origErr = console.error;
   let envelope = null;
+  let raw = null;
   let exited = false;
-  console.error = (s) => { try { envelope = JSON.parse(s); } catch { envelope = s; } };
+  console.error = (s) => { raw = s; try { envelope = JSON.parse(s); } catch { envelope = s; } };
   process.exit = () => { exited = true; throw new Error("__EXIT__"); };
   try {
     fn();
@@ -42,7 +47,7 @@ function captureFail(fn) {
     process.exit = origExit;
     console.error = origErr;
   }
-  return { envelope, exited };
+  return { envelope, raw, exited };
 }
 
 function bindingDir(wallet, localWallet) {
@@ -166,11 +171,52 @@ describe("resolveWallet — conflict + validation", () => {
     assert.equal(r.name, "personal"); // env still wins; no error
     rmSync(dir, { recursive: true, force: true });
   });
+
+  // The WALLET_SELECTION_CONFLICT check runs BEFORE assertValidNameCore, so a
+  // secret-shaped RUN402_WALLET reaches it unvalidated whenever a directory
+  // binding also exists — routine for any checkout following this repo's own
+  // fleet-coordination convention (`.run402.json`). This is a stricter variant
+  // of kychee-com/run402-private#640: no BAD_WALLET_NAME format check ever
+  // gets a chance to run first, so the redaction has to happen at this site
+  // too, not just at assertValidNameCore.
+  it("never echoes a secret-shaped RUN402_WALLET via the conflict path", () => {
+    const dir = bindingDir("client-a"); // a real, differently-named binding
+    const privateKey = "0x" + "22a3f0".repeat(11); // 66 chars
+    const { envelope, raw } = captureFail(() =>
+      resolveWallet({ env: { RUN402_WALLET: privateKey }, cwd: dir, cmd: "deploy" }));
+    assert.equal(envelope.code, "WALLET_SELECTION_CONFLICT");
+    assert.ok(!raw.includes(privateKey), "full stderr line must not contain the secret");
+    assert.ok(!raw.includes("22a3f0"), "stderr line must not contain a substring of the secret");
+    rmSync(dir, { recursive: true, force: true });
+  });
   it("rejects an invalid wallet name", () => {
     const dir = mkdtempSync(join(tmpdir(), "nobind-"));
     const { envelope } = captureFail(() =>
       resolveWallet({ env: { RUN402_WALLET: "../evil" }, cwd: dir, cmd: "status" }));
     assert.equal(envelope.code, "BAD_WALLET_NAME");
+    // A short, plainly-a-typo value is still shown in full — that's what
+    // makes the error useful for debugging an actual mistake.
+    assert.match(envelope.message, /\.\.\/evil/);
+    assert.equal(envelope.details.name, "../evil");
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  // kychee-com/run402-private#640: a live Base-mainnet private key was pasted
+  // into RUN402_WALLET (a NAME field, not a key field), failed this exact
+  // check, and got echoed verbatim into a terminal, a log, and a session
+  // transcript. A value that fails validation is a value the CLI knows
+  // nothing about, and secret-shaped values must never be echoed — no
+  // matter which field of the envelope, or how much of the envelope is
+  // serialized (message, hint, details, or the raw JSON line as printed).
+  it("never echoes a secret-shaped wallet name anywhere in the failure envelope", () => {
+    const dir = mkdtempSync(join(tmpdir(), "nobind-"));
+    const privateKey = "0x" + "22a3f0".repeat(11); // 66 chars — the exact shape of #640
+    const { envelope, raw } = captureFail(() =>
+      resolveWallet({ env: { RUN402_WALLET: privateKey }, cwd: dir, cmd: "status" }));
+    assert.equal(envelope.code, "BAD_WALLET_NAME");
+    assert.ok(!raw.includes(privateKey), "full stderr line must not contain the secret");
+    assert.ok(!raw.includes("22a3f0"), "stderr line must not contain a substring of the secret");
+    assert.ok(!raw.toLowerCase().includes("22a3f022a3f0"), "stderr line must not contain a longer run of the secret");
     rmSync(dir, { recursive: true, force: true });
   });
 });
@@ -189,6 +235,11 @@ describe("enforceWalletExists — fail closed", () => {
       enforceWalletExists({ name: "ghost", source: "binding" }, "deploy"));
     assert.ok(exited);
     assert.equal(envelope.code, "WALLET_NOT_FOUND");
+    // A short, ordinary name is still shown in full and gets an actionable
+    // "create it" suggestion — redaction must not degrade the common case.
+    assert.match(envelope.message, /ghost/);
+    assert.equal(envelope.details.wallet, "ghost");
+    assert.match(envelope.hint, /wallets new ghost/);
   });
   it("wallets + init are exempt (create paths)", () => {
     assert.doesNotThrow(() => enforceWalletExists({ name: "ghost", source: "flag" }, "wallets"));
@@ -199,6 +250,21 @@ describe("enforceWalletExists — fail closed", () => {
       enforceWalletExists({ name: "0x" + "a".repeat(40), source: "flag" }, "deploy"));
     assert.match(envelope.hint, /--wallet-address/);
   });
+
+  // A bare (no "0x" prefix) 64-char lowercase-hex private key satisfies the
+  // wallet-name CHARSET (lowercase letters/digits/'_'/'-'), so it sails past
+  // assertValidNameCore's format check and only fails HERE, on existence —
+  // the second, easy-to-miss half of kychee-com/run402-private#640's blast
+  // radius. It must still never be echoed.
+  it("redacts a bare-hex value that passes the name format check but not existence", () => {
+    const bareKey = "22a3f0".repeat(10) + "aabb"; // 64 lowercase-hex chars
+    assert.match(bareKey, /^[a-z0-9][a-z0-9_-]{0,63}$/); // sanity: really does pass the name regex
+    const { envelope, raw } = captureFail(() =>
+      enforceWalletExists({ name: bareKey, source: "binding" }, "deploy"));
+    assert.equal(envelope.code, "WALLET_NOT_FOUND");
+    assert.ok(!raw.includes(bareKey), "full stderr line must not contain the secret");
+    assert.ok(!raw.includes("22a3f0"), "stderr line must not contain a substring of the secret");
+  });
 });
 
 describe("emitProvenance", () => {

package/lib/wallets.mjs

@@ -31,6 +31,7 @@ import {
   setDefaultWallet,
 } from "../core-dist/profiles.js";
 import { readAllowance, saveAllowance } from "../core-dist/allowance.js";
+import { describeRejectedValue } from "../core-dist/redact.js";
 import { getSdk } from "./sdk.mjs";
 import { readBindingFile, updateBindingFile } from "./wallet-context.mjs";
 
@@ -71,15 +72,19 @@ function out(obj) {
   console.log(JSON.stringify(obj, null, 2));
 }
 
+// See core-dist/redact.js's doc comment (kychee-com/run402-private#640): a
+// value that fails this check may be a secret pasted into a name argument
+// by mistake, so it must never be echoed verbatim — describeRejectedValue()
+// still shows a short/plain typo in full.
 function requireName(name, what = "wallet name") {
   if (!name) fail({ code: "BAD_USAGE", message: `Missing ${what}.`, hint: "run402 wallets --help" });
   if (name === DEFAULT) return name;
   if (!isValidProfileName(name)) {
     fail({
       code: "BAD_WALLET_NAME",
-      message: `Invalid ${what} ${JSON.stringify(name)}.`,
+      message: `Invalid ${what} ${JSON.stringify(describeRejectedValue(name))}.`,
       hint: "Names must match /^[a-z0-9][a-z0-9_-]{0,63}$/ (lowercase letters, digits, '_' and '-').",
-      details: { name },
+      details: { name: describeRejectedValue(name) },
     });
   }
   return name;
@@ -169,7 +174,10 @@ async function cmdNew(args) {
 function cmdUse(args) {
   const name = requireName(args.find((a) => a && !a.startsWith("-")));
   if (name !== DEFAULT && !profileExists(name)) {
-    fail({ code: "WALLET_NOT_FOUND", message: `No local wallet named '${name}'.`, hint: "run402 wallets list", details: { name } });
+    // `name` already passed requireName's charset check, but a bare (no
+    // "0x") 64-hex private key satisfies that charset too — describeRejectedValue()
+    // is the backstop against echoing it here (kychee-com/run402-private#640).
+    fail({ code: "WALLET_NOT_FOUND", message: `No local wallet named '${describeRejectedValue(name)}'.`, hint: "run402 wallets list", details: { name: describeRejectedValue(name) } });
   }
   setDefaultWallet(name);
   out({ local_label: name, active: true });
@@ -184,7 +192,7 @@ async function cmdRename(args) {
     fail({ code: "BAD_WALLET_NAME", message: "Cannot rename a wallet to the reserved name 'default'.", details: { name: newName } });
   }
   if (!profileExists(oldName)) {
-    fail({ code: "WALLET_NOT_FOUND", message: `No local wallet named '${oldName}'.`, hint: "run402 wallets list", details: { name: oldName } });
+    fail({ code: "WALLET_NOT_FOUND", message: `No local wallet named '${describeRejectedValue(oldName)}'.`, hint: "run402 wallets list", details: { name: describeRejectedValue(oldName) } });
   }
   try {
     renameProfile(oldName, newName);
@@ -277,7 +285,7 @@ function cmdRm(args) {
     fail({ code: "WALLET_PROTECTED", message: "Refusing to remove the reserved 'default' wallet.", details: { name } });
   }
   if (!profileExists(name)) {
-    fail({ code: "WALLET_NOT_FOUND", message: `No local wallet named '${name}'.`, hint: "run402 wallets list", details: { name } });
+    fail({ code: "WALLET_NOT_FOUND", message: `No local wallet named '${describeRejectedValue(name)}'.`, hint: "run402 wallets list", details: { name: describeRejectedValue(name) } });
   }
   if (!args.includes("--yes")) {
     fail({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "4.61.0",
+  "version": "4.62.0",
   "description": "CLI for Run402 — full-stack backend infrastructure for AI agents: Postgres, auth, storage, serverless functions and atomic deploys. Paid with x402/MPP. Includes $0.03 image generation.",
   "type": "module",
   "bin": {

package/sdk/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/sdk/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/sdk/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/sdk/dist/namespaces/gitvault.d.ts

@@ -31,7 +31,7 @@
 import type { Client } from "../kernel.js";
 import { GITVAULT_DURABILITY_STATEMENT, GITVAULT_MIRROR_KEYSTORE_STILL_REQUIRED_STATEMENT, GITVAULT_MIRROR_VALIDITY_NOT_FRESHNESS_STATEMENT, GITVAULT_TERMINAL_LOSS_DOCTOR_TEXT, GITVAULT_TERMINAL_LOSS_STATEMENT } from "./gitvault.crypto.js";
 import type { GitvaultCaptureReceipt, GitvaultHeadsListingPage, GitvaultHeadsListingRequest, GitvaultHeadTarget, GitvaultOpenReceipt, GitvaultRecipientConfirmationReceipt, GitvaultRecoveryReceipt, GitvaultRotationReason } from "./gitvault.types.js";
-import type { GitvaultMaintenanceLease, GitvaultMaintenanceLeaseRequest, GitvaultTransport, GitvaultVaultRecord } from "../node/gitvault-publication.js";
+import type { GitvaultCompactionGrant, GitvaultMaintenanceLease, GitvaultMaintenanceLeaseRequest, GitvaultTransport, GitvaultVaultRecord } from "../node/gitvault-publication.js";
 import type { GitvaultDeployOptions, GitvaultDeployResult } from "../node/gitvault-deploy.js";
 import type { GitvaultPublishResult, GitvaultRefMap, GitvaultReconcileEnvelopeRecipientsResult, GitvaultVerifiedState } from "../node/gitvault-publication.js";
 import type { GitvaultCreationResult } from "../node/gitvault-creation-journal.js";
@@ -228,16 +228,29 @@ export interface GitvaultCompactResult {
 export interface GitvaultCompactHeadroom {
     /** Pooled storage the org is already using, across every project it owns. */
     pool_used_bytes: number;
-    /** The org's pooled tier storage limit. */
+    /** The org's plain, unraised pooled tier storage limit — always the tier's own figure, never the grant-raised one, so a disclosed "used of X pooled" never implies the tier itself grew. */
     pool_limit_bytes: number;
     /** The vault's billed `source_bytes` — the checkpoint-size proxy (design D1). */
     vault_source_bytes: number;
     /** `pool_used_bytes + vault_source_bytes`. */
     projected_transient_bytes: number;
-    /** `false` when the projection exceeds the limit. */
+    /** `false` when the projection exceeds the EFFECTIVE limit (`effective_pool_limit_bytes` when a grant is active, else `pool_limit_bytes`). */
     ok: boolean;
     /** `true` when the caller passed the override and a `false` `ok` was proceeded past anyway. */
     overridden: boolean;
+    /**
+     * gitvault-checkpoint-cadence design D3: `pool_limit_bytes` PLUS an active
+     * compaction grant's `granted_bytes`, when one is active for this cycle —
+     * the limit `ok`/`projected_transient_bytes` are actually computed
+     * against. Equal to `pool_limit_bytes` (and omittable) when no grant is
+     * active.
+     */
+    effective_pool_limit_bytes?: number;
+    /** The grant this compaction opened for itself, when one was opened and is still tracked at disclosure time — `null`/absent otherwise (no grant, an older gateway, or one already closed). */
+    compaction_grant?: {
+        granted_bytes: number;
+        expires_at: string;
+    } | null;
 }
 /**
  * `run402 gitvault snapshot --dry-run`'s report shape
@@ -1111,6 +1124,20 @@ export declare class Gitvault {
      * figures cannot be read.
      */
     compactHeadroom(options?: GitvaultVaultHandleOptions): Promise<GitvaultCompactHeadroom | null>;
+    /**
+     * Open this vault's compaction headroom grant directly (gitvault-checkpoint-cadence
+     * design D3) — `compact()` already does this internally; this standalone
+     * entry point exists for callers that need to inspect or drive the grant
+     * without also running a full compaction cycle (tests; a future
+     * operator/diagnostic surface). Throws `GITVAULT_COMPACTION_GRANT_ACTIVE`
+     * (409) verbatim when another compaction already holds this project's
+     * grant.
+     */
+    openCompactionGrant(options?: GitvaultVaultHandleOptions): Promise<GitvaultCompactionGrant>;
+    /** Close this vault's compaction headroom grant directly — idempotent; `{closed: false}` when nothing was active. */
+    closeCompactionGrant(options?: GitvaultVaultHandleOptions): Promise<{
+        closed: boolean;
+    }>;
     /**
      * Publish a checkpoint covering the canonical refs, every root unexpired at
      * the cutoff, and the `HEAD` target — under a maintenance lease so a