run402 4.32.0 → 4.33.0

package/cli.mjs

@@ -18,62 +18,79 @@ https://run402.com
 Usage:
   run402 <command> [subcommand] [options]
 
-Commands:
-  up          Provision/link/deploy the current app with SDK orchestration
+Commands, grouped by when you reach for them:
+
+SET UP — get an agent funded and entitled
   init        Set up allowance, funding, and check tier status (x402 default)
   init mpp    Set up with MPP payment rail (Tempo Moderato testnet)
-  pay         Call an arbitrary x402-priced URL with a bounded payment
-  redeem      Redeem a promo code for run402 credit
-  status      Show full account state (allowance, balance, tier, projects)
   wallets     Manage multiple named wallets (list, new, use, rename, bind, import)
-  credentials Manage local credential material (project-keys)
   allowance   Manage your agent allowance (create, fund, balance, status)
   tier        Manage tier subscription (status, set)
+  redeem      Redeem a promo code for run402 credit
+  pay         Call an arbitrary x402-priced URL with a bounded payment
+
+BUILD & SHIP — the app and everything it serves
+  up          Provision/link/deploy the current app with SDK orchestration
   projects    Manage projects (provision, list, get, sql, delete)
+  deploy      Unified deploy operations (requires active tier)
   apply       Alias for deploy apply; supports --rehearse for migration rehearsal
+  functions   Manage serverless functions (deploy, invoke, logs, list, delete)
+  secrets     Manage project secrets (set, list, delete)
+  sites       Deploy static sites
+  assets      Direct-to-S3 asset storage (put, get, ls, rm, sign, diagnose) — up to 5 TiB
+  domains     Manage ProjectDomain lifecycle (connect, check, repair, wait)
+  subdomains  Manage custom subdomains (claim, list, delete)
+
+OPERATE — what happened, and is it healthy
+  events      What happened to your project since you last looked (cursored feed)
+  errors      Grouped error fingerprints + a promote/revert verdict (release-baselined)
+  logs        Fetch function logs by request id (--request-id req_...)
+  status      Show full account state (allowance, balance, tier, projects)
+  doctor      Health and config diagnostics (JSON by default; includes --buzz preflight)
+  service     Run402 service health and availability (status, health)
   snapshots   Create/list/restore/delete project data snapshots
   branches    Create/list/renew/delete contained project branches
+
+COORDINATE — work alongside other agents and humans
+  messages    Room-visible messages between agents (send/list/get/ack)
+  rooms       Arrive in a room and see who is live (join)
+  claims      Say what you're working on before you collide (advisory)
+  escalations Page a human when you judge you need one (raise/list/ack)
+  feedback    Send feedback to the Run402 developers (free with an active tier)
+
+AUTHORITY — who may act, and with what credential
+  credentials Manage local credential material (project-keys)
+  delegates   Scoped deploy credentials for agents (create, list, revoke, rotate)
+  grants      Per-project capability grants for agent/CI principals (create, revoke)
+  org         Org membership, invites & audit (whoami, list, member, invite, audit)
+  identity    Public proof-backed external agent identity links
+  auth        Manage project user authentication (magic link, passwords, settings)
+  ci          Link GitHub Actions OIDC deploy bindings
+  operator    Operator (human/email) session — login, then overview across your wallets
+
+DELIVER — reach a human when something happens
+  notifications  Delivery records, preferences, channels and routing rules
+  webhook-secret Rotate the operator webhook signing secret
+  email          Send template-based emails from your project
+
+PLATFORM — everything else, and the things still finding a home
   admin       Platform-admin operations (lease-perpetual, archive, reactivate)
+  billing     Email organizations, Stripe tier checkout, email packs
+  contracts   KMS signers ($0.04/day rental + $0.000005/sign)
+  jobs        Submit and inspect platform-managed jobs
+  transfer    Two-party project transfer (init, preview, list, accept, cancel)
   cloud       Cloud portability archive export (archives create/download/status)
   archives    Inspect and verify portable project archives locally
-  core        Local Run402 Core import helpers
-  deploy      Unified deploy operations (requires active tier)
-  ci          Link GitHub Actions OIDC deploy bindings
-  transfer    Two-party project transfer (init, preview, list, accept, cancel)
-  org         Org membership, invites & audit (whoami, list, member, invite, audit)
-  identity    Public proof-backed external agent identity links
-  buzz        Buzz human/community/agent control-plane workflows
-  grants      Per-project capability grants for agent/CI principals (create, revoke)
-  delegates   Scoped deploy credentials for agents (create, list, revoke, rotate)
-  events      What happened to your project since you last looked (cursored feed)
-  rooms       Coordinate with the other agents on your project (who/send/ack)
-  escalations Page a human when you judge you need one (raise/list/ack)
-  claims      Say what you're working on before you collide (advisory)
   gitvault    Host-blind encrypted Git remote (init/status/push/policy/compact/prune/verify)
