run402 4.97.0 → 4.99.0

package/lib/org-context.mjs

@@ -1,182 +1,42 @@
 /**
- * Shared organization resolution for org-scoped CLI families
- * (attention-architecture Wave E — one resolver, not one per family;
- * extended by add-cli-current-org with the local-context classes).
- *
- * 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.
- *
- * 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 <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.
+ * Organization resolution for org-scoped CLI families: the CLI edge of
+ * `r.orgs.resolve()` (`@run402/sdk/node`), which owns the precedence chain —
+ * flag (`--org`, then `--project`), environment (`RUN402_ORG`, the org half of
+ * `RUN402_ROOM`, then `RUN402_PROJECT_ID`), the `.run402.json` binding, this
+ * checkout's vault pin, then profile state (`orgs use`, then the active
+ * project). This module adds only what is CLI-shaped: reading the flags out of
+ * argv, the leading `<org_id>` positional contract, the per-command conflict
+ * exemption, and printing a refusal as the CLI's error envelope.
  *
  * `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).
+ * `RUN402_ROOM` form — see `rooms-context.mjs`; only the org half of their
+ * fallback delegates here.
  */
 import { getSdk } from "./sdk.mjs";
 import { flagValue, positionalArgs } from "./argparse.mjs";
-import { findBindingKey } from "./wallet-context.mjs";
-import { fail } from "./sdk-errors.mjs";
-import { nextAction } from "./next-actions.mjs";
-import { describeRejectedValue } from "../core-dist/redact.js";
-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";
+import { fail, failLocal } from "./sdk-errors.mjs";
+import { ORG_ID_RE, assertOrgIdShape, orgProvenance, orgRequiredError } from "#sdk/node";
 
