run402 4.69.8 → 4.70.0

package/README.md

@@ -68,10 +68,12 @@ 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`, `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.
+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`, `invite`, `join`) 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`/`invite`/`join`; 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. On a wallet with no active tier, `resume` first folds the same cold-start chain `create` does (allowance → faucet → one x402 prototype payment); `--no-init` opts out, and the claim itself never waits on it. 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.
 
+**Invite / join.** The second claim kind beside handoff/resume: a Handoff passes the work on and the sender stops; an Invite grows the team while the sender keeps working. `run402 repos invite [--room <key>] [--note-file <path>]` captures the checkpoint exactly like `handoff` — the inviter's own worktree, index, branch, refs, and access are all untouched — registers the inviter's presence in a coordination room (the project's default room, or `--room <key>` for a named org room), mints a single-use bearer key (`kgi1_…`, printed to stdout exactly once), and posts ONE room message naming the checkpoint (never the key). `run402 repos join <kgi1_…>` folds the SAME cold-start chain `resume` does before the claim, clones fresh, restores the exact dirty state, pins the invite's room locally, registers its own presence, posts ONE arrival message, and reports the inviter (name, labels, liveness), the room's other live presences, and the last few messages. `run402 messages wait` is the room's blocking read from there — the agent's ear, never an error on silence. Neither `invite` nor `join` has an MCP tool, same reasoning as `handoff`/`resume`.
+
 **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.
 
 ### Allowance

package/gitvault-surface.json

@@ -1,5 +1,5 @@
 {
-  "surface_version": "4.69.8",
+  "surface_version": "4.70.0",
   "verbs": [
     "repos create",
     "repos list",
@@ -9,6 +9,8 @@
     "repos snapshot",
     "repos handoff",
     "repos resume",
+    "repos invite",
+    "repos join",
     "repos policy",
     "repos mirror",
     "repos fsck",
@@ -77,6 +79,8 @@
     "snapshot_dirty_default": "refuse",
     "handoff_live": true,
     "handoff_dirty_default": "capture",
+    "invite_live": true,
+    "join_live": true,
     "remote_schemes": [
       "run402",
       "kygit"

package/lib/command-manifest.mjs

@@ -296,6 +296,8 @@ export const COMMAND_MANIFEST = [
   // (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", "invite"], 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, posting a real room message — never run against the gate's own checkout" },
+  { path: ["repos", "join"], positionals: [p("key")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["kgi1_0000000000000000000000000000000000000000000000000000000000000000"], runStyle: "sub", skipBehavioral: "folds the cold-start chain, claims a live invite (a real org-membership mutation + one x402 payment), 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/gitvault-capabilities.mjs

@@ -53,6 +53,12 @@ export const GITVAULT_CAPABILITIES = {
   // from `snapshot_dirty_default` above) — two verbs, two defaults, one
   // capture path (design D1).
   handoff_dirty_default: "capture",
+  // kygit-invite (design D10): `repos invite` / `repos join` mint and claim
+  // a second claim kind — a real single-use bearer key against a live
+  // gateway route, admitting the recipient to a shared coordination room
+  // while the inviter keeps working.
+  invite_live: true,
+  join_live: true,
   // Both remote door spellings resolve identically (design D8):
   // `run402::` (canonical, plumbing) and `kygit::` (rendered by
   // `@kychee/kygit` once it sets `RUN402_REMOTE_SCHEME=kygit`).

package/lib/harness-context.mjs

@@ -23,6 +23,8 @@ import { randomBytes } from "node:crypto";
 
 export const SESSION_KEY_OVERRIDE_ENV = "RUN402_SESSION_KEY";
 export const TASK_FROM_TITLE_OPT_OUT_ENV = "RUN402_NO_TASK_FROM_TITLE";
+export const PROGRAM_OVERRIDE_ENV = "RUN402_PROGRAM";
+export const MODEL_OVERRIDE_ENV = "RUN402_MODEL";
 const SESSION_KEY_CACHE_RELATIVE_PATH = ".run402/session-key.json";
 const CLAUDE_SESSIONS_DIR_PARTS = ["Library", "Application Support", "Claude", "claude-code-sessions"];
 const CODEX_STATE_DB_PARTS = [".codex", "state_5.sqlite"];
@@ -81,6 +83,54 @@ export function resolveSessionKey({
   return { key: generated, source: "generated" };
 }
 
+/**
+ * Best-effort presence labels sourced from the harness this CLI invocation
+ * is running under (kygit-invite design D8) — `program`/`model` on
+ * `rooms join`, the implicit registration inside `messages send`, and every
+ * `repos invite`/`repos join` presence registration. Precedence: explicit
+ * env overrides first (`RUN402_PROGRAM`/`RUN402_MODEL`), then `program`
+ * inferred from the SAME harness signals {@link resolveSessionKey} already
+ * trusts (`CLAUDE_CODE_SESSION_ID` or `CLAUDECODE` -> `"claude-code"`;
+ * `CODEX_THREAD_ID` -> `"codex"`). `model` has no harness-exposed signal to
+ * infer from today (open question in kygit-invite design.md) — it is
+ * ALWAYS env-override-or-null, never guessed from `program`. Null stays
+ * null in both fields: a placeholder label would be a Faithful breach.
+ */
+export function resolveHarnessLabels({ env = process.env } = {}) {
+  const programOverride = env[PROGRAM_OVERRIDE_ENV]?.trim();
+  const modelOverride = env[MODEL_OVERRIDE_ENV]?.trim();
+  let program = programOverride || null;
+  if (!program) {
+    if (env.CLAUDE_CODE_SESSION_ID?.trim() || env.CLAUDECODE?.trim()) {
+      program = "claude-code";
+    } else if (env.CODEX_THREAD_ID?.trim()) {
+      program = "codex";
+    }
+  }
+  const model = modelOverride || null;
+  return { program, model };
+}
+
+/**
+ * Persist a session key into ANOTHER checkout's cache. `repos join` uses it
+ * so the freshly cloned checkout resolves the SAME session identity the join
+ * registered its presence under (kygit-invite design D5), instead of
+ * generating a stranger's key on the first `messages wait` run there. Only
+ * meaningful for the generated-key path — a harness-provided id is found in
+ * the environment first regardless of cwd, so callers skip this for those
+ * sources. Best-effort, never throws; returns whether the write landed.
+ */
+export function persistSessionKey(cwd, key, { mkdirSyncImpl = mkdirSync, writeFileSyncImpl = writeFileSync } = {}) {
+  if (typeof key !== "string" || !key) return false;
+  try {
+    mkdirSyncImpl(join(cwd, ".run402"), { recursive: true });
+    writeFileSyncImpl(join(cwd, SESSION_KEY_CACHE_RELATIVE_PATH), `${JSON.stringify({ session_key: key }, null, 2)}\n`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Bounded-depth search for a file named `filename` under `root`. Stops at
  * the first match, or after MAX_TITLE_SEARCH_DIRS directories visited,

package/lib/messages.mjs

@@ -33,7 +33,7 @@ import {
   getRoomState,
   updateRoomState,
 } from "./rooms-context.mjs";
-import { resolveTaskLabel } from "./harness-context.mjs";
+import { resolveTaskLabel, resolveHarnessLabels } from "./harness-context.mjs";
 
 export const IMPORTANCE = ["normal", "high"];
 
@@ -44,6 +44,7 @@ const HELP = `run402 messages — room-visible messages between agents
 Usage:
   run402 messages send <body> [--to <names>] [--ack] [--thread <id>]
   run402 messages list [--unread] [--cursor <mcr_...>] [--thread <id>]
+  run402 messages wait [--addressed-to me] [--thread <id>] [--timeout <s>] [--cursor <mcr_...>]
   run402 messages get <message_id>
   run402 messages ack <message_id>
 
@@ -62,6 +63,17 @@ Notes:
     your existing presence (no rename) when one is resolvable, and --task —
     or, if omitted, your harness's own thread title — refreshes what the room
     sees you working on.
+  - wait is the session's EAR: it blocks until a message lands past this
+    checkout's stored cursor (or --cursor), using the gateway's held read
+    when available and plain polling when an older gateway answers at once —
+    the output shape never changes. Default timeout 120s, max 600s (a
+    coding harness's own shell-call limit — a wait that outlives the tool
+    call is a wait the agent never hears). Silence is an answer, never an
+    error: it exits 0 with an empty messages[] and \`live_presences[]\`
+    naming who is still in the room, so "did they leave" needs no second
+    call. The returned cursor is persisted, exactly like \`list\` — the next
+    wait resumes right after the last message seen. Join the room first
+    with \`run402 rooms join\` if you want a chosen name.
   - The room itself — arriving, leaving, seeing who is live — is \`run402 rooms\`.
 `;
 
@@ -118,6 +130,10 @@ async function send(args) {
   });
   try {
     const { task } = await resolveTaskLabel({ explicitTask: flagValue(a, "--task") });
+    // kygit-invite design D8: the implicit presence-creation path (no
+    // presenceId cached yet) carries harness-derived labels too — never
+    // guessed, null stays null.
+    const { program, model } = resolveHarnessLabels();
     const result = await withPresenceRetry(room.orgId, room.roomKey, (presenceId, sessionKey) =>
       getSdk().rooms.sendMessage(room.orgId, room.roomKey, {
         body: positionals[0],
@@ -131,6 +147,8 @@ async function send(args) {
         sessionKey,
         requestedName: flagValue(a, "--name") ?? undefined,
         task: task ?? undefined,
+        program: program ?? undefined,
+        model: model ?? undefined,
       }),
       { name: flagValue(a, "--name"), task });
     rememberPresence(room.orgId, room.roomKey, result.sender_presence, flagValue(a, "--name"));
@@ -177,6 +195,66 @@ async function list(args) {
   }
 }
 
+/**
+ * `run402 messages wait` — the agent's ear (kygit-invite design D7). Blocks
+ * until a matching message lands past this checkout's stored cursor, or the
+ * timeout elapses, using the shared `rooms.waitForMessages` (held read when
+ * the gateway supports it, bounded polling otherwise). Stdout is ALWAYS one
+ * JSON document — silence is a normal, exit-0 answer, never a thrown error.
+ */
+async function wait(args) {
+  const a = normalizeArgv(args);
+  const valueFlags = [...ROOM_FLAGS, "--thread", "--timeout", "--cursor", "--addressed-to"];
+  assertKnownFlags(a, [...valueFlags, "--help", "-h"], valueFlags);
+  requirePositionalCount(positionalArgs(a, valueFlags), valueFlags, {
+    min: 0, max: 0, command: "run402 messages wait", missing: "",
+  });
+  const addressedTo = flagValue(a, "--addressed-to");
+  if (addressedTo != null) assertAllowedValue(addressedTo, ["me"], "--addressed-to");
+  const timeoutRaw = flagValue(a, "--timeout");
+  // Default 120s, max 600s: a Claude Code shell call dies at 600s, so a wait
+  // that outlives the tool call is a wait the agent never hears (design D7).
+  const timeoutSeconds = timeoutRaw != null ? parseIntegerFlag("--timeout", timeoutRaw, { min: 1, max: 600 }) : 120;
+  const room = await resolveRoom({
+    org: flagValue(a, "--org"), room: flagValue(a, "--room"), project: flagValue(a, "--project"),
+  });
+  const stored = getRoomState(room.orgId, room.roomKey).cursor;
+  const cursor = flagValue(a, "--cursor") ?? (typeof stored === "string" ? stored : undefined);
+  try {
+    const { task } = await resolveTaskLabel({});
+    const me = await ensurePresence(room, { task });
+    console.error(`waiting in ${room.roomKey} as ${me.name} (timeout ${timeoutSeconds}s)…`);
+    const result = await getSdk().rooms.waitForMessages(room.orgId, room.roomKey, {
+      ...(cursor !== undefined ? { cursor } : {}),
+      threadId: flagValue(a, "--thread") ?? undefined,
+      addressedTo: addressedTo === "me" ? "me" : undefined,
+      presenceId: me.presence_id,
+      timeoutMs: timeoutSeconds * 1000,
+    });
+    if (typeof result.cursor === "string") {
+      updateRoomState(room.orgId, room.roomKey, { cursor: result.cursor });
+    }
+    console.log(JSON.stringify({
+      messages: result.messages,
+      cursor: result.cursor,
+      has_more: result.has_more,
+      settled: result.settled,
+      waited_ms: result.waited_ms,
+      live_presences: result.live_presences,
+    }, null, 2));
+    if (result.settled) {
+      console.error(`${result.messages.length} message(s) arrived.`);
+    } else {
+      const live = result.live_presences ?? [];
+      console.error(live.length > 0
+        ? `silence — still live: ${live.map((p) => p.name).join(", ")}.`
+        : "silence — nobody else is currently live in this room.");
+    }
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
 async function get(args) {
   const a = normalizeArgv(args);
   assertKnownFlags(a, [...ROOM_FLAGS, "--help", "-h"], ROOM_FLAGS);
@@ -232,6 +310,10 @@ export async function run(sub, args) {
       await list(argv);
       break;
     }
+    case "wait": {
+      await wait(argv);
+      break;
+    }
     case "get": {
       await get(argv);
       break;