run402 4.26.0 → 4.28.0

package/core-dist/profile-state.js

@@ -126,6 +126,52 @@ export function clearActiveProjectId(projectId, path, scope = {}) {
         saveProfileState(state, p);
     });
 }
+// ---------------------------------------------------------------------------
+// Selected organization (add-cli-current-org, design D3).
+//
+// Scoped exactly like the active project id — by api_base, profile, and
+// principal — and stored in the SAME per-profile state.json, never in the
+// base-level config.json beside `active_wallet`. The chain is
+// wallet -> principal -> memberships, so a globally-selected org survives
+// `wallets use other` and then either 403s or, worse, silently resolves to a
+// valid-but-wrong org when both principals are members. Per-profile makes the
+// failure mode "this profile has no current org", which the ORG_REQUIRED
+// envelope already knows how to explain.
+//
+// There is deliberately no top-level `active_org_id` mirror: the project one
+// exists only to carry pre-scoping installs forward, and this key is new.
+// ---------------------------------------------------------------------------
+export function getActiveOrgId(path, scope = {}) {
+    const state = loadProfileState(path);
+    return state.active_orgs?.[activeProjectScopeKey(scope)]?.org_id;
+}
+export function setActiveOrgId(orgId, path, scope = {}) {
+    const p = path ?? getProfileStatePath();
+    withFileLock(p, () => {
+        const state = loadProfileState(p);
+        const key = activeProjectScopeKey(scope);
+        const resolved = defaultActiveProjectScope(scope);
+        state.active_orgs = state.active_orgs ?? {};
+        state.active_orgs[key] = {
+            org_id: orgId,
+            api_base: resolved.api_base,
+            principal: resolved.principal ?? null,
+            profile: resolved.profile,
+            updated_at: new Date().toISOString(),
+        };
+        saveProfileState(state, p);
+    });
+}
+export function clearActiveOrgId(path, scope = {}) {
+    const p = path ?? getProfileStatePath();
+    withFileLock(p, () => {
+        const state = loadProfileState(p);
+        const key = activeProjectScopeKey(scope);
+        if (state.active_orgs?.[key])
+            delete state.active_orgs[key];
+        saveProfileState(state, p);
+    });
+}
 export function recordMigration(marker, value, path) {
     const p = path ?? getProfileStatePath();
     withFileLock(p, () => {

package/lib/claims.mjs

@@ -51,7 +51,9 @@ Advisory, always:
 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.
+  named org room. --room <key> alone works when the org resolves on its own
+  (--org / RUN402_ORG / the 'org' key of the nearest .run402.json / 'org use'),
+  and {"org":"...","room":"..."} in .run402.json binds a whole checkout.
 
 Options:
   --mode <m>        exclusive (default) — one worker; shared — parallel-safe.

package/lib/command-manifest.mjs

@@ -199,6 +199,11 @@ export const COMMAND_MANIFEST = [
   { path: ["org", "payout-wallet"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1", "--wallet", "0x1111111111111111111111111111111111111111"] },
   { path: ["org", "whoami"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
   { path: ["org", "audit"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1"] },
+  { path: ["org", "use"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["11111111-2222-3333-4444-555555555555"] },
+  { path: ["org", "current"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
+  { path: ["org", "clear"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
+  { path: ["org", "bind"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["--org", "11111111-2222-3333-4444-555555555555"] },
+  { path: ["org", "unbind"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
   { path: ["org", "member", "list"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1"] },
   { path: ["org", "member", "add"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1", "--wallet", "0x1111111111111111111111111111111111111111"] },
   { path: ["org", "member", "role"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1", "--principal", "prn_gate1", "--role", "viewer"] },

package/lib/init.mjs

@@ -627,6 +627,29 @@ export async function run(args = []) {
     }
   }
 
+  // 5b. The org. `init` already materializes it (the tier read above
+  // authenticates, which provisions the wallet's org-of-one), so NOT reporting
+  // it forced every agent that wanted to coordinate to go find it with a second
+  // command and copy a UUID by hand. It is an identifier, not a credential.
+  try {
+    const orgs = await getSdk().orgs.list();
+    const rows = Array.isArray(orgs) ? orgs : (orgs?.orgs ?? []);
+    summary.orgs = rows.map((o) => ({
+      org_id: o.org_id,
+      display_name: o.display_name ?? null,
+      role: o.role ?? null,
+    }));
+    if (rows.length === 1) {
+      line("Org", `${rows[0].org_id}${rows[0].display_name ? ` (${rows[0].display_name})` : ""}`);
+    } else if (rows.length > 1) {
+      line("Org", `${rows.length} organizations — run402 org list`);
+    }
+  } catch {
+    // Best-effort, exactly like the billing read: a listing failure must never
+    // fail setup.
+    summary.orgs = null;
+  }
+
   // 6. Next step — canonical typed action(s); `next_step` is the back-compat
   // string mirror of the first action's command (one spelling, surface-wide).
   write("");

package/lib/org-context.mjs

@@ -1,29 +1,310 @@
 /**
  * Shared organization resolution for org-scoped CLI families
- * (attention-architecture Wave E — one resolver, not one per family).
+ * (attention-architecture Wave E — one resolver, not one per family;
+ * extended by add-cli-current-org with the local-context classes).
  *
- * Precedence: explicit `--org` flag → `RUN402_ORG` env → the active project's
- * owning org (the zero-config checkout path, one SDK lookup). Every org-scoped
- * family (`escalations`, and whatever ships next) resolves through here so a
- * checkout needs no flags and the precedence cannot drift per family.
+ * The org is the ownership root — it owns projects, holds memberships, and is
+ * the scope for rooms, escalations, members, grants, and audit. This is the one
+ * place org precedence is expressed.
  *
- * `rooms`/`claims` predate this and resolve a PAIR ({orgId, roomKey}) with
- * their own `RUN402_ROOM` env form — see `rooms-context.mjs`; forcing them
- * through a single-value resolver would contort both. One resolver per SHAPE.
+ * Precedence is four INTENT CLASSES, highest first, and inside each class an
+ * organization named directly outranks one derived from a project named in that
+ * same class:
+ *
+ *   1. flag          --org <org_id>           else --project <id> -> its org
+ *   2. environment   RUN402_ORG, else the org else RUN402_PROJECT_ID -> its org
+ *                    half of RUN402_ROOM
+ *   3. binding       the `org` key of the nearest .run402(.local).json
+ *   4. profile state the profile's selected org else its active project -> org
+ *
+ * The class rule is what makes `--project X` behave: naming a project IS naming
+ * its organization, so a stale profile selection must not outrank it. Classes 3
+ * and 4 are what let an org that owns NO project be addressed at all — every
+ * earlier rung needed an argument, a variable, or a deployed project.
+ *
+ * `rooms`/`claims` resolve a PAIR ({orgId, roomKey}) with their own
+ * `RUN402_ROOM` env form — see `rooms-context.mjs`. They are not forced through
+ * this single-value resolver: the pair keeps its own shape and its own
+ * precedence, and only the ORG HALF of its fallback delegates here. One
+ * resolver per shape, composed for the half they share.
+ *
+ * Two things this deliberately does NOT do:
+ * - Infer the org from the caller's memberships, at any count. Membership is
+ *   server state that changes without the caller acting, so a heuristic that is
+ *   right today silently changes meaning the day they are invited elsewhere.
+ * - Validate membership locally. A well-formed id goes to the server and the
+ *   server's answer is surfaced as returned — never rewritten into a local
+ *   not-found (that would invent the existence oracle the gateway refuses to
+ *   provide) and never retried against a lower class (that would act on a
+ *   different organization than the caller named).
  */
 import { getSdk } from "./sdk.mjs";
 import { flagValue } from "./argparse.mjs";
+import { findBindingKey } from "./wallet-context.mjs";
+import { fail } from "./sdk-errors.mjs";
+import { nextAction } from "./next-actions.mjs";
+import {
+  getActiveOrgId as coreGetActiveOrgId,
+  setActiveOrgId as coreSetActiveOrgId,
+  clearActiveOrgId as coreClearActiveOrgId,
+} from "../core-dist/profile-state.js";
+import { getActiveProjectId } from "../core-dist/keystore.js";
 import { getProject, resolveProjectId, updateProject } from "./config.mjs";
 
-/** Resolve the addressed organization from normalized argv (one SDK lookup at most). */
-export async function resolveOrgId(a) {
-  const explicit = flagValue(a, "--org");
-  if (explicit) return explicit;
-  const envOrg = (process.env.RUN402_ORG ?? "").trim();
-  if (envOrg) return envOrg;
-  const projectId = resolveProjectId(flagValue(a, "--project"));
-  const scoped = await getSdk().rooms.forProject(projectId);
-  return scoped.orgId;
+export const ORG_ENV = "RUN402_ORG";
+export const ROOM_ENV = "RUN402_ROOM";
+export const PROJECT_ENV = "RUN402_PROJECT_ID";
+
+/** Command groups that must stay usable while selection is ambiguous. */
+const CONFLICT_EXEMPT = new Set(["org", "wallets", "doctor"]);
+
+/** `org_id` is a UUID at every API boundary (`uuidParam` on every route). */
+const ORG_ID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+
+const trimmed = (v) => (typeof v === "string" && v.trim() ? v.trim() : null);
+
+/**
+ * Shape-validate an organization id supplied by a local source. Membership is
+ * NEVER checked here — only that the value could be an org id at all.
+ */
+function assertOrgIdShape(orgId, origin) {
+  if (ORG_ID_RE.test(orgId)) return orgId;
+  fail({
+    code: "BAD_ORG_ID",
+    message: `Invalid organization id ${JSON.stringify(orgId)} (from ${origin}).`,
+    hint: "An org_id is a UUID. Run 'run402 org list' to see the organizations you belong to.",
+    details: { org_id: orgId, origin },
+    next_actions: [listOrgsAction()],
+  });
+}
+
+/** The org half of `RUN402_ROOM=<org_id>/<room_key>`, or null. */
+function orgFromRoomEnv(env) {
+  const raw = trimmed(env[ROOM_ENV]);
+  if (!raw) return null;
+  const slash = raw.indexOf("/");
+  if (slash <= 0 || slash === raw.length - 1) return null; // rooms-context reports the malformed form
+  return raw.slice(0, slash);
+}
+
+function listOrgsAction() {
+  return nextAction("edit_request", {
+    command: "run402 org list",
+    why: "List the organizations this wallet belongs to.",
+  });
+}
+
+function orgRequiredActions() {
+  return [
+    nextAction("edit_request", {
+      command: "run402 org use <org_id>",
+      why: "Select a current organization for this wallet profile.",
+    }),
+    listOrgsAction(),
+    nextAction("edit_request", {
+      command: "run402 <command> --org <org_id>",
+      why: "Name the organization on this one call.",
+    }),
+    nextAction("edit_request", {
+      command: "export RUN402_ORG=<org_id>",
+      why: "Name the organization for every call in this shell (harness wiring).",
+    }),
+    nextAction("edit_request", {
+      command: `echo '{"org":"<org_id>"}' > .run402.json`,
+      why: "Bind this checkout to an organization so every agent in it inherits the same one.",
+    }),
+    nextAction("edit_request", {
+      command: "run402 projects use <project_id>",
+      why: "Select a project; its owning organization becomes the current one.",
+    }),
+  ];
+}
+
+/** Resolve a project's owning org (one GET). Returns null when unresolvable. */
+async function orgOfProject(projectId, { required }) {
+  // Upstream's per-project cache answers the same question for free when it is
+  // warm. It is NOT used as the whole implementation: it returns null on
+  // failure, and an explicitly named project must be able to HARD STOP rather
+  // than fall through to a lower class.
+  const cached = getProject(projectId)?.org_id;
+  if (typeof cached === "string" && cached.length > 0) return cached;
+  try {
+    const scoped = await getSdk().rooms.forProject(projectId);
+    return scoped.orgId;
+  } catch (err) {
+    // An EXPLICITLY named project that cannot be resolved is a hard stop — the
+    // caller named it, so falling to a lower class would act on a different
+    // organization than the one they asked for. An implicitly selected project
+    // (profile state) may simply be stale; skip the class.
+    if (!required) return null;
+    throw err;
+  }
+}
+
+/**
+ * Resolve the organization an org-scoped command acts on.
+ *
+ * Accepts either normalized argv (the Wave E call shape, still used by
+ * `escalations`) or an options object for callers that already hold values.
+ *
+ * @param {string[]|object} input normalized argv, or { org, project }
+ * @param {object}  [opts]
+ * @param {string}  [opts.cmd]      command group, for the conflict exemption
+ * @param {object}  [opts.env]      environment (injectable for tests)
+ * @param {string}  [opts.cwd]      directory to walk up from (injectable)
+ * @param {boolean} [opts.optional] return null instead of failing when absent
+ * @returns {Promise<{orgId: string, source: string, sourceDetail: string}|null>}
+ */
+export async function resolveOrg(input = {}, opts = {}) {
+  const { cmd, env = process.env, cwd = process.cwd(), optional = false } = opts;
+  const org = Array.isArray(input) ? flagValue(input, "--org") : input.org;
+  const project = Array.isArray(input) ? flagValue(input, "--project") : input.project;
+
+  // --- Class 1: flag -------------------------------------------------------
+  const orgFlag = trimmed(org);
+  if (orgFlag) {
+    return { orgId: assertOrgIdShape(orgFlag, "--org"), source: "flag", sourceDetail: "--org" };
+  }
+  const projectFlag = trimmed(project);
+  if (projectFlag) {
+    const orgId = await orgOfProject(projectFlag, { required: true });
+    if (orgId) return { orgId, source: "flag", sourceDetail: "--project" };
+  }
+
+  // --- Class 2 and 3: environment vs binding (the conflict pair) ------------
+  const bindingHit = findBindingKey(cwd, "org");
+  const bindingOrg = bindingHit ? assertOrgIdShape(bindingHit.value, bindingHit.file) : null;
+
+  const envDirect = trimmed(env[ORG_ENV]);
+  const envRoomOrg = envDirect ? null : orgFromRoomEnv(env);
+  const envProject = envDirect || envRoomOrg ? null : trimmed(env[PROJECT_ENV]);
+
+  let envOrg = null;
+  let envDetail = null;
+  if (envDirect) {
+    envOrg = assertOrgIdShape(envDirect, ORG_ENV);
+    envDetail = ORG_ENV;
+  } else if (envRoomOrg) {
+    envOrg = assertOrgIdShape(envRoomOrg, ROOM_ENV);
+    envDetail = ROOM_ENV;
+  } else if (envProject && bindingOrg) {
+    // Only worth a lookup when a binding exists to disagree with; otherwise the
+    // env class wins uncontested and the lookup happens once, below.
+    envOrg = await orgOfProject(envProject, { required: false });
+    envDetail = PROJECT_ENV;
+  }
+
+  if (envOrg && bindingOrg && envOrg !== bindingOrg && !CONFLICT_EXEMPT.has(cmd)) {
+    // The wallet tier's rule, scoped to the same pair. A binding deliberately
+    // declared by a checkout outranks the profile's selection SILENTLY — that
+    // is what a binding is for — but an ambient env var disagreeing with a
+    // committed file is exactly the surprise worth stopping on.
+    fail({
+      code: "AMBIGUOUS_ORG",
+      message: `Ambiguous organization: ${envDetail}=${envOrg} but ${bindingHit.file} binds ${bindingOrg}.`,
+      hint: `Resolve with one of: pass --org <org_id>, unset ${envDetail}, or edit the binding file.`,
+      details: {
+        candidates: [
+          { org_id: envOrg, source: "env", source_detail: envDetail },
+          { org_id: bindingOrg, source: "binding", source_detail: bindingHit.file },
+        ],
+      },
+      next_actions: [
+        nextAction("edit_request", {
+          command: "run402 <command> --org <org_id>",
+          why: "The flag resolves the conflict for this call.",
+        }),
+      ],
+    });
+  }
+
+  if (envOrg) return { orgId: envOrg, source: "env", sourceDetail: envDetail };
+  if (envProject) {
+    const orgId = await orgOfProject(envProject, { required: false });
+    if (orgId) return { orgId, source: "env", sourceDetail: PROJECT_ENV };
+  }
+  if (bindingOrg) return { orgId: bindingOrg, source: "binding", sourceDetail: bindingHit.file };
+
+  // --- Class 4: profile state ----------------------------------------------
+  const selected = trimmed(coreGetActiveOrgId());
+  if (selected) {
+    return { orgId: assertOrgIdShape(selected, "org use"), source: "profile", sourceDetail: "org use" };
+  }
+  const activeProject = trimmed(getActiveProjectId());
+  if (activeProject) {
+    const orgId = await orgOfProject(activeProject, { required: false });
+    if (orgId) return { orgId, source: "profile", sourceDetail: "projects use" };
+  }
+
+  if (optional) return null;
+  fail({
+    code: "ORG_REQUIRED",
+    message: "No organization specified and no current organization set.",
+    hint: `Pass --org <org_id>, set ${ORG_ENV}, bind this directory in .run402.json, or run: run402 org use <org_id>`,
+    next_actions: orgRequiredActions(),
+  });
+  return null; // unreachable — fail() exits
+}
+
+/**
+ * Resolve the addressed organization id from normalized argv.
+ *
+ * The Wave E signature, preserved: callers that only need the id keep passing
+ * argv and getting a string back. Use {@link resolveOrg} when the provenance
+ * pair is wanted too.
+ */
+export async function resolveOrgId(a, opts = {}) {
+  const resolved = await resolveOrg(a, opts);
+  return resolved ? resolved.orgId : null;
+}
+
+/** Validate an org id supplied by a human, naming the origin. Throws via fail(). */
+export function requireOrgIdShape(orgId, origin = "--org") {
+  return assertOrgIdShape(orgId, origin);
+}
+
+/** The profile's selected organization, without running the chain. */
+export function getSelectedOrgId() {
+  return trimmed(coreGetActiveOrgId());
+}
+
+/** Record the profile's selected organization. */
+export function setSelectedOrgId(orgId, origin = "org use") {
+  coreSetActiveOrgId(assertOrgIdShape(orgId, origin));
+}
+
+/** Clear the profile's selected organization. */
+export function clearSelectedOrgId() {
+  coreClearActiveOrgId();
+}
+
+/**
+ * Stamp a project's owning organization as the profile selection.
+ *
+ * Called by `projects use`: a project determines its organization
+ * unambiguously, so selecting one keeps the two lowest classes from ever
+ * disagreeing in practice — and gives an existing user a current org without
+ * reading a changelog. Best-effort: a failure here must never fail the project
+ * selection the caller actually asked for.
+ */
+export async function stampOrgFromProject(projectId) {
+  try {
+    const orgId = await orgOfProject(projectId, { required: false });
+    if (orgId) {
+      coreSetActiveOrgId(orgId);
+      return orgId;
+    }
+  } catch {
+    /* best-effort */
+  }
+  return null;
+}
+
+/** Provenance pair for command output: bounded, never a resolution trace. */
+export function orgProvenance(resolved) {
+  return resolved
+    ? { org_id: resolved.orgId, org_source: resolved.source, org_source_detail: resolved.sourceDetail }
+    : { org_id: null, org_source: null, org_source_detail: null };
 }
 
 /**

package/lib/org.mjs

@@ -1,9 +1,20 @@
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
+import { readBindingFile, updateBindingFile } from "./wallet-context.mjs";
+import { nextAction } from "./next-actions.mjs";
+import {
+  requireOrgIdShape,
+  resolveOrg,
+  orgProvenance,
+  getSelectedOrgId,
+  setSelectedOrgId,
+  clearSelectedOrgId,
+} from "./org-context.mjs";
 import {
   normalizeArgv,
   assertKnownFlags,
   flagValue,
+  positionalArgs,
   parseIntegerFlag,
   requirePositionalCount,
   failUnknownSubcommand,
@@ -20,6 +31,11 @@ Usage:
   run402 org rename <org_id> --name <display_name>   (or: --clear to remove the label)
   run402 org payout-wallet <org_id> --wallet <wallet_address>  (or: --clear to remove the explicit default)
   run402 org whoami
+  run402 org use     <org_id>
+  run402 org current
+  run402 org clear
+  run402 org bind   [--org <org_id>] [--room <key>]
+  run402 org unbind
   run402 org audit  <org_id> [--limit N] [--after <cursor>] [--before <cursor>]
   run402 org member list <org_id>
   run402 org member add  <org_id> --wallet <wallet_address> [--role <role>]
@@ -37,6 +53,11 @@ Subcommands:
   list        Orgs you are a member of
   get         Read one org (label + tier/lease + your role)
   rename      Set or clear an org's display label (owner-only)
+  use         Select the current org for this wallet profile
+  current     Report the resolved current org and where it came from
+  clear       Clear this wallet profile's org selection
+  bind        Write this checkout's org (+room) into .run402.json — commit it
+  unbind      Remove the org/room keys from .run402.json
   payout-wallet  Set or clear the tenant route payout wallet (admin+)
   whoami      Resolved principal + org memberships (GET /agent/v1/whoami)
   member      Manage members (list, add, role, rm) — mutations require owner
@@ -198,6 +219,145 @@ async function whoami(args) {
   }
 }
 
+// ── Current organization (add-cli-current-org) ─────────────────────────────────
+//
+// The selection is per WALLET PROFILE, not global: the chain is
+// wallet -> principal -> memberships, so a global selection survives
+// `wallets use other` and then either 403s or silently resolves to a
+// valid-but-wrong org when both principals are members.
+
+async function use(args) {
+  const a = normalizeArgv(args);
+  assertKnownFlags(a, ["--help", "-h"]);
+  requirePositionalCount(a, [], {
+    min: 1, max: 1, command: "run402 org use <org_id>", missing: "<org_id>",
+  });
+  const orgId = positionalArgs(a, [])[0];
+  setSelectedOrgId(orgId);
+  console.log(JSON.stringify({ org_id: orgId, selected: true, scope: "wallet_profile" }, null, 2));
+}
+
+async function clear(args) {
+  const a = normalizeArgv(args);
+  assertKnownFlags(a, ["--help", "-h"]);
+  requirePositionalCount(a, [], { min: 0, max: 0, command: "run402 org clear" });
+  const previous = getSelectedOrgId();
+  clearSelectedOrgId();
+  console.log(JSON.stringify({ org_id: null, selected: false, previous_org_id: previous ?? null }, null, 2));
+}
+
+/**
+ * Slugify a directory name into a legal room key.
+ * Room keys match /^[a-z0-9][a-z0-9._-]{0,63}$/ (the DB CHECK on every
+ * agent-messaging table), so the repo's own name has to be coerced, not trusted.
+ */
+function roomKeyFromDir(dir) {
+  const base = dir.split("/").filter(Boolean).pop() ?? "";
+  const slug = base.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+/, "").slice(0, 64);
+  return /^[a-z0-9]/.test(slug) ? slug : null;
+}
+
+/**
+ * Write this checkout's org (and room) into `.run402.json`.
+ *
+ * WHY THIS PICKS FOR YOU WHEN YOU OWN EXACTLY ONE ORG, while the resolution
+ * chain never does: they are different acts. The chain runs on EVERY command
+ * and must not change meaning the day you are invited to a second org — so it
+ * refuses to infer. This runs ONCE, because you asked it to, and it WRITES THE
+ * ANSWER DOWN. Nothing is inferred afterwards; the file is read verbatim
+ * forever after. An explicit act with a recorded result is not a heuristic.
+ *
+ * With two or more orgs there is nothing to pick, so it lists them and stops.
+ */
+async function bind(args) {
+  const a = normalizeArgv(args);
+  const valueFlags = ["--org", "--room"];
+  assertKnownFlags(a, [...valueFlags, "--help", "-h"], valueFlags);
+  requirePositionalCount(a, valueFlags, { min: 0, max: 0, command: "run402 org bind [--org <org_id>] [--room <key>]" });
+
+  let orgId = flagValue(a, "--org");
+  let picked = "flag";
+  if (!orgId) {
+    let orgs;
+    try {
+      orgs = await getSdk().orgs.list();
+    } catch (err) {
+      reportSdkError(err);
+      return;
+    }
+    const rows = Array.isArray(orgs) ? orgs : (orgs?.orgs ?? []);
+    if (rows.length === 0) {
+      fail({
+        code: "NO_ORGS",
+        message: "This wallet is a member of no organization yet.",
+        hint: "Run 'run402 init' to provision one, or ask an owner to add you with 'run402 org member add'.",
+        next_actions: [nextAction("initialize_wallet", { command: "run402 init", why: "Provision this wallet's organization, then retry." })],
+      });
+    }
+    if (rows.length > 1) {
+      fail({
+        code: "AMBIGUOUS_ORG",
+        message: `This wallet belongs to ${rows.length} organizations — name the one to bind.`,
+        hint: "run402 org bind --org <org_id>",
+        details: { orgs: rows.map((o) => ({ org_id: o.org_id, display_name: o.display_name ?? null, role: o.role ?? null })) },
+        next_actions: [nextAction("edit_request", { command: "run402 org bind --org <org_id>", why: "Name which organization this checkout coordinates in." })],
+      });
+    }
+    orgId = rows[0].org_id;
+    picked = "sole_membership";
+  }
+
+  const room = flagValue(a, "--room") ?? roomKeyFromDir(process.cwd());
+  const { contents, file } = updateBindingFile(process.cwd(), {
+    org: requireOrgIdShape(orgId, picked === "flag" ? "--org" : "org list"),
+    ...(room ? { room } : {}),
+  });
+  console.log(JSON.stringify({
+    org_id: orgId,
+    room_key: room ?? null,
+    org_source: picked,
+    file: ".run402.json",
+    path: file,
+    bound: true,
+    safe_to_commit: true,
+    note: "Safe to commit — an org id is an identifier, not a credential; authorization stays server-side.",
+    binding: contents,
+  }, null, 2));
+}
+
+async function unbind(args) {
+  const a = normalizeArgv(args);
+  assertKnownFlags(a, ["--help", "-h"]);
+  requirePositionalCount(a, [], { min: 0, max: 0, command: "run402 org unbind" });
+  const previous = readBindingFile(process.cwd());
+  const { contents, removed } = updateBindingFile(process.cwd(), { org: null, room: null });
+  console.log(JSON.stringify({
+    file: ".run402.json",
+    unbound: previous.org !== undefined || previous.room !== undefined,
+    removed,
+    binding: contents,
+  }, null, 2));
+}
+
+async function current(args) {
+  const a = normalizeArgv(args);
+  assertKnownFlags(a, ["--help", "-h"]);
+  requirePositionalCount(a, [], { min: 0, max: 0, command: "run402 org current" });
+  try {
+    // `cmd: "org"` exempts this from the ambiguity error on purpose: the
+    // command that reports the selection must stay usable while it is ambiguous.
+    // `optional` keeps an empty selection an explicit null state rather than a
+    // failure — reporting is not acting.
+    const resolved = await resolveOrg([], { cmd: "org", optional: true });
+    console.log(JSON.stringify({
+      ...orgProvenance(resolved),
+      selected_org_id: getSelectedOrgId() ?? null,
+    }, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
 async function get(args) {
   const a = normalizeArgv(args);
   assertKnownFlags(a, ["--help", "-h"]);
@@ -471,6 +631,11 @@ export async function run(sub, args) {
     case "rename": await rename(args); break;
     case "payout-wallet": await payoutWallet(args); break;
     case "whoami": await whoami(args); break;
+    case "use": await use(args); break;
+    case "current": await current(args); break;
+    case "clear": await clear(args); break;
+    case "bind": await bind(args); break;
+    case "unbind": await unbind(args); break;
     case "audit": await audit(args); break;
     default:
       failUnknownSubcommand("org", sub);

package/lib/projects.mjs

@@ -5,6 +5,7 @@ import { loadLiveControlPlaneSession } from "../core-dist/control-plane-session.
 import { withAutoApprove } from "./operator.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail, parseFlagJson } from "./sdk-errors.mjs";
+import { stampOrgFromProject } from "./org-context.mjs";
 import { assertKnownFlags, failBadProjectId, flagValue, hasHelp, normalizeArgv, positionalArgs, resolveProjectSelector, validateRegularFile, failUnknownSubcommand } from "./argparse.mjs";
 
 const HELP = `run402 projects — Manage your deployed Run402 projects
@@ -802,7 +803,11 @@ async function use(projectId) {
   }
   try {
     await getSdk().projects.use(projectId);
-    console.log(JSON.stringify({ active_project_id: projectId, set: true }));
+    // A project determines its org unambiguously, so selecting one also makes
+    // that org current (add-cli-current-org D4). Best-effort by construction:
+    // the project selection the caller asked for must not fail on this.
+    const orgId = await stampOrgFromProject(projectId);
+    console.log(JSON.stringify({ active_project_id: projectId, set: true, org_id: orgId ?? null }));
   } catch (err) {
     reportSdkError(err);
   }

package/lib/rooms-context.mjs

@@ -5,6 +5,10 @@
  * Room addressing (precedence):
  *   --org <org_id> + --room <key>   explicit (named org rooms)
  *   RUN402_ROOM=<org_id>/<key>      env form of the same
+ *   <room key> + the shared chain   a room key from --room or the binding
+ *                                   file's `room`, with the ORG resolved by
+ *                                   `org-context.mjs` — this is what reaches a
+ *                                   named room in a checkout with no project
  *   (default)                       the project's DEFAULT room — the room key
  *                                   IS the project id; org resolved via the
  *                                   project overview (`rooms.forProject`).
@@ -21,8 +25,11 @@
 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 { getActiveProjectId } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
+import { resolveOrg } from "./org-context.mjs";
+import { findBindingKey } from "./wallet-context.mjs";
+import { nextAction } from "./next-actions.mjs";
 
 export const ROOM_ENV = "RUN402_ROOM";
 export const PRESENCE_ENV = "RUN402_PRESENCE_ID";
@@ -30,16 +37,22 @@ 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). */
+/**
+ * Resolve the addressed room to { orgId, roomKey } (one SDK lookup at most).
+ *
+ * A room is a PAIR, and this function owns the pair. What it no longer owns is
+ * the org half of its own fallback: below the explicit forms, the org comes
+ * from the shared chain in `org-context.mjs` (flag → env → binding → profile
+ * selection → active project) while the room key comes from `--room`, the
+ * binding file's `room` key, or the project's default room. That is what makes
+ * a named room reachable in a checkout with no project link at all.
+ */
 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 };
+  // 1. Both halves named explicitly.
+  if (org && room) return { orgId: org, roomKey: room, orgSource: "flag", orgSourceDetail: "--org" };
+
+  // 2. The compound env form names both, and keeps outranking everything below
+  //    it — a harness wired with RUN402_ROOM selects exactly the room it names.
   const envRoom = (process.env[ROOM_ENV] ?? "").trim();
   if (envRoom) {
     const slash = envRoom.indexOf("/");
@@ -50,11 +63,61 @@ export async function resolveRoom({ org, room, project } = {}) {
         details: { value: envRoom },
       });
     }
-    return { orgId: envRoom.slice(0, slash), roomKey: envRoom.slice(slash + 1) };
+    return {
+      orgId: envRoom.slice(0, slash),
+      roomKey: envRoom.slice(slash + 1),
+      orgSource: "env",
+      orgSourceDetail: ROOM_ENV,
+    };
+  }
+
+  // 3. A room key without an org: the org resolves through the shared chain.
+  //    (`--room` alone used to be a hard error; it now works whenever the org
+  //    resolves, and fails with ORG_REQUIRED — naming every way to supply one —
+  //    when it does not.)
+  const bindingRoom = findBindingKey(process.cwd(), "room");
+  const roomKey = room ?? bindingRoom?.value ?? null;
+  if (roomKey) {
+    const resolved = await resolveOrg({ org, project }, { cmd: "rooms" });
+    return {
+      orgId: resolved.orgId,
+      roomKey,
+      orgSource: resolved.source,
+      orgSourceDetail: resolved.sourceDetail,
+    };
+  }
+
+  // 4. No room key anywhere: the project's DEFAULT room, whose key IS the
+  //    project id — the zero-config rendezvous carried by run402.config.json.
+  const effectiveProject = project || (process.env.RUN402_PROJECT_ID ?? "").trim() || getActiveProjectId();
+  if (!effectiveProject) {
+    fail({
+      code: "ROOM_REQUIRED",
+      message: "No room addressed and no current project to take a default room from.",
+      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>",
+          why: "Name the organization and room on this one call.",
+        }),
+        nextAction("edit_request", {
+          command: `echo '{"org":"<org_id>","room":"<key>"}' > .run402.json`,
+          why: "Bind this checkout so every agent in it lands in the same room with no flags.",
+        }),
+        nextAction("edit_request", {
+          command: "run402 projects use <project_id>",
+          why: "Select a project to use its default room (the room key IS the project id).",
+        }),
+      ],
+    });
   }
-  const projectId = resolveProjectId(project);
-  const scoped = await getSdk().rooms.forProject(projectId);
-  return { orgId: scoped.orgId, roomKey: scoped.roomKey };
+  const scoped = await getSdk().rooms.forProject(effectiveProject);
+  return {
+    orgId: scoped.orgId,
+    roomKey: scoped.roomKey,
+    orgSource: "profile",
+    orgSourceDetail: "projects use",
+  };
 }
 
 function statePath() {

package/lib/rooms.mjs

@@ -50,6 +50,12 @@ Room addressing (all subcommands):
   --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
@@ -155,6 +161,8 @@ async function who(args) {
     });
     console.log(JSON.stringify({
       org_id: room.orgId,
+      org_source: room.orgSource ?? null,
+      org_source_detail: room.orgSourceDetail ?? null,
       room_key: room.roomKey,
       you: me,
       ...page,

package/lib/wallet-context.mjs

@@ -19,7 +19,7 @@
  * wallets and no flag is given, that is a hard error (not a silent pick).
  */
 
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
 import { fail } from "./sdk-errors.mjs";
 import { isValidProfileName } from "../core-dist/config.js";
@@ -27,6 +27,7 @@ import { getDefaultWallet, profileExists, readMeta, profileDir } from "../core-d
 import { readAllowance } from "../core-dist/allowance.js";
 
 const DEFAULT = "default";
+const BINDING_FILE = ".run402.json";
 const GLOBAL_FLAGS = new Set(["--wallet", "--profile"]);
 // The `wallets` group is the management + escape surface — it must work even
 // when selection is ambiguous (so you can `wallets unbind`), and it validates
@@ -69,14 +70,14 @@ export function splitWalletFlag(rawArgv = []) {
   return { argv, walletFlag: flag };
 }
 
-function readBindingFrom(dir) {
+function readBindingKeyFrom(dir, key) {
   // .run402.local.json (gitignored personal override) beats .run402.json.
   for (const fname of [".run402.local.json", ".run402.json"]) {
     const p = join(dir, fname);
     try {
       const parsed = JSON.parse(readFileSync(p, "utf8"));
-      const w = parsed?.wallet;
-      if (typeof w === "string" && w.trim()) return { wallet: w.trim(), file: p };
+      const v = parsed?.[key];
+      if (typeof v === "string" && v.trim()) return { value: v.trim(), file: p };
     } catch {
       /* missing / unreadable / malformed → skip */
     }
@@ -84,18 +85,71 @@ function readBindingFrom(dir) {
   return null;
 }
 
-/** Nearest binding walking up from `startDir` to the filesystem root. */
-export function findBinding(startDir) {
+/** Path of the committed binding file for a directory. */
+export function bindingFilePath(dir = process.cwd()) {
+  return join(dir, BINDING_FILE);
+}
+
+/** Parse a directory's committed binding file, or `{}` when absent/unreadable. */
+export function readBindingFile(dir = process.cwd()) {
+  try {
+    const parsed = JSON.parse(readFileSync(bindingFilePath(dir), "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * MERGE keys into a directory's binding file. A `null` value removes its key;
+ * a file left with no keys is deleted rather than committed empty.
+ *
+ * The file is shared by tiers (`wallet` from `wallets bind`, `org`/`room` from
+ * `org bind`) and unknown keys are preserved, so one tier can never clobber
+ * another's binding — which a whole-file write did until this existed.
+ */
+export function updateBindingFile(dir, patch) {
+  const file = bindingFilePath(dir);
+  const next = { ...readBindingFile(dir) };
+  for (const [k, v] of Object.entries(patch)) {
+    if (v === null || v === undefined) delete next[k];
+    else next[k] = v;
+  }
+  if (Object.keys(next).length === 0) {
+    const existed = existsSync(file);
+    if (existed) rmSync(file, { force: true });
+    return { file, contents: null, removed: existed };
+  }
+  writeFileSync(file, JSON.stringify(next, null, 2) + "\n");
+  return { file, contents: next, removed: false };
+}
+
+/**
+ * Nearest binding carrying `key`, walking up from `startDir` to the root.
+ *
+ * Keys bind INDEPENDENTLY (add-cli-current-org, design D7): a file declaring
+ * only `org` leaves wallet resolution untouched, and each key resolves at the
+ * nearest file that carries it — so `/work/.run402.json` may supply the org
+ * while `/work/api/.run402.json` supplies the wallet. Unknown keys are ignored,
+ * which is what makes older CLIs forward-compatible with these files.
+ */
+export function findBindingKey(startDir, key) {
   let dir = resolve(startDir);
   for (;;) {
-    const b = readBindingFrom(dir);
-    if (b) return b;
+    const hit = readBindingKeyFrom(dir, key);
+    if (hit) return hit;
     const parent = dirname(dir);
     if (parent === dir) return null;
     dir = parent;
   }
 }
 
+/** Nearest wallet binding walking up from `startDir` to the filesystem root. */
+export function findBinding(startDir) {
+  const hit = findBindingKey(startDir, "wallet");
+  return hit ? { wallet: hit.value, file: hit.file } : null;
+}
+
 function assertValidName(name, origin) {
   if (name === DEFAULT || isValidProfileName(name)) return;
   fail({

package/lib/wallets.mjs

@@ -32,6 +32,7 @@ import {
 } from "../core-dist/profiles.js";
 import { readAllowance, saveAllowance } from "../core-dist/allowance.js";
 import { getSdk } from "./sdk.mjs";
+import { readBindingFile, updateBindingFile } from "./wallet-context.mjs";
 
 const DEFAULT = "default";
 const PRIVATE_KEY_RE = /^0x[0-9a-fA-F]{64}$/;
@@ -208,14 +209,15 @@ async function cmdRename(args) {
 function cmdBind(args) {
   let name = args.find((a) => a && !a.startsWith("-"));
   name = name ? requireName(name) : getActiveProfile();
-  const file = join(process.cwd(), ".run402.json");
-  writeFileSync(file, JSON.stringify({ wallet: name }, null, 2) + "\n");
+  // MERGE, never clobber: the same file carries `org`/`room` from `org bind`.
+  const { contents } = updateBindingFile(process.cwd(), { wallet: name });
   const result = {
     wallet: name,
     file: ".run402.json",
     bound: true,
     safe_to_commit: true,
     note: "Safe to commit — contains no secrets, only the wallet name.",
+    binding: contents,
   };
   if (name !== DEFAULT && !profileExists(name)) {
     result.warning = `No local wallet named '${name}' yet — create it with 'run402 wallets new ${name}'.`;
@@ -224,10 +226,12 @@ function cmdBind(args) {
 }
 
 function cmdUnbind() {
-  const file = join(process.cwd(), ".run402.json");
-  const existed = existsSync(file);
-  if (existed) rmSync(file, { force: true });
-  out({ file: ".run402.json", unbound: existed });
+  // Removes only the WALLET key. An `org`/`room` binding in the same file
+  // belongs to another tier and must survive; the file is deleted only when
+  // unbinding leaves nothing behind.
+  const had = readBindingFile(process.cwd()).wallet !== undefined;
+  const { contents, removed } = updateBindingFile(process.cwd(), { wallet: null });
+  out({ file: ".run402.json", unbound: had, removed, binding: contents });
 }
 
 async function cmdImport(args) {

package/package.json

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

package/sdk/core-dist/profile-state.js

@@ -126,6 +126,52 @@ export function clearActiveProjectId(projectId, path, scope = {}) {
         saveProfileState(state, p);
     });
 }
+// ---------------------------------------------------------------------------
+// Selected organization (add-cli-current-org, design D3).
+//
+// Scoped exactly like the active project id — by api_base, profile, and
+// principal — and stored in the SAME per-profile state.json, never in the
+// base-level config.json beside `active_wallet`. The chain is
+// wallet -> principal -> memberships, so a globally-selected org survives
+// `wallets use other` and then either 403s or, worse, silently resolves to a
+// valid-but-wrong org when both principals are members. Per-profile makes the
+// failure mode "this profile has no current org", which the ORG_REQUIRED
+// envelope already knows how to explain.
+//
+// There is deliberately no top-level `active_org_id` mirror: the project one
+// exists only to carry pre-scoping installs forward, and this key is new.
+// ---------------------------------------------------------------------------
+export function getActiveOrgId(path, scope = {}) {
+    const state = loadProfileState(path);
+    return state.active_orgs?.[activeProjectScopeKey(scope)]?.org_id;
+}
+export function setActiveOrgId(orgId, path, scope = {}) {
+    const p = path ?? getProfileStatePath();
+    withFileLock(p, () => {
+        const state = loadProfileState(p);
+        const key = activeProjectScopeKey(scope);
+        const resolved = defaultActiveProjectScope(scope);
+        state.active_orgs = state.active_orgs ?? {};
+        state.active_orgs[key] = {
+            org_id: orgId,
+            api_base: resolved.api_base,
+            principal: resolved.principal ?? null,
+            profile: resolved.profile,
+            updated_at: new Date().toISOString(),
+        };
+        saveProfileState(state, p);
+    });
+}
+export function clearActiveOrgId(path, scope = {}) {
+    const p = path ?? getProfileStatePath();
+    withFileLock(p, () => {
+        const state = loadProfileState(p);
+        const key = activeProjectScopeKey(scope);
+        if (state.active_orgs?.[key])
+            delete state.active_orgs[key];
+        saveProfileState(state, p);
+    });
+}
 export function recordMigration(marker, value, path) {
     const p = path ?? getProfileStatePath();
     withFileLock(p, () => {