run402 4.68.3 → 4.69.0

package/lib/remote-helper-session.mjs

@@ -84,12 +84,12 @@
  *     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` 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
+ *   - `push` REPAIRS a DANGLING vault HEAD and otherwise never moves it.
+ *     A fresh vault defaults its HEAD symref to `refs/heads/main`. Without
+ *     the repair, a first push of any OTHER branch would leave that symref
+ *     naming a ref that never exists, and the first
+ *     `git clone` warns "remote HEAD refers to nonexistent ref" and checks
+ *     out an EMPTY tree — publishing lands, but nothing is 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
@@ -98,7 +98,7 @@
  *     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
+ *   - `option dry-run true` 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,
@@ -210,12 +210,11 @@ const endBlock = () => process.stdout.write("\n");
 const note = (line) => process.stderr.write(`git-remote-run402: ${line}\n`);
 
 /**
- * Wallet selection (kychee-com/run402#558). Before this, this file called
- * `getSdk()` directly and ran NO wallet selection at all — a `.run402.json`
- * binding, and even the global `wallets use` default, silently never
- * reached it; only the `RUN402_WALLET` env layer worked, so a bound
- * checkout's very next `git push run402 main` after a correctly-bound
- * `run402 repos create` used the WRONG wallet's (usually empty) allowance.
+ * Wallet selection. Calling `getSdk()` directly here would run NO wallet
+ * selection at all — a `.run402.json` binding, and even the global
+ * `wallets use` default, would silently never reach it; only the
+ * `RUN402_WALLET` env layer would work, so a bound checkout's `git push
+ * run402 main` would use the WRONG wallet's (usually empty) allowance.
  *
  * Shares `resolveWalletCore`/`enforceWalletExistsCore` with the CLI
  * (`cli/lib/wallet-context.mjs`) — ONE implementation, minus the CLI's
@@ -261,7 +260,7 @@ function walletSourceLabel(resolved) {
  * an env var or a binding DID name one, the remedy is actively harmful —
  * `run402 init` recreates the DEFAULT wallet's allowance, a DIFFERENT
  * wallet than the one that was actually resolved and whose allowance is
- * actually missing/broken (kychee-com/run402#558's second defect). Replace
+ * actually missing/broken. Replace
  * it with the resolved wallet's name and how selection works, so the fix is
  * "correct the selection" rather than "recreate the wrong wallet".
  */
@@ -358,7 +357,7 @@ export function partitionProtectedRefPushes(specs) {
 
 /**
  * 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:
+ * — 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
@@ -432,11 +431,10 @@ export function shouldRunAutoGc(threshold, generationsSinceCheckpoint) {
  * `process.cwd()` only in CALLER convention, never inside the SDK's own
  * `open()` (which sets it ONLY when `options.repo_dir !== undefined`).
  * Building the auto-gc target from `{ ...target }` alone — omitting
- * `repo_dir` — made every real post-push auto-gc cycle fail closed with
+ * `repo_dir` — makes every real post-push auto-gc cycle fail closed with
  * `GITVAULT_REPO_DIR_REQUIRED`, silently degrading to the advisory on
- * EVERY push, live in production shape, until a push-latency guard bench
- * finally drove the real trigger path (found 2026-08-31; `repos gc`'s CLI
- * wrapper passes repo_dir explicitly and never hit this).
+ * EVERY push. `repos gc`'s CLI wrapper passes repo_dir explicitly, so it
+ * never exercises this path.
  */
 export function buildAutoGcCompactionTarget(target, repoDir) {
   return { ...target, repo_dir: repoDir };
@@ -462,10 +460,8 @@ async function main(argv, { onBackgroundWork } = {}) {
   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.
+  // `option dry-run true` is a REAL dry run — see `handleOption`'s
+  // `dry-run` case and `runPush` below. It never reports a fake success.
   let dryRun = false;
 
   /**
@@ -533,8 +529,8 @@ async function main(argv, { onBackgroundWork } = {}) {
   }
 
   /**
-   * 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.
+   * What to tell a human when we refuse. `git clone` is the case that
+   * fails here; naming the working alternative beats a bare error.
    */
   function repoRefusalNote(err) {
     note(describeError(err));
@@ -757,7 +753,7 @@ async function main(argv, { onBackgroundWork } = {}) {
     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
     // plain `git clone` prints "cloned an empty repository" with no hint the
-    // history exists (blind-acceptance finding, 2026-08-28). Say where it is.
+    // history exists. Say where it is.
     const refNames = Object.keys(refs);
     if (refNames.length > 0 && !refNames.some((r) => r.startsWith("refs/heads/"))) {
       note(`this vault has no branch heads yet — its history lives on ${refNames.sort()[0]}`);
@@ -898,9 +894,7 @@ async function main(argv, { onBackgroundWork } = {}) {
     // convention, not an SDK fallback (`open()` only sets repo_dir when
     // `options.repo_dir !== undefined`). Omitting it here made every real
     // post-push auto-gc cycle fail closed with GITVAULT_REPO_DIR_REQUIRED,
-    // silently degrading to the advisory on every push (found live,
-    // 2026-08-31, via a push-latency guard bench that finally drove the
-    // ACTUAL trigger path instead of a synthetic `repos gc` invocation).
+    // silently degrading to the advisory on every push.
     const compactionTarget = buildAutoGcCompactionTarget(target, repoDir);
     const runCycle = async () => {
       const sdk = getCachedSdk();
@@ -966,7 +960,7 @@ async function main(argv, { onBackgroundWork } = {}) {
       }
 
       if (dryRun) {
-        // kychee-com/run402#565: READ-ONLY resolution — `openVault`, never
+        // 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
@@ -1034,7 +1028,7 @@ async function main(argv, { onBackgroundWork } = {}) {
           force: spec.force && expectedOld !== null,
         });
       }
-      // Repair a DANGLING HEAD from this batch's own branches (#568) — see
+      // Repair a DANGLING HEAD from this batch's own branches — 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).
@@ -1114,7 +1108,7 @@ async function main(argv, { onBackgroundWork } = {}) {
         out("ok");
         return;
       case "dry-run":
-        // kychee-com/run402#565: a REAL dry run — `runPush` runs the actual
+        // 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.

package/lib/repos.mjs

@@ -95,6 +95,7 @@ Maintenance:
   run402 repos access repair [--project <id>] [--repo <repo_id>] --recipient-state-version <n> --recipient-revocation-version <n>
   run402 repos access revoke-key <principal_id> [--project <id>] [--repo <repo_id>]
   run402 repos access declare-exposure [--project <id>] [--repo <repo_id>]
+  run402 repos access repin   [--project <id>] [--repo <repo_id>] --principal <principal_id> --fingerprint <ek_fingerprint>
   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)
 
@@ -407,6 +408,10 @@ Options:
                     verified prefix, so a budget-exceeded run resumes; a
                     --no-write run does not, since nothing was persisted)
   --mirror          fsck: also run the keyless mirror integrity probe
+  --no-reconcile    view/access: defer the session-start envelope fulfilment
+                    (a key-holder normally wraps every pending member on its
+                    first ordinary read); reported as deferred_by_local_policy,
+                    never as coverage. fsck/recover never wrap regardless.
   --no-write        fsck: audit mode — compute and report the real answer,
                     persist neither local trust pin
   --submit          gc: submit the planned prune intent. Requires
@@ -629,6 +634,29 @@ async function formatRepoHuman(s, mirror) {
       : "can decrypt (read-only — no signing key)";
   lines.push(`This machine: ${decryptPart}. Policy: ${s.gitvault_policy ?? "(none)"}`);
 
+  // gitvault-multi-writer (rev 47) task 6.1 — the writer roster, one line
+  // per writer: `writer_set` is the chain-verified set exactly as `verify`/
+  // `fsck` would derive it (never re-verified here — this is `view`'s own
+  // side-effect-free read of the vault RECORD's already-verified pointer).
+  // `pending_writers` is the reverse direction (eligible org members not
+  // yet admitted); `read_only_terminal` (D228) is the forced sole-writer-
+  // removal terminal — surfaced prominently since a vault in that state
+  // still serves reads but can never accept another push until recovered.
+  const writerSet = s.vault.writer_set;
+  if (writerSet) {
+    lines.push(`Writers (${writerSet.writers.length}):`);
+    for (const w of writerSet.writers) {
+      lines.push(`  ${w.writer_key_id} — admitted generation ${decimal(w.admitted_generation)} (${w.authorization_kind})`);
+    }
+    if (s.vault.read_only_terminal) {
+      lines.push("  ⚠ read-only terminal: the last writer was removed — this vault serves reads but cannot accept a push until a new writer is admitted through a recovery path.");
+    }
+    const pendingWriters = s.vault.pending_writers ?? [];
+    if (pendingWriters.length > 0) {
+      lines.push(`Pending writers (${pendingWriters.length}, eligible but not yet admitted): ${pendingWriters.map((p) => p.writer_key_id).join(", ")} — run 'run402 repos access sync' if this machine is already a writer.`);
+    }
+  }
+
   // gitvault-mirror-default: the SDK-computed vault_unmirrored finding is
   // echoed verbatim (never rephrased here) — informational, never blocking.
   if (mirror?.finding) {
@@ -855,10 +883,9 @@ async function createProvision(name, dir, a) {
 
   // A genuinely bare machine has no allowance file at all, and the NO_ALLOWANCE
   // precheck below would refuse before the provision call could ever answer
-  // NO_ACTIVE_TIER — so the cold-start fold (design D5) never ran for the one
-  // case it was written for. Found 2026-09-02 by driving `repos create` on a
-  // fresh config dir. Fold first when there is no wallet; `--no-init` keeps
-  // the bare refusal.
+  // NO_ACTIVE_TIER, so the cold-start fold would never reach the one case it
+  // exists for. Fold first when there is no wallet; `--no-init` keeps the
+  // bare refusal.
   if (!isCoreApiTarget() && !loadLiveControlPlaneSession() && !readAllowance() && !a.includes("--no-init")) {
     console.error("no wallet on this machine — folding the cold-start chain (allowance -> faucet -> prototype tier)");
     try {
@@ -1066,7 +1093,7 @@ async function list(args) {
 
 async function view(args) {
   const a = normalizeArgv(args);
-  assertKnownFlags(a, [...COMMON_VALUE_FLAGS, "--human", "-v", "--verbose", "--help", "-h"], COMMON_VALUE_FLAGS);
+  assertKnownFlags(a, [...COMMON_VALUE_FLAGS, "--human", "--no-reconcile", "-v", "--verbose", "--help", "-h"], COMMON_VALUE_FLAGS);
   requirePositionalCount(a, COMMON_VALUE_FLAGS, { min: 0, max: 0, command: "run402 repos view", missing: "" });
   const human = a.includes("--human");
   if (human && a.includes("--json")) {
@@ -1077,7 +1104,7 @@ async function view(args) {
   try {
     // Design D3: `view` NEVER passes `refs: true` — it is side-effect-free
     // by construction, not by convention. Materialization belongs to `fsck`.
-    const s = await sdk.gitvault.status(target);
+    const s = await sdk.gitvault.status({ ...target, ...(a.includes("--no-reconcile") ? { reconcile: "deferred" } : {}) });
     const isByo = s.vault?.storage_profile === "byo";
     let mirror = null;
     if (s.repo_id) {
@@ -1493,8 +1520,7 @@ async function snapshot(args) {
     if (manifestOutPath != null) writeManifestOut(manifestOutPath, result);
     // Snapshot-only vault (no branch head published): a plain `git clone`
     // of this vault prints "cloned an empty repository" with no hint the
-    // snapshot exists (blind-acceptance finding, 2026-08-28). Name the
-    // restore path in the result itself.
+    // snapshot exists. Name the restore path in the result itself.
     const resultRefNames = Object.keys(result.refs ?? {});
     const snapshotOnly = resultRefNames.length > 0 && !resultRefNames.some((r) => r.startsWith("refs/heads/"));
     const payload = summarizeSnapshotPayload(result, { verbose, manifestPath: manifestOutPath });
@@ -1674,6 +1700,12 @@ async function handoff(args) {
       console.error(w.message ?? `${w.code}`);
     }
     console.error(`handoff minted: role ${result.minted_role}, expires ${result.expires_at}`);
+    // gitvault-multi-writer (rev 47) task 6.4 — a handoff is now also a
+    // WRITER admission, not just a checkout pass: the recipient signs its
+    // own future pushes with a NEW key this vault's chain recognizes as a
+    // writer the moment `resume` claims it (design D4 — a grant minted here,
+    // a two-signature acceptance the recipient's own resume completes).
+    console.error(`the recipient becomes a WRITER on this vault the moment they resume — their own key signs future pushes, not yours.`);
     console.error(`recipient runs: kygit resume <key printed below>`);
     if (asJson) {
       printJson(sdk, result);
@@ -1781,8 +1813,7 @@ async function resume(args) {
     key = (await readStdinText()).trim();
     if (!key) fail({ code: "BAD_USAGE", message: "Missing the Handoff Key on stdin.", hint: "Pipe the kgh1_… key, or pass it as a positional argument." });
   }
-  // Decided 2026-09-02 (Tal; amends kygit-handoff design D5's "none on
-  // resume"): a resumed agent is a NEW run402 wallet, and the loop is the
+  // A resumed agent is a NEW run402 wallet, and the loop is the
   // point — so on a wallet with no active tier `resume` folds the same
   // cold-start chain `create` does (allowance → faucet → one x402
   // prototype payment, announced) BEFORE the claim. The claim itself needs
@@ -1804,6 +1835,13 @@ async function resume(args) {
       }
       console.error("");
       console.error(`resumed into ${result.restored.dir} (branch ${result.restored.branch})`);
+      // gitvault-multi-writer (rev 47) task 6.4 — this checkout's own writer
+      // activation (design D5): the outcome is "active" either way, whether
+      // this call submitted a fresh activation head or a prior attempt's
+      // already landed (crash-resumable, task 5.6's own idempotent-skip).
+      if (result.writer_activation) {
+        console.error(`writer: ${result.writer_activation.outcome} (generation ${result.writer_activation.generation})`);
+      }
       if (result.deduplicated) console.error("note: this key was already claimed by this same principal — the ORIGINAL envelope was reused (safe replay)");
       for (const na of result.next_actions ?? []) {
         if (na.command) console.error(`next: ${na.command}${na.why ? ` — ${na.why}` : ""}`);
@@ -2355,7 +2393,7 @@ function printMemberCustodySummary(mc) {
 
 async function accessRead(args) {
   const a = normalizeArgv(args);
-  assertKnownFlags(a, [...COMMON_VALUE_FLAGS, "--human", "-v", "--verbose", "--help", "-h"], COMMON_VALUE_FLAGS);
+  assertKnownFlags(a, [...COMMON_VALUE_FLAGS, "--human", "--no-reconcile", "-v", "--verbose", "--help", "-h"], COMMON_VALUE_FLAGS);
   requirePositionalCount(a, COMMON_VALUE_FLAGS, { min: 0, max: 0, command: "run402 repos access", missing: "" });
   const human = a.includes("--human");
   if (human && a.includes("--json")) {
@@ -2364,7 +2402,7 @@ async function accessRead(args) {
   const sdk = getSdk();
   const target = await vaultTarget(a);
   try {
-    const result = await sdk.gitvault.access(target);
+    const result = await sdk.gitvault.access({ ...target, ...(a.includes("--no-reconcile") ? { reconcile: "deferred" } : {}) });
     // gitvault-recovery-custody — the "you" block: YOUR OWN wrapper custody
     // (kind/state per wrapper, custody scheme), rendered inside the family's
     // custody roster read. Principal-scoped, so it needs your control-plane
@@ -2523,8 +2561,8 @@ async function accessRevokeKey(args) {
  * self-contained; the FOLLOW-UP rotation it authorizes is NOT auto-run
  * here, because — same confirmed gap as `access repair` — the D194
  * counters it must be fenced against have no client-visible read for this
- * reason value either. This is the rekey remedy the exposed-key incident
- * needs: declare here, then rotate (via `--recipient-state-version`/
+ * reason value either. This is the rekey remedy for an exposed key:
+ * declare here, then rotate (via `--recipient-state-version`/
  * `--recipient-revocation-version` once known, e.g. from platform staff).
  *
  * **If a `/confirm`/`/repin` receipt is already pending** (a directory
@@ -2532,7 +2570,7 @@ async function accessRevokeKey(args) {
  * the rotation is outstanding), do NOT call `publishPinManifestUpdate`
  * separately — that call is itself an ORDINARY admission and is itself
  * refused `EPOCH_ROTATION_REQUIRED` for as long as this declaration stays
- * outstanding (reproduced live in production 2026-08-27). Pass the receipt
+ * outstanding. Pass the receipt
  * to `r.gitvault.rotateEpoch({..., pending_confirmations: [{principal_id,
  * ek_fingerprint, receipt}]})` instead — it rides the SAME head as the
  * rotation this declaration requires, publishing durably without needing a
@@ -2541,6 +2579,33 @@ async function accessRevokeKey(args) {
  * excluded from THIS rotation's own envelope set (D196) and becomes
  * eligible starting at the NEXT rotation.
  */
+/**
+ * `repos access repin --principal <id> --fingerprint <ek_…>` — a KEY-HOLDER
+ * explicitly accepts a recipient's CHANGED key (gitvault-agent-envelopes D3).
+ * The session-start reconcile refuses `pinned_key_mismatch` and never
+ * bypasses it, not even after an owner's revoke — acceptance names the new
+ * fingerprint (the out-of-band verification point) and moves the local pin.
+ * Adapter only: `sdk.gitvault.acceptRecipientKeyChange`.
+ */
+async function accessRepin(args) {
+  const a = normalizeArgv(args);
+  assertKnownFlags(a, [...COMMON_VALUE_FLAGS, "--principal", "--fingerprint", "--help", "-h"], [...COMMON_VALUE_FLAGS, "--principal", "--fingerprint"]);
+  requirePositionalCount(a, [...COMMON_VALUE_FLAGS, "--principal", "--fingerprint"], { min: 0, max: 0, command: "run402 repos access repin --principal <principal_id> --fingerprint <ek_fingerprint>", missing: "" });
+  const principalId = flagValue(a, "--principal");
+  const fingerprint = flagValue(a, "--fingerprint");
+  if (!principalId || !fingerprint) {
+    fail({ code: "BAD_USAGE", message: "repin needs --principal <principal_id> and --fingerprint <ek_fingerprint> (read the fingerprint back with the recipient — it is public data).", hint: "run402 repos access repin --principal <principal_id> --fingerprint <ek_fingerprint>" });
+  }
+  const sdk = getSdk();
+  const target = await vaultTarget(a);
+  try {
+    const result = await sdk.gitvault.acceptRecipientKeyChange({ ...target, principal_id: principalId, new_fingerprint: fingerprint });
+    console.log(JSON.stringify({ ...result, next_actions: [{ type: "retry", command: "run402 repos view", why: "the next ordinary gitvault operation on this machine wraps the vault to the accepted key" }] }, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
 async function accessDeclareExposure(args) {
   const a = normalizeArgv(args);
   assertKnownFlags(a, [...COMMON_VALUE_FLAGS, "-v", "--verbose", "--help", "-h"], COMMON_VALUE_FLAGS);
@@ -2561,11 +2626,48 @@ async function accessDeclareExposure(args) {
   }
 }
 
+// gitvault-multi-writer (rev 47) task 6.4 — an on-demand tail on the
+// existing `access` family: `r.gitvault.reconcile()` admits every eligible
+// `pending_writers[]` candidate right now, rather than waiting for this
+// machine's next push/deploy to do it as a side effect. Same shape as
+// `accessRepin` above — one SDK call, echo the result, a next_action
+// pointing at the normal follow-up.
+async function accessSync(args) {
+  const a = normalizeArgv(args);
+  assertKnownFlags(a, [...COMMON_VALUE_FLAGS, "--human", "-v", "--verbose", "--help", "-h"], COMMON_VALUE_FLAGS);
+  requirePositionalCount(a, COMMON_VALUE_FLAGS, { min: 0, max: 0, command: "run402 repos access sync", missing: "" });
+  const human = a.includes("--human");
+  if (human && a.includes("--json")) {
+    fail({ code: "BAD_USAGE", message: "--human cannot be combined with --json.", details: { flags: a.filter((arg) => arg === "--human" || arg === "--json") } });
+  }
+  const sdk = getSdk();
+  const target = await vaultTarget(a);
+  try {
+    const result = await sdk.gitvault.reconcile(target);
+    if (!human) console.log(JSON.stringify(result, null, 2));
+    if (!result.eligible) {
+      console.error("this machine's key is not an active writer on this vault — nothing to sync. Ask a current writer to admit you (org membership at role developer+ and a published signing key make you eligible).");
+    } else if (result.admitted.length === 0) {
+      console.error("no pending writer candidates — nothing to sync.");
+    } else {
+      for (const w of result.admitted) console.error(`admitted ${w.writer_key_id} (${w.principal_id}) at generation ${w.generation}.`);
+    }
+    if (result.skipped.length > 0) {
+      for (const s of result.skipped) console.error(`skipped ${s.writer_key_id} (${s.principal_id}): ${s.reason}`);
+    }
+    printVerboseStats(a, sdk);
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
 async function access(args) {
   const a = normalizeArgv(args);
   if (a[0] === "repair") return accessRepair(a.slice(1));
   if (a[0] === "revoke-key") return accessRevokeKey(a.slice(1));
   if (a[0] === "declare-exposure") return accessDeclareExposure(a.slice(1));
+  if (a[0] === "repin") return accessRepin(a.slice(1));
+  if (a[0] === "sync") return accessSync(a.slice(1));
   return accessRead(a);
 }
 

package/lib/rooms-context.mjs

@@ -54,7 +54,7 @@ const STATE_FILE = "messaging.json";
 /**
  * Resolve the addressed room to { orgId, roomKey } (one SDK lookup at most).
  *
- * A room is a PAIR, and this function owns the pair. What it no longer owns is
+ * A room is a PAIR, and this function owns the pair. It does NOT own
  * the org half of its own fallback: below the explicit forms, the org comes
  * from the shared chain in `org-context.mjs` (flag → env → binding → profile
  * selection → active project) while the room key comes from `--room`, the
@@ -71,8 +71,8 @@ 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.
+      // A malformed RUN402_ROOM is a value we know nothing about (a leaked
+      // secret included), so it must not be echoed raw.
       fail({
         code: "BAD_USAGE",
         message: `${ROOM_ENV} must be "<org_id>/<room_key>".`,
@@ -239,8 +239,8 @@ export async function registerFreshPresence(orgId, roomKey, { name, task } = {})
  * REGISTER a replacement, and retry ONCE with it. The registration is
  * explicit on purpose: a bare call cannot mean "me" from the credential
  * alone, because the server cannot tell one credential's concurrent sessions
- * apart — it would either guess (adopting a sibling session's presence,
- * run402-private#663) or refuse. Asking — by session identity when we have
+ * apart — it would either guess (adopting a sibling session's presence)
+ * or refuse. Asking — by session identity when we have
  * one, by explicit (re-)registration when we don't — is unambiguous.
  */
 export async function withPresenceRetry(orgId, roomKey, call, { name, task } = {}) {

package/lib/sdk-errors.mjs

@@ -6,8 +6,7 @@
  * `process.exit(1)`. Preserves specific behaviors:
  *   - `ProjectCredentialNotFound` → preserves
  *     `code: "PROJECT_CREDENTIAL_NOT_FOUND"` and local-cache provenance.
- *   - HTML / non-JSON error bodies → `body_preview` field (first 500 chars),
- *     matching GH-84 behavior.
+ *   - HTML / non-JSON error bodies → `body_preview` field (first 500 chars).
  *   - Network errors → `{status: "error", message: "..."}`.
  *
  * For client-side validation failures (missing flags, bad JSON, no-op

package/lib/status.mjs

@@ -137,7 +137,7 @@ export async function run(args = []) {
   const walletName = getActiveProfile();
   const walletMeta = readMeta(walletName);
 
-  // GH-32 follow-up: balances are grouped under one object so the on-chain and
+  // Balances are grouped under one object so the on-chain and
   // prepaid-credit numbers are unambiguous and rail-legible.
   //   - on_chain_usd_micros / on_chain_token: on-chain USDC (x402) or pathUSD
   //     (mpp), null if the RPC read failed

package/lib/update-check.test.mjs

@@ -448,7 +448,7 @@ describe("CLI update notices and scheduler", () => {
     assert.equal(check.status, "skipped");
   }));
 
-  // ─── the real TTL, and what happens at every edge of it (kychee-com/run402#561) ──
+  // ─── the real TTL, and what happens at every edge of it ──
   //
   // THE DEFECT (grok dogfood, 4.38.0 installed): `run402 doctor` reported
   // the latest CLI as 4.17.5 from a cache dated Aug 1 — three minor versions

package/lib/wallet-context.mjs

@@ -133,10 +133,10 @@ 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
+// mistake is a typo, but a live Base-mainnet private key pasted into
+// RUN402_WALLET (a NAME field, not a key field) is a demonstrated case, and
+// echoing the raw value prints it 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.
@@ -167,11 +167,11 @@ function assertValidName(name, origin) {
  * Shared verbatim by `resolveWallet` below (the CLI wrapper: `--wallet` flag
  * layered on top, failures routed through `fail()`) AND by
  * `git-remote-run402` (no flag layer — the helper has no argv flags at all
- * — failures routed through its own protocol-safe error reporting). This is
- * THE fix for kychee-com/run402#558: before it, `git-remote-run402` called
- * `getSdk()` directly and ran no wallet selection at all, so a `.run402.json`
- * binding — and even the global `wallets use` default — silently never
- * reached it; only the `RUN402_WALLET` env layer worked.
+ * — failures routed through its own protocol-safe error reporting). Calling
+ * `getSdk()` directly instead would run no wallet selection at all, so a
+ * `.run402.json` binding — and even the global `wallets use` default —
+ * would silently never reach the helper; only the `RUN402_WALLET` env layer
+ * would work.
  *
  * Precedence beneath an optional flag (highest first): `RUN402_WALLET` /
  * `RUN402_PROFILE` env > nearest `.run402.local.json`/`.run402.json` binding
@@ -197,7 +197,7 @@ export function resolveWalletCore({ walletFlag, env = {}, cwd = process.cwd(), c
 
   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)
+    // unvalidated (possibly secret-shaped)
     // 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`

