@elliotsystems/eai 0.1.7 → 0.1.9

package/bin/eai

@@ -31,6 +31,9 @@ const { runStatus } = require("../lib/status.js")
 const { runLogout } = require("../lib/logout.js")
 const { runConnect } = require("../lib/connect.js")
 const { runUpdate, maybeNotify } = require("../lib/update.js")
+const { runLogin } = require("../lib/login.js")
+const { runTeamsList, runTeamsUse, runTeamsCurrent, runTeamsClear } = require("../lib/teams.js")
+const { startupSummary } = require("../lib/context.js")
 const gdrive = require("../lib/gdrive.js")
 
 /**
@@ -119,6 +122,37 @@ if (process.argv[2] === "setup") {
   return
 }
 
+// `eai login` and `eai teams` are intercepted here for the same reason as
+// `setup`/`status`/`logout`: they configure this machine's Elliot session
+// and must work when nothing is configured yet (or before the runtime can
+// even be located). Neither is an OpenCode command, so nothing is shadowed.
+//
+// `login` reuses the paste-token provisioning path (`lib/login.js`), and
+// `teams` the same session service (`lib/auth.js`) + the exact setup
+// rematerialisation path (`lib/setup.js::runSetup`) — one auth implementation
+// for every entry point.
+if (process.argv[2] === "login") {
+  const argv = process.argv.slice(3)
+  const backendIdx = argv.indexOf("--backend-url")
+  const backendUrl = backendIdx >= 0 && argv[backendIdx + 1] ? argv[backendIdx + 1] : undefined
+  finishWith(runLogin({ backendUrl }), "login")
+  return
+}
+
+if (process.argv[2] === "teams") {
+  const verb = process.argv[3]
+  const run =
+    verb === "use"
+      ? () => runTeamsUse({ team: process.argv[4] })
+      : verb === "current"
+        ? runTeamsCurrent
+        : verb === "clear"
+          ? runTeamsClear
+          : runTeamsList
+  finishWith(run(), "teams")
+  return
+}
+
 // `--version` answers for BOTH layers, because a bug report that says only
 // "1.18.30" names the runtime and not the product — and the two move
 // independently: one is this package, the other is its `opencode-ai`
@@ -230,6 +264,20 @@ if (process.env.ELLIOT_LAUNCHER_DEBUG) {
 // the child inherits process.env, so setting it here is enough.
 injectToken(process.env)
 
+// A concise startup context summary (TTY only, read-only, network-free — see
+// lib/context.js). The fail-closed gate for an invalid context lives at the
+// CREDENTIAL level (empty ELLIOT_TOKEN => LiteLLM rejects, no master-key
+// fallback), so this never blocks or fails startup; it just tells the user
+// what context the session resolves to.
+if (process.stdout.isTTY) {
+  try {
+    for (const line of startupSummary()) process.stdout.write(`${line}\n`)
+    process.stdout.write("\n")
+  } catch {
+    // A context summary may never be the reason a session fails to start.
+  }
+}
+
 // Elliot's identity travels WITH this package, not with the directory the user
 // happens to be standing in. Before this, branding came from a `tui.json` in the
 // Elliot repository root, so an installed `eai` outside that repo rendered as

package/lib/auth.js

@@ -0,0 +1,173 @@
+"use strict"
+
+/**
+ * Shared authentication/session service for the EAI CLI.
+ *
+ * `eai login`, `eai teams`, `eai status` and the startup path all resolve the
+ * same facts from the same file and the same backend endpoints, so this
+ * module is where those facts live once:
+ *
+ *   ~/.elliot/config.json   the secure session store (0600, written by
+ *                           `eai login`/`eai setup`, single source of truth)
+ *   POST /auth/cli-token    exchange a portal token for a CLI access/refresh
+ *                           pair (backend/app/auth/router.py:238)
+ *   POST /auth/refresh      refresh a session (backend/app/auth/router.py:175)
+ *   GET  /usage/me          verify the session and read the user (usage.py:86)
+ *
+ * Security rules from docs/architecture/EAI_ONBOARDING_BILLING_AUDIT.md §5/§7:
+ *   - the backend is the only authority for identity and membership;
+ *   - a missing/expired/revoked session fails closed with an actionable
+ *     message — never a silent fallback to a privileged credential;
+ *   - credentials are never printed or written to project files.
+ */
+
+const fs = require("fs")
+const os = require("os")
+const path = require("path")
+
+const { elliotConfigPath, writeElliotConfig } = require("./setup.js")
+
+// The default backend a pasted login token targets. The token itself carries
+// no backend URL (it is minted by whichever portal produced it), so an
+// existing config's `backend_url` wins, `--backend-url` overrides, and this
+// production default is the fallback — see runLogin.
+const DEFAULT_BACKEND_URL = "https://backend.elliotsystemsonline.com"
+
+/** Read ~/.elliot/config.json, or null when absent/unreadable. */
+function readConfig() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(elliotConfigPath(), "utf8"))
+    return parsed && typeof parsed === "object" ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+/** The backend URL to use, from config or the default. */
+function backendUrl(config) {
+  return String((config && config.backend_url) || "").replace(/\/+$/, "") || DEFAULT_BACKEND_URL
+}
+
+/**
+ * Resolve a fresh access token, refreshing from `~/.elliot/config.json` when
+ * the stored one is expired or the backend rejects it. Returns the token, or
+ * null when no session is usable (and explains why).
+ *
+ * `POST /auth/refresh` takes the refresh token in the body (auth/router.py:
+ * 175-235); it is the credential there, and is refused for audience-bound
+ * tokens. Non-rotating: the same refresh token keeps working until revoked.
+ *
+ * @param {{log?: (s: string) => void}} [opts]
+ * @returns {Promise<{token: string, config: object} | null>}
+ */
+async function ensureFreshAccessToken(opts = {}) {
+  const log = opts.log || ((s) => process.stdout.write(s + "\n"))
+  const config = readConfig()
+  if (!config) {
+    log("Not logged in. Run `eai login` first.")
+    return null
+  }
+  if (!config.jwt_token) {
+    log("Your login is incomplete (no session token). Run `eai login` again.")
+    return null
+  }
+
+  // Refresh proactively when we know the access token has expired. Parsed
+  // leniently: a missing/odd `expires_at` simply means "don't refresh early".
+  const expiresAt = Date.parse(String(config.access_token_expires_at || ""))
+  const needsRefresh = Number.isFinite(expiresAt) && expiresAt <= Date.now()
+
+  if (needsRefresh && config.refresh_token) {
+    const fresh = await refresh(config)
+    if (fresh) return { token: fresh.token, config: fresh.config }
+    log(
+      "Your session has expired and could not be refreshed. Run `eai login` again.",
+    )
+    return null
+  }
+
+  return { token: config.jwt_token, config }
+}
+
+/**
+ * Call `POST /auth/refresh` and persist the new access token. Returns
+ * `{token, config}` on success, null on any failure (never throws).
+ */
+async function refresh(config) {
+  try {
+    const base = backendUrl(config)
+    const res = await fetch(`${base}/auth/refresh`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ refresh_token: config.refresh_token }),
+    })
+    if (!res.ok) return null
+    const body = await res.json()
+    if (!body || typeof body.access_token !== "string") return null
+    const next = {
+      ...config,
+      jwt_token: body.access_token,
+      ...(typeof body.access_token_expires_at === "string"
+        ? { access_token_expires_at: body.access_token_expires_at }
+        : {}),
+    }
+    writeElliotConfig(next)
+    return { token: next.jwt_token, config: next }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Authenticated GET. Uses `ensureFreshAccessToken` for a fresh bearer, and
+ * retries once after a refresh when the backend answers 401 (a token that
+ * was still unexpired locally but revoked server-side).
+ *
+ * @returns {Promise<{ok: boolean, status: number, body: any} | null>}
+ *   null when no usable session exists.
+ */
+async function authorizedGet(url, opts = {}) {
+  const session = await ensureFreshAccessToken(opts)
+  if (!session) return null
+  const { token, config } = session
+  const base = backendUrl(config)
+
+  let res
+  try {
+    res = await fetch(`${base}${url}`, {
+      headers: { Authorization: `Bearer ${token}` },
+      signal: opts.signal,
+    })
+  } catch (error) {
+    opts.log && opts.log(`Could not reach the backend at ${base}: ${error.message}`)
+    return { ok: false, status: 0, body: null }
+  }
+
+  if (res.status === 401 && config.refresh_token) {
+    const fresh = await refresh(config)
+    if (fresh) {
+      res = await fetch(`${base}${url}`, {
+        headers: { Authorization: `Bearer ${fresh.token}` },
+        signal: opts.signal,
+      })
+    }
+  }
+
+  let body = null
+  try {
+    body = await res.json()
+  } catch {
+    // Non-JSON body; callers fall back to the status.
+  }
+  return { ok: res.ok, status: res.status, body }
+}
+
+module.exports = {
+  DEFAULT_BACKEND_URL,
+  readConfig,
+  backendUrl,
+  ensureFreshAccessToken,
+  refresh,
+  authorizedGet,
+  elliotConfigPath,
+}