-export const ORG_ENV = "RUN402_ORG";
-export const ROOM_ENV = "RUN402_ROOM";
-export const PROJECT_ENV = "RUN402_PROJECT_ID";
+export { ORG_ENV, ROOM_ENV, PROJECT_ENV, orgProvenance } from "#sdk/node";
 
 /** Command groups that must stay usable while selection is ambiguous. */
 const CONFLICT_EXEMPT = new Set(["orgs", "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}$/;
+/** The refusals the resolver itself raises; anything else is the server's answer. */
+const RESOLVER_CODES = new Set(["BAD_ORG_ID", "AMBIGUOUS_ORG", "ORG_REQUIRED"]);
 
 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.
- *
- * A rejected value is a value we know nothing about — see
- * core-dist/redact.js's doc comment: the
- * same class of mistake that put a private key into RUN402_WALLET can put
- * one into RUN402_ORG / --org, so this must never echo the raw value.
- */
-function assertOrgIdShape(orgId, origin) {
-  if (ORG_ID_RE.test(orgId)) return orgId;
-  fail({
-    code: "BAD_ORG_ID",
-    message: `Invalid organization id ${JSON.stringify(describeRejectedValue(orgId))} (from ${origin}).`,
-    hint: "An org_id is a UUID. Run 'run402 orgs list' to see the organizations you belong to.",
-    details: { org_id: describeRejectedValue(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);
-}
-
-/**
- * `r402.orgId` from `cwd`'s LOCAL git config (kygit-handoff design D10) —
- * best-effort, gracefully degrading like `findBindingKey`: no repository,
- * no pin, or a shape-invalid value all answer `null` rather than throwing,
- * so a bare directory or a checkout with no vault remote costs nothing.
- * Checks a real vault checkout's pin first (gated on `r402.repoId`), then
- * falls back to the bare org/room pin a room-only `rooms join <key>` writes
- * in a directory with no vault at all (add-room-invite design D10).
- */
-async function readVaultPinnedOrgId(cwd) {
-  try {
-    const { readPinnedVaultRepo, readPinnedRoomBinding } = await import("#sdk/node");
-    const pinned = await readPinnedVaultRepo(cwd);
-    const orgId = trimmed(pinned?.org_id);
-    if (orgId && ORG_ID_RE.test(orgId)) return orgId;
-    const bare = await readPinnedRoomBinding(cwd);
-    const bareOrgId = trimmed(bare?.org_id);
-    return bareOrgId && ORG_ID_RE.test(bareOrgId) ? bareOrgId : null;
-  } catch {
-    return null;
-  }
-}
-
-function listOrgsAction() {
-  return nextAction("edit_request", {
-    command: "run402 orgs list",
-    why: "List the organizations this wallet belongs to.",
-  });
-}
-
-function orgRequiredActions() {
-  return [
-    nextAction("edit_request", {
-      command: "run402 orgs 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;
-  }
+/** Print a resolver refusal as the CLI envelope; rethrow a server or network error. */
+function failResolver(err) {
+  if (err?.kind === "local_error" && RESOLVER_CODES.has(err?.code)) failLocal(err);
+  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 {string[]|object} input normalized argv (`--org`, `--project` read from it), or { org, project }
  * @param {object}  [opts]
  * @param {string}  [opts.cmd]      command group, for the conflict exemption
  * @param {object}  [opts.env]      environment (injectable for tests)
@@ -188,136 +48,30 @@ 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 3.5: vault local pin (kygit-handoff design D10) ------------
-  // `r402.orgId` in this checkout's LOCAL git config — written by every
-  // vault pin site (`repos create`, `resume`, address resolution), a
-  // rung below env/binding and above profile state: a checkout that IS a
-  // resumed/pinned vault should resolve its own org with zero configuration,
-  // but an explicit env var or a committed `.run402.json` binding still wins.
-  const pinnedOrg = await readVaultPinnedOrgId(cwd);
-  if (pinnedOrg) return { orgId: pinnedOrg, source: "vault_pin", sourceDetail: "r402.orgId (local git config)" };
-
-  // --- Class 4: profile state ----------------------------------------------
-  const selected = trimmed(coreGetActiveOrgId());
-  if (selected) {
-    return { orgId: assertOrgIdShape(selected, "orgs use"), source: "profile", sourceDetail: "orgs use" };
-  }
-  const activeProject = trimmed(getActiveProjectId());
-  if (activeProject) {
-    const orgId = await orgOfProject(activeProject, { required: false });
-    if (orgId) return { orgId, source: "profile", sourceDetail: "projects use" };
+  try {
+    return await getSdk().orgs.resolve({ org, project }, { env, cwd, optional, allowConflict: CONFLICT_EXEMPT.has(cmd) });
+  } catch (err) {
+    return failResolver(err);
   }
-
-  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 orgs 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.
- */
+/** The addressed organization id from normalized argv (see {@link resolveOrg}). */
 export async function resolveOrgId(a, opts = {}) {
   const resolved = await resolveOrg(a, opts);
   return resolved ? resolved.orgId : null;
 }
 
 /**
- * The org-scoped POSITIONAL contract (cli-org-context, "One Resolver Serves
- * Every Org-Scoped Command").
- *
- * `<org_id>` is optional sugar on every verb that acts on an organization —
- * `orgs get`, `orgs members add`, `billing link-wallet`, … A leading positional
- * that IS an org id (a UUID) addresses that org; anything else is the verb's
- * own next positional (a wallet, an email, a principal) and the org comes from
- * the shared chain: `--org`, then `RUN402_ORG`, then the `.run402.json`
- * binding, then `orgs use`. So inside a bound checkout the two-agent case reads
- * `run402 orgs members add 0xB… --role developer` with nothing else to know.
- *
- * Naming the org twice with different values (positional AND `--org`) is
- * `AMBIGUOUS_ORG`, never a silent pick — the same refusal the env-vs-binding
- * pair gets. A non-org first positional with no chain answer fails
- * `ORG_REQUIRED` and NAMES the rejected value, so `orgs get foo` says why `foo`
- * did not count rather than reporting a bare "no organization".
+ * The org-scoped POSITIONAL contract: `<org_id>` is optional sugar on every
+ * verb that acts on an organization. A leading positional that IS an org id
+ * addresses that org; anything else is the verb's own next positional and the
+ * org comes from the chain. Naming the org twice with different values
+ * (positional AND `--org`) is `AMBIGUOUS_ORG`; a non-org first positional with
+ * no chain answer fails `ORG_REQUIRED` naming the rejected value.
  *
  * Returns the org id with provenance plus the REMAINING positionals; bound
- * those with {@link requireRest} using the verb's own usage line. Enforced
- * mechanically: every `orgScoped` entry in the command manifest is driven
- * through this shape by `cli-conventions-gate.test.mjs`.
+ * those with {@link requireRest}. Every `orgScoped` entry in the command
+ * manifest is driven through this shape by `cli-conventions-gate.test.mjs`.
  *
  * @param {string[]} a          normalized argv
  * @param {string[]} valueFlags flags that take a value (must include "--org")
@@ -345,16 +99,8 @@ export async function takeOrgPositional(a, valueFlags = [], opts = {}) {
   }
   const resolved = await resolveOrg(a, { ...opts, optional: true });
   if (resolved) return { orgId: resolved.orgId, rest: positionals, source: resolved.source, sourceDetail: resolved.sourceDetail };
-  fail({
-    code: "ORG_REQUIRED",
-    message: typeof first === "string"
-      ? `No organization specified and no current organization set (${JSON.stringify(first)} is not an org_id — an org_id is a UUID).`
-      : "No organization specified and no current organization set.",
-    hint: `Pass --org <org_id> (or a leading <org_id> positional), set ${ORG_ENV}, bind this directory in .run402.json, or run: run402 orgs use <org_id>`,
-    ...(typeof first === "string" ? { details: { rejected_positional: first } } : {}),
-    next_actions: orgRequiredActions(),
-  });
-  return null; // unreachable — fail() exits
+  failLocal(orgRequiredError({ ...(typeof first === "string" ? { rejectedPositional: first } : {}), positionalHint: true }));
+  return null; // unreachable — failLocal() exits
 }
 
 /**
@@ -377,94 +123,11 @@ export function requireRest(rest, opts = {}) {
   return rest;
 }
 
-/** Validate an org id supplied by a human, naming the origin. Throws via fail(). */
+/** Validate an org id supplied by a human, naming the origin. Exits on a bad shape. */
 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 = "orgs 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 };
-}
-
-/**
- * The organization that OWNS a specific project, or `null`.
- *
- * Distinct from {@link resolveOrgId}: that one answers "which org is this
- * command addressed at" (flag → env → active project); this one answers "who
- * owns THIS project id", which is what a project-scoped scaffold needs and
- * where an `--org` override would be a mis-binding, not a convenience.
- *
- * WHY IT CACHES (task 5.12c): the vault scaffold is the one part of
- * `run402 init` the client-surface spec says adds no network dependency to the
- * cold-start path, and resolving the org through `projects.list()` quietly made
- * that untrue. `org_id` is a non-secret routing identifier the control plane
- * already hands back with every listing, so the honest fix is to remember it —
- * the FIRST call on a machine still asks, every returning one reads it locally.
- *
- * Cached in the local project entry after the first lookup, and an EXACT id
- * match is required: a near-miss must never bind a vault or a git remote to
- * somebody else's project. `updateProject` is a no-op for a project this
- * machine holds no credentials for, so such a project asks again next time
- * rather than being silently mis-cached. Returns `null` rather than throwing —
- * every caller has something better to say than a stack trace.
- */
-export async function resolveOwningOrgId(projectId) {
-  const cached = getProject(projectId)?.org_id;
-  if (typeof cached === "string" && cached.length > 0) return cached;
   try {
-    const listed = await getSdk().projects.list();
-    const rows = Array.isArray(listed?.projects) ? listed.projects : [];
-    const row = rows.find((p) => (p?.id ?? p?.project_id) === projectId);
-    const orgId = row?.org_id;
-    if (typeof orgId !== "string" || orgId.length === 0) return null;
-    try {
-      updateProject(projectId, { org_id: orgId });
-    } catch {
-      // Caching is an optimization; a read-only or contended keystore costs a
-      // round trip next time and must never fail the caller.
-    }
-    return orgId;
-  } catch {
-    return null;
+    return assertOrgIdShape(orgId, origin);
+  } catch (err) {
+    return failResolver(err);
   }
 }

package/lib/orgs.mjs

@@ -1,17 +1,6 @@
 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,
-  takeOrgPositional,
-  requireRest,
-  orgProvenance,
-  getSelectedOrgId,
-  setSelectedOrgId,
-  clearSelectedOrgId,
-} from "./org-context.mjs";
+import { reportSdkError, fail, failLocal } from "./sdk-errors.mjs";
+import { resolveOrg, takeOrgPositional, requireRest } from "./org-context.mjs";
 import {
   normalizeArgv,
   assertKnownFlags,
@@ -370,130 +359,57 @@ async function use(args) {
   requirePositionalCount(a, [], {
     min: 1, max: 1, command: "run402 orgs 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));
+  await printOrgContext((orgs) => orgs.use(positionalArgs(a, [])[0]));
 }
 
 async function clear(args) {
   const a = normalizeArgv(args);
   assertKnownFlags(a, ["--help", "-h"]);
   requirePositionalCount(a, [], { min: 0, max: 0, command: "run402 orgs clear" });
-  const previous = getSelectedOrgId();
-  clearSelectedOrgId();
-  console.log(JSON.stringify({ org_id: null, selected: false, previous_org_id: previous ?? null }, null, 2));
+  await printOrgContext((orgs) => orgs.clear());
 }
 
 /**
- * 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.
+ * Write this checkout's org (and room) into `.run402.json`. With no `--org`,
+ * the caller's sole membership is written down; the resolution chain itself
+ * never infers one.
  */
 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 orgs 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 orgs members 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 orgs 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 orgs 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" : "orgs 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));
+  await printOrgContext((orgs) => orgs.bind(flagValue(a, "--org"), { room: flagValue(a, "--room") }));
 }
 
 async function unbind(args) {
   const a = normalizeArgv(args);
   assertKnownFlags(a, ["--help", "-h"]);
   requirePositionalCount(a, [], { min: 0, max: 0, command: "run402 orgs 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));
+  await printOrgContext((orgs) => orgs.unbind());
 }
 
 async function current(args) {
   const a = normalizeArgv(args);
   assertKnownFlags(a, ["--help", "-h"]);
   requirePositionalCount(a, [], { min: 0, max: 0, command: "run402 orgs current" });
+  await printOrgContext((orgs) => orgs.current());
+}
+
+/** The organization-context refusals `r.orgs` raises locally; anything else is the server's answer. */
+const ORG_CONTEXT_CODES = new Set(["BAD_ORG_ID", "AMBIGUOUS_ORG", "ORG_REQUIRED", "NO_ORGS"]);
+
+/** Run one `r.orgs` context verb and print its result, or the refusal envelope. */
+async function printOrgContext(fn) {
+  let result;
   try {
-    // `cmd: "orgs"` 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: "orgs", optional: true });
-    console.log(JSON.stringify({
-      ...orgProvenance(resolved),
-      selected_org_id: getSelectedOrgId() ?? null,
-    }, null, 2));
+    result = await fn(getSdk().orgs);
   } catch (err) {
+    if (err?.kind === "local_error" && ORG_CONTEXT_CODES.has(err?.code)) failLocal(err);
     reportSdkError(err);
+    return;
   }
+  console.log(JSON.stringify(result, null, 2));
 }
 
 async function get(args) {

package/lib/projects.mjs

@@ -4,7 +4,6 @@ import { loadLiveControlPlaneSession } from "../core-dist/control-plane-session.
 import { withAutoApprove } from "./sign-in.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
@@ -805,7 +804,7 @@ async function use(projectId) {
     // 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);
+    const orgId = await getSdk().orgs.selectFromProject(projectId);
     console.log(JSON.stringify({ active_project_id: projectId, set: true, org_id: orgId ?? null }));
   } catch (err) {
     reportSdkError(err);