run402 4.70.9 → 4.72.0

package/gitvault-surface.json

@@ -1,5 +1,5 @@
 {
-  "surface_version": "4.70.9",
+  "surface_version": "4.72.0",
   "verbs": [
     "repos create",
     "repos list",

package/lib/cold-start.mjs

@@ -14,6 +14,14 @@
  * 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.
+ *
+ * add-room-invite design D9 splits the funded-wallet half (allowance →
+ * faucet-if-empty → brief settlement poll) out as {@link ensureFundedWallet}
+ * — `rooms join <key>` needs exactly that half, with NO tier purchase and NO
+ * project creation (the claim itself is the one x402 payment that funds the
+ * onboarding). {@link foldColdStartChain} is now their composition —
+ * `ensureFundedWallet` followed by the tier step — so every EXISTING caller
+ * (`repos create`/`resume`/`join`) is unchanged.
  */
 import { readAllowance, saveAllowance } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
@@ -22,13 +30,16 @@ const USDC_ABI = [{ name: "balanceOf", type: "function", stateMutability: "view"
 const USDC_SEPOLIA = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
 
 /**
+ * Allowance → faucet-if-empty → brief settlement poll. NO tier purchase, no
+ * project creation — the caller decides what (if anything) to pay for next.
+ *
  * @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}>}
+ * @returns {Promise<{allowance_created: boolean, faucet_requested: boolean, address: string}>}
  */
-export async function foldColdStartChain(announce = () => {}) {
-  const out = { allowance_created: false, faucet_requested: false, tier: null };
+export async function ensureFundedWallet(announce = () => {}) {
+  const out = { allowance_created: false, faucet_requested: false, address: "" };
 
   let allowance = readAllowance();
   if (!allowance) {
@@ -40,6 +51,7 @@ export async function foldColdStartChain(announce = () => {}) {
     out.allowance_created = true;
     announce(`allowance created: ${allowance.address}`);
   }
+  out.address = allowance.address;
 
   const { createPublicClient, http } = await import("viem");
   const { baseSepolia } = await import("viem/chains");
@@ -48,7 +60,7 @@ export async function foldColdStartChain(announce = () => {}) {
   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 */
+    /* an RPC hiccup here is not fatal — the payment below will surface a real failure if the balance really is zero */
   }
   if (balance === 0) {
     announce("balance is 0 — requesting the testnet faucet");
@@ -70,8 +82,22 @@ export async function foldColdStartChain(announce = () => {}) {
     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;
 }
+
+/**
+ * `ensureFundedWallet` + the tier step. Unchanged from before the split —
+ * every existing caller (`repos create`/`resume`/`join`) keeps working with
+ * no edits.
+ *
+ * @param {(line: string) => void} announce Called once per step.
+ * @returns {Promise<{allowance_created: boolean, faucet_requested: boolean, tier: object|null}>}
+ */
+export async function foldColdStartChain(announce = () => {}) {
+  const funded = await ensureFundedWallet(announce);
+
+  announce("subscribing to the prototype tier (one x402 testnet payment, perpetual)");
+  const tier = await getSdk().tier.set("prototype");
+  announce(`prototype tier active${tier?.status === "already_active" ? " (already active)" : ""}`);
+  return { allowance_created: funded.allowance_created, faucet_requested: funded.faucet_requested, tier };
+}

package/lib/command-manifest.mjs

@@ -257,7 +257,14 @@ export const COMMAND_MANIFEST = [
   { path: ["subscriptions", "add"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub" },
   { path: ["subscriptions", "list"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub" },
   { path: ["subscriptions", "rm"], positionals: [p("subscription_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["r_1"], runStyle: "sub" },
-  { path: ["rooms", "join"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub" },
+  // add-room-invite design D9: `rooms join` is one verb, two forms — no
+  // positional registers a presence (the behaviorally-tested path, unchanged
+  // by the optional positional below since minimalArgs stays empty); a
+  // `kri1_…` positional claims a room seat first (a real x402 payment + an
+  // org-membership mutation), so that form is never behaviorally exercised
+  // here — the same reasoning `repos join`'s own row states.
+  { path: ["rooms", "join"], positionals: [p("key", { required: false })], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub" },
+  { path: ["rooms", "invite"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "mints a single-use bearer key from a live room, registering the inviter's presence and posting a real room message — never run against the gate's own checkout" },
   { path: ["rooms", "leave"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub" },
   { path: ["messages", "send"], positionals: [p("body")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["hello"], runStyle: "sub" },
   { path: ["messages", "list"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub" },
@@ -415,7 +422,7 @@ export const COMMAND_MANIFEST = [
   { path: ["email", "webhooks", "redrive"], positionals: [p("delivery_id")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["dlv_gate1"] },
 
   // ── message / agent / operator ───────────────────────────────────────────
-  { path: ["feedback", "send"], positionals: [p("words", { variadic: true })], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["hello", "from", "the", "gate"] },
+  { path: ["feedback", "send"], positionals: [p("words", { variadic: true })], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["hello", "from", "the", "gate"] },
   { path: ["agent", "contact"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["--name", "gate-agent"] },
   { path: ["agent", "status"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
   { path: ["agent", "verify-email"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },

package/lib/feedback.mjs

@@ -1,12 +1,12 @@
 import { allowanceAuthHeaders } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { assertKnownFlags, normalizeArgv, failUnknownSubcommand } from "./argparse.mjs";
+import { assertKnownFlags, normalizeArgv, failUnknownSubcommand, flagValue, positionalArgs } from "./argparse.mjs";
 
 const HELP = `run402 feedback — Send feedback to the Run402 developers
 
 Usage:
-  run402 feedback send <text>
+  run402 feedback send <text> [--project <project_id>] [--handle <handle>]
 
 Notes:
   - WRITE-ONLY: there is no inbox to read and no reply path. If you need an
@@ -18,8 +18,24 @@ Notes:
     inbox useful and prevent payload-dump misuse. Trim or summarize long
     content (e.g. stack traces) before sending.
 
+Finishing a deploy — the promotion consent flow:
+  When a commit or promote response reaches status "ready" with a public
+  site, it carries a next_actions entry of type hand_to_operator. That is
+  Run402 asking, through you, whether it may promote what your human built
+  on @run402com — for free, credited to your presence name (credited_as)
+  and to your human. Show your human both links (urls.site, urls.console),
+  relay the offer in your own words ("Run402 would like to promote what you
+  built..."), and ask yes or no. On yes, optionally ask for an X/Twitter
+  handle, then:
+    run402 feedback send "promote: yes" --project <project_id> [--handle <handle>]
+  Say no honestly if your human declines; nothing is sent. The offer is
+  asked once per project and stops after a "promote: yes" lands. If
+  credited_as is missing, join the project room with a name so future
+  offers credit you: run402 rooms join --name <name>
+
 Examples:
   run402 feedback send "Hello from my agent!"
+  run402 feedback send "promote: yes" --project prj_abc123 --handle @hobo_hi
 `;
 
 // Cap message body at a Twitter-ish but engineer-generous size: enough for
@@ -33,25 +49,45 @@ const SUB_HELP = {
   send: `run402 feedback send — Send feedback to the Run402 developers
 
 Usage:
-  run402 feedback send <text>
+  run402 feedback send <text> [--project <project_id>] [--handle <handle>]
 
 Arguments:
-  <text>              Message body (quote it; remaining args are joined with
-                      spaces if multiple positional words are provided)
+  <text>              Message body (quote it; remaining positional words are
+                      joined with spaces if multiple are provided)
+
+Flags:
+  --project <id>      Project this feedback concerns. Required to relay a
+                      promotion consent (the hand_to_operator next action
+                      from a deploy response) — the server resolves the
+                      project's site URL, org, and your presence name for
+                      the delivered message.
+  --handle <handle>   Your human's X/Twitter handle, at most 64 characters.
+                      Only used with --project; delivered as-is, stored
+                      nowhere else.
 
 Notes:
   - Requires an active tier (run402 tier set <tier>)
   - Requires an allowance (run402 allowance create)
   - Messages are capped at 8 KB (8192 bytes UTF-8) to keep the developer
     inbox useful and prevent payload-dump misuse.
+  - Finishing a deploy: when a commit/promote response carries a
+    hand_to_operator next action, show your human urls.site and
+    urls.console, relay that Run402 would like to promote what they built
+    on @run402com for free (credited to credited_as and to them), and ask
+    yes or no. On yes: run402 feedback send "promote: yes" --project <id>
+    [--handle <handle>]
 
 Examples:
   run402 feedback send "Hello from my agent!"
+  run402 feedback send "promote: yes" --project prj_abc123 --handle @hobo_hi
 `,
 };
 
-async function send(text) {
-  if (!text || typeof text !== "string") {
+async function send(args) {
+  const valueFlags = ["--project", "--handle"];
+  assertKnownFlags(args, [...valueFlags, "--help", "-h"], valueFlags);
+  const text = positionalArgs(args, valueFlags).join(" ");
+  if (!text) {
     fail({ code: "BAD_USAGE", message: "Missing message text." });
   }
   // Cap check runs BEFORE the allowance check so oversized payloads surface
@@ -66,11 +102,24 @@ async function send(text) {
       details: { bytes, max_bytes: MESSAGE_MAX_BYTES },
     });
   }
+  const projectId = flagValue(args, "--project");
+  const handle = flagValue(args, "--handle");
+  if (handle && handle.length > 64) {
+    fail({
+      code: "BAD_FLAG",
+      message: `--handle must be at most 64 characters, got ${handle.length}.`,
+      details: { flag: "--handle", length: handle.length, max: 64 },
+    });
+  }
   // Preserve the aggressive early exit when no allowance is configured.
   allowanceAuthHeaders("/feedback/v1");
 
+  const opts = {};
+  if (projectId) opts.project_id = projectId;
+  if (handle) opts.handle = handle;
+
   try {
-    await getSdk().admin.sendFeedback(text);
+    await getSdk().admin.sendFeedback(text, opts);
     console.log(JSON.stringify({
       bytes_sent: bytes,
       sent: true,
@@ -90,6 +139,5 @@ export async function run(sub, args) {
     failUnknownSubcommand("feedback", sub);
   }
   const parsedArgs = normalizeArgv(args);
-  assertKnownFlags(parsedArgs, ["--help", "-h"]);
-  await send(parsedArgs.join(" "));
+  await send(parsedArgs);
 }

package/lib/org-context.mjs

@@ -98,13 +98,19 @@ function orgFromRoomEnv(env) {
  * 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.
+ * Checks a real vault checkout's pin first (gated on `r402.repoId`), then
+ * falls back to the bare org/room pin a room-only `rooms join <key>` writes
+ * in a directory with no vault at all (add-room-invite design D10).
  */
 async function readGitvaultPinnedOrgId(cwd) {
   try {
-    const { readPinnedGitvaultRepo } = await import("#sdk/node");
+    const { readPinnedGitvaultRepo, readPinnedRoomBinding } = await import("#sdk/node");
     const pinned = await readPinnedGitvaultRepo(cwd);
     const orgId = trimmed(pinned?.org_id);
-    return orgId && ORG_ID_RE.test(orgId) ? orgId : null;
+    if (orgId && ORG_ID_RE.test(orgId)) return orgId;
+    const bare = await readPinnedRoomBinding(cwd);
+    const bareOrgId = trimmed(bare?.org_id);
+    return bareOrgId && ORG_ID_RE.test(bareOrgId) ? bareOrgId : null;
   } catch {
     return null;
   }

package/lib/rooms-context.mjs

@@ -36,13 +36,24 @@ import { describeRejectedValue } from "../core-dist/redact.js";
 export const ROOM_ENV = "RUN402_ROOM";
 export const PRESENCE_ENV = "RUN402_PRESENCE_ID";
 
-/** `r402.room` from `cwd`'s LOCAL git config (kygit-handoff design D10) — best-effort, `null` on any absence or failure. */
+/**
+ * `r402.room` from `cwd`'s LOCAL git config (kygit-handoff design D10) —
+ * best-effort, `null` on any absence or failure. Checks a real vault
+ * checkout's pin first (`readPinnedGitvaultRepo`, gated on `r402.repoId`
+ * being present), then falls back to the bare room/org pin `rooms join
+ * <key>` writes in a directory with NO vault at all (add-room-invite design
+ * D10) — `readPinnedGitvaultRepo` would otherwise see that pin as absent,
+ * since it never sets `r402.repoId`.
+ */
 async function readGitvaultPinnedRoom(cwd) {
   try {
-    const { readPinnedGitvaultRepo } = await import("#sdk/node");
+    const { readPinnedGitvaultRepo, readPinnedRoomBinding } = await import("#sdk/node");
     const pinned = await readPinnedGitvaultRepo(cwd);
     const room = typeof pinned?.room === "string" ? pinned.room.trim() : "";
-    return room.length > 0 ? room : null;
+    if (room.length > 0) return room;
+    const bare = await readPinnedRoomBinding(cwd);
+    const bareRoom = typeof bare?.room === "string" ? bare.room.trim() : "";
+    return bareRoom.length > 0 ? bareRoom : null;
   } catch {
     return null;
   }

package/lib/rooms.mjs

@@ -10,6 +10,7 @@
  * Gateway subsystem: add-agent-messaging (/orgs/v1/:org_id/rooms/:room_key/*).
  * Session presence cache: ./.run402/messaging.json (gitignore).
  */
+import { readFileSync } from "node:fs";
 import { getSdk } from "./sdk.mjs";
 import { fail, reportSdkError } from "./sdk-errors.mjs";
 import {
@@ -22,6 +23,7 @@ import {
   positionalArgs,
   requirePositionalCount,
   failUnknownSubcommand,
+  validateRegularFile,
 } from "./argparse.mjs";
 import {
   resolveRoom,
@@ -29,19 +31,23 @@ import {
   withPresenceRetry,
   registerFreshPresence,
   rememberPresence,
-  getRoomState,
   updateRoomState,
 } from "./rooms-context.mjs";
 import { resolveTaskLabel } from "./harness-context.mjs";
+import { ensureFundedWallet } from "./cold-start.mjs";
 
 export const IMPORTANCE = ["normal", "high"];
 
 const ROOM_FLAGS = ["--project", "--org", "--room"];
+const INVITE_VALUE_FLAGS = [...ROOM_FLAGS, "--note", "--note-file", "--expires-in"];
 
 const HELP = `run402 rooms — arrive in a room, see who is live, leave when done
 
 Usage:
   run402 rooms join [--name <name>] [--task <text>]
+  run402 rooms join <kri1_…> [--json]
+  run402 rooms invite [--note <text> | --note-file <path> | stdin]
+                      [--room <key>] [--expires-in <seconds>] [--json]
   run402 rooms leave [<presence_id>]
 
 Addressing:
@@ -50,6 +56,27 @@ Addressing:
   (omit both)       Resolved from RUN402_ROOM, a .run402.json binding, or the
                     wallet profile's selected org
 
+Room Invite (mint a key from the room you stand in, join through one):
+  - \`rooms invite\` mints a single-use \`kri1_…\` bearer key. Whoever claims it
+    FIRST becomes a permanent \`viewer\` of this org — the narrowest membership
+    that can message, and NEVER wider: there is no --role, and a viewer can
+    never be auto-admitted as a vault writer. To bring a collaborator into the
+    CODE (a vault, a checkpoint, write access), use \`run402 repos invite\`
+    instead — this door is talk-only.
+  - The key is printed to stdout EXACTLY ONCE (\`--json\` still keeps it out of
+    stderr). It is not recoverable if lost — mint a new one.
+  - \`rooms join <kri1_…>\` folds a funded-wallet chain (allowance → faucet if
+    empty → briefly wait for settlement) and pays a $0.01 testnet seat via
+    x402 to claim it — the payment IS the join, so a joiner with no funds
+    fails closed rather than joining unpaid. No tier is purchased, no project
+    is created. A same-payer replay never pays twice.
+  - After a key-form join: the host org becomes this wallet's current org,
+    and the binding is written where the next \`run402 messages wait\` reads
+    it from — \`.run402.json\` in a plain directory, or local git config
+    (\`r402.orgId\`/\`r402.room\`, excluded from git via .git/info/exclude) when
+    standing inside a git repository (never a .run402.json committed into a
+    stranger's clone).
+
 Notes:
   - join registers this session's presence and returns who else is live, what
     they are working on, and what they have claimed — the arrive-and-look call.
@@ -194,6 +221,261 @@ async function leave(argv) {
   }
 }
 
+async function readStdinTextLocal() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}
+
+/**
+ * `rooms invite`'s note is a PLAIN STRING, ≤4 KiB (design D7) — not the
+ * structured `kygit.invite-note.v1` JSON `run402 repos invite` reads: the
+ * gateway already reads every room message in plaintext, so there is
+ * nothing to seal and nothing to schema-validate beyond a length cap.
+ * Optional — `undefined` when nothing was supplied and stdin is a TTY.
+ */
+async function readRoomInviteNote(a) {
+  const inline = flagValue(a, "--note");
+  const noteFile = flagValue(a, "--note-file");
+  if (inline != null && noteFile != null) {
+    fail({ code: "BAD_USAGE", message: "Pass either --note or --note-file, not both.", hint: "run402 rooms invite --help" });
+  }
+  if (inline != null) return inline;
+  if (noteFile != null) {
+    validateRegularFile(noteFile, "--note-file");
+    return readFileSync(noteFile, "utf-8");
+  }
+  if (process.stdin?.isTTY) return undefined; // no note source given — the note is optional
+  const text = await readStdinTextLocal();
+  return text.trim().length > 0 ? text : undefined;
+}
+
+/**
+ * `run402 rooms invite` (add-room-invite design D7) — mint from the room
+ * this checkout stands in: register-or-resume the inviter's OWN presence
+ * FIRST (reusing {@link ensurePresence}, the same logic `rooms join`'s
+ * no-key form already runs) so the row carries `inviter_presence_id`, mint,
+ * post ONE room fact naming the invite id (never the key), echo the
+ * gateway's blast-radius warning to stderr, and print the `kri1_` key to
+ * stdout EXACTLY ONCE. A presence or fact failure is reported on the result
+ * and never voids the mint.
+ */
+async function invite(argv) {
+  const a = normalizeArgv(argv);
+  assertKnownFlags(a, [...INVITE_VALUE_FLAGS, "--json", "--help", "-h"], INVITE_VALUE_FLAGS);
+  requirePositionalCount(positionalArgs(a, INVITE_VALUE_FLAGS), INVITE_VALUE_FLAGS, {
+    min: 0, max: 0, command: "run402 rooms invite",
+  });
+
+  const room = await resolveRoom({
+    org: flagValue(a, "--org"), room: flagValue(a, "--room"), project: flagValue(a, "--project"),
+  });
+  const note = await readRoomInviteNote(a);
+  const expiresRaw = flagValue(a, "--expires-in");
+  const expiresInSeconds = expiresRaw != null ? parseIntegerFlag("--expires-in", expiresRaw, { min: 60, max: 86400 }) : undefined;
+  const asJson = a.includes("--json");
+
+  const sdk = getSdk();
+  try {
+    const { task } = await resolveTaskLabel({});
+    // design D7: register (or resume) the inviter's OWN presence BEFORE
+    // minting, so the row carries `inviter_presence_id`. A failure here is
+    // reported, never thrown — the mint proceeds without one.
+    let inviterPresence = null;
+    let inviterPresenceReport = { registered: false };
+    try {
+      const presence = await ensurePresence(room, { task });
+      inviterPresence = presence;
+      inviterPresenceReport = { registered: true, presence_id: presence.presence_id, name: presence.name };
+    } catch (e) {
+      inviterPresenceReport = { registered: false, error: e instanceof Error ? e.message : String(e) };
+    }
+
+    const result = await sdk.rooms.invite(room.orgId, room.roomKey, {
+      ...(note !== undefined ? { note } : {}),
+      ...(inviterPresence ? { inviterPresenceId: inviterPresence.presence_id } : {}),
+      ...(expiresInSeconds != null ? { expiresInSeconds } : {}),
+    });
+
+    for (const w of result.warnings ?? []) {
+      console.error(w.message ?? `${w.code}`);
+    }
+    console.error(`invite minted: role ${result.role}, expires ${result.expires_at}, room ${result.room?.room_key ?? room.roomKey}`);
+    console.error("recipient runs: run402 rooms join <key printed below>");
+
+    // design D7: post ONE room fact AFTER the mint succeeds — never before
+    // (a mint refusal must leave no orphan message), and never naming the
+    // key, only the invite id.
+    let roomFact = { posted: false, reason: "inviter presence was not registered" };
+    if (inviterPresence) {
+      const inviteShort = result.invite_id.slice(0, 8);
+      try {
+        const sent = await sdk.rooms.sendMessage(room.orgId, room.roomKey, {
+          body: `Invited another agent to this room (invite ${inviteShort}, expires ${result.expires_at}).`,
+          presenceId: inviterPresence.presence_id,
+          idempotencyKey: `room-invite:${result.invite_id}:minted`,
+        });
+        roomFact = { posted: true, message_id: sent.message_id, cursor: sent.cursor };
+        // The inviter's own fact must not wake the inviter's next `messages
+        // wait` — advance this checkout's stored cursor past it (best-effort).
+        try { updateRoomState(room.orgId, room.roomKey, { cursor: sent.cursor }); } catch { /* never fails a mint */ }
+      } catch (e) {
+        roomFact = { posted: false, reason: e instanceof Error ? e.message : String(e) };
+      }
+    }
+    if (inviterPresenceReport.registered === false) {
+      console.error(`note: your own presence was not registered (${inviterPresenceReport.error}) — the invite still mints and is claimable`);
+    }
+    if (roomFact.posted === false && inviterPresence) {
+      console.error(`note: the room fact was not posted (${roomFact.reason}) — the invite still mints and remains claimable`);
+    }
+
+    const finalResult = { ...result, inviter_presence: inviterPresenceReport, room_fact: roomFact };
+    if (asJson) {
+      printInviteResultJson(finalResult);
+    } else {
+      printInviteResultKeyOnly(result);
+    }
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+/** The key rides the JSON result — still stdout, still exactly once. */
+function printInviteResultJson(finalResult) {
+  console.log(JSON.stringify(finalResult, null, 2));
+}
+
+/** The key alone, so `KEY=$(run402 rooms invite ...)` works — everything else (the warning, the mint summary) is on stderr. */
+function printInviteResultKeyOnly(result) {
+  console.log(result.key);
+}
+
+/**
+ * `run402 rooms join <kri1_…>` (add-room-invite design D9/D10) — parse the
+ * key CLIENT-SIDE first (a wrong-kind vault key refuses by name before ANY
+ * network call, including the faucet), fold `ensureFundedWallet` (allowance
+ * → faucet-if-empty → brief settlement poll, announced on stderr), claim
+ * through the SDK's paid fetch, then leave arrival state exactly where
+ * `run402 messages wait` reads it: the host org as this wallet's current
+ * org; the binding written to `.run402.json` outside a git repository, or
+ * pinned in local git config (and `.run402/` excluded from git) inside one;
+ * the returned cursor persisted. There is no `--no-init` — the payment IS
+ * the claim.
+ */
+async function joinWithKey(key, a) {
+  const asJson = a.includes("--json");
+
+  // Parse-only pre-check (design D9): refuses a `kgh1_`/`kgi1_` vault key by
+  // name, synchronously, before `ensureFundedWallet` ever touches the
+  // network — the gateway (faucet included) must never be contacted for a
+  // wrong-kind key.
+  const { parseRoomInviteKey } = await import("#sdk/node");
+  try {
+    parseRoomInviteKey(key);
+  } catch (err) {
+    reportSdkError(err);
+    return;
+  }
+
+  try {
+    await ensureFundedWallet((line) => console.error(line));
+    const result = await getSdk().rooms.join(key);
+
+    // Arrival state (design D10) — best-effort throughout: the claim already
+    // succeeded, and none of this may fail a completed join.
+    try {
+      const { setSelectedOrgId } = await import("./org-context.mjs");
+      setSelectedOrgId(result.org_id);
+    } catch { /* best-effort */ }
+
+    const cwd = process.cwd();
+    let insideGitRepo = false;
+    try {
+      const { hardenedGit } = await import("#sdk/node");
+      await hardenedGit(cwd, ["rev-parse", "--git-dir"]);
+      insideGitRepo = true;
+    } catch {
+      insideGitRepo = false;
+    }
+    if (!insideGitRepo) {
+      try {
+        const { updateBindingFile } = await import("./wallet-context.mjs");
+        updateBindingFile(cwd, { org: result.org_id, room: result.room.room_key });
+      } catch { /* best-effort */ }
+    } else {
+      try {
+        const { pinRoomBinding, excludeMessagingCacheFromGit } = await import("#sdk/node");
+        await pinRoomBinding(cwd, { org_id: result.org_id, room_key: result.room.room_key });
+        await excludeMessagingCacheFromGit(cwd);
+      } catch { /* best-effort */ }
+    }
+    if (typeof result.cursor === "string") {
+      try { updateRoomState(result.org_id, result.room.room_key, { cursor: result.cursor }); } catch { /* best-effort */ }
+    }
+    // Live-proof defect A: cache the presence the CLAIM ITSELF registered,
+    // exactly the way `registerFreshPresence`'s no-key `join` already does
+    // via `rememberPresence` — without this, the joiner's very next
+    // coordination call (no cached presence_id) registers a SECOND presence
+    // for the same arrival. Guarded for an older gateway that predates the
+    // `presence` field: `rememberPresence` itself no-ops on anything that
+    // isn't `{presence_id: string, ...}`, so this never throws either way.
+    try { rememberPresence(result.org_id, result.room.room_key, result.presence); } catch { /* best-effort */ }
+
+    const nextActions = [...(result.next_actions ?? [])];
+    if (!nextActions.some((na) => na.type === "wait_room")) {
+      nextActions.push({ type: "wait_room", command: "run402 messages wait", why: "Block until the other agent speaks; silence returns who is still here." });
+    }
+
+    if (asJson) {
+      printClaimResultJson(result, nextActions);
+    } else {
+      renderClaimResultText(result, nextActions);
+    }
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+function printClaimResultJson(result, nextActions) {
+  console.log(JSON.stringify({ ...result, next_actions: nextActions }, null, 2));
+}
+
+function renderClaimResultText(result, nextActions) {
+  // The note is plain text, not a structured schema — printed verbatim as
+  // Markdown (it may already contain Markdown formatting the inviter wrote).
+  if (result.note) {
+    console.log(result.note);
+    console.error("");
+  }
+  console.error(`joined org ${result.org_id}, room ${result.room.room_key} — role ${result.membership.role}`);
+  if (result.deduplicated) {
+    console.error("note: this key was already claimed by this same payer — no second payment was made (safe replay)");
+  }
+  console.error(`seat: $${(result.seat.amount_usd_micros / 1_000_000).toFixed(2)} on ${result.seat.network}${result.seat.charge_id ? ` (charge ${result.seat.charge_id})` : ""}`);
+  if (result.inviter) {
+    const labels = [result.inviter.program, result.inviter.model].filter(Boolean).join("/");
+    const liveness = result.inviter.state === "active" ? "live" : result.inviter.state;
+    console.error(`invited by ${result.inviter.name}${labels ? ` (${labels})` : ""} — ${liveness}`);
+  } else {
+    console.error("invited by: unknown (the inviter never registered a presence)");
+  }
+  const others = (result.live_presences ?? []);
+  if (others.length > 0) console.error(`also live: ${others.map((p) => p.name).join(", ")}`);
+  const recent = result.recent_messages ?? [];
+  if (recent.length > 0) {
+    console.error(`recent messages (${recent.length}):`);
+    for (const m of recent.slice().reverse()) {
+      console.error(`  ${m.sender ?? "?"}: ${m.body_snippet ?? m.body ?? ""}`);
+    }
+  }
+  for (const na of nextActions) {
+    if (na.command) console.error(`next: ${na.command}${na.why ? ` — ${na.why}` : ""}`);
+  }
+}
+
 export async function run(sub, args) {
   const argv = Array.isArray(args) ? args : [];
   if (!sub || hasHelp([sub, ...argv])) {
@@ -202,7 +484,22 @@ export async function run(sub, args) {
   }
   switch (sub) {
     case "join": {
-      await who(argv);
+      // `run402 rooms join <kri1_…>` (add-room-invite design D9): a
+      // positional key form claims a seat and arrives; no positional keeps
+      // the existing arrive-and-look behavior unchanged.
+      const a = normalizeArgv(argv);
+      const positionals = positionalArgs(a, ["--name", "--task", ...ROOM_FLAGS]);
+      if (positionals.length === 0) {
+        await who(argv);
+        break;
+      }
+      assertKnownFlags(a, ["--json", "--help", "-h"], []);
+      requirePositionalCount(positionals, [], { min: 1, max: 1, command: "run402 rooms join [<kri1_…>]" });
+      await joinWithKey(positionals[0], a);
+      break;
+    }
+    case "invite": {
+      await invite(argv);
       break;
     }
     case "leave": {