package/lib/context.js

@@ -0,0 +1,52 @@
+"use strict"
+
+/**
+ * The EAI CLI's effective billing context, resolved from the local session.
+ *
+ * The BACKEND remains the authority for identity, membership and the
+ * budgeted credential — this module only renders what a session already
+ * resolved (see `docs/architecture/EAI_ONBOARDING_BILLING_AUDIT.md` §6/§7).
+ * It is read-only and network-free, so it can run on the startup path and in
+ * `eai status` without adding latency or a hard dependency on the backend.
+ *
+ * The fail-closed gate for an invalid/unresolved context is at the CREDENTIAL
+ * level, not here: if `~/.elliot/config.json` carries no budgeted LiteLLM key
+ * (`litellm_master_key`), `lib/token-env.js` injects no `ELLIOT_TOKEN`, and
+ * the runtime's model calls are rejected by LiteLLM — no unbudgeted spend, no
+ * shared-master-key fallback.
+ */
+
+const { readConfig } = require("./auth.js")
+
+/** `{type: "team"|"individual", label, teamId}` from the local session. */
+function billingContext(config) {
+  if (!config) return { type: "none", label: "Not signed in", teamId: null }
+  if (config.team_id) {
+    return {
+      type: "team",
+      label: `Team — ${config.team_name || config.team_id}`,
+      teamId: String(config.team_id),
+    }
+  }
+  return { type: "individual", label: "Individual", teamId: null }
+}
+
+/**
+ * The lines printed when starting `eai` (TTY only) and in `eai status`.
+ * Never prints credentials; identifiers are shown only where they are the
+ * user-facing value (e.g. the team id when no name is known).
+ */
+function startupSummary(config = readConfig()) {
+  const billing = billingContext(config)
+  const signedIn = config && (config.email || config.user_id) ? config.email || config.user_id : "(none)"
+  const gateway = config && config.litellm_base_url ? "LiteLLM" : "(unconfigured)"
+  return [
+    "Elliot AI",
+    `Signed in: ${signedIn}`,
+    `Billing:   ${billing.label}`,
+    `Gateway:   ${gateway}`,
+    "Project:   (none)",
+  ]
+}
+
+module.exports = { billingContext, startupSummary }