-  errors      Grouped error fingerprints + a promote/revert verdict (release-baselined)
-  jobs        Submit and inspect platform-managed jobs
-  functions   Manage serverless functions (deploy, invoke, logs, list, delete)
-  secrets     Manage project secrets (set, list, delete)
-  assets      Direct-to-S3 asset storage (put, get, ls, rm, sign, diagnose) — up to 5 TiB
-  sites       Deploy static sites
-  cdn         CloudFront CDN diagnostics (wait-fresh) for public asset URLs
-  subdomains  Manage custom subdomains (claim, list, delete)
-  domains     Manage ProjectDomain lifecycle (connect, check, repair, wait)
+  buzz        Buzz human/community/agent control-plane workflows
   apps        Browse and manage the app marketplace
   ai          AI translation and moderation tools
   image       Generate AI images via x402 or MPP micropayments
-  email       Send template-based emails from your project
-  feedback    Send feedback to the Run402 developers (free with an active tier)
-  auth        Manage project user authentication (magic link, passwords, settings)
-  billing     Email organizations, Stripe tier checkout, email packs
-  contracts   KMS signers ($0.04/day rental + $0.000005/sign)
-  agent       Manage agent identity (contact info)
-  operator    Operator (human/email) session — login, then overview across your wallets
-  service     Run402 service health and availability (status, health)
+  cdn         CloudFront CDN diagnostics (wait-fresh) for public asset URLs
   cache       Inspect and invalidate the SSR origin cache (inspect, invalidate)
-  doctor      Health and config diagnostics (JSON by default; includes --buzz preflight)
+  agent       Manage agent identity (contact info)
+  core        Local Run402 Core import helpers
   dev         Run Astro dev with Run402 env + credentials in scope
-  logs        Fetch function logs by request id (--request-id req_...)
 
 Global options (any command):
   --wallet <name>   Select a named wallet for this command (see 'run402 wallets')
@@ -282,6 +299,11 @@ switch (cmd) {
     await run(sub, rest);
     break;
   }
+  case "messages": {
+    const { run } = await import("./lib/messages.mjs");
+    await run(sub, rest);
+    break;
+  }
   case "rooms": {
     const { run } = await import("./lib/rooms.mjs");
     await run(sub, rest);
@@ -384,7 +406,7 @@ switch (cmd) {
       details: { was: "message", now: "feedback", reserved: "the `message` noun is reserved for addressed agent/human messaging" },
       next_actions: [
         { type: "edit_request", command: "run402 feedback send \"<text>\"", why: "Send feedback to the Run402 developers." },
-        { type: "edit_request", command: "run402 rooms send \"<text>\"", why: "Message the other agents working in this room." },
+        { type: "edit_request", command: "run402 messages send \"<text>\"", why: "Message the other agents working in this room." },
         { type: "edit_request", command: "run402 escalations raise \"<text>\"", why: "Page a human and wait for a named one to take it." },
       ],
     });

package/lib/claims.mjs

@@ -62,7 +62,7 @@ Options:
   --all             list: include released/expired history.
 
 Tip: claim before you edit, release when you hand off — and put the handoff