package/lib/wallet-context.test.mjs

@@ -175,10 +175,9 @@ describe("resolveWallet — conflict + validation", () => {
   // 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.
+  // fleet-coordination convention (`.run402.json`). 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
@@ -201,7 +200,7 @@ describe("resolveWallet — conflict + validation", () => {
     rmSync(dir, { recursive: true, force: true });
   });
 
-  // kychee-com/run402-private#640: a live Base-mainnet private key was pasted
+  // 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
@@ -254,8 +253,8 @@ describe("enforceWalletExists — fail closed", () => {
   // 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.
+  // the second, easy-to-miss half of the 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

package/lib/wallets.mjs

@@ -72,7 +72,7 @@ function out(obj) {
   console.log(JSON.stringify(obj, null, 2));
 }
 
-// See core-dist/redact.js's doc comment (kychee-com/run402-private#640): a
+// See core-dist/redact.js's doc comment: 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.
@@ -176,7 +176,7 @@ function cmdUse(args) {
   if (name !== DEFAULT && !profileExists(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).
+    // is the backstop against echoing it here.
     fail({ code: "WALLET_NOT_FOUND", message: `No local wallet named '${describeRejectedValue(name)}'.`, hint: "run402 wallets list", details: { name: describeRejectedValue(name) } });
   }
   setDefaultWallet(name);

package/lib/webhooks.mjs

@@ -152,7 +152,7 @@ async function update(args) {
   if (!url && !eventsRaw) {
     fail({ code: "BAD_USAGE", message: "Provide at least --url or --events" });
   }
-  // GH-192: scheme-only local validation. Server-side SSRF defenses are out
+  // scheme-only local validation. Server-side SSRF defenses are out
   // of scope for the CLI (private-IP / DNS rebinding / IMDS belongs on the
   // gateway). `validateWebhookUrl` is a no-op when `url` is null/undefined,
   // so partial updates that change only `--events` still work.
@@ -186,7 +186,7 @@ async function register(args) {
       hint: "run402 email webhooks register --url <url> --events <e1,e2>",
     });
   }
-  // GH-192: validate scheme locally before any network call. Catches
+  // validate scheme locally before any network call. Catches
   // javascript:/file:/http:/data: schemes that the gateway would reject
   // anyway, but with a friendlier round-trip-free error.
   validateWebhookUrl(url, "--url");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "4.68.3",
+  "version": "4.69.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/allowance-auth.js

@@ -115,7 +115,7 @@ export function buildSIWxAuthHeaders(opts) {
  * @param path - API path (e.g. "/projects/v1") used to build the SIWE uri field.
  */
 export function getAllowanceAuthHeaders(path, allowancePath) {
-    // GH-194: readAllowance throws on a malformed-shape allowance file. The
+    // readAllowance throws on a malformed-shape allowance file. The
     // CLI's higher-level readAllowance wrapper surfaces this as a structured
     // BAD_ALLOWANCE_FILE envelope; here we preserve the public contract that
     // this helper returns SIWxAuthHeaders | null. Re-throw so callers above

package/sdk/core-dist/allowance.js

@@ -14,7 +14,7 @@ const PRIVATE_KEY_RE = /^0x[a-fA-F0-9]{64}$/;
  *   - the file exists but is not parseable JSON (preserve existing UX —
  *     consumers print "no_allowance" and tell the user to run init)
  *
- * Throws a structured `Error` (GH-194) when the file parses as JSON but the
+ * Throws a structured `Error` when the file parses as JSON but the
  * shape is wrong (missing/wrong-type/wrong-length fields). Without this guard
  * downstream callers crash with raw stack traces:
  *   - `cli/lib/status.mjs` reaches for `allowance.address.toLowerCase()`

package/sdk/core-dist/config.js

@@ -83,10 +83,10 @@ function assertSafeProfileName(name) {
         return;
     if (!isValidProfileName(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).
+        // most likely mistake is a typo, but a Base-mainnet private key pasted
+        // into RUN402_WALLET (a NAME field) is a demonstrated case, and echoing
+        // the raw value propagates it into terminals, logs, and 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.