package/lib/login.js

@@ -0,0 +1,114 @@
+"use strict"
+
+/**
+ * `eai login` — establish an authenticated CLI session with a pasted token.
+ *
+ * Approved flow (docs/architecture/EAI_ONBOARDING_BILLING_AUDIT.md §5/§15):
+ * reuse the existing paste-token mechanism. The token is obtained from the
+ * portal (or the existing `eai setup` handoff), prompted for SECURELY (never
+ * via argv, so it cannot leak into shell history or `ps`), exchanged for a
+ * CLI access/refresh pair at `POST /auth/cli-token`, then provisioned through
+ * the exact same path `eai setup` uses (`lib/setup.js::runSetup`), so there
+ * is ONE authentication implementation, not two.
+ *
+ * Fail-closed: an unreadable/invalid token, an expired/revoked session or a
+ * backend that cannot resolve a budgeted credential all abort with an
+ * actionable message. No credential is ever printed.
+ */
+
+const readline = require("readline")
+
+const auth = require("./auth.js")
+const { decodeJwtPayload, runSetup } = require("./setup.js")
+
+/**
+ * Prompt for a token without echoing it to the terminal (no shell history, no
+ * process-argument exposure). On a non-TTY stdin (piped/CI), reads a plain
+ * line — callers can also pass `opts.token` to skip the prompt entirely.
+ */
+function promptHidden(question) {
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY) {
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+      rl.question(`${question} `, (answer) => {
+        rl.close()
+        resolve(String(answer || "").trim())
+      })
+      return
+    }
+    process.stdout.write(question + " ")
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: true })
+    rl._writeToOutput = (str) => {
+      // Mask the echoed token as asterisks; keep newlines/control output.
+      if (/[\r\n]/.test(str)) rl.output.write(str)
+      else rl.output.write("*".repeat(str.length))
+    }
+    rl.question("", (answer) => {
+      process.stdout.write("\n")
+      rl.close()
+      resolve(String(answer || "").trim())
+    })
+  })
+}
+
+/**
+ * @param {{token?: string, backendUrl?: string, log?: (s: string) => void}} opts
+ * @returns {Promise<number>} exit code
+ */
+async function runLogin(opts = {}) {
+  const log = opts.log || ((s) => process.stdout.write(s + "\n"))
+  const existing = auth.readConfig()
+  const backendUrl = String(
+    opts.backendUrl || auth.backendUrl(existing) || auth.DEFAULT_BACKEND_URL,
+  ).replace(/\/+$/, "")
+
+  log("Elliot AI login")
+  log("─────────────────────────────")
+  log(
+    "Get a login token from the Elliot portal (or from `eai setup`'s own " +
+      "handoff), then paste it below. It is not echoed and never appears in " +
+      "your shell history.",
+  )
+  if (!existing) {
+    log(`Backend: ${backendUrl} (use --backend-url to target another environment)`)
+  }
+  log("")
+
+  const token = opts.token || (await promptHidden("Paste your login token:"))
+  if (!token) {
+    log("Login cancelled — no token entered.")
+    return 1
+  }
+
+  // Validate before any network call: the token must look like an Elliot
+  // access token carrying a tenant claim.
+  const claims = decodeJwtPayload(token) || {}
+  if (!claims.tenant_id) {
+    log(
+      "That does not look like a valid Elliot login token (no tenant). " +
+        "Copy the full token from the portal and try again.",
+    )
+    return 1
+  }
+
+  log("")
+  try {
+    // The exact provisioning path `eai setup` uses: cli-token exchange,
+    // /onboarding/config fetch, secure config writes, opencode.json
+    // materialisation, agent files. One implementation, both entry points.
+    const result = await runSetup({ token, backendUrl, log })
+    log("")
+    log("Logged in.")
+    log("Next: run `eai teams` to view your teams, `eai teams use \"<name>\"`")
+    log("      to pick a billing team, or `eai` to start with individual billing.")
+    return result ? 0 : 1
+  } catch (error) {
+    // Includes the fail-closed 503 from /onboarding/config when no budgeted
+    // credential resolves — the message from the backend is actionable and
+    // confirms no model request was configured.
+    log(String(error && error.message ? error.message : error))
+    return 1
+  }
+}
+
+module.exports = { runLogin, promptHidden }

