run402 4.66.0 → 4.67.0

package/README.md

@@ -54,7 +54,7 @@ For typed `run402.deploy.ts` configs, pass `--manifest` explicitly because TypeS
 
 ### repos — host-blind encrypted git repos (zero deploy ceremony)
 
-One noun, twelve verbs (`repo` singular resolves identically). `run402 gitvault <verb>` answers `COMMAND_MOVED`/`COMMAND_REMOVED`.
+One noun, fourteen verbs (`repo` singular resolves identically). `run402 gitvault <verb>` answers `COMMAND_MOVED`/`COMMAND_REMOVED`.
 
 ```bash
 run402 init                                   # once per machine
@@ -68,7 +68,9 @@ run402 repos list --org org_1a2b3c
 run402 repos delete --project prj_xyz --force # refuses without --force while the vault holds generations
 ```
 
-A hosted git remote, encrypted before it leaves the machine — no deploy, no manifest, no app. `origin` is claimed additively — an existing `origin` is never touched, the run402 remote falls back to `run402` instead. Every mutating `repos` verb (`create`, `rename`, `delete`, `snapshot`, `policy`, `mirror`, `gc`) is CLI/OpenClaw-only by design — no MCP tool exists or will exist for them (one-shot recovery receipts, immutable generations, irreversible delete). Three READ-ONLY tools do exist — `repos_view`, `repos_list_heads`, `repos_fsck` — teaching only `repos` spellings. See `run402 repos --help` for the full tiered surface (common: `create`/`view`/`list`; occasional: `snapshot`/`mirror`/`recover`; lifecycle: `rename`/`delete`; maintenance: `fsck`/`gc`/`access`/`policy`), and the CLI reference's `repos` section for the terminal-loss statement and the progressive backup warning.
+A hosted git remote, encrypted before it leaves the machine — no deploy, no manifest, no app. `origin` is claimed additively — an existing `origin` is never touched, the run402 remote falls back to `run402` instead. Every mutating `repos` verb (`create`, `rename`, `delete`, `snapshot`, `policy`, `mirror`, `gc`, `handoff`, `resume`) is CLI/OpenClaw-only by design — no MCP tool exists or will exist for them (one-shot recovery receipts, immutable generations, irreversible delete, single-use bearer keys). Three READ-ONLY tools do exist — `repos_view`, `repos_list_heads`, `repos_fsck` — teaching only `repos` spellings. See `run402 repos --help` for the full tiered surface (common: `create`/`view`/`list`; occasional: `snapshot`/`mirror`/`recover`/`handoff`/`resume`; lifecycle: `rename`/`delete`; maintenance: `fsck`/`gc`/`access`/`policy`), and the CLI reference's `repos` section for the terminal-loss statement and the progressive backup warning.
+
+**Handoff / resume.** `run402 repos handoff [--note-file <path>]` captures the actual working tree (staged/unstaged/untracked, like `git stash push -u`) into the vault and mints a single-use bearer key (`kgh1_…`, printed to stdout exactly once); `run402 repos resume <kgh1_…>` claims it on another machine, clones fresh, and reapplies the exact dirty state with `git stash apply --index`. No shared keystore, no shared allowance — the key is the whole handoff. Sensitive untracked files (`.env`, `*.pem`, SSH/AWS/GPG dirs, …) are excluded from capture by default (`--include-sensitive <glob>` re-admits one). See the reference `run402.com/llms-cli.txt` for the full note-schema and flag reference.
 
 **Named addressing.** `run402 org slug <slug>` (owner-only, small one-time fee) claims an org's globally-unique, address-form slug, after which `run402::<slug>/<name>` addresses any repo under it — `git push` to a name that doesn't exist yet push-to-creates it. `run402 repos rename <name> [--project <id>]` claims the per-org-unique `<name>` half explicitly (no fee); `repos create` claims one automatically, best-effort, when the org already has a slug. Also CLI/SDK-only — no MCP tool.
 

package/gitvault-surface.json

@@ -1,5 +1,5 @@
 {
-  "surface_version": "4.66.0",
+  "surface_version": "4.67.0",
   "verbs": [
     "repos create",
     "repos list",
@@ -7,6 +7,8 @@
     "repos rename",
     "repos delete",
     "repos snapshot",
+    "repos handoff",
+    "repos resume",
     "repos policy",
     "repos mirror",
     "repos fsck",
@@ -71,6 +73,12 @@
     "byo_live": true,
     "recover_live": true,
     "allocation": "create_immediate",
-    "snapshot_dirty_default": "refuse"
+    "snapshot_dirty_default": "refuse",
+    "handoff_live": true,
+    "handoff_dirty_default": "capture",
+    "remote_schemes": [
+      "run402",
+      "kygit"
+    ]
   }
 }

package/lib/cold-start.mjs

