run402 4.17.9 → 4.18.0

package/cli.mjs

@@ -45,6 +45,8 @@ Commands:
   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)
+  claims      Say what you're working on before you collide (advisory)
   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)
@@ -273,6 +275,16 @@ switch (cmd) {
     await run(sub, rest);
     break;
   }
+  case "rooms": {
+    const { run } = await import("./lib/rooms.mjs");
+    await run(sub, rest);
+    break;
+  }
+  case "claims": {
+    const { run } = await import("./lib/claims.mjs");
+    await run(sub, rest);
+    break;
+  }
   case "errors": {
     const { run } = await import("./lib/errors.mjs");
     await run(sub, rest);

package/lib/buzz.mjs

@@ -22,6 +22,9 @@ The four independent states are:
 Canonical workflows:
   run402 buzz status
   run402 buzz adopt offer --org <org_id> --identity-link <idlnk_id> [--deployment-context-file <json>]
+      --org                       the Run402 organization id as "run402 org whoami" returns it (a UUID)
+      --deployment-context-file   JSON with exactly these five non-empty strings, and no others:
+                                  project_id, release_id, live_url, source_revision, verified_at
   run402 buzz install --org <org_id> --community <buzz:community:host> --authority <hex-pubkey>
   run402 buzz enroll --installation <buzzci_id> --identity-link <idlnk_id> --grants-file <json> --expires-at <ISO-8601>
 

package/lib/claims.mjs

@@ -0,0 +1,165 @@
+/**
+ * `run402 claims` — advisory work claims for agent coordination.
+ *
+ * Gateway subsystem: add-agent-messaging (/orgs/v1/:org_id/rooms/:room_key/claims).
+ * A claim declares "I'm working on X until T" so concurrent agents discover
+ * collisions BEFORE they happen. Claims are ADVISORY: creating a conflicting
+ * claim succeeds and reports the complete conflict set — nothing, ever, is
+ * blocked by a claim (deploys included). JSON to stdout (pipe contract).
+ */
+import { getSdk } from "./sdk.mjs";
+import { reportSdkError } from "./sdk-errors.mjs";
+import {
+  normalizeArgv,
+  hasHelp,
+  assertKnownFlags,
+  assertAllowedValue,
+  parseIntegerFlag,
+  flagValue,
+  positionalArgs,
+  requirePositionalCount,
+  failUnknownSubcommand,
+} from "./argparse.mjs";
+import { resolveRoom, withPresenceRetry } from "./rooms-context.mjs";
+
+export const MODES = ["exclusive", "shared"];
+
+const ROOM_FLAGS = ["--project", "--org", "--room"];
+
+const HELP = `run402 claims — say what you're working on before you collide
+
+Usage:
+  run402 claims create <resource> [--mode exclusive|shared] [--ttl <seconds>]
+  run402 claims list [--all]
+  run402 claims release <claim_id>
+
+Resources (namespaced; conflicts never cross namespaces):
+  repo:<glob>        Repo paths — repo:src/auth/** (glob overlap detection)
+  function:<name>    A deployed function by name
+  table:<name>       A database table
+  deploy             The deploy itself (a soft mutex by convention)
+  <free-form>        Anything else (exact-match overlap)
+
+Advisory, always:
+  Creating a conflicting claim SUCCEEDS — the response carries the complete
+  conflicts[] (holder, resource, mode, expiry) and the deploy-path responses
+  surface other agents' claims automatically. A claim never blocks anything;
+  it makes collisions visible before they happen. Claims auto-expire (default
+  1h, max 24h) so a dead session cannot wedge the room; <=32 active per
+  presence.
+
+Room addressing:
+  Default room of the active project with no flags; --project <id> for another
+  project; --org <org_id> --room <key> (or RUN402_ROOM=<org_id>/<key>) for a
+  named org room.
+
+Options:
+  --mode <m>        exclusive (default) — one worker; shared — parallel-safe.
+  --ttl <seconds>   Claim lifetime (default 3600, max 86400).
+  --note <text>     Why you're claiming it (shown to everyone).
+  --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.
+
+Examples:
+  run402 claims create repo:src/auth/** --note "migrating to passkeys"
+  run402 claims create deploy --ttl 900
+  run402 claims list
+  run402 claims release clm_1a
+`;
+
+async function create(args) {
+  const a = normalizeArgv(args);
+  const valueFlags = [...ROOM_FLAGS, "--mode", "--ttl", "--note"];
+  assertKnownFlags(a, [...valueFlags, "--help", "-h"], valueFlags);
+  const positionals = positionalArgs(a, valueFlags);
+  requirePositionalCount(positionals, valueFlags, {
+    min: 1, max: 1, command: "run402 claims create <resource>", missing: "<resource>",
+  });
+  const mode = flagValue(a, "--mode") ?? "exclusive";
+  assertAllowedValue(mode, MODES, "--mode");
+  const ttl = flagValue(a, "--ttl");
+  const room = await resolveRoom({
+    org: flagValue(a, "--org"), room: flagValue(a, "--room"), project: flagValue(a, "--project"),
+  });
+  try {
+    const created = await withPresenceRetry(room.orgId, room.roomKey, (presenceId) =>
+      getSdk().rooms.createClaim(room.orgId, room.roomKey, {
+        resource: positionals[0],
+        mode,
+        ttlSeconds: ttl != null ? parseIntegerFlag("--ttl", ttl, { min: 1, max: 86400 }) : undefined,
+        note: flagValue(a, "--note") ?? undefined,
+        presenceId: presenceId ?? undefined,
+      }));
+    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.`);
+    }
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function list(args) {
+  const a = normalizeArgv(args);
+  assertKnownFlags(a, [...ROOM_FLAGS, "--all", "--help", "-h"], ROOM_FLAGS);
+  requirePositionalCount(positionalArgs(a, ROOM_FLAGS), ROOM_FLAGS, {
+    min: 0, max: 0, command: "run402 claims list", missing: "",
+  });
+  const room = await resolveRoom({
+    org: flagValue(a, "--org"), room: flagValue(a, "--room"), project: flagValue(a, "--project"),
+  });
+  try {
+    const page = await getSdk().rooms.listClaims(room.orgId, room.roomKey, {
+      includeInactive: a.includes("--all"),
+    });
+    console.log(JSON.stringify(page, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function release(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 claims release <claim_id>", missing: "<claim_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.releaseClaim(room.orgId, room.roomKey, positionals[0]), 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 "create": {
+      await create(argv);
+      break;
+    }
+    case "list": {
+      await list(argv);
+      break;
+    }
+    case "release": {
+      await release(argv);
+      break;
+    }
+    default:
+      failUnknownSubcommand("claims", sub, {
+        hint: "Run `run402 claims --help` for usage.",
+      });
+  }
+}

package/lib/command-manifest.mjs

@@ -200,6 +200,14 @@ 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: ["claims", "create"], positionals: [p("resource")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["deploy"], runStyle: "sub" },
+  { path: ["claims", "list"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub" },
+  { path: ["claims", "release"], positionals: [p("claim_id")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["clm_1"], runStyle: "sub" },
   { path: ["errors"], positionals: [p("fingerprint_id", { required: false })], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "merged" },
 
   // ── jobs ─────────────────────────────────────────────────────────────────

package/lib/rooms-context.mjs

@@ -0,0 +1,132 @@
+/**
+ * Shared room resolution + per-checkout session state for the agent-messaging
+ * commands (`run402 messages`, `run402 claims`).
+ *
+ * Room addressing (precedence):
+ *   --org <org_id> + --room <key>   explicit (named org rooms)
+ *   RUN402_ROOM=<org_id>/<key>      env form of the same
+ *   (default)                       the project's DEFAULT room — the room key
+ *                                   IS the project id; org resolved via the
+ *                                   project overview (`rooms.forProject`).
+ *
+ * Session state lives at ./.run402/messaging.json (per-checkout — the house
+ * discipline of one worktree per agent session makes per-checkout equal
+ * per-session). It caches, per room: the session's presence_id + name and the
+ * read cursor. Add `.run402/` to .gitignore. Two sessions sharing one checkout
+ * share a presence (coherent, just undifferentiated); RUN402_PRESENCE_ID
+ * overrides for harnesses that multiplex.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fail } from "./sdk-errors.mjs";
+import { resolveProjectId } from "./config.mjs";
+import { getSdk } from "./sdk.mjs";
+
+export const ROOM_ENV = "RUN402_ROOM";
+export const PRESENCE_ENV = "RUN402_PRESENCE_ID";
+
+const STATE_DIR = ".run402";
+const STATE_FILE = "messaging.json";
+
+/** Resolve the addressed room to { orgId, roomKey } (one SDK lookup at most). */
+export async function resolveRoom({ org, room, project } = {}) {
+  if (room && !org) {
+    fail({
+      code: "BAD_USAGE",
+      message: "--room names an org room and needs --org <org_id> beside it.",
+      hint: "For the project's default room, omit both (or pass --project). For a named room: --org <org_id> --room <key>.",
+    });
+  }
+  if (org && room) return { orgId: org, roomKey: room };
+  const envRoom = (process.env[ROOM_ENV] ?? "").trim();
+  if (envRoom) {
+    const slash = envRoom.indexOf("/");
+    if (slash <= 0 || slash === envRoom.length - 1) {
+      fail({
+        code: "BAD_USAGE",
+        message: `${ROOM_ENV} must be "<org_id>/<room_key>".`,
+        details: { value: envRoom },
+      });
+    }
+    return { orgId: envRoom.slice(0, slash), roomKey: envRoom.slice(slash + 1) };
+  }
+  const projectId = resolveProjectId(project);
+  const scoped = await getSdk().rooms.forProject(projectId);
+  return { orgId: scoped.orgId, roomKey: scoped.roomKey };
+}
+
+function statePath() {
+  return join(process.cwd(), STATE_DIR, STATE_FILE);
+}
+
+function loadState() {
+  try {
+    const raw = readFileSync(statePath(), "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" && parsed.rooms && typeof parsed.rooms === "object"
+      ? parsed
+      : { rooms: {} };
+  } catch {
+    return { rooms: {} };
+  }
+}
+
+function saveState(state) {
+  try {
+    const dir = join(process.cwd(), STATE_DIR);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(statePath(), `${JSON.stringify(state, null, 2)}\n`);
+  } catch {
+    // Best-effort cache: an unwritable checkout degrades to stateless calls.
+  }
+}
+
+const roomStateKey = (orgId, roomKey) => `${orgId}/${roomKey}`;
+
+export function getRoomState(orgId, roomKey) {
+  return loadState().rooms[roomStateKey(orgId, roomKey)] ?? {};
+}
+
+export function updateRoomState(orgId, roomKey, patch) {
+  const state = loadState();
+  const key = roomStateKey(orgId, roomKey);
+  state.rooms[key] = { ...(state.rooms[key] ?? {}), ...patch };
+  saveState(state);
+}
+
+/** The session's presence id for a room: env override, else the checkout cache. */
+export function cachedPresenceId(orgId, roomKey) {
+  const env = (process.env[PRESENCE_ENV] ?? "").trim();
+  if (env) return env;
+  const cached = getRoomState(orgId, roomKey).presence_id;
+  return typeof cached === "string" && cached ? cached : null;
+}
+
+/**
+ * Run a room call that carries the cached presence. On PRESENCE_EXPIRED (410 —
+ * this session's presence aged out), drop the cache and retry ONCE without a
+ * presence_id so the gateway's resolve-or-create issues a fresh one.
+ */
+export async function withPresenceRetry(orgId, roomKey, call) {
+  const presenceId = cachedPresenceId(orgId, roomKey);
+  try {
+    return await call(presenceId);
+  } catch (err) {
+    const code = err?.body?.code ?? err?.code;
+    if (code === "PRESENCE_EXPIRED" && presenceId) {
+      updateRoomState(orgId, roomKey, { presence_id: null, name: null });
+      return call(null);
+    }
+    throw err;
+  }
+}
+
+/** Cache the presence a response attributed this session to. */
+export function rememberPresence(orgId, roomKey, presence) {
+  if (!presence || typeof presence !== "object") return;
+  const id = presence.presence_id;
+  const name = presence.name;
+  if (typeof id === "string" && id) {
+    updateRoomState(orgId, roomKey, { presence_id: id, ...(typeof name === "string" ? { name } : {}) });
+  }
+}

package/lib/rooms.mjs

@@ -0,0 +1,297 @@
+/**
+ * `run402 rooms` — agent-to-agent coordination rooms (agent messaging).
+ *
+ * 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).
+ */
+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,
+  rememberPresence,
+  getRoomState,
+  updateRoomState,
+} from "./rooms-context.mjs";
+
+export const IMPORTANCE = ["normal", "high"];
+
+const ROOM_FLAGS = ["--project", "--org", "--room"];
+
+const HELP = `run402 rooms — coordinate with the other agents on your project
+
+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>.
+
+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
+`;
+
+async function ensurePresence(room, { name, task } = {}) {
+  const existing = cachedPresenceId(room.orgId, room.roomKey);
+  if (existing) return { presence_id: existing, registered: false };
+  const sdk = getSdk();
+  const registration = await sdk.rooms.registerPresence(room.orgId, room.roomKey, {
+    ...(name ? { requestedName: name } : {}),
+    ...(task ? { task } : {}),
+  });
+  rememberPresence(room.orgId, room.roomKey, registration);
+  return { ...registration, registered: true };
+}
+
+async function who(args) {
+  const a = normalizeArgv(args);
+  const valueFlags = [...ROOM_FLAGS, "--name", "--task"];
+  assertKnownFlags(a, [...valueFlags, "--all", "--help", "-h"], valueFlags);
+  requirePositionalCount(positionalArgs(a, valueFlags), valueFlags, {
+    min: 0, max: 0, command: "run402 rooms who", missing: "",
+  });
+  const room = await resolveRoom({
+    org: flagValue(a, "--org"), room: flagValue(a, "--room"), project: flagValue(a, "--project"),
+  });
+  try {
+    const me = await ensurePresence(room, { name: flagValue(a, "--name"), task: flagValue(a, "--task") });
+    const page = await getSdk().rooms.listPresences(room.orgId, room.roomKey, {
+      includeExpired: a.includes("--all"),
+    });
+    console.log(JSON.stringify({
+      org_id: room.orgId,
+      room_key: room.roomKey,
+      you: me,
+      ...page,
+    }, null, 2));
+    if (me.registered && me.renamed) {
+      console.error(`You are ${me.name} — ${me.requested_name} was taken.`);
+    }
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+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,
+      }));
+    rememberPresence(room.orgId, room.roomKey, result.sender_presence);
+    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,
+      }));
+    // 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 : [];
+  if (!sub || hasHelp([sub, ...argv])) {
+    console.log(HELP);
+    process.exit(0);
+  }
+  switch (sub) {
+    case "who": {
+      await who(argv);
+      break;
+    }
+    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("rooms", sub, {
+        hint: "Run `run402 rooms --help` for usage.",
+      });
+  }
+}

package/package.json

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