-     in \`run402 rooms send\` so the room's timeline tells the story.
+     in \`run402 messages send\` so the room's timeline tells the story.
 
 Examples:
   run402 claims create repo:src/auth/** --note "migrating to passkeys"
@@ -97,7 +97,7 @@ async function create(args) {
     console.log(JSON.stringify(created, null, 2));
     const conflicts = Array.isArray(created.conflicts) ? created.conflicts : [];
     if (conflicts.length > 0) {
-      console.error(`Granted with ${conflicts.length} conflict(s) — advisory, nothing is blocked. Coordinate via run402 rooms send.`);
+      console.error(`Granted with ${conflicts.length} conflict(s) — advisory, nothing is blocked. Coordinate via run402 messages send.`);
     }
   } catch (err) {
     reportSdkError(err);

package/lib/command-manifest.mjs

@@ -224,11 +224,11 @@ export const COMMAND_MANIFEST = [
 
   // ── events / errors (flat, merged runners) ───────────────────────────────
   { path: ["events"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "merged" },
-  { path: ["rooms", "who"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub" },
-  { path: ["rooms", "send"], positionals: [p("body")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["hello"], runStyle: "sub" },
-  { path: ["rooms", "list"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub" },
-  { path: ["rooms", "get"], positionals: [p("message_id")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["msg_1"], runStyle: "sub" },
-  { path: ["rooms", "ack"], positionals: [p("message_id")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["msg_1"], runStyle: "sub" },
+  { path: ["rooms", "join"], 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" },
+  { path: ["messages", "get"], positionals: [p("message_id")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["msg_1"], runStyle: "sub" },
+  { path: ["messages", "ack"], positionals: [p("message_id")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["msg_1"], runStyle: "sub" },
   { path: ["escalations", "raise"], positionals: [p("reason")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["a human is needed"], runStyle: "sub" },
   { path: ["escalations", "list"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub" },
   { path: ["escalations", "get"], positionals: [p("escalation_id")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["esc_1"], runStyle: "sub" },
@@ -423,8 +423,28 @@ export const SKIPPED_FAMILIES = {
   "apply": "pure alias for `deploy apply` (covered by the deploy family)",
   "dev": "interactive wrapper that spawns `astro dev`",
   // RESERVED, not dispatched: every `run402 message …` fails with
-  // COMMAND_REMOVED pointing at `feedback send` / `rooms send` /
+  // COMMAND_REMOVED pointing at `feedback send` / `messages send` /
   // `escalations raise`. It has no subcommands to manifest because it takes
   // none — the noun is being held for addressed agent/human messaging.
   "message": "reserved noun; fails with COMMAND_REMOVED (renamed to `feedback`)",
 };
+
+/**
+ * SUBCOMMAND spellings kept alive only to answer `COMMAND_REMOVED`.
+ *
+ * A retired spelling still needs a `case` branch — that branch IS the redirect,
+ * and without it a caller gets a generic "unknown subcommand" instead of being
+ * told where the verb went. But it is not a command: it dispatches nothing and
+ * belongs in no capability mapping, so the inventory gate must not demand one.
+ *
+ * The family-level equivalent is SKIPPED_FAMILIES above. This exists because
+ * legible-cli-surface retired four spellings INSIDE a family rather than a
+ * whole family, which the family list could not express.
+ */
+export const RESERVED_SUBCOMMANDS = {
+  "rooms:who": "renamed to `rooms join` — an interrogative must not name a write",
+  "rooms:send": "moved to `messages send` — the verb acts on a message",
+  "rooms:list": "moved to `messages list` — the verb acts on a message",
+  "rooms:get": "moved to `messages get` — the verb acts on a message",
+  "rooms:ack": "moved to `messages ack` — the verb acts on a message",
+};

package/lib/messages.mjs

@@ -0,0 +1,227 @@
+/**
+ * `run402 messages` — the room-visible messages agents coordinate with.
+ *
+ * Split out of `run402 rooms` by legible-cli-surface: four of that family's
+ * five verbs acted on a MESSAGE, not on a room. The container was the noun and
+ * the thing you actually handle had none.
+ *
+ * Gateway subsystem: add-agent-messaging (/orgs/v1/:org_id/rooms/:room_key/*).
+ * Org-scoped; a project id names that project's DEFAULT room, so inside a
+ * checkout the room resolves from the active project with zero flags. JSON
+ * envelopes to stdout (pipe contract); flags map 1:1 to the HTTP surface.
+ * Session presence + read cursor cache: ./.run402/messaging.json (gitignore).
+ */
+import { getSdk } from "./sdk.mjs";
+import { fail, reportSdkError } from "./sdk-errors.mjs";
+import {
+  normalizeArgv,
+  hasHelp,
+  assertKnownFlags,
+  assertAllowedValue,
+  parseIntegerFlag,
+  flagValue,
+  positionalArgs,
+  requirePositionalCount,
+  failUnknownSubcommand,
+} from "./argparse.mjs";
+import {
+  resolveRoom,
+  cachedPresenceId,
+  withPresenceRetry,
+  registerFreshPresence,
+  rememberPresence,
+  getRoomState,
+  updateRoomState,
+} from "./rooms-context.mjs";
+
+export const IMPORTANCE = ["normal", "high"];
+
+const ROOM_FLAGS = ["--project", "--org", "--room"];
+
+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 get <message_id>
+  run402 messages ack <message_id>
+
+Addressing (all subcommands):
+  --project <id>    That project's DEFAULT room (the room key IS the project id)
+  --org <id> --room <key>   A named org room
+  (omit both)       Resolved from RUN402_ROOM, a .run402.json binding, or the
+                    wallet profile's selected org
+
+Notes:
+  - to/cc route ATTENTION, not access: every agent in the room reads every
+    message. --ack asks the recipient to confirm they saw it.
+  - Messages are durable. An agent that is not running now reads them when it
+    next wakes.
+  - The room itself — arriving, leaving, seeing who is live — is \`run402 rooms\`.
+`;
+
+async function ensurePresence(room, { name, task } = {}) {
+  const existing = cachedPresenceId(room.orgId, room.roomKey);
+  if (existing) {
+    // Trust, but verify: a cached id whose presence aged out (or was swept)
+    // would otherwise ride along until the first send failed. Arrival is the
+    // right moment to notice — it costs one GET, once per session.
+    const live = await stillLive(room, existing);
+    if (live) return { ...live, presence_id: existing, registered: false };
+  }
+  const registration = await registerFreshPresence(room.orgId, room.roomKey, { name, task });
+  return { ...registration, registered: true };
+}
+
+/** The cached presence if it is still live in the room, else null. */
+async function stillLive(room, presenceId) {
+  try {
+    const presence = await getSdk().rooms.getPresence(room.orgId, room.roomKey, presenceId);
+    const expiresAt = Date.parse(presence?.expires_at ?? "");
+    return Number.isFinite(expiresAt) && expiresAt > Date.now() ? presence : null;
+  } catch {
+    // Unknown/unreachable presence: fall through to registering a fresh one
+    // rather than failing arrival.
+    return null;
+  }
+}
+
+async function send(args) {
+  const a = normalizeArgv(args);
+  const valueFlags = [...ROOM_FLAGS, "--to", "--cc", "--thread", "--importance", "--idempotency-key", "--name", "--task"];
+  assertKnownFlags(a, [...valueFlags, "--ack", "--help", "-h"], valueFlags);
+  const positionals = positionalArgs(a, valueFlags);
+  requirePositionalCount(positionals, valueFlags, {
+    min: 1, max: 1, command: 'run402 messages send "<body>" [--to <names>]', missing: "<body>",
+  });
+  const importance = flagValue(a, "--importance");
+  if (importance != null) assertAllowedValue(importance, IMPORTANCE, "--importance");
+  const room = await resolveRoom({
+    org: flagValue(a, "--org"), room: flagValue(a, "--room"), project: flagValue(a, "--project"),
+  });
+  try {
+    const result = await withPresenceRetry(room.orgId, room.roomKey, (presenceId) =>
+      getSdk().rooms.sendMessage(room.orgId, room.roomKey, {
+        body: positionals[0],
+        to: splitNames(flagValue(a, "--to")),
+        cc: splitNames(flagValue(a, "--cc")),
+        threadId: flagValue(a, "--thread") ?? undefined,
+        importance: importance ?? undefined,
+        ackRequired: a.includes("--ack"),
+        idempotencyKey: flagValue(a, "--idempotency-key") ?? undefined,
+        presenceId: presenceId ?? undefined,
+        requestedName: flagValue(a, "--name") ?? undefined,
+        task: flagValue(a, "--task") ?? undefined,
+      }),
+      { name: flagValue(a, "--name"), task: flagValue(a, "--task") });
+    rememberPresence(room.orgId, room.roomKey, result.sender_presence, flagValue(a, "--name"));
+    console.log(JSON.stringify(result, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function list(args) {
+  const a = normalizeArgv(args);
+  const valueFlags = [...ROOM_FLAGS, "--cursor", "--before", "--thread", "--limit"];
+  assertKnownFlags(a, [...valueFlags, "--unread", "--help", "-h"], valueFlags);
+  requirePositionalCount(positionalArgs(a, valueFlags), valueFlags, {
+    min: 0, max: 0, command: "run402 rooms list", missing: "",
+  });
+  const limit = flagValue(a, "--limit");
+  const before = flagValue(a, "--before");
+  const unread = a.includes("--unread");
+  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") ?? (before ? undefined : (typeof stored === "string" ? stored : undefined));
+  try {
+    const page = await withPresenceRetry(room.orgId, room.roomKey, (presenceId) =>
+      getSdk().rooms.listMessages(room.orgId, room.roomKey, {
+        ...(before ? { order: "desc", before } : cursor ? { cursor } : {}),
+        threadId: flagValue(a, "--thread") ?? undefined,
+        ...(unread ? { addressedTo: "me", unread: true } : {}),
+        presenceId: presenceId ?? undefined,
+        limit: limit != null ? parseIntegerFlag("--limit", limit, { min: 1, max: 200 }) : undefined,
+      }));
+    // NOTE: an unread/addressed_to=me read needs a resolvable "me"; the retry
+    // above registers a replacement when this session's presence has expired.
+    // Ascending reads advance the stored cursor; display-mode (--before) never does.
+    if (!before && typeof page.cursor === "string") {
+      updateRoomState(room.orgId, room.roomKey, { cursor: page.cursor });
+    }
+    console.log(JSON.stringify(page, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function get(args) {
+  const a = normalizeArgv(args);
+  assertKnownFlags(a, [...ROOM_FLAGS, "--help", "-h"], ROOM_FLAGS);
+  const positionals = positionalArgs(a, ROOM_FLAGS);
+  requirePositionalCount(positionals, ROOM_FLAGS, {
+    min: 1, max: 1, command: "run402 rooms get <message_id>", missing: "<message_id>",
+  });
+  const room = await resolveRoom({
+    org: flagValue(a, "--org"), room: flagValue(a, "--room"), project: flagValue(a, "--project"),
+  });
+  try {
+    console.log(JSON.stringify(await getSdk().rooms.getMessage(room.orgId, room.roomKey, positionals[0]), null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function ack(args) {
+  const a = normalizeArgv(args);
+  assertKnownFlags(a, [...ROOM_FLAGS, "--help", "-h"], ROOM_FLAGS);
+  const positionals = positionalArgs(a, ROOM_FLAGS);
+  requirePositionalCount(positionals, ROOM_FLAGS, {
+    min: 1, max: 1, command: "run402 messages ack <message_id>", missing: "<message_id>",
+  });
+  const room = await resolveRoom({
+    org: flagValue(a, "--org"), room: flagValue(a, "--room"), project: flagValue(a, "--project"),
+  });
+  try {
+    const result = await withPresenceRetry(room.orgId, room.roomKey, (presenceId) =>
+      getSdk().rooms.ackMessage(room.orgId, room.roomKey, positionals[0], {
+        presenceId: presenceId ?? undefined,
+      }));
+    console.log(JSON.stringify(result, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+
+export async function run(sub, args) {
+  const argv = Array.isArray(args) ? args : [];
+  if (!sub || hasHelp([sub, ...argv])) {
+    console.log(HELP);
+    process.exit(0);
+  }
+  switch (sub) {
+    case "send": {
+      await send(argv);
+      break;
+    }
+    case "list": {
+      await list(argv);
+      break;
+    }
+    case "get": {
+      await get(argv);
+      break;
+    }
+    case "ack": {
+      await ack(argv);
+      break;
+    }
+    default:
+      failUnknownSubcommand("messages", sub, {
+        hint: "Run `run402 messages --help` for usage.",
+      });
+  }
+}

package/lib/rooms-context.mjs

@@ -97,7 +97,7 @@ export async function resolveRoom({ org, room, project } = {}) {
       hint: `Pass --org <org_id> --room <key>, set ${ROOM_ENV}="<org_id>/<room_key>", add a "room" key to .run402.json, or select a project with: run402 projects use <project_id>`,
       next_actions: [
         nextAction("edit_request", {
-          command: "run402 rooms who --org <org_id> --room <key>",
+          command: "run402 rooms join --org <org_id> --room <key>",
           why: "Name the organization and room on this one call.",
         }),
         nextAction("edit_request", {

package/lib/rooms.mjs

@@ -1,11 +1,16 @@
 /**
- * `run402 rooms` — agent-to-agent coordination rooms (agent messaging).
+ * `run402 rooms` — the coordination room itself: arriving, leaving, and who is
+ * in it.
+ *
+ * The MESSAGES exchanged in a room are `run402 messages` (legible-cli-surface).
+ * Four of this family's five verbs used to act on a message, which made the
+ * container the noun and left the thing you handle without one.
+ *
+ * `who` is now `join`: it REGISTERS a presence, and an interrogative must not
+ * name a write.
  *
  * Gateway subsystem: add-agent-messaging (/orgs/v1/:org_id/rooms/:room_key/*).
- * Org-scoped rooms; a project id names that project's DEFAULT room, so inside
- * a checkout the room resolves from the active project with zero flags. JSON
- * envelopes to stdout (pipe contract); flags map 1:1 to the HTTP surface.
- * Session presence + read cursor cache: ./.run402/messaging.json (gitignore).
+ * Session presence cache: ./.run402/messaging.json (gitignore).
  */
 import { getSdk } from "./sdk.mjs";
 import { fail, reportSdkError } from "./sdk-errors.mjs";
@@ -34,88 +39,24 @@ export const IMPORTANCE = ["normal", "high"];
 
 const ROOM_FLAGS = ["--project", "--org", "--room"];
 
-const HELP = `run402 rooms — coordinate with the other agents on your project
+const HELP = `run402 rooms — arrive in a room, see who is live, leave when done
 
 Usage:
-  run402 rooms who [--name <name>] [--task <text>]
-  run402 rooms send <body> [--to <names>] [--ack] [--thread <id>]
-  run402 rooms list [--unread] [--cursor <mcr_...>] [--thread <id>]
-  run402 rooms get <message_id>
-  run402 rooms ack <message_id>
-
-Room addressing (all subcommands):
-  (default)             The active project's default room — the room key IS
-                        the project id, so a checkout needs no flags.
-  --project <id>        Another project's default room.
-  --org <org_id> --room <key>
-                        A named org room (multi-repo products); also
-                        RUN402_ROOM=<org_id>/<key>.
-  --room <key>          A named org room whose ORG comes from the current-org
-                        chain: --org / RUN402_ORG / the 'org' key of the nearest
-                        .run402.json / 'run402 org use'. A checkout that hosts
-                        nothing on run402 reaches a room this way.
-  .run402.json          {"org":"<org_id>","room":"<key>"} binds a checkout, so
-                        every agent in it lands in the same room with no flags.
-
-Subcommands:
-  who     Who is live in the room (name, task, active claims). Registers your
-          session presence on first use — pass --name to choose your own name
-          (honored when free; suffixed Opus -> Opus-2 when taken, and the
-          output says so) and --task to say what you're working on.
-  send    Send a room-visible message. --to routes attention (comma-separated
-          presence names) and --ack asks those recipients to acknowledge.
-          Messages are visible to the whole room; to/cc is not access control.
-  list    Read messages, oldest-first from your stored cursor. --unread limits
-          to messages addressed to you that you haven't read; the cursor
-          auto-saves to ./.run402/messaging.json so the next list resumes.
-  get     One message with its FULL body (lists carry snippets) + ack state.
-  ack     Acknowledge a message addressed to you.
-
-Options:
-  --name <name>         who/send: requested presence name (first use only).
-  --task <text>         who/send: what this session is working on.
-  --to <a,b>            send: presence names to address (comma-separated).
-  --cc <a,b>            send: additional attention, no ack expectation.
-  --ack                 send: request acknowledgment from --to recipients.
-  --thread <id>         send/list: conversation thread id (<=128 chars).
-  --importance <v>      send: normal (default) | high.
-  --idempotency-key <k> send: safe-retry key — a replay returns the ORIGINAL
-                        message with deduplicated: true, never a double-post.
-  --cursor <mcr_...>    list: explicit resume point (overrides the cache).
-  --before <mcr_...>    list: page OLDER history (newest-first display mode).
-  --limit <n>           list: page size (default 50, max 200).
-  --unread              list: only unread messages addressed to you.
-  --all                 who: include expired presences (history).
-
-The cursor model:
-  - Every list response carries "cursor": the high-water mark. The CLI stores
-    it per room in ./.run402/messaging.json and resumes automatically.
-  - A stale cursor never errors: the response says reset: true and includes
-    earliest_cursor to restart from. Cursors are opaque — store, never parse.
-  - Reads hide the newest ~2s (the visibility watermark, same as the events
-    feed): a message you JUST sent appears on the next read, not instantly.
-
-Presence and names:
-  - Your presence is this SESSION, not your model or wallet: two sessions of
-    the same agent are two presences. Names are unique per room forever.
-  - A presence expires after ~1h of silence; the CLI transparently re-registers
-    on the next call (your name will be new — introduce yourself).
-
-Auth:
-  Org members (any role) reach all the org's rooms. A delegate
-  (RUN402_DELEGATE_TOKEN) reaches its own project's default room plus the
-  org's named rooms. Project service keys are read-only in their room.
-
-Tip: start every session with \`run402 rooms who --name <yours> --task "<what you're doing>"\`
-     then \`run402 rooms list --unread\` — arrive, look, then work.
-
-Examples:
-  run402 rooms who --name Opus --task "migrating auth"
-  run402 rooms send "auth dir is mine until 14:30" --to BlueLake --ack
-  run402 rooms list --unread                # catch up, cursor auto-saves
-  run402 rooms get msg_2f                   # full body
-  run402 rooms ack msg_2f
-  run402 rooms list --org 5f3a... --room run402-dev   # named org room
+  run402 rooms join [--name <name>] [--task <text>]
+
+Addressing:
+  --project <id>    That project's DEFAULT room (the room key IS the project id)
+  --org <id> --room <key>   A named org room
+  (omit both)       Resolved from RUN402_ROOM, a .run402.json binding, or the
+                    wallet profile's selected org
+
+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.
+  - Presence expires after ~1h of silence. Releasing it early (\`rooms leave\`),
+    enumerating reachable rooms, and inspecting one are not here yet — each
+    needs a gateway route that does not exist. Filed as follow-ups.
+  - The messages themselves are \`run402 messages\`.
 `;
 
 async function ensurePresence(room, { name, task } = {}) {
@@ -179,114 +120,6 @@ function splitNames(value) {
   return value ? value.split(",").map((s) => s.trim()).filter(Boolean) : [];
 }
 
-async function send(args) {
-  const a = normalizeArgv(args);
-  const valueFlags = [...ROOM_FLAGS, "--to", "--cc", "--thread", "--importance", "--idempotency-key", "--name", "--task"];
-  assertKnownFlags(a, [...valueFlags, "--ack", "--help", "-h"], valueFlags);
-  const positionals = positionalArgs(a, valueFlags);
-  requirePositionalCount(positionals, valueFlags, {
-    min: 1, max: 1, command: 'run402 rooms send "<body>" [--to <names>]', missing: "<body>",
-  });
-  const importance = flagValue(a, "--importance");
-  if (importance != null) assertAllowedValue(importance, IMPORTANCE, "--importance");
-  const room = await resolveRoom({
-    org: flagValue(a, "--org"), room: flagValue(a, "--room"), project: flagValue(a, "--project"),
-  });
-  try {
-    const result = await withPresenceRetry(room.orgId, room.roomKey, (presenceId) =>
-      getSdk().rooms.sendMessage(room.orgId, room.roomKey, {
-        body: positionals[0],
-        to: splitNames(flagValue(a, "--to")),
-        cc: splitNames(flagValue(a, "--cc")),
-        threadId: flagValue(a, "--thread") ?? undefined,
-        importance: importance ?? undefined,
-        ackRequired: a.includes("--ack"),
-        idempotencyKey: flagValue(a, "--idempotency-key") ?? undefined,
-        presenceId: presenceId ?? undefined,
-        requestedName: flagValue(a, "--name") ?? undefined,
-        task: flagValue(a, "--task") ?? undefined,
-      }),
-      { name: flagValue(a, "--name"), task: flagValue(a, "--task") });
-    rememberPresence(room.orgId, room.roomKey, result.sender_presence, flagValue(a, "--name"));
-    console.log(JSON.stringify(result, null, 2));
-  } catch (err) {
-    reportSdkError(err);
-  }
-}
-
-async function list(args) {
-  const a = normalizeArgv(args);
-  const valueFlags = [...ROOM_FLAGS, "--cursor", "--before", "--thread", "--limit"];
-  assertKnownFlags(a, [...valueFlags, "--unread", "--help", "-h"], valueFlags);
-  requirePositionalCount(positionalArgs(a, valueFlags), valueFlags, {
-    min: 0, max: 0, command: "run402 rooms list", missing: "",
-  });
-  const limit = flagValue(a, "--limit");
-  const before = flagValue(a, "--before");
-  const unread = a.includes("--unread");
-  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") ?? (before ? undefined : (typeof stored === "string" ? stored : undefined));
-  try {
-    const page = await withPresenceRetry(room.orgId, room.roomKey, (presenceId) =>
-      getSdk().rooms.listMessages(room.orgId, room.roomKey, {
-        ...(before ? { order: "desc", before } : cursor ? { cursor } : {}),
-        threadId: flagValue(a, "--thread") ?? undefined,
-        ...(unread ? { addressedTo: "me", unread: true } : {}),
-        presenceId: presenceId ?? undefined,
-        limit: limit != null ? parseIntegerFlag("--limit", limit, { min: 1, max: 200 }) : undefined,
-      }));
-    // NOTE: an unread/addressed_to=me read needs a resolvable "me"; the retry
-    // above registers a replacement when this session's presence has expired.
-    // Ascending reads advance the stored cursor; display-mode (--before) never does.
-    if (!before && typeof page.cursor === "string") {
-      updateRoomState(room.orgId, room.roomKey, { cursor: page.cursor });
-    }
-    console.log(JSON.stringify(page, null, 2));
-  } catch (err) {
-    reportSdkError(err);
-  }
-}
-
-async function get(args) {
-  const a = normalizeArgv(args);
-  assertKnownFlags(a, [...ROOM_FLAGS, "--help", "-h"], ROOM_FLAGS);
-  const positionals = positionalArgs(a, ROOM_FLAGS);
-  requirePositionalCount(positionals, ROOM_FLAGS, {
-    min: 1, max: 1, command: "run402 rooms get <message_id>", missing: "<message_id>",
-  });
-  const room = await resolveRoom({
-    org: flagValue(a, "--org"), room: flagValue(a, "--room"), project: flagValue(a, "--project"),
-  });
-  try {
-    console.log(JSON.stringify(await getSdk().rooms.getMessage(room.orgId, room.roomKey, positionals[0]), null, 2));
-  } catch (err) {
-    reportSdkError(err);
-  }
-}
-
-async function ack(args) {
-  const a = normalizeArgv(args);
-  assertKnownFlags(a, [...ROOM_FLAGS, "--help", "-h"], ROOM_FLAGS);
-  const positionals = positionalArgs(a, ROOM_FLAGS);
-  requirePositionalCount(positionals, ROOM_FLAGS, {
-    min: 1, max: 1, command: "run402 rooms ack <message_id>", missing: "<message_id>",
-  });
-  const room = await resolveRoom({
-    org: flagValue(a, "--org"), room: flagValue(a, "--room"), project: flagValue(a, "--project"),
-  });
-  try {
-    const result = await withPresenceRetry(room.orgId, room.roomKey, (presenceId) =>
-      getSdk().rooms.ackMessage(room.orgId, room.roomKey, positionals[0], {
-        presenceId: presenceId ?? undefined,
-      }));
-    console.log(JSON.stringify(result, null, 2));
-  } catch (err) {
-    reportSdkError(err);
-  }
-}
 
 export async function run(sub, args) {
   const argv = Array.isArray(args) ? args : [];
@@ -295,26 +128,45 @@ export async function run(sub, args) {
     process.exit(0);
   }
   switch (sub) {
-    case "who": {
+    case "join": {
       await who(argv);
       break;
     }
-    case "send": {
-      await send(argv);
-      break;
-    }
-    case "list": {
-      await list(argv);
-      break;
-    }
-    case "get": {
-      await get(argv);
+    // `list`, `get` and `leave` are NOT here. Each needs a gateway route that
+    // does not exist (there is no list-rooms, get-room, or release-presence
+    // endpoint), and this change states plainly that it adds none. They are
+    // filed as follow-ups rather than shipped as a CLI calling into nothing.
+    //
+    // `rooms list` and `rooms get` additionally carry design D3b: they are
+    // FREED by the move of the message verbs, and a freed spelling stays dead
+    // for one major before anything reuses it — a spelling that silently
+    // answers with different data is worse than one that fails.
+    // Retired here, and NOT aliased (design D3): each answers with its
+    // successor so one failed call teaches the new model, where an alias
+    // would teach the old one forever.
+    case "who":
+      fail({
+        code: "COMMAND_REMOVED",
+        message: "`run402 rooms who` was renamed to `run402 rooms join`.",
+        hint: "run402 rooms join --name <name> --task <text>",
+        details: { was: "rooms who", now: "rooms join", why: "an interrogative must not name a write — it registers a presence" },
+      });
       break;
-    }
-    case "ack": {
-      await ack(argv);
+    case "list":
+    case "get":
+    case "send":
+    case "ack":
+      fail({
+        code: "COMMAND_REMOVED",
+        message: `\`run402 rooms ${sub}\` moved to \`run402 messages ${sub}\`.`,
+        hint: `run402 messages ${sub}`,
+        details: {
+          was: `rooms ${sub}`,
+          now: `messages ${sub}`,
+          why: "the verb acts on a message, not on the room that contains it",
+        },
+      });
       break;
-    }
     default:
       failUnknownSubcommand("rooms", sub, {
         hint: "Run `run402 rooms --help` for usage.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "4.32.0",
+  "version": "4.33.0",
   "description": "CLI for Run402 — provision Postgres databases, deploy static sites, generate images, and manage wallets via x402 and MPP micropayments.",
   "type": "module",
   "bin": {