@@ -0,0 +1,77 @@
+/**
+ * `cold-start.mjs` — the minimal x402/Base-Sepolia cold-start chain
+ * (kygit-handoff design D5): allowance → faucet → one x402 prototype
+ * payment. `repos create` (and so `kygit create`) folds this in when it is
+ * refused `NO_ACTIVE_TIER`, so `kygit create` on a genuinely fresh machine
+ * ends with a vault, no human signup, no cloud dashboard.
+ *
+ * This is the SAME shape `run402 init` already walks (allowance create →
+ * balance check → faucet → tier), factored down to the x402/Base-Sepolia
+ * default rail only (MPP/Tempo is `init`'s own separate concern — an agent
+ * hitting NO_ACTIVE_TIER mid-`repos create` gets the default rail, not a
+ * rail-selection prompt). `init.mjs`'s own richer flow (voucher redemption,
+ * rail switching, astro scaffolding, its own help/exit-code contract) is
+ * untouched; this module does not replace it, only the one path `repos
+ * create` needs when it discovers there is no tier and nothing else has
+ * set one up yet.
+ */
+import { readAllowance, saveAllowance } from "./config.mjs";
+import { getSdk } from "./sdk.mjs";
+
+const USDC_ABI = [{ name: "balanceOf", type: "function", stateMutability: "view", inputs: [{ name: "account", type: "address" }], outputs: [{ name: "", type: "uint256" }] }];
+const USDC_SEPOLIA = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
+
+/**
+ * @param {(line: string) => void} announce Called once per step, so the
+ *   caller can print each one it took (client-surface spec: "announcing
+ *   each step").
+ * @returns {Promise<{allowance_created: boolean, faucet_requested: boolean, tier: object|null}>}
+ */
+export async function foldColdStartChain(announce = () => {}) {
+  const out = { allowance_created: false, faucet_requested: false, tier: null };
+
+  let allowance = readAllowance();
+  if (!allowance) {
+    const { generatePrivateKey, privateKeyToAccount } = await import("viem/accounts");
+    const privateKey = generatePrivateKey();
+    const account = privateKeyToAccount(privateKey);
+    allowance = { address: account.address, privateKey, created: new Date().toISOString(), funded: false, rail: "x402" };
+    saveAllowance(allowance);
+    out.allowance_created = true;
+    announce(`allowance created: ${allowance.address}`);
+  }
+
+  const { createPublicClient, http } = await import("viem");
+  const { baseSepolia } = await import("viem/chains");
+  const client = createPublicClient({ chain: baseSepolia, transport: http() });
+  let balance = 0;
+  try {
+    balance = Number(await client.readContract({ address: USDC_SEPOLIA, abi: USDC_ABI, functionName: "balanceOf", args: [allowance.address] }));
+  } catch {
+    /* an RPC hiccup here is not fatal — the tier purchase below will surface a real payment failure if the balance really is zero */
+  }
+  if (balance === 0) {
+    announce("balance is 0 — requesting the testnet faucet");
+    // The faucet is throttled (0.25 USDC / 24h): a throttle refusal is
+    // surfaced with its wait and NEVER retried silently (client-surface
+    // spec) — this call is not wrapped in a swallowing catch.
+    await getSdk().allowance.faucet(allowance.address);
+    out.faucet_requested = true;
+    announce("faucet requested — waiting briefly for on-chain confirmation");
+    for (let i = 0; i < 30; i++) {
+      await new Promise((r) => setTimeout(r, 1000));
+      try {
+        balance = Number(await client.readContract({ address: USDC_SEPOLIA, abi: USDC_ABI, functionName: "balanceOf", args: [allowance.address] }));
+        if (balance > 0) break;
+      } catch {
+        /* keep polling */
+      }
+    }
+    saveAllowance({ ...allowance, funded: true, lastFaucet: new Date().toISOString() });
+  }
+
+  announce("subscribing to the prototype tier (one x402 testnet payment, perpetual)");
+  out.tier = await getSdk().tier.set("prototype");
+  announce(`prototype tier active${out.tier?.status === "already_active" ? " (already active)" : ""}`);
+  return out;
+}

package/lib/command-manifest.mjs

