@runuai/host 0.9.99 → 0.9.101

package/db/migrations/0017_engine_account_scope.sql

@@ -0,0 +1,7 @@
+-- ADR-131 Decision 3: engine accounts carry a scope — 'host' (the owner's,
+-- today's rows) or 'org:<orgId>' (a workspace's account on a shared host).
+-- Tasks resolve accounts by their scope; org scopes never see the default
+-- slot or the host's rows.
+ALTER TABLE `host_engine_accounts` ADD `scope` text NOT NULL DEFAULT 'host';--> statement-breakpoint
+CREATE INDEX `host_engine_accounts_scope_kind_idx` ON `host_engine_accounts` (`scope`,`kind`);--> statement-breakpoint
+ALTER TABLE `uai_host_tasks` ADD `engine_account_scope` text;

package/db/migrations/meta/_journal.json

@@ -120,6 +120,13 @@
       "when": 1786406402000,
       "tag": "0016_task_environment",
       "breakpoints": true
+    },
+    {
+      "idx": 17,
+      "version": "6",
+      "when": 1788820000000,
+      "tag": "0017_engine_account_scope",
+      "breakpoints": true
     }
   ]
 }

package/db/schema.ts

@@ -37,6 +37,10 @@ export const hostTasks = sqliteTable(
     ownerEmail: text("owner_email"),
     ownerName: text("owner_name"),
     projectSlugs: text("project_slugs").notNull().default("[]"),
+    // ADR-131 D3: which engine-account scope this task resolves credentials
+    // from ("org:<orgId>" on a shared host; null = "host"). Persisted so a
+    // host restart re-provisions the same scope before the cloud re-sends it.
+    engineAccountScope: text("engine_account_scope"),
     lockedAt: integer("locked_at", { mode: "number" }),
     startedAt: integer("started_at", { mode: "number" }),
     endedAt: integer("ended_at", { mode: "number" }),
@@ -271,6 +275,9 @@ export const engineAccounts = sqliteTable("host_engine_accounts", {
   authKind: text("auth_kind").notNull(), // "env" | "config-dir"
   secretEnc: text("secret_enc"), // sealed JSON (env kind); null for config-dir
   configDir: text("config_dir"), // host dir (config-dir kind); null for env
+  // ADR-131 D3: "host" (owner-level, default) or "org:<orgId>" (a workspace's
+  // account on a shared host). Resolution is by exact scope.
+  scope: text("scope").notNull().default("host"),
   createdAt: integer("created_at", { mode: "number" }).notNull(),
 });
 

package/lib/agents/cursor.ts

@@ -192,7 +192,12 @@ export class CursorSession implements AgentSession {
     this.agentEnv = args.agentEnv ?? {};
     this.spawner =
       args.spawner ?? ((request) => spawnEnvironmentProcess(this.environment, request));
-    this.apiKey = args.apiKey ?? process.env.CURSOR_API_KEY ?? "";
+    // An account-bound key (ADR-076/ADR-131 D3, injected through agentEnv)
+    // beats the host's own .env.local key — a workspace's Cursor account must
+    // never fall through to the operator's, and on a shared host the ambient
+    // key is usually absent anyway.
+    this.apiKey =
+      args.apiKey ?? this.agentEnv.CURSOR_API_KEY ?? process.env.CURSOR_API_KEY ?? "";
   }
 
   onEvent(handler: AgentEventHandler): () => void {

package/lib/agents/registry.ts

@@ -72,6 +72,21 @@ const adapters = new Map<string, RegisteredAdapter>();
 /** Listeners fired after any registry mutation (manual re-advertise hook). */
 const changeListeners = new Set<() => void>();
 
+/**
+ * ADR-131 D3: a second source of "usable on this host" beyond the adapter's
+ * own `available()`, which only sees the host's default credential. The host
+ * agent installs the engine-account store here so a kind with a stored
+ * (workspace- or host-scoped) account is advertised even when the owner never
+ * signed in to it. Installed by main.ts; absent in unit tests.
+ */
+let advertisementFallback: (kind: string) => boolean = () => false;
+
+export function setAdvertisementFallback(
+  fallback: ((kind: string) => boolean) | null,
+): void {
+  advertisementFallback = fallback ?? (() => false);
+}
+
 /**
  * Register (or replace) an adapter for a kind. Called at module load by the
  * adapter modules. Replacing is allowed so a later import wins deterministically.
@@ -107,7 +122,10 @@ export function supportsExecutionProfile(kind: string, profileId: string): boole
  */
 export function capabilities(): AgentKindCapability[] {
   return list()
-    .filter((adapter) => adapter.available?.() ?? true)
+    .filter(
+      (adapter) =>
+        (adapter.available?.() ?? true) || advertisementFallback(adapter.kind),
+    )
     .map((adapter) => {
     const out: AgentKindCapability = {
       kind: adapter.kind,
@@ -143,4 +161,5 @@ export function onChange(listener: () => void): () => void {
 export function reset(): void {
   adapters.clear();
   changeListeners.clear();
+  advertisementFallback = () => false;
 }

package/lib/engine-accounts.ts

@@ -22,6 +22,10 @@
  * caps reset over time).
  */
 
+import {
+  HOST_ACCOUNT_SCOPE,
+  isEngineAccountScope,
+} from "../src/protocol";
 import { chmodSync, existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -60,6 +64,11 @@ interface KindDescriptor {
 
 const KINDS: Record<string, KindDescriptor> = {
   claude: { authKind: "env" },
+  // API-key engines: an extra account is one env var. The default slot stays
+  // the host's own `.env.local` key (the adapters read process.env), so these
+  // never synthesize a default — `defaultAvailable` is false for them.
+  grok: { authKind: "env" },
+  cursor: { authKind: "env" },
   codex: {
     authKind: "config-dir",
     defaultHostDir: (owner) => join(owner, ".codex"),
@@ -78,6 +87,39 @@ const KINDS: Record<string, KindDescriptor> = {
   },
 };
 
+/** The env var an extra API-key account injects, per kind (the same vars the
+ *  adapters read for the host's own key). Claude is special-cased in
+ *  `addEngineAccount` (token vs. key); Codex writes an auth.json instead. */
+const API_KEY_ENV_VARS: Record<string, string> = {
+  grok: "XAI_API_KEY",
+  cursor: "CURSOR_API_KEY",
+};
+const API_KEY_ENGINE_LABELS: Record<string, string> = {
+  grok: "Grok",
+  cursor: "Cursor",
+};
+
+/**
+ * Whether ANY stored account exists for `kind`, in any scope. The
+ * advertisement fallback (ADR-131 D3): an adapter's `available()` only sees
+ * the host's own credential, so a shared host whose owner never signed in to
+ * Codex hid the kind from every workspace that had connected its own account
+ * — the cloud then refused the crew with "host does not support agent kind".
+ * A stored account is a usable credential; the cloud scopes it per caller.
+ */
+export function hasStoredEngineAccounts(kind: string): boolean {
+  if (!KINDS[kind]) return false;
+  try {
+    return getDb()
+      .select()
+      .from(schema.engineAccounts)
+      .all()
+      .some((row) => row.kind === kind);
+  } catch {
+    return false;
+  }
+}
+
 /** Public (secret-free) account descriptor for the host UI. */
 export interface EngineAccountInfo {
   id: string;
@@ -85,6 +127,8 @@ export interface EngineAccountInfo {
   label: string;
   authKind: AccountAuthKind;
   isDefault: boolean;
+  /** ADR-131 D3: "host" or "org:<orgId>". */
+  scope: string;
 }
 
 /** A fully-resolved account, ready to inject / provision (host-trusted; the
@@ -94,6 +138,8 @@ export interface ResolvedEngineAccount {
   kind: string;
   label: string;
   isDefault: boolean;
+  /** ADR-131 D3: "host" or "org:<orgId>". */
+  scope: string;
   authKind: AccountAuthKind;
   /** Env merged into the agent's docker exec. Empty for the default env
    *  account (the ambient `.env.local` credential is account #1). */
@@ -141,6 +187,27 @@ function unpackSecret(enc: string): string {
   return openAesGcm(ct, nonce);
 }
 
+// ---------------------------------------------------------------------------
+// Scopes (ADR-131 Decision 3).
+// ---------------------------------------------------------------------------
+
+/**
+ * Every account has a scope. `host` is the owner's: the default slot plus
+ * every extra account connected before scopes existed (and every one an
+ * owner connects on a BYO/dedicated host). `org:<orgId>` is a workspace's
+ * account on a shared host: resolved ONLY for that workspace's tasks, and
+ * never joined by the default slot — a tenant sees exactly what it connected.
+ */
+export { HOST_ACCOUNT_SCOPE, isEngineAccountScope };
+
+/** A row's scope (legacy rows read as `host`) matches the requested one. */
+export function accountInScope(
+  rowScope: string | null | undefined,
+  scope: string,
+): boolean {
+  return (rowScope ?? HOST_ACCOUNT_SCOPE) === scope;
+}
+
 // ---------------------------------------------------------------------------
 // Resolution.
 // ---------------------------------------------------------------------------
@@ -177,6 +244,7 @@ function synthesizeDefault(
       label: "Default",
       isDefault: true,
       authKind: "env",
+      scope: HOST_ACCOUNT_SCOPE,
       execEnv: {},
     };
   }
@@ -187,6 +255,7 @@ function synthesizeDefault(
     label: "Default",
     isDefault: true,
     authKind: "config-dir",
+    scope: HOST_ACCOUNT_SCOPE,
     execEnv: d.selectVar ? { [d.selectVar]: containerDir } : {},
     configDir: {
       hostDir: (d.defaultHostDir as (o: string) => string)(s.ownerHome()),
@@ -196,14 +265,22 @@ function synthesizeDefault(
 }
 
 /** DB extras for a kind, resolved into injectable form. */
-function resolveExtras(kind: string, s: AccountSeams): ResolvedEngineAccount[] {
+function resolveExtras(
+  kind: string,
+  s: AccountSeams,
+  scope: string,
+): ResolvedEngineAccount[] {
   const d = KINDS[kind];
   if (!d) return [];
   const rows = getDb()
     .select()
     .from(schema.engineAccounts)
     .all()
-    .filter((r) => r.kind === kind);
+    .filter(
+      (r) =>
+        r.kind === kind &&
+        accountInScope((r as { scope?: string | null }).scope, scope),
+    );
   const out: ResolvedEngineAccount[] = [];
   for (const row of rows) {
     if (row.authKind === "env") {
@@ -226,6 +303,7 @@ function resolveExtras(kind: string, s: AccountSeams): ResolvedEngineAccount[] {
         label: row.label,
         isDefault: false,
         authKind: "env",
+        scope,
         execEnv,
       });
     } else if (row.authKind === "config-dir" && row.configDir && d.selectVar) {
@@ -236,6 +314,7 @@ function resolveExtras(kind: string, s: AccountSeams): ResolvedEngineAccount[] {
         label: row.label,
         isDefault: false,
         authKind: "config-dir",
+        scope,
         execEnv: { [d.selectVar]: containerDir },
         configDir: { hostDir: row.configDir, containerDir },
       });
@@ -248,12 +327,16 @@ function resolveExtras(kind: string, s: AccountSeams): ResolvedEngineAccount[] {
 export function resolveEngineAccounts(
   kind: string,
   seams: Partial<AccountSeams> = {},
+  scope: string = HOST_ACCOUNT_SCOPE,
 ): ResolvedEngineAccount[] {
   const s = withDefaults(seams);
   const accounts: ResolvedEngineAccount[] = [];
-  const def = synthesizeDefault(kind, s);
-  if (def) accounts.push(def);
-  accounts.push(...resolveExtras(kind, s));
+  // The default slot is the OWNER's credential: it joins the host scope only.
+  if (scope === HOST_ACCOUNT_SCOPE) {
+    const def = synthesizeDefault(kind, s);
+    if (def) accounts.push(def);
+  }
+  accounts.push(...resolveExtras(kind, s, scope));
   return accounts;
 }
 
@@ -261,22 +344,47 @@ export function resolveEngineAccounts(
 export function listEngineAccounts(
   kind: string,
   seams: Partial<AccountSeams> = {},
+  scope: string = HOST_ACCOUNT_SCOPE,
 ): EngineAccountInfo[] {
-  return resolveEngineAccounts(kind, seams).map((a) => ({
+  return resolveEngineAccounts(kind, seams, scope).map((a) => ({
     id: a.id,
     kind: a.kind,
     label: a.label,
     authKind: a.authKind,
     isDefault: a.isDefault,
+    scope: a.scope,
   }));
 }
 
+/** Every scope holding at least one stored account for the kind, plus
+ *  `host` (which may consist of the default slot alone). */
+export function engineAccountScopes(kind: string): string[] {
+  const scopes = new Set<string>([HOST_ACCOUNT_SCOPE]);
+  for (const row of getDb().select().from(schema.engineAccounts).all()) {
+    if (row.kind !== kind) continue;
+    scopes.add((row as { scope?: string | null }).scope ?? HOST_ACCOUNT_SCOPE);
+  }
+  return [...scopes];
+}
+
+/** Account list across ALL scopes — the capabilities advertisement. The
+ *  cloud filters per caller; labels only, never credentials. */
+export function listEngineAccountsAllScopes(
+  kind: string,
+  seams: Partial<AccountSeams> = {},
+): EngineAccountInfo[] {
+  return engineAccountScopes(kind).flatMap((scope) =>
+    listEngineAccounts(kind, seams, scope),
+  );
+}
+
 /** How many accounts a kind has right now (default + extras). */
 export function engineAccountCount(
   kind: string,
   seams: Partial<AccountSeams> = {},
+  scope: string = HOST_ACCOUNT_SCOPE,
 ): number {
-  return resolveEngineAccounts(kind, seams).length;
+  return resolveEngineAccounts(kind, seams, scope).length;
 }
 
 // ---------------------------------------------------------------------------
@@ -339,9 +447,19 @@ export function selectAccount(
 /** Pick an account for a kind (default + extras), applying rotation state. */
 export function pickEngineAccount(
   kind: string,
-  opts: { exclude?: Set<string>; seams?: Partial<AccountSeams>; now?: number } = {},
+  opts: {
+    exclude?: Set<string>;
+    seams?: Partial<AccountSeams>;
+    now?: number;
+    /** ADR-131 D3: the task's scope; default = the host's own accounts. */
+    scope?: string;
+  } = {},
 ): ResolvedEngineAccount | null {
-  const accounts = resolveEngineAccounts(kind, opts.seams ?? {});
+  const accounts = resolveEngineAccounts(
+    kind,
+    opts.seams ?? {},
+    opts.scope ?? HOST_ACCOUNT_SCOPE,
+  );
   return selectAccount(accounts, { exclude: opts.exclude, now: opts.now });
 }
 
@@ -495,6 +613,7 @@ export async function provisionEngineAccounts(
   kinds: Iterable<string>,
   seams: Partial<AccountSeams> = {},
   environment?: Pick<TaskEnvironmentHandle, "exec" | "copy">,
+  scope: string = HOST_ACCOUNT_SCOPE,
 ): Promise<ProvisionEngineAccountsResult> {
   const s = withDefaults(seams);
   const seen = new Set<string>();
@@ -504,7 +623,7 @@ export async function provisionEngineAccounts(
   for (const kind of kinds) {
     if (seen.has(kind)) continue;
     seen.add(kind);
-    for (const account of resolveEngineAccounts(kind, s)) {
+    for (const account of resolveEngineAccounts(kind, s, scope)) {
       if (account.isDefault || !account.configDir) continue;
       if (!s.fileExists(account.configDir.hostDir)) {
         failed += 1;
@@ -554,8 +673,12 @@ export function addEngineAccount(
   label: string,
   creds: { apiKey?: string; token?: string },
   seams: Partial<AccountSeams> = {},
+  scope: string = HOST_ACCOUNT_SCOPE,
 ): AddAccountResult {
   const s = withDefaults(seams);
+  if (!isEngineAccountScope(scope)) {
+    return { ok: false, message: "The account scope is invalid." };
+  }
   const trimmedLabel = label.trim();
   if (!trimmedLabel) return { ok: false, message: "Give the account a label." };
   const secret = (creds.token ?? creds.apiKey ?? "").trim();
@@ -581,11 +704,34 @@ export function addEngineAccount(
         secretEnc: packSecret(JSON.stringify({ [envVar]: secret })),
         configDir: null,
         createdAt: now,
+        scope,
       })
       .run();
     return { ok: true, message: `Added Claude account "${trimmedLabel}".`, id };
   }
 
+  const envKeyVar = API_KEY_ENV_VARS[kind];
+  if (envKeyVar) {
+    getDb()
+      .insert(schema.engineAccounts)
+      .values({
+        id,
+        kind,
+        label: trimmedLabel,
+        authKind: "env",
+        secretEnc: packSecret(JSON.stringify({ [envKeyVar]: secret })),
+        configDir: null,
+        createdAt: now,
+        scope,
+      })
+      .run();
+    return {
+      ok: true,
+      message: `Added ${API_KEY_ENGINE_LABELS[kind] ?? kind} account "${trimmedLabel}".`,
+      id,
+    };
+  }
+
   if (kind === "codex") {
     const d = KINDS.codex as KindDescriptor;
     const hostDir = (d.extraHostDir as (o: string, i: string) => string)(
@@ -621,6 +767,7 @@ export function addEngineAccount(
         secretEnc: null,
         configDir: hostDir,
         createdAt: now,
+        scope,
       })
       .run();
     return { ok: true, message: `Added Codex account "${trimmedLabel}".`, id };
@@ -642,7 +789,11 @@ export function addCodexAccountFromAuthJson(
   label: string,
   authJson: string,
   seams: Partial<AccountSeams> = {},
+  scope: string = HOST_ACCOUNT_SCOPE,
 ): AddAccountResult {
+  if (!isEngineAccountScope(scope)) {
+    return { ok: false, message: "The account scope is invalid." };
+  }
   const s = withDefaults(seams);
   const trimmedLabel = label.trim();
   if (!trimmedLabel) return { ok: false, message: "Give the account a label." };
@@ -690,6 +841,7 @@ export function addCodexAccountFromAuthJson(
       secretEnc: null,
       configDir: hostDir,
       createdAt: Date.now(),
+      scope,
     })
     .run();
   return { ok: true, message: `Added Codex account "${trimmedLabel}".`, id };
@@ -698,7 +850,19 @@ export function addCodexAccountFromAuthJson(
 /** Remove an EXTRA account (idempotent). The synthesized default can't be
  *  removed here (use the engine disconnect flow for the legacy slot). The
  *  isolated host config dir of a config-dir account is deleted too. */
-export function removeEngineAccount(id: string): { ok: boolean; message: string } {
+/** Whether a caller acting in `scope` may remove `row`. `undefined` is the
+ *  host's own local UI, which may remove anything. */
+export function accountRemovableInScope(
+  row: { scope?: string | null },
+  scope: string | undefined,
+): boolean {
+  return scope === undefined || accountInScope(row.scope, scope);
+}
+
+export function removeEngineAccount(
+  id: string,
+  scope?: string,
+): { ok: boolean; message: string } {
   if (id.startsWith("default:")) {
     return {
       ok: false,
@@ -711,6 +875,11 @@ export function removeEngineAccount(id: string): { ok: boolean; message: string
     .where(eq(schema.engineAccounts.id, id))
     .get();
   if (!row) return { ok: true, message: "Account already removed." };
+  // ADR-131 D3: a workspace removes only its own accounts — never the host's
+  // and never another workspace's, whatever id it names.
+  if (!accountRemovableInScope(row, scope)) {
+    return { ok: false, message: "That account belongs to a different scope." };
+  }
   getDb().delete(schema.engineAccounts).where(eq(schema.engineAccounts.id, id)).run();
   if (row.authKind === "config-dir" && row.configDir) {
     try {

package/lib/engine-connect.ts

@@ -10,7 +10,9 @@
  */
 
 import {
+  HOST_ACCOUNT_SCOPE,
   isEngineAccountLabel,
+  isEngineAccountScope,
   isHostOpId,
   MAX_ENGINE_CONNECT_LINE_CHARS,
   MAX_ENGINE_CONNECT_SECRET_CHARS,
@@ -57,8 +59,10 @@ export class EngineConnectManager {
     secret: string | undefined,
     label: string | undefined,
     emit: EmitEngineConnectEvent,
+    scope: string | undefined = undefined,
   ): boolean {
     if (!isHostOpId(opId) || this.operations.has(opId)) return false;
+    if (scope !== undefined && !isEngineAccountScope(scope)) return false;
     if (
       secret !== undefined &&
       (secret.length < 1 || secret.length > MAX_ENGINE_CONNECT_SECRET_CHARS)
@@ -93,7 +97,7 @@ export class EngineConnectManager {
       this.finish(operation, false, "Engine connect timed out.");
     }, CONNECT_TIMEOUT_MS);
     operation.timer.unref?.();
-    void this.run(operation, secret, label).catch((error: unknown) => {
+    void this.run(operation, secret, label, scope).catch((error: unknown) => {
       this.finish(
         operation,
         false,
@@ -118,6 +122,7 @@ export class EngineConnectManager {
     operation: ConnectOperation,
     secret: string | undefined,
     label: string | undefined,
+    scope: string | undefined,
   ): Promise<void> {
     const { engine } = operation;
     const emitLine = (line: string): void => {
@@ -153,11 +158,28 @@ export class EngineConnectManager {
 
     // ADR-116 labeled extra account — the sink validates kind support.
     if (label !== undefined && secret !== undefined) {
-      const added = addEngineAccount(engine, label, { token: secret });
+      const added = addEngineAccount(
+        engine,
+        label,
+        { token: secret },
+        {},
+        scope ?? HOST_ACCOUNT_SCOPE,
+      );
       if (added.ok) this.afterMutation(engine, false);
       this.finish(operation, added.ok, added.message);
       return;
     }
+    // ADR-131 D3: everything below writes the host's DEFAULT slot or re-detects
+    // a host-side login — the owner's credential, never a workspace's. A
+    // tenant scope must not reach it.
+    if (scope !== undefined && scope !== HOST_ACCOUNT_SCOPE) {
+      this.finish(
+        operation,
+        false,
+        "Workspace accounts need a label and a pasted secret; the host's own sign-in is not available to workspaces.",
+      );
+      return;
+    }
 
     const result = await connectEngine(
       engine as EngineKind,

package/lib/engine-login.ts

@@ -27,7 +27,9 @@ import { homedir, tmpdir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 
 import {
+  HOST_ACCOUNT_SCOPE,
   isEngineAccountLabel,
+  isEngineAccountScope,
   isHostOpId,
   MAX_ENGINE_LOGIN_QUERY_CHARS,
   MAX_ENGINE_LOGIN_TEXT_CHARS,
@@ -145,8 +147,16 @@ export interface EngineLoginSeams {
   persistClaudeToken(token: string): Promise<void>;
   persistCodexAuth(sourceFile: string): Promise<void>;
   /** ADR-116: labeled extra-account captures (never the default slots). */
-  addClaudeAccount(label: string, token: string): { ok: boolean; message: string };
-  addCodexAccount(label: string, authJson: string): { ok: boolean; message: string };
+  addClaudeAccount(
+    label: string,
+    token: string,
+    scope: string,
+  ): { ok: boolean; message: string };
+  addCodexAccount(
+    label: string,
+    authJson: string,
+    scope: string,
+  ): { ok: boolean; message: string };
   refreshEngineAccountAgents(engine: "claude"): Promise<void>;
   reinjectCodexRunningTasks(): Promise<void>;
   ownerHome(): string;
@@ -209,6 +219,8 @@ interface LoginOperation {
   /** ADR-116: when set, the captured credential lands in a labeled extra
    * account instead of the default slot. */
   accountLabel: string | null;
+  /** ADR-131 D3: the scope a labeled capture is stored under. */
+  accountScope: string;
   /** Diagnosis breadcrumb: has ANY output arrived after the one-time code
    * was written? Distinguishes "stdin never delivered" from "CLI answered
    * and we ignored it" without reading the PTY transcript. */
@@ -299,10 +311,10 @@ function defaultSeams(options: EngineLoginManagerOptions): EngineLoginSeams {
     },
     persistClaudeToken: (token) => persistClaudeTokenAtomic(token),
     persistCodexAuth: (sourceFile) => persistCodexAuthAtomic(sourceFile),
-    addClaudeAccount: (label, token) =>
-      addEngineAccount("claude", label, { token }),
-    addCodexAccount: (label, authJson) =>
-      addCodexAccountFromAuthJson(label, authJson),
+    addClaudeAccount: (label, token, scope) =>
+      addEngineAccount("claude", label, { token }, {}, scope),
+    addCodexAccount: (label, authJson, scope) =>
+      addCodexAccountFromAuthJson(label, authJson, {}, scope),
     refreshEngineAccountAgents: options.refreshEngineAccountAgents,
     reinjectCodexRunningTasks: () => reinjectCodexRunningTasks(),
     ownerHome,
@@ -370,8 +382,25 @@ export class EngineLoginManager {
     engine: EngineLoginKind,
     emit: EmitEngineLoginEvent,
     label?: string,
+    scope?: string,
   ): boolean {
     if (!isHostOpId(opId)) return false;
+    if (scope !== undefined && !isEngineAccountScope(scope)) {
+      safeEmit(
+        emit,
+        failedEvent(opId, engine, "start_failed", "The account scope is invalid."),
+      );
+      return false;
+    }
+    // A workspace's sign-in is always a labeled account: the default slot is
+    // the host owner's and must never be written on a tenant's behalf.
+    if (scope !== undefined && scope !== HOST_ACCOUNT_SCOPE && label === undefined) {
+      safeEmit(
+        emit,
+        failedEvent(opId, engine, "start_failed", "A workspace account needs a label."),
+      );
+      return false;
+    }
     if (label !== undefined && !isEngineAccountLabel(label)) {
       safeEmit(
         emit,
@@ -426,6 +455,7 @@ export class EngineLoginManager {
       pendingInput: null,
       callbackTarget: null,
       accountLabel: label ?? null,
+      accountScope: scope ?? HOST_ACCOUNT_SCOPE,
       postInputOutputSeen: false,
     };
     this.operations.set(opId, operation);
@@ -941,7 +971,11 @@ export class EngineLoginManager {
       // ADR-116: labeled capture — an extra account, not the default slot.
       // Extras are picked up at the next agent spawn / rotation, so no
       // running-agent refresh is needed (mirrors the local accounts API).
-      const added = this.seams.addClaudeAccount(operation.accountLabel, token);
+      const added = this.seams.addClaudeAccount(
+        operation.accountLabel,
+        token,
+        operation.accountScope,
+      );
       terminal = added.ok
         ? {
             kind: "engine.login.event",
@@ -1011,7 +1045,11 @@ export class EngineLoginManager {
           join(tempDir, "codex", "auth.json"),
           "utf8",
         );
-        added = this.seams.addCodexAccount(operation.accountLabel, contents);
+        added = this.seams.addCodexAccount(
+          operation.accountLabel,
+          contents,
+          operation.accountScope,
+        );
       } catch {
         added = {
           ok: false,

package/lib/orchestrator.ts

@@ -106,14 +106,14 @@ import {
 } from "./browser-testing";
 import { injectCodexIntoContainer } from "./codex-auth";
 import {
+  codexHomeIsolatable,
+  codexHomeSeedCommand,
+  codexPerAgentHome,
   cooldownEngineAccount,
   noteEngineAccountUsed,
   pickEngineAccount,
   provisionEngineAccounts,
   resolveEngineAccounts,
-  codexHomeIsolatable,
-  codexPerAgentHome,
-  codexHomeSeedCommand,
   type ResolvedEngineAccount,
 } from "./engine-accounts";
 import { clearTaskGatewayAcl, setupMcpTaskConfig } from "./mcp-gateway";
@@ -133,6 +133,7 @@ import type {
   HostEvent,
 } from "../src/protocol";
 import {
+  HOST_ACCOUNT_SCOPE,
   MAX_AGENT_ID_CHARS,
   MAX_SECRETARY_DISPATCH_ID_CHARS,
   SECRETARY_TYPED_DISPATCH_PROTOCOL_FEATURE,
@@ -155,6 +156,9 @@ const RESTRICTED_SECRETARY_SESSION_ATTACH_KEY =
 interface Channel {
   taskId: string;
   roster: Roster;
+  /** ADR-131 D3: the engine-account scope this task's agents resolve
+   *  credentials from. `host` unless the cloud scoped the task to a workspace. */
+  engineAccountScope: string;
   /** ADR-083: host-derived role assignment for execution-profile enforcement. */
   mode: "open" | "secretary";
   secretaryAgentId?: string;
@@ -527,6 +531,7 @@ export class Orchestrator {
     channel.browserTesting = spec.browserTesting === true;
     channel.sharedFiles = spec.sharedFiles ?? "ro";
     channel.mcpConnections = spec.mcpConnections ?? [];
+    if (spec.engineAccountScope) channel.engineAccountScope = spec.engineAccountScope;
     const nextMcpShape = JSON.stringify({
       connections: channel.mcpConnections,
       kinds: [...new Set(channel.roster.map((agent) => agent.kind))].sort(),
@@ -640,6 +645,10 @@ export class Orchestrator {
     const channel: Channel = {
       taskId,
       roster,
+      engineAccountScope:
+        spec.engineAccountScope ??
+        getHostTask(taskId)?.engineAccountScope ??
+        HOST_ACCOUNT_SCOPE,
       mode: spec.mode === "secretary" ? "secretary" : "open",
       secretaryAgentId: spec.secretaryAgentId,
       sessions: new Map(),
@@ -797,9 +806,9 @@ export class Orchestrator {
    * copies use this gate: a false→true toggle queues migration after the older
    * copy, so that copy cannot land last and erase the managed browser block.
    */
-  private codexHomes(hasCodex: boolean): string[] {
+  private codexHomes(hasCodex: boolean, scope: string): string[] {
     if (!hasCodex) return [];
-    const homes = resolveEngineAccounts("codex")
+    const homes = resolveEngineAccounts("codex", {}, scope)
       .map((account) => account.configDir?.containerDir)
       .filter((home): home is string => Boolean(home));
     return [...new Set([DEFAULT_CODEX_HOME, ...homes])];
@@ -825,9 +834,9 @@ export class Orchestrator {
     if (this.isActiveChannel(channel)) channel.configGeneration += 1;
   }
 
-  private provisionFingerprint(kinds: readonly string[]): string {
+  private provisionFingerprint(kinds: readonly string[], scope: string): string {
     const accounts = kinds.flatMap((kind) =>
-      resolveEngineAccounts(kind)
+      resolveEngineAccounts(kind, {}, scope)
         .filter((account) => !account.isDefault && account.configDir)
         .map((account) => ({
           kind,
@@ -864,15 +873,15 @@ export class Orchestrator {
     const requestedHasCodex =
       hasCodex || channel.roster.some((agent) => agent.kind === "codex");
     const requestedHomes = requestedBrowser
-      ? this.codexHomes(requestedHasCodex)
+      ? this.codexHomes(requestedHasCodex, channel.engineAccountScope)
       : [];
     const requestedKinds = [
       ...new Set(channel.roster.map((agent) => agent.kind)),
     ];
     const requestedProvisionFingerprint =
-      this.provisionFingerprint(requestedKinds);
+      this.provisionFingerprint(requestedKinds, channel.engineAccountScope);
     const mayProvisionConfig = requestedKinds.some((kind) =>
-      resolveEngineAccounts(kind).some(
+      resolveEngineAccounts(kind, {}, channel.engineAccountScope).some(
         (account) => !account.isDefault && Boolean(account.configDir),
       ),
     );
@@ -891,13 +900,13 @@ export class Orchestrator {
         requestedHasCodex ||
         channel.roster.some((agent) => agent.kind === "codex");
       const latestHomes = latestBrowser
-        ? this.codexHomes(latestHasCodex)
+        ? this.codexHomes(latestHasCodex, channel.engineAccountScope)
         : [];
       const latestKinds = [
         ...new Set(channel.roster.map((agent) => agent.kind)),
       ];
       const latestProvisionFingerprint =
-        this.provisionFingerprint(latestKinds);
+        this.provisionFingerprint(latestKinds, channel.engineAccountScope);
       if (
         (latestBrowser &&
           coverage?.browserAttempted !== true &&
@@ -949,10 +958,14 @@ export class Orchestrator {
                   requestedKinds,
                   {},
                   channel.agentHandle,
+                  channel.engineAccountScope,
                 )
               : await provisionEngineAccounts(
                   channel.containerName,
                   requestedKinds,
+                  {},
+                  undefined,
+                  channel.engineAccountScope,
                 );
             copiedOrUnknown =
               provisioned.copied > 0 || provisioned.mayHaveMutated;
@@ -1075,12 +1088,15 @@ export class Orchestrator {
       requestedHasCodex ||
       channel.roster.some((agent) => agent.kind === "codex");
     const latestHomes = latestBrowser
-      ? this.codexHomes(latestHasCodex)
+      ? this.codexHomes(latestHasCodex, channel.engineAccountScope)
       : [];
     const latestKinds = [
       ...new Set(channel.roster.map((agent) => agent.kind)),
     ];
-    const latestProvisionFingerprint = this.provisionFingerprint(latestKinds);
+    const latestProvisionFingerprint = this.provisionFingerprint(
+      latestKinds,
+      channel.engineAccountScope,
+    );
     if (
       (latestBrowser &&
         !coverage.browserAttempted &&
@@ -1169,7 +1185,7 @@ export class Orchestrator {
       ...new Set(channel.roster.map((agent) => agent.kind)),
     ].sort();
     const codexHomes = engineKinds.includes("codex")
-      ? this.codexHomes(true)
+      ? this.codexHomes(true, channel.engineAccountScope)
       : [];
     const fingerprint = JSON.stringify({
       connections,
@@ -1529,7 +1545,9 @@ export class Orchestrator {
     agent: RosterAgent,
     base: Record<string, string>,
   ): Record<string, string> {
-    const account = pickEngineAccount(agent.kind);
+    const account = pickEngineAccount(agent.kind, {
+      scope: channel.engineAccountScope,
+    });
     if (!account) {
       channel.accountByAgent.delete(agent.id);
       return base;
@@ -2598,7 +2616,7 @@ export class Orchestrator {
       );
       const boundAccountId = channel.accountByAgent.get(agentId);
       const boundAccount = boundAccountId
-        ? resolveEngineAccounts(agent.kind).find(
+        ? resolveEngineAccounts(agent.kind, {}, channel.engineAccountScope).find(
             (account) => account.id === boundAccountId,
           )
         : undefined;
@@ -2667,7 +2685,9 @@ export class Orchestrator {
     // A concurrent terminal event for the same session is already being
     // handled by the path that owns this spawn slot.
     if (channel.spawning.has(agentId)) return true;
-    if (resolveEngineAccounts(agent.kind).length < 2) return false;
+    if (resolveEngineAccounts(agent.kind, {}, channel.engineAccountScope).length < 2) {
+      return false;
+    }
 
     const budget = (channel.rotations.get(agentId) ?? 0) + 1;
     channel.rotations.set(agentId, budget);
@@ -2676,6 +2696,7 @@ export class Orchestrator {
     const current = channel.accountByAgent.get(agentId);
     if (current) cooldownEngineAccount(current);
     const next = pickEngineAccount(agent.kind, {
+      scope: channel.engineAccountScope,
       exclude: current ? new Set([current]) : undefined,
     });
     if (!next) return false;
@@ -2918,7 +2939,7 @@ export class Orchestrator {
       return;
     }
 
-    const accounts = resolveEngineAccounts(agent.kind);
+    const accounts = resolveEngineAccounts(agent.kind, {}, channel.engineAccountScope);
     const account =
       accounts.find((a) => a.id === channel.accountByAgent.get(agentId)) ??
       accounts[0];

package/lib/runtime-state.ts

@@ -231,12 +231,14 @@ export function recordTaskOwner(
   ownerEmail: string | null,
   ownerName: string | null,
   projectSlugs: string[],
+  engineAccountScope: string | null = null,
 ): void {
   upsertHostTask(taskId, {
     ownerUserId,
     ownerEmail,
     ownerName,
     projectSlugs: JSON.stringify(projectSlugs),
+    engineAccountScope,
   });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.9.99",
+  "version": "0.9.101",
   "description": "Uai host — runs ephemeral AI tasks in containers on a machine you control.",
   "license": "MIT",
   "author": "Uai Tech <team@runuai.com>",

package/src/index.ts

@@ -768,6 +768,8 @@ export const hostCommands: HostCommands = {
         input.ownerEmail ?? null,
         input.ownerName ?? null,
         input.projects.map((p) => p.slug),
+        // ADR-131 D3: persisted so recovery re-provisions the same scope.
+        input.task.engineAccountScope ?? null,
       );
       // ADR-048: persist the cloud-issued per-task cli secret (host-private) so the
       // `uai` CLI's per-agent tokens can be minted now + after a host restart.
@@ -1227,7 +1229,7 @@ export const hostCommands: HostCommands = {
   async engineAccountRemove(ctx, input) {
     logCommand(ctx, "engineAccountRemove", input.id);
     try {
-      const result = removeEngineAccount(input.id);
+      const result = removeEngineAccount(input.id, input.scope);
       if (!result.ok) {
         return ok({ removed: false, message: result.message });
       }

package/src/main.ts

@@ -132,6 +132,7 @@ import { newId } from "../lib/ulid";
 import {
   capabilities as agentKindCapabilities,
   onChange as onRegistryChange,
+  setAdvertisementFallback,
 } from "../lib/agents/registry";
 import { canAdvertiseTypedSecretaryDispatch } from "../lib/agents/mode";
 import {
@@ -150,7 +151,10 @@ import {
   patchHostConfig,
   type HostConfigResult,
 } from "../lib/host-config";
-import { listEngineAccounts } from "../lib/engine-accounts";
+import {
+  hasStoredEngineAccounts,
+  listEngineAccountsAllScopes,
+} from "../lib/engine-accounts";
 import { createEngineConnectManager } from "../lib/engine-connect";
 import { createEngineLoginManager } from "../lib/engine-login";
 import {
@@ -182,7 +186,9 @@ import {
   HOST_TASK_STOP_PROTOCOL_FEATURE,
   HOST_ENGINE_ACCOUNTS_PROTOCOL_FEATURE,
   HOST_ENGINE_CONNECT_PROTOCOL_FEATURE,
+  HOST_ENGINE_ACCOUNT_SCOPES_PROTOCOL_FEATURE,
   HOST_ENGINE_LOGIN_PROTOCOL_FEATURE,
+  isEngineAccountScope,
   HOST_LOGS_PROTOCOL_FEATURE,
   HOST_TASK_INVENTORY_PROTOCOL_FEATURE,
   MAX_ENGINE_ACCOUNT_LABEL_CHARS,
@@ -601,6 +607,7 @@ function buildCapabilities(): HostCapabilities {
       HOST_TASK_STOP_PROTOCOL_FEATURE,
       HOST_ENGINE_ACCOUNTS_PROTOCOL_FEATURE,
       HOST_ENGINE_CONNECT_PROTOCOL_FEATURE,
+      HOST_ENGINE_ACCOUNT_SCOPES_PROTOCOL_FEATURE,
       // The echo adapter cannot execute the in-task CLI. Advertising typed
       // dispatch in mock mode would let the composer create a Secretary that
       // has no way to wake crew.
@@ -694,15 +701,17 @@ function engineCatalogCapabilities(): EngineCatalogCapability[] {
 /** ADR-116: the labeled-accounts advertisement — bounded, labels-only. */
 function engineAccountSummaries(): EngineAccountSummary[] {
   const summaries: EngineAccountSummary[] = [];
-  for (const kind of ["claude", "codex", "opencode"] as const) {
+  for (const kind of ["claude", "codex", "grok", "cursor", "opencode"] as const) {
     try {
-      for (const account of listEngineAccounts(kind)) {
+      // ADR-131 D3: every scope — the cloud filters per caller.
+      for (const account of listEngineAccountsAllScopes(kind)) {
         summaries.push({
           id: account.id,
           kind,
           label: account.label.slice(0, MAX_ENGINE_ACCOUNT_LABEL_CHARS),
           authKind: account.authKind,
           isDefault: account.isDefault,
+          scope: account.scope,
         });
       }
     } catch (error) {
@@ -739,6 +748,9 @@ function flushStoppedTaskStatuses(socket: WebSocket | null = ws): void {
   });
 }
 
+// ADR-131 D3: a stored account (any scope) makes a kind advertisable even
+// when the host's own credential is absent — see hasStoredEngineAccounts.
+setAdvertisementFallback((kind) => hasStoredEngineAccounts(kind));
 onRegistryChange(() => sendCapabilities());
 onContainerRuntimeChange((next, previous) => {
   if (stopping) return;
@@ -1227,6 +1239,7 @@ async function connect(): Promise<void> {
           frame.engine,
           emitEngineLoginEvent,
           frame.label,
+          frame.scope,
         );
         break;
       case "engine.login.input":
@@ -1247,6 +1260,7 @@ async function connect(): Promise<void> {
           frame.secret,
           frame.label,
           (event) => sendRemoteOperationFrame(event),
+          frame.scope,
         );
         break;
       case "engine.connect.stop":
@@ -2434,7 +2448,7 @@ async function dispatchCommand(
 function expectEngineAccountRemoveInput(
   args: unknown[],
   index: number,
-): { id: string } {
+): { id: string; scope?: string } {
   const value = args[index];
   if (
     !value ||
@@ -2445,7 +2459,14 @@ function expectEngineAccountRemoveInput(
   ) {
     throw new Error(`invalid command args: expected account id at ${index}`);
   }
-  return { id: (value as { id: string }).id };
+  const scope = (value as { scope?: unknown }).scope;
+  if (scope !== undefined && !isEngineAccountScope(scope)) {
+    throw new Error(`invalid command args: bad account scope at ${index}`);
+  }
+  return {
+    id: (value as { id: string }).id,
+    ...(scope !== undefined ? { scope } : {}),
+  };
 }
 
 function expectNumberArg(args: unknown[], index: number): number {

package/src/protocol.ts

@@ -102,6 +102,25 @@ export const MAX_ENGINE_ACCOUNTS_ADVERTISED = 48;
 /** ADR-117: one-shot engine credentials over the bridge + the full engine
  * catalog in capabilities, so every engine renders on the cloud pane. */
 export const HOST_ENGINE_CONNECT_PROTOCOL_FEATURE = "host-engine-connect-v1";
+/** ADR-131 Decision 3: engine accounts carry a scope — `host` (the owner's)
+ * or `org:<orgId>` (a workspace's account on a shared host). A host that
+ * advertises this accepts `scope` on engine.login.start / engine.connect.start
+ * / engineAccountRemove, `engineAccountScope` on channelEnsure and task-up,
+ * and stamps `scope` on every EngineAccountSummary it advertises. The cloud
+ * sends none of those to a host without the feature (the v1 exact-shape
+ * guards would reject the frames). */
+export const HOST_ENGINE_ACCOUNT_SCOPES_PROTOCOL_FEATURE =
+  "host-engine-account-scopes-v1";
+/** The owner-level account scope; every pre-scope account lives here. */
+export const HOST_ACCOUNT_SCOPE = "host";
+const ORG_ACCOUNT_SCOPE_RE = /^org:[A-Za-z0-9_-]{1,128}$/;
+/** `host` or `org:<orgId>` — bounded, single-token, safe in every surface. */
+export function isEngineAccountScope(value: unknown): value is string {
+  return (
+    value === HOST_ACCOUNT_SCOPE ||
+    (typeof value === "string" && ORG_ACCOUNT_SCOPE_RE.test(value))
+  );
+}
 export const MAX_ENGINE_CONNECT_SECRET_CHARS = 8_192;
 export const MAX_ENGINE_CONNECT_LINE_CHARS = 512;
 export const MAX_ENGINE_CATALOG_ENTRIES = 8;
@@ -307,6 +326,10 @@ export interface EngineLoginStartFrame {
    * slot. Only sent to hosts advertising `host-engine-accounts-v1`; the v1
    * exact-shape guard on older hosts rejects frames carrying it. */
   label?: string;
+  /** ADR-131 D3: capture into this account scope (`org:<orgId>` on a shared
+   * host). Only sent to hosts advertising `host-engine-account-scopes-v1`;
+   * absent = the host scope. An org scope requires a label. */
+  scope?: string;
 }
 
 /** The only generic one-time response channel. Long-lived tokens must never
@@ -375,10 +398,14 @@ export interface EngineLoginCapability {
  * Operator-chosen label + shape metadata only — never credentials. */
 export interface EngineAccountSummary {
   id: string;
-  kind: "claude" | "codex" | "opencode";
+  /** grok/cursor since host 0.9.101 (API-key accounts, ADR-131 D3). */
+  kind: "claude" | "codex" | "grok" | "cursor" | "opencode";
   label: string;
   authKind: "env" | "config-dir";
   isDefault: boolean;
+  /** ADR-131 D3: `host` or `org:<orgId>`. Absent from hosts that predate
+   * scopes — read as `host`. */
+  scope?: string;
 }
 
 /** ADR-117 engine kinds — every engine the host's descriptor table knows. */
@@ -416,6 +443,8 @@ export interface EngineConnectStartFrame {
   engine: EngineConnectKind;
   secret?: string;
   label?: string;
+  /** ADR-131 D3: see EngineLoginStartFrame.scope. */
+  scope?: string;
 }
 
 export interface EngineConnectStopFrame {
@@ -454,13 +483,14 @@ export function isEngineConnectStartFrame(
   const frame = exactWireObject(
     value,
     ["kind", "opId", "engine"],
-    ["secret", "label"],
+    ["secret", "label", "scope"],
   );
   if (
     !frame ||
     frame.kind !== "engine.connect.start" ||
     !isHostOpId(frame.opId) ||
-    !isEngineConnectKind(frame.engine)
+    !isEngineConnectKind(frame.engine) ||
+    (frame.scope !== undefined && !isEngineAccountScope(frame.scope))
   ) {
     return false;
   }
@@ -705,13 +735,18 @@ export function isHostLogsEndFrame(value: unknown): value is HostLogsEndFrame {
 export function isEngineLoginStartFrame(
   value: unknown,
 ): value is EngineLoginStartFrame {
-  const frame = exactWireObject(value, ["kind", "opId", "engine"], ["label"]);
+  const frame = exactWireObject(
+    value,
+    ["kind", "opId", "engine"],
+    ["label", "scope"],
+  );
   return Boolean(
     frame &&
       frame.kind === "engine.login.start" &&
       isHostOpId(frame.opId) &&
       isEngineLoginKind(frame.engine) &&
-      (frame.label === undefined || isEngineAccountLabel(frame.label)),
+      (frame.label === undefined || isEngineAccountLabel(frame.label)) &&
+      (frame.scope === undefined || isEngineAccountScope(frame.scope)),
   );
 }
 
@@ -1087,6 +1122,9 @@ export interface TaskCommandTask {
   previewEnv?: Record<string, string>;
   /** ADR-062: owning org — locates the org shared-files root on the host. */
   ownerOrgId?: string;
+  /** ADR-131 D3: the engine-account scope the task's agents resolve
+   *  credentials from (`org:<orgId>` on a shared host). Absent = `host`. */
+  engineAccountScope?: string;
   /** ADR-062: shared-files mount mode ("off" | "ro" | "rw"; default "ro"). */
   sharedFiles?: string;
 }
@@ -1188,6 +1226,10 @@ export interface ChannelEnsureInput {
   /** ADR-053: any joined project opted into browser testing — the host wires
    *  the Playwright MCP browser at session start. */
   browserTesting?: boolean;
+  /** ADR-131 D3: see TaskCommandTask.engineAccountScope — the channel's
+   *  agents pick accounts from this scope. Absent = the task's persisted
+   *  scope, else `host`. */
+  engineAccountScope?: string;
   /** ADR-057: the owner's usable MCP connections (policy "on", connected,
    *  remote). The host writes gateway-URL MCP configs at session start. */
   mcpConnections?: Array<{ id: string; slug: string }>;
@@ -1358,7 +1400,7 @@ export interface HostCommands {
    * exactly like the local API; re-advertises capabilities on success. */
   engineAccountRemove(
     ctx: CommandContext,
-    input: { id: string },
+    input: { id: string; scope?: string },
   ): Promise<HostCommandResult<{ removed: boolean; message?: string }>>;
   cloneRepo(
     ctx: CommandContext,