package/lib/setup.js

@@ -36,6 +36,14 @@ const path = require("path")
 const PROVIDER_ID = "elliot"
 const GENERAL_MODEL_ID = "elliot-general"
 const CODER_MODEL_ID = "elliot-coder"
+// The guardrail name a team's own request-level `metadata.guardrails`
+// override names — must match the real `guardrail_name` LiteLLM's
+// `deploy/litellm/config.yaml` configures (`jev-policy`), and the exact
+// value `ProviderManager._guardrail_names_for_team` already injects for Web
+// Chat's own RAG/orchestration path. Restated here (mirrors `teamconfig.py`'s
+// own `JEV_GUARDRAIL_NAME`) rather than imported, since this file has no
+// dependency on that Python module — a test pins both equal.
+const JEV_GUARDRAIL_NAME = "jev-policy"
 
 /** Matches OpenCode's own resolution (xdg-basedir, whose fallback is ~/.config everywhere). */
 function opencodeConfigDir(env = process.env) {
@@ -107,8 +115,22 @@ function decodeJwtPayload(token) {
  * from OFFERING a model that will be rejected. Falsy (undefined/null/[]) —
  * every team until an admin restricts it — offers both, unchanged from
  * before this parameter existed.
+ *
+ * `jevPolicyEnabled` closes the cross-client enforcement gap the staging
+ * integration audit found: the backend's `ProviderManager.
+ * _guardrail_names_for_team` already injects the request-level `metadata.
+ * guardrails` override for Web Chat's own native RAG/orchestration
+ * completions when a team's `jev_policy_enabled` is set, but this CLI (like
+ * OpenCode) calls LiteLLM directly via `@ai-sdk/openai-compatible`, outside
+ * that Python code path — so the override never reached it. Straight from
+ * the same onboarding response's `jev_policy_enabled` field
+ * (`app/routers/onboarding.py`). `false`/undefined (every team until
+ * explicitly opted in) produces a config identical to one built before this
+ * parameter existed. Mirrors the identical fix in `app/services/opencode/
+ * teamconfig.py::build_opencode_config` for OpenCode's own web runtimes —
+ * same flag, same mechanism, second client.
  */
-function elliotProvider(litellmBaseUrl, identity = undefined, allowedModels = undefined) {
+function elliotProvider(litellmBaseUrl, identity = undefined, allowedModels = undefined, jevPolicyEnabled = false) {
   const base = String(litellmBaseUrl).replace(/\/+$/, "")
   const options = { baseURL: `${base}/v1`, apiKey: "{env:ELLIOT_TOKEN}" }
   const headers = litellmIdentityHeaders(identity)
@@ -119,7 +141,7 @@ function elliotProvider(litellmBaseUrl, identity = undefined, allowedModels = un
     // — EAI branding only, never the gateway's own vendor name.
     name: "EAI Gateway",
     options,
-    models: offeredModels(allowedModels),
+    models: offeredModels(allowedModels, jevPolicyEnabled),
   }
 }
 
@@ -131,18 +153,33 @@ function elliotProvider(litellmBaseUrl, identity = undefined, allowedModels = un
  * degrades to offering both for that listing only, exactly like the
  * backend's own fallback — LiteLLM still rejects any actual request the
  * team isn't allowed to make either way.
+ *
+ * `jevPolicyEnabled` adds `options.metadata.guardrails` to EACH offered
+ * model — see `elliotProvider`'s own docstring for why. A model-level
+ * `options` object is the one static, declarative opencode.json field
+ * confirmed (offline, against the real `@ai-sdk/openai-compatible`
+ * package) to reach the request body this CLI's runtime actually sends.
  */
-function offeredModels(allowedModels) {
+function offeredModels(allowedModels, jevPolicyEnabled = false) {
   const all = { [GENERAL_MODEL_ID]: { name: "EAI General" }, [CODER_MODEL_ID]: { name: "EAI Coder" } }
-  if (!allowedModels || allowedModels.length === 0) return all
-
-  const allowed = new Set(allowedModels)
-  const offered = Object.keys(all).filter((id) => allowed.has(id))
-  if (offered.length === 0) return all
-
-  const filtered = {}
-  for (const id of offered) filtered[id] = all[id]
-  return filtered
+  let result = all
+  if (allowedModels && allowedModels.length > 0) {
+    const allowed = new Set(allowedModels)
+    const offered = Object.keys(all).filter((id) => allowed.has(id))
+    if (offered.length > 0) {
+      const filtered = {}
+      for (const id of offered) filtered[id] = all[id]
+      result = filtered
+    }
+  }
+  if (jevPolicyEnabled) {
+    const withGuardrails = {}
+    for (const [id, entry] of Object.entries(result)) {
+      withGuardrails[id] = { ...entry, options: { metadata: { guardrails: [JEV_GUARDRAIL_NAME] } } }
+    }
+    result = withGuardrails
+  }
+  return result
 }
 
 /** The default `model` field, given whatever `models` ended up offered —
@@ -298,6 +335,15 @@ function elliotCommands() {
         "intentionally omitted\".\n\n" +
         "Do not list individual skills here; SKILLS.md is the skill index and " +
         "`/eai-skills` generates it.\n\n" +
+        "Append the standard operating guidance: call the " +
+        "`elliot_eai_agents_standard` tool (the `elliot` MCP server exposes it), " +
+        "and append its `markdown` value verbatim to the END of AGENTS.md under " +
+        "a `## Standard guidance` heading. That tool returns the same canonical " +
+        "sections every runtime-generated AGENTS.md carries, from the backend's " +
+        "single source of truth — do not paraphrase or rewrite them. If the tool " +
+        "is not available yet, try once more after `sleep 3` before skipping; a " +
+        "project initialised here should carry the same standard sections a " +
+        "team's runtime does.\n\n" +
         "When done, report the file written and the key facts you detected.",
     },
     "eai-skills": {
@@ -339,6 +385,7 @@ function writeOpencodeConfig(
   servers = undefined,
   identity = undefined,
   allowedModels = undefined,
+  jevPolicyEnabled = false,
 ) {
   const dir = opencodeConfigDir(env)
   const file = path.join(dir, "opencode.json")
@@ -362,7 +409,7 @@ function writeOpencodeConfig(
   // replacement. Every other key is the user's own and survives untouched.
   const { [PROVIDER_ID]: _ours, ...theirs } = existing.mcp || {}
   const mcp = { ...theirs, ...(servers || elliotMcpServers()) }
-  const provider = elliotProvider(litellmBaseUrl, identity, allowedModels)
+  const provider = elliotProvider(litellmBaseUrl, identity, allowedModels, jevPolicyEnabled)
   // Org commands are spread LAST, same rule as `mcp` above: this repairs a
   // stale `/usage` from an older package rather than leaving it, while a
   // user's own unrelated custom commands are untouched.
@@ -390,6 +437,16 @@ function writeOpencodeConfig(
     // Follows the restriction, not always General — a team restricted to
     // Coder-only must not default to a model its own menu just excluded.
     model: existing.model || `${PROVIDER_ID}/${defaultModelId(provider.models)}`,
+    // OpenCode's own self-updater can never succeed here: it detects its
+    // install method by grepping `npm list -g --depth=0` for `opencode-ai`,
+    // but opencode-ai is a pinned dependency of this package, not its own
+    // top-level global install, so that check never matches and `/update`
+    // (and the unprompted "Update available" notice) always dead-ends on
+    // "Installation method not found". `eai update` is the one supported
+    // update path (see lib/update.js) and is unaffected by this setting.
+    // Only defaulted, same as `model` above, so a user who already set their
+    // own `autoupdate` keeps it.
+    autoupdate: existing.autoupdate ?? false,
     mcp,
     command,
   }
@@ -539,23 +596,80 @@ function writeAgentFile(agent, env = process.env) {
 }
 
 /**
- * Every agent the backend's `eai_agents` response named, in one pass.
+ * Path to the manifest recording which files in the agents directory THIS
+ * launcher itself wrote on its last run.
+ *
+ * It is the one safe way to tell "ours, now stale" apart from "a user's own
+ * file that happens to live here" without guessing from the filename -- which
+ * is exactly the guess `elliotCommands()`'s "OURS TO REPLACE, THEIRS TO KEEP"
+ * rule exists to avoid making. A file never named in any manifest this
+ * launcher wrote is never touched, no matter what it's called.
+ */
+function agentManifestPath(dir) {
+  return path.join(dir, ".eai-manifest.json")
+}
+
+/** The manifest's own filenames, or `[]` for "none yet" -- missing, corrupt,
+ *  or never written are the same case: nothing to clean up against. */
+function readAgentManifest(manifestFile) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(manifestFile, "utf-8"))
+    return Array.isArray(parsed) ? parsed : []
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Every agent the backend's `eai_agents` response named, in one pass --
+ * and, via the manifest above, nothing it no longer names.
  *
  * `agents` is exactly the `eai_agents` array `fetchOnboardingConfig`'s
  * response carries (or `[]`/undefined for a backend that predates it, which
  * this treats as "nothing to write" rather than an error -- a CLI update
  * must not need a backend update released in lockstep, the same tolerance
  * `writeOpencodeConfig`'s own `servers` fallback already extends to
- * `mcp_servers`).
- *
- * Stale-file cleanup is deliberately NOT done here: deleting a file this
- * launcher did not just enumerate would mean trusting a naming convention to
- * tell an EAI-generated agent apart from one the user wrote themselves under
- * the same directory, which is exactly the kind of guess `elliotCommands()`'s
- * "OURS TO REPLACE, THEIRS TO KEEP" rule exists to avoid making.
+ * `mcp_servers`). `undefined` specifically (backend doesn't send the field at
+ * all) skips the manifest reconcile too -- it carries no information about
+ * what the agent set NOW is, so nothing is safe to remove.
+ *
+ * A RENAME is a REMOVAL from this function's point of view: migration 090
+ * is exactly this -- `dev` became `eai-dev` as the SAME backend row, but
+ * `writeAgentFile` only ever knows the key it's given today, so the file
+ * named after the OLD key is, from here, indistinguishable from an agent
+ * that was deleted outright. Either way, this launcher wrote it and it is
+ * no longer in the current set, which is the one condition that makes
+ * deleting it safe.
  */
 function writeAllAgentFiles(agents, env = process.env) {
-  return (agents || []).map((agent) => writeAgentFile(agent, env))
+  if (!Array.isArray(agents)) return []
+
+  const dir = path.join(opencodeConfigDir(env), "agents")
+  const manifestFile = agentManifestPath(dir)
+  const previousFiles = readAgentManifest(manifestFile)
+
+  const written = agents.map((agent) => writeAgentFile(agent, env))
+  const writtenNames = new Set(written.map((f) => path.basename(f)))
+
+  for (const name of previousFiles) {
+    if (writtenNames.has(name)) continue
+    try {
+      fs.unlinkSync(path.join(dir, name))
+    } catch {
+      // Already gone (hand-deleted, or a second setup run) -- not an error.
+    }
+  }
+
+  // Only touch the manifest -- and so only ever create the directory -- when
+  // there is something to record or clean up. An empty/undefined response
+  // with no prior manifest must leave the directory exactly as this function
+  // always has: never created at all.
+  if (written.length > 0 || previousFiles.length > 0) {
+    fs.mkdirSync(dir, { recursive: true })
+    fs.writeFileSync(manifestFile, JSON.stringify([...writtenNames].sort(), null, 2))
+  }
+
+  return written
 }
 
 /** Owner-only: this file holds a bearer token and a refresh token. */
@@ -611,7 +725,20 @@ async function fetchOnboardingConfig(backendUrl, tenantId, token, teamId) {
     headers: { Authorization: `Bearer ${token}` },
   })
   if (!res.ok) {
-    throw new Error(`backend returned ${res.status} fetching the organisation config`)
+    // Surface the backend's own detail when it sent one (e.g. the fail-closed
+    // "no budgeted credential" 503 — EAI_ONBOARDING_BILLING_AUDIT.md §7), so
+    // `eai login`/`eai setup`/`eai teams use` show an actionable message
+    // rather than a bare status code.
+    let detail = ""
+    try {
+      const body = await res.json()
+      if (body && typeof body.detail === "string") detail = body.detail
+    } catch {
+      // Non-JSON error body; fall back to the status below.
+    }
+    throw new Error(
+      detail || `backend returned ${res.status} fetching the organisation config`,
+    )
   }
   return (await res.json()) || {}
 }
@@ -694,6 +821,7 @@ async function runSetup(opts) {
     servers,
     identity,
     orgConfig.allowed_models,
+    orgConfig.jev_policy_enabled,
   )
 
   const agentFiles = writeAllAgentFiles(orgConfig.eai_agents, process.env)
@@ -738,4 +866,5 @@ module.exports = {
   PROVIDER_ID,
   GENERAL_MODEL_ID,
   CODER_MODEL_ID,
+  JEV_GUARDRAIL_NAME,
 }