@@ -261,7 +261,7 @@ export const COMMAND_MANIFEST = [
   // COMMAND_REMOVED) redirect that dispatches nothing — see
   // RESERVED_SUBCOMMANDS below, and "gitvault" in SKIPPED_FAMILIES.
 
-  // ── repos (the consolidated 13-verb family) ─
+  // ── repos (the consolidated 15-verb family) ─
   // Every verb needs a real principal keystore and, for most, an allocated
   // repo and a local git working tree, so the gate runs structural checks
   // only — an in-process behavioral run would either no-op against the
@@ -274,6 +274,11 @@ export const COMMAND_MANIFEST = [
   { path: ["repos", "rename"], positionals: [p("new_name")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["my-notes"], runStyle: "sub", skipBehavioral: "claims a per-org-unique repo name against a live project" },
   { path: ["repos", "delete"], positionals: [], projectScoped: true, legacyPositionalProject: true, minimalArgs: [], runStyle: "sub", skipBehavioral: "irreversibly deletes a project after reading its live non-repo-resource state and vault generation count" },
   { path: ["repos", "snapshot"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "captures the cwd git working tree and publishes a signed head" },
+  // kygit-handoff: `handoff` captures a stash-shaped checkpoint and mints a
+  // single-use bearer key through a live gateway call; `resume` claims one
+  // (a real membership mutation) and writes into a fresh working tree.
+  { path: ["repos", "handoff"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "captures the cwd git working tree and mints a single-use bearer key against a live vault — never run against the gate's own checkout" },
+  { path: ["repos", "resume"], positionals: [p("key")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["kgh1_0000000000000000000000000000000000000000000000000000000000000000"], runStyle: "sub", skipBehavioral: "claims a live handoff (a real org-membership mutation) and clones a fresh working tree" },
   { path: ["repos", "policy"], positionals: [p("repos_policy")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["required"], runStyle: "sub", skipBehavioral: "owner + step-up mutation of the live project's activation policy" },
   // ONE flag-driven verb; `<destination>` is a real attribute (not a
   // sub-verb literal), so this stays a single manifest entry.

package/lib/doctor.mjs

@@ -705,6 +705,16 @@ export async function run(sub, args = []) {
         if (gv.remote && gv.remote.matches === false) {
           gaps.push(`the '${gv.remote.name}' git remote points at a different project than ${value.project_id} (${gv.remote.url})`);
         }
+        // kygit-handoff design D8: the mirror of the OLD `npm i -g @kychee/kygit`
+        // bug, pointing the other way — a `kygit::` remote with no
+        // `git-remote-kygit` helper on PATH means every push/clone/fetch
+        // in this checkout fails inside git with an opaque error.
+        if (gv.remote?.url?.startsWith("kygit::")) {
+          const { isExecutableOnPath } = await import("./path-lookup.mjs");
+          if (!isExecutableOnPath("git-remote-kygit")) {
+            gaps.push("this checkout's remote is kygit:: but git-remote-kygit is not on PATH — run `npm i -g @kychee/kygit`");
+          }
+        }
         // Echoed exactly as the SDK reported them — including the
         // doctor-persistent `grandfathered` advisory it owns.
         for (const w of gv.warnings ?? []) gaps.push(`${w.kind}: ${w.message}`);

package/lib/gitvault-capabilities.mjs

@@ -45,4 +45,16 @@ export const GITVAULT_CAPABILITIES = {
   // `repos snapshot` refuses to capture a dirty working tree
   // (`SNAPSHOT_DIRTY_TREE`) by default; `--allow-dirty` opts in explicitly.
   snapshot_dirty_default: "refuse",
+  // kygit-handoff (design D10): `repos handoff` / `repos resume` mint and
+  // claim a real single-use bearer key against a live gateway route —
+  // shipped, not aspirational.
+  handoff_live: true,
+  // `repos handoff` captures dirty work by DEFAULT (the opposite default
+  // from `snapshot_dirty_default` above) — two verbs, two defaults, one
+  // capture path (design D1).
+  handoff_dirty_default: "capture",
+  // Both remote door spellings resolve identically (design D8):
+  // `run402::` (canonical, plumbing) and `kygit::` (rendered by
+  // `@kychee/kygit` once it sets `RUN402_REMOTE_SCHEME=kygit`).
+  remote_schemes: ["run402", "kygit"],
 };

package/lib/org-context.mjs

@@ -93,6 +93,23 @@ function orgFromRoomEnv(env) {
   return raw.slice(0, slash);
 }
 
+/**
+ * `r402.orgId` from `cwd`'s LOCAL git config (kygit-handoff design D10) —
+ * best-effort, gracefully degrading like `findBindingKey`: no repository,
+ * no pin, or a shape-invalid value all answer `null` rather than throwing,
+ * so a bare directory or a checkout with no gitvault remote costs nothing.
+ */
+async function readGitvaultPinnedOrgId(cwd) {
+  try {
+    const { readPinnedGitvaultRepo } = await import("#sdk/node");
+    const pinned = await readPinnedGitvaultRepo(cwd);
+    const orgId = trimmed(pinned?.org_id);
+    return orgId && ORG_ID_RE.test(orgId) ? orgId : null;
+  } catch {
+    return null;
+  }
+}
+
 function listOrgsAction() {
   return nextAction("edit_request", {
     command: "run402 org list",
@@ -231,6 +248,15 @@ export async function resolveOrg(input = {}, opts = {}) {
   }
   if (bindingOrg) return { orgId: bindingOrg, source: "binding", sourceDetail: bindingHit.file };
 
+  // --- Class 3.5: gitvault local pin (kygit-handoff design D10) ------------
+  // `r402.orgId` in this checkout's LOCAL git config — written by every
+  // gitvault pin site (`repos create`, `resume`, address resolution), a
+  // rung below env/binding and above profile state: a checkout that IS a
+  // resumed/pinned vault should resolve its own org with zero configuration,
+  // but an explicit env var or a committed `.run402.json` binding still wins.
+  const pinnedOrg = await readGitvaultPinnedOrgId(cwd);
+  if (pinnedOrg) return { orgId: pinnedOrg, source: "gitvault_pin", sourceDetail: "r402.orgId (local git config)" };
+
   // --- Class 4: profile state ----------------------------------------------
   const selected = trimmed(coreGetActiveOrgId());
   if (selected) {

package/lib/path-lookup.mjs

@@ -0,0 +1,24 @@
+/**
+ * `path-lookup.mjs` — the tiny, dependency-free "is this executable on
+ * PATH" check kygit-handoff design D8 needs twice (`run402 doctor` and
+ * `repos view`, both naming `npm i -g @kychee/kygit` when a `kygit::`
+ * remote has no `git-remote-kygit` helper installed). No shell, no `which`
+ * subprocess — a plain directory scan mirrors what the OS loader itself
+ * does to resolve an unqualified command name.
+ */
+import { accessSync, constants } from "node:fs";
+import { delimiter, join } from "node:path";
+
+/** True iff `name` resolves to an executable file somewhere on `PATH`. Windows `PATHEXT` is out of scope — this CLI targets POSIX (`engines.node` + the hardened-git doc comments assume it) — so no `.exe`/`.cmd` suffix search. */
+export function isExecutableOnPath(name, env = process.env) {
+  const dirs = (env.PATH ?? "").split(delimiter).filter(Boolean);
+  for (const dir of dirs) {
+    try {
+      accessSync(join(dir, name), constants.X_OK);
+      return true;
+    } catch {
+      // not here — keep looking
+    }
+  }
+  return false;
+}

package/lib/path-lookup.test.mjs

@@ -0,0 +1,66 @@
+/**
+ * `path-lookup.mjs` — the PATH-executable probe `doctor.mjs`/`repos.mjs`'s
+ * `view()` both use to detect a `kygit::` remote with no `git-remote-kygit`
+ * helper installed (kygit-handoff design D8, mirroring
+ * `kygit/kygit.mjs`'s own `findRemoteHelper`).
+ */
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, chmodSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { isExecutableOnPath } from "./path-lookup.mjs";
+
+describe("isExecutableOnPath", () => {
+  it("finds an executable file on PATH", () => {
+    const dir = mkdtempSync(join(tmpdir(), "path-lookup-"));
+    try {
+      const bin = join(dir, "git-remote-kygit");
+      writeFileSync(bin, "#!/bin/sh\n");
+      chmodSync(bin, 0o755);
+      assert.equal(isExecutableOnPath("git-remote-kygit", { PATH: dir }), true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("returns false when the name exists but is not executable", () => {
+    const dir = mkdtempSync(join(tmpdir(), "path-lookup-"));
+    try {
+      const bin = join(dir, "git-remote-kygit");
+      writeFileSync(bin, "not executable");
+      chmodSync(bin, 0o644);
+      assert.equal(isExecutableOnPath("git-remote-kygit", { PATH: dir }), false);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("returns false when the name is nowhere on PATH", () => {
+    const dir = mkdtempSync(join(tmpdir(), "path-lookup-"));
+    try {
+      assert.equal(isExecutableOnPath("git-remote-kygit", { PATH: dir }), false);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("checks every directory on a multi-entry PATH, in order", () => {
+    const dirA = mkdtempSync(join(tmpdir(), "path-lookup-a-"));
+    const dirB = mkdtempSync(join(tmpdir(), "path-lookup-b-"));
+    try {
+      const bin = join(dirB, "git-remote-kygit");
+      writeFileSync(bin, "#!/bin/sh\n");
+      chmodSync(bin, 0o755);
+      assert.equal(isExecutableOnPath("git-remote-kygit", { PATH: `${dirA}:${dirB}` }), true);
+    } finally {
+      rmSync(dirA, { recursive: true, force: true });
+      rmSync(dirB, { recursive: true, force: true });
+    }
+  });
+
+  it("returns false for an empty or missing PATH rather than throwing", () => {
+    assert.equal(isExecutableOnPath("git-remote-kygit", {}), false);
+    assert.equal(isExecutableOnPath("git-remote-kygit", { PATH: "" }), false);
+  });
+});