viewable-one 0.0.0-stage → 0.12.1

package/lib/hosted.mjs

@@ -0,0 +1,112 @@
+// THE HOSTED BOARD CLIENT (brief 30, W2a, 2026-09-11). Replaces rowsource.mjs
+// entirely: there is no longer a separate "rows mode" a folder opts into with
+// GLYTCH_BOARD_SOURCE - every agent reaches the board through the hosted
+// endpoint (supabase/functions/board-mcp) whenever there is no local mirror
+// to read instead, and lib/auth.mjs is the one place that resolves a bearer
+// for it (a `glytch login` credential, or VIEWABLE_BOARD_TOKEN for a script).
+//
+// WHY THE ENDPOINT AND NOT POSTGREST DIRECTLY, still: neither a `pmb_`
+// personal access token nor a `pmo_` OAuth token is a Supabase JWT, and
+// PostgREST authenticates JWTs. The Edge Function's own resolve step
+// (supabase/functions/_shared/auth.mjs, shared with board-runner since brief
+// 30 Move 2) is the only thing that turns either shape into a user id, so
+// this file talks to it and nothing else.
+
+import { hostedConfig } from "./auth.mjs";
+import { authenticatedJsonPost } from "./authenticatedHttp.mjs";
+import { runnerMcpUrlFrom } from "./mcpjson.mjs";
+export { NOT_SIGNED_IN_HINT } from "./authenticatedHttp.mjs";
+
+let nextId = 1;
+
+/** Runner-owned calls use the same direct endpoint resolver as run children. */
+export async function callRunnerTool(name, args, options = {}) {
+  const env = options.env ?? process.env;
+  const config = await hostedConfig({ env });
+  return callTool(name, args, { ...options, mcpUrl: runnerMcpUrlFrom(config, env) });
+}
+
+/**
+ * Call one tool on the hosted endpoint and return its text.
+ *
+ * @param {string} name    the tool, e.g. "get_board"
+ * @param {object} args
+ * @param {{sessionKey?: string, boardId?: string, mcpUrl?: string, env?: object, fetchImpl?: Function, forceRefresh?: boolean}} [options]
+ *   `sessionKey`, when given, rides as `X-Glytch-Session` - the board-mcp
+ *   endpoint (2026-09-11) lets it replace the token-derived session key, so a
+ *   spawned child's tool calls land under the same run key its report(),
+ *   ask_user and everything else on this run already use.
+ *   For `get_node`, `boardId` selects a board in the same sequential JSON-RPC
+ *   batch. Separate requests do not retain the server's board selection. This
+ *   option is read-only: the server continues a batch after selection errors,
+ *   so it must never be used for a write. A failed selection refuses the read.
+ * @returns {Promise<{text: string, isError: boolean}>}
+ */
+export async function callTool(name, args, options = {}) {
+  const { sessionKey, boardId, env = process.env } = options;
+  if (boardId !== undefined && (name !== "get_node" || typeof boardId !== "string" || boardId.trim() === "")) {
+    return { text: "A board-scoped read requires get_node and a non-empty boardId.", isError: true };
+  }
+
+  // Resolve before fetching so transport failures name the actual endpoint.
+  // This override only affects the MCP POST, never OAuth refresh requests.
+  const mcpUrl = options.mcpUrl ?? (await hostedConfig({ env })).mcpUrl;
+  const request = { jsonrpc: "2.0", id: nextId++, method: "tools/call", params: { name, arguments: args ?? {} } };
+  const select = boardId === undefined ? null : {
+    jsonrpc: "2.0", id: nextId++, method: "tools/call",
+    params: { name: "get_board", arguments: { board_id: boardId, limit: 1 } },
+  };
+  const headers = typeof sessionKey === "string" && sessionKey.trim() !== "" ? { "X-Glytch-Session": sessionKey.trim() } : {};
+  let result;
+  try {
+    result = await authenticatedJsonPost(mcpUrl, select ? [select, request] : request, { ...options, headers });
+  } catch (error) {
+    return { text: `Could not reach ${mcpUrl}: ${error instanceof Error ? error.message : String(error)}`, isError: true };
+  }
+  if (result.authError) return { text: result.authError, isError: true };
+  const { response, text } = result;
+  let { payload } = result;
+  if (select && response.ok) {
+    const selected = Array.isArray(payload) ? payload.find((part) => part?.id === select.id) : null;
+    const answer = Array.isArray(payload) ? payload.find((part) => part?.id === request.id) : null;
+    // The endpoint may execute the read after a failed selection. Never
+    // mistake its default-board answer for the board the caller requested.
+    if (selected?.error || selected?.result?.isError === true) payload = selected;
+    else if (!selected?.result || !answer) payload = { error: { message: "The board endpoint returned an incomplete board-scoped response." } };
+    else payload = answer;
+  }
+
+  if (payload?.error) {
+    const extra =
+      response.status === 401
+        ? " Sign in again with `viewable login`, or mint a new personal access token and set VIEWABLE_BOARD_TOKEN."
+        : "";
+    return { text: `${typeof payload.error === "string" ? payload.error : payload.error.message ?? "The board endpoint refused the request."}${extra}`, isError: true };
+  }
+  if (!response.ok) {
+    return {
+      text: `The board endpoint answered ${response.status}: ${text.slice(0, 400)}`,
+      isError: true,
+    };
+  }
+  if (!Array.isArray(payload?.result?.content)) {
+    return { text: "The board endpoint returned an incomplete or unreadable JSON response.", isError: true };
+  }
+  const content = payload.result.content;
+  const joined = content
+    .filter((part) => part?.type === "text")
+    .map((part) => part.text)
+    .join("\n");
+  // IMAGE BLOCKS, ALONGSIDE THE TEXT (2026-09-11, brief 30 Move 2b, item 6).
+  // No tool on this endpoint sends any today - `collect_session`'s own reply
+  // is text-only, and the `session_messages.images` column this would carry
+  // is another worker's change, not yet landed here - but the shape is data
+  // the wire format (an MCP content array) already allows, so this is
+  // forward-compatible plumbing rather than a guess: the day a tool DOES
+  // send an image block, every caller of `callTool` picks it up with no
+  // change on its own side.
+  const images = content
+    .filter((part) => part?.type === "image" && typeof part.data === "string")
+    .map((part) => ({ mediaType: part.mimeType ?? part.mediaType ?? "image/png", data: part.data }));
+  return { text: joined, isError: payload?.result?.isError === true, ...(images.length > 0 ? { images } : {}) };
+}

package/lib/imageAttachments.mjs

@@ -0,0 +1,31 @@
+// One attachment contract for the runner and all native transports. Validation
+// is deliberately lossless: no remote fetches, format conversions or dropped
+// entries. Decoding verifies transport bytes and image signatures; the engine
+// still has to report if its selected model cannot inspect an image.
+const FORMATS = {
+  "image/png": { ext: "png", matches: (b) => b.length >= 24 && b.subarray(0, 8).equals(Buffer.from([137,80,78,71,13,10,26,10])) && b.toString("ascii", 12, 16) === "IHDR" && b.readUInt32BE(16) > 0 && b.readUInt32BE(20) > 0 },
+  "image/jpeg": { ext: "jpg", matches: (b) => b.length >= 4 && b[0] === 255 && b[1] === 216 && b[2] === 255 && b.at(-2) === 255 && b.at(-1) === 217 },
+  "image/gif": { ext: "gif", matches: (b) => b.length >= 13 && /^GIF8[79]a$/.test(b.toString("ascii", 0, 6)) && b.readUInt16LE(6) > 0 && b.readUInt16LE(8) > 0 },
+  "image/webp": { ext: "webp", matches: (b) => b.length >= 20 && b.toString("ascii", 0, 4) === "RIFF" && b.toString("ascii", 8, 12) === "WEBP" && /^VP8[ LX]$/.test(b.toString("ascii", 12, 16)) },
+};
+
+export function imageAttachments(images) {
+  if (images === undefined) return [];
+  if (!Array.isArray(images)) throw new Error("Reference images must be an array of attached image data URLs. Reattach the images and try again.");
+  return images.map((url, index) => {
+    const fail = (reason) => { throw new Error(`Reference image ${index + 1} ${reason}. Reattach a PNG, JPEG, GIF or WebP image and try again.`); };
+    if (typeof url !== "string") fail("is missing its image data");
+    const match = /^data:(image\/[a-zA-Z0-9.+-]+);base64,([A-Za-z0-9+/]*={0,2})$/.exec(url);
+    if (!match || !match[2]) fail("has missing or invalid base64 image data");
+    const format = FORMATS[match[1]];
+    if (!format) fail(`uses an unsupported format (${match[1]})`);
+    const bytes = Buffer.from(match[2], "base64");
+    if (bytes.length === 0 || bytes.toString("base64").replace(/=+$/, "") !== match[2].replace(/=+$/, "") || (match[2].includes("=") && match[2].length % 4 !== 0)) fail("has invalid base64 image data");
+    if (!format.matches(bytes)) fail(`does not contain recognizable ${format.ext.toUpperCase()} image bytes`);
+    return { url, mimeType: match[1], data: match[2], bytes, extension: format.ext };
+  });
+}
+
+export function imageInspectionInstruction(count, planMode) {
+  return `\n\nREFERENCE IMAGE INSPECTION${count ? ` (${count} attached image${count === 1 ? "" : "s"})` : ""}\n${count ? "Inspect every attached reference image" : "Check the supplied board context for reference images, including images returned by board tools, and inspect each available reference"} before proposing a plan or editing files. Describe concrete visible observations (layout, content, spacing, colors, or other relevant details) and use them to guide the work. Identify each reference by attachment number or board node/title when recording these observations. Do not infer the image contents from filenames or surrounding text. If any image is missing, unreadable, or unsupported by your tools or model, stop and explicitly report which image you cannot inspect; do not proceed as if you saw it.${planMode === "draft" ? " Include a visual verification step in the plan; do not implement it during this draft." : " For visual or UI changes with references, inspect the final rendered result and compare it against the reference images before reporting completion. Report any differences you could not verify."}`;
+}

package/lib/init-connect.mjs

@@ -0,0 +1,418 @@
+// THE TWO STEPS `glytch init` USED TO ONLY TALK ABOUT (brief 31, Moves 1 and
+// 2, 2026-09-12): signing this machine in, and running each selected agent's
+// own OAuth verb.
+//
+// WHAT WAS MEASURED BEFORE THIS EXISTED. Six user steps to a working machine:
+// install the agents, install the package, `glytch init`, `glytch login`,
+// link the folder, then one OAuth per agent typed by hand from lines `init`
+// printed. Four of those six are this package's own, and three of the four
+// were instructions rather than actions. This module is the three.
+//
+// WHY NOT ONE SHARED TOKEN (ruling 1, same day). Writing one `pmb_`
+// bearer into every agent's config was raised and dropped: the board endpoint
+// carries `send_message` into running sessions and the daemon executes what
+// the board files, so a stolen board token is a way into a coding agent with
+// a shell. Per-agent OAuth stays - each agent keeps its own 1h token,
+// rotating refresh, 30-day silence expiry, hashed at rest, revocable.
+//
+// THE ONE-PASTE PROMPT NARROWS THAT RULING RATHER THAN REVERSING IT
+// (2026-09-19, persona walk finding 1a). The pasting agent runs
+// `VIEWABLE_BOARD_TOKEN=<token> npx -y glytch init --yes` with no TTY, so
+// there is no browser to send OAuth's redirect to and no terminal to wait
+// on it in - the per-agent OAuth verb below can only ever print itself as a
+// hint there. `personalBoardToken` below is that SAME token, already
+// sitting in this process's own env or on disk from `signInStep` a few
+// lines earlier in the same `init` run - not a second, wider-reaching
+// credential minted for this purpose - and it is registered for Claude Code
+// alone, at LOCAL scope: private to this account, ahead of the project
+// entry in Claude Code's own resolution order, and never written into the
+// project file the ruling above was protecting against. codex and opencode still get only the printed
+// verb (AGENT_CONNECT_HINT), because their CLIs were not found on this
+// machine to verify a header-based add against (see AGENT_CONNECT_HINT).
+//
+// EVERYTHING HERE IS INJECTED, the logindaemon.mjs rule: `exec` and `login`
+// are seams, every test asserts the argv sequence, and NOTHING in the suite
+// runs claude, codex, opencode or a browser on the machine running it.
+
+import { hostedStatus, login as hostedLogin, readAuthFile } from "./auth.mjs";
+import { projectMcpServerKey } from "./project-mcp.mjs";
+import { execProbe, runInteractive } from "./detect.mjs";
+import { compareVersions } from "./update.mjs";
+import { bold, fail, hint, ok, warn } from "./cli-output.mjs";
+import { BOARD_MCP_URL, entryIsAtRetiredUrl } from "./mcpjson.mjs";
+import { claudeRegistration, moveClaudeRegistration } from "./retired-address.mjs";
+
+/** Runtime namespaces stay compatible; only fresh project setup uses the new name (#2328). */
+export const SERVER_KEY = "glytch";
+export const INIT_SERVER_KEY = "viewable";
+
+/** `claude mcp login <name>` exists from Claude Code 2.1.186. Below it there
+ *  is no shell verb at all and the only path is `/mcp` inside a session.
+ *  Verified 2026-09-12 on 2.1.269 against the board (then prompt.glytch.ai):
+ *  "Authenticated with "board". Its tools are now available in Claude Code."
+ *  The line in doctor.mjs that called this unverified was true on 2.1.34. */
+export const CLAUDE_LOGIN_FLOOR = "2.1.186";
+
+/** A browser round trip with a person in it. The 5s probe timeout is for
+ *  `--version`; this one waits for someone to find their password manager. */
+export const LOGIN_TIMEOUT_MS = 5 * 60_000;
+
+/** Per agent: the binary, and the verb that drives its own OAuth flow.
+ *
+ * WHAT EACH ONE REPORTS ABOUT ALREADY BEING SIGNED IN, asked of the real
+ * binaries on this machine 2026-09-12 (claude 2.1.269, codex-cli 0.153.4,
+ * opencode 1.18.23) rather than guessed:
+ *
+ *   claude    `claude mcp get <name>` prints "Status: ✔ Connected", and
+ *             `claude mcp list` prints "! Needs authentication" for a server
+ *             that needs one. So the marker is reliable and we skip on it.
+ *   opencode  `opencode mcp list` prints "⚠ <name> needs authentication" or
+ *             "✓ <name> connected", per server. Also reliable; also skipped.
+ *             (`opencode mcp get` does not exist - list is the only asker.)
+ *   codex     NEITHER `codex mcp list` NOR `codex mcp get <name>` says. The
+ *             list has an `Auth` column, but it names the MECHANISM the
+ *             transport supports ("OAuth" for an http server, "Unsupported"
+ *             for stdio), not whether this machine holds a token: an http
+ *             server nobody has ever logged into still reads "OAuth". So
+ *             there is nothing to skip on, and the verb runs every time and
+ *             is left to short-circuit itself.
+ */
+export const AGENT_VERBS = {
+  claude: { label: "Claude Code", bin: "claude", verb: ["mcp", "login", INIT_SERVER_KEY] },
+  codex: { label: "codex", bin: "codex", verb: ["mcp", "login", INIT_SERVER_KEY] },
+  opencode: { label: "opencode", bin: "opencode", verb: ["mcp", "auth", INIT_SERVER_KEY] },
+};
+
+/** ONE SENTENCE SHE CAN ACT ON, per agent, when a token-carrying no-terminal
+ *  registration (below) is not possible for that agent either - the sentence
+ *  `init`'s own last lines print instead of leaving a warn row buried mid
+ *  output (2026-09-19, persona walk finding 1b). Claude Code's own in-chat
+ *  verb is `/mcp`; codex and opencode have no chat-native equivalent, so
+ *  theirs names the same CLI verb AGENT_VERBS already runs from a terminal. */
+export const AGENT_CONNECT_HINT = {
+  claude: "Type /mcp in this tab and sign in to Viewable.",
+  codex: "Run `codex mcp login viewable` from a terminal, then restart this session, to connect the board.",
+  opencode: "Run `opencode mcp auth viewable` from a terminal to connect the board.",
+};
+
+/** A personal `pmb_` token this machine can already reach the board with -
+ *  `VIEWABLE_BOARD_TOKEN` in this process's own env, or a stored
+ *  `personal: true` record `login()` already wrote to ~/.glytch/auth.json.
+ *  Mirrors the order `hostedToken` (lib/auth.mjs) checks in, but returns the
+ *  raw token rather than a possibly-refreshed OAuth pair: what this needs is
+ *  a bearer worth handing an agent's OWN config, not this process's own call.
+ *  `readAuth` is the injection point every test in this file uses. */
+export async function personalBoardToken({ env = process.env, readAuth = readAuthFile } = {}) {
+  // Compatibility read: old installs may still set GLYTCH_BOARD_TOKEN (#2196).
+  const scripted = typeof (env.VIEWABLE_BOARD_TOKEN ?? env.GLYTCH_BOARD_TOKEN) === "string" ? (env.VIEWABLE_BOARD_TOKEN ?? env.GLYTCH_BOARD_TOKEN).trim() : "";
+  if (scripted !== "") return scripted;
+  const stored = await readAuth(env);
+  if (stored?.personal === true && typeof stored.accessToken === "string" && stored.accessToken.trim() !== "") {
+    return stored.accessToken.trim();
+  }
+  return null;
+}
+
+/** `claude mcp add`'s own argv for a LOCAL-SCOPE http server carrying a
+ *  bearer header - verified against `claude mcp add --help` on 2.1.278
+ *  (2026-09-19). `-s local`, not `user`, and the scope is the whole point:
+ *  Claude Code resolves a server name local > project > user, and step 2 of
+ *  this same `init` writes an unauthenticated `glytch` entry into the
+ *  project's `.mcp.json`. A user-scope entry would be silently shadowed by
+ *  it; a local-scope one wins. Local scope lives in `~/.claude.json` under
+ *  this project's path - this account's own file, never the project's
+ *  `.mcp.json` (which a stranger could commit and read the token from).
+ *  `--header "Authorization: Bearer <token>"` exactly as the hosted
+ *  endpoint's own `bearer()` reads it (supabase/functions/board-mcp/index.ts). */
+export function claudeAddArgs(url, token, scope = "local", serverKey = INIT_SERVER_KEY) {
+  return ["mcp", "add", "-s", scope, "--transport", "http", serverKey, url, "--header", `Authorization: Bearer ${token}`];
+}
+
+const strip = (value) => String(value ?? "").replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "");
+
+/** The last line of a failed verb's stderr - what the agent actually said,
+ *  rather than "exited 1". Empty lines and a trailing newline are skipped. */
+export function lastStderrLine(result) {
+  const lines = strip(result?.stderr).split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  return lines.length ? lines[lines.length - 1] : "the verb failed with no message";
+}
+
+const row = (agent, label, status, text, detail) => ({ agent, label, status, text, ...(detail ? { detail } : {}) });
+
+/** One painted line per outcome, in `checkSections`' shape so `init` reads as
+ *  one list from the first step to the last. */
+export function resultLine({ label, status, text }, options = {}) {
+  const tag = status === "ok" ? "OK" : status === "fail" ? "FAIL" : "WARN";
+  const paint = status === "ok" ? ok : status === "fail" ? fail : warn;
+  return `  ${paint(tag.padEnd(4), options)} ${label} — ${text}`;
+}
+
+// ------------------------------------------------------------------ Move 1
+
+/**
+ * Sign THIS MACHINE in, if it is not already.
+ *
+ * `viewable login` stays as its own command for re-auth; this runs the same
+ * `login()` from lib/auth.mjs rather than printing "now run viewable login".
+ *
+ * NOT ON A PIPE. The flow opens a browser and waits on a loopback redirect,
+ * which is fine without a terminal, but a script that gets a browser window
+ * it never asked for is worse than a script that is told what to run - and
+ * `chooseAgents` already sets the precedent for "no terminal, say the command
+ * instead". So a non-TTY stdin prints the line and does nothing.
+ */
+export async function signInStep({
+  env = process.env,
+  status = hostedStatus,
+  login = hostedLogin,
+  isTTY = Boolean(process.stdin.isTTY),
+  skip = false,
+  log = () => {},
+  color,
+} = {}) {
+  const options = color === undefined ? {} : { color };
+  // THE ROW COMES FIRST, THEN WHAT TO DO ABOUT IT. A hint printed before its
+  // own outcome reads as an instruction for the step that is about to run.
+  const settle = (status_, text, next) => {
+    const result = row("machine", "Your computer", status_, text);
+    log(resultLine(result, options));
+    if (next) log(hint(next, options));
+    return result;
+  };
+  // THE SCRIPT DOOR PERSISTS ITSELF (brief 43, 2026-09-19). `hostedStatus`
+  // already reads VIEWABLE_BOARD_TOKEN as "signed in" with NOTHING on disk -
+  // true for this process, but the daemon `init` is about to hand this folder
+  // to is a separate process with no such variable of its own. Route through
+  // `login()` whenever the variable is set, even though `status(env)` below
+  // would already call this machine signed in, so the credential lands in
+  // ~/.glytch/auth.json rather than staying an environment variable nobody
+  // downstream inherits. `login()` writes it and returns with no browser and
+  // no wait, so this ignores `isTTY` - there is nothing a missing terminal
+  // would be protecting against here.
+  //
+  // `skip` (--no-login) IS STILL HONOURED (2026-09-19, brief 43 review,
+  // B10). This used to run ahead of the `skip` check entirely, so a CI box
+  // that set VIEWABLE_BOARD_TOKEN and passed `--no-login` specifically to avoid
+  // writing a long-lived token to a shared runner's disk got it written
+  // anyway. The env var still authenticates THIS process on its own -
+  // `hostedToken` checks it first, with no file involved - so `--no-login`
+  // costs nothing here but the write.
+  // Compatibility read: old installs may still set GLYTCH_BOARD_TOKEN (#2196).
+  if (typeof (env.VIEWABLE_BOARD_TOKEN ?? env.GLYTCH_BOARD_TOKEN) === "string" && (env.VIEWABLE_BOARD_TOKEN ?? env.GLYTCH_BOARD_TOKEN).trim() !== "") {
+    if (skip) {
+      return settle(
+        "warn",
+        "skipped (--no-login): VIEWABLE_BOARD_TOKEN still authenticates this process, but was not saved to disk",
+        "Run `viewable login` (without --no-login) to save it for this folder.",
+      );
+    }
+    try {
+      const stored = await login({ env, log: (line) => log(hint(line, options)) });
+      return settle("ok", `VIEWABLE_BOARD_TOKEN saved to ~/.glytch/auth.json (${stored.appUrl})`);
+    } catch (error) {
+      return settle("fail", error instanceof Error ? error.message : String(error));
+    }
+  }
+
+  const current = await status(env);
+  if (current?.signedIn) {
+    return settle("ok", `already signed in (${current.via ?? "credential on file"})`);
+  }
+  if (skip) {
+    return settle("warn", "skipped (--no-login)", "Run `viewable login` when you want your computer to reach the board.");
+  }
+  if (!isTTY) {
+    return settle("warn", "skipped (no terminal)", "No terminal here. Run `viewable login` from one to sign your computer in.");
+  }
+  log(bold("Viewable needs a browser sign-in for your computer.", options));
+  try {
+    const stored = await login({ env, log: (line) => log(hint(line, options)) });
+    return settle("ok", `signed in to ${stored.appUrl}`);
+  } catch (error) {
+    return settle("fail", error instanceof Error ? error.message : String(error));
+  }
+}
+
+// ------------------------------------------------------------------ Move 2
+
+/** Does this agent already hold a token for our server? `null` means "this
+ *  agent cannot say", which is not the same as "no" - see AGENT_VERBS.
+ *
+ *  2026-10-03: for Claude Code, an entry that still points at the retired
+ *  prompt.glytch.ai address is NOT connected whatever its status line says
+ *  (the redirect to app.viewable.one drops the Authorization header). The answer
+ *  is `{ retired: { scope, bearer } }` when that entry lives in a scope this
+ *  file may replace (local or user), for the caller to move, and `false` for
+ *  one in the project file. Any other answer is true, false or null as
+ *  before. */
+async function alreadyConnected(key, { exec, env, serverKey = INIT_SERVER_KEY }) {
+  // The ASKING commands are probes, not browser flows: they keep execProbe's
+  // own short timeout rather than LOGIN_TIMEOUT_MS.
+  const run = (bin, args) => exec(bin, args, { env });
+  if (key === "claude") {
+    const result = await run("claude", ["mcp", "get", serverKey]);
+    if (!result?.ok) return null;
+    const text = strip(`${result.stdout}${result.stderr}`);
+    const found = claudeRegistration(text);
+    if (entryIsAtRetiredUrl(found, env)) {
+      return found.scope === "local" || found.scope === "user" ? { retired: found } : false;
+    }
+    return !text.includes("Needs authentication");
+  }
+  if (key === "opencode") {
+    const result = await run("opencode", ["mcp", "list"]);
+    if (!result?.ok) return null;
+    // One entry per server, each opened by "●". Only the entry naming our
+    // server answers for it; another server needing auth is not our problem.
+    const entry = strip(`${result.stdout}${result.stderr}`)
+      .split("●")
+      .find((part) => new RegExp(`\\b${serverKey}\\b`).test(part));
+    if (!entry) return null;
+    return !/needs authentication/i.test(entry);
+  }
+  return null;
+}
+
+/**
+ * Run each selected and FOUND agent's own OAuth verb.
+ *
+ * A selected agent that is not installed gets no row at all: `init` already
+ * prints the detection table above this, and telling someone their missing
+ * binary was not logged in is noise. `init` still prints its sign-in line
+ * under Next steps for those, exactly as it did before this module existed.
+ *
+ * THE VERBS NEED A TERMINAL, AND EXACTLY ONE ATTEMPT. `claude mcp login`
+ * refused with "stdin isn't a terminal" when run from a pipe on 2.1.269, so
+ * they run through `runInteractive` - stdin and stdout are the person's own
+ * terminal, stderr stays piped so a failure still has a line to report, and
+ * the command is resolved once and spawned once (2026-09-12 review, F3: as a
+ * mode of `execProbe` these inherited its `claude` PATH-miss retry, so a
+ * consent declined in the browser opened a second browser window). The ASKING
+ * commands above are probes and stay on `exec`. With no TTY the verb is
+ * printed as a hint instead of run.
+ */
+export async function agentLoginStep({
+  root = null,
+  selected = [],
+  agents = {},
+  exec = execProbe,
+  interactive = runInteractive,
+  env = process.env,
+  isTTY = Boolean(process.stdin.isTTY),
+  skip = false,
+  timeoutMs = LOGIN_TIMEOUT_MS,
+  // A personal token this run can hand an agent's own config, and the URL to
+  // register it against - both default to the same sources `signInStep`/
+  // `mergeBoardServer` use, injectable so a test never reads a real
+  // ~/.glytch/auth.json or depends on GLYTCH_BOARD_URL being unset.
+  token = null,
+  boardUrl = BOARD_MCP_URL(env),
+  log = () => {},
+  color,
+} = {}) {
+  const options = color === undefined ? {} : { color };
+  const rows = [];
+  for (const key of Object.keys(AGENT_VERBS)) {
+    if (!selected.includes(key)) continue;
+    const found = agents?.[key];
+    if (!found?.found) continue;
+    const serverKey = await projectMcpServerKey(root, key);
+    const { label, bin } = AGENT_VERBS[key];
+    const verb = [...AGENT_VERBS[key].verb.slice(0, -1), serverKey];
+    const command = `${bin} ${verb.join(" ")}`;
+    // The row first, then what to do about it - see signInStep above.
+    const settle = (status, text, next) => {
+      const result = row(key, label, status, text);
+      rows.push(result);
+      log(resultLine(result, options));
+      if (next) log(hint(next, options));
+    };
+
+    // A registration at the retired address is replaced, not kept, and before
+    // the gates below: skipping sign-in must not leave it on prompt.glytch.ai.
+    let connected = key === "claude" ? await alreadyConnected(key, { exec, env, serverKey }) : undefined;
+    if (connected !== null && typeof connected === "object") {
+      const moved = await moveClaudeRegistration({
+        exec, bin, env, serverKey, ...connected.retired, token, boardUrl,
+        addArgs: (url, bearer, scope) => claudeAddArgs(url, bearer, scope, serverKey), stderrOf: lastStderrLine,
+      });
+      if (moved.status !== "relogin") {
+        settle(moved.status, moved.message);
+        continue;
+      }
+      log(hint(moved.message, options));
+      connected = false;
+    }
+    if (skip) {
+      settle("warn", "skipped (--no-agent-login)", `Run \`${command}\` when you want it connected.`);
+      continue;
+    }
+
+    // THE ONE VERSION FLOOR. `claude mcp login` does not exist below 2.1.186
+    // and an unreadable version is treated as below it: guessing high here
+    // costs a confusing "unknown command" where guessing low costs one extra
+    // printed line.
+    if (key === "claude" && compareVersions(found.version ?? "0.0.0", CLAUDE_LOGIN_FLOOR) < 0) {
+      const seen = found.version ?? "an unreadable version";
+      settle(
+        "warn",
+        `skipped (Claude Code ${seen} < ${CLAUDE_LOGIN_FLOOR})`,
+        `Open a session on this project, run /mcp, and authenticate the ${serverKey} connection. Upgrade Claude Code to ${CLAUDE_LOGIN_FLOOR} or newer to skip this step.`,
+      );
+      continue;
+    }
+
+    if (connected === undefined) connected = await alreadyConnected(key, { exec, env, serverKey });
+    if (connected === true) {
+      settle("ok", "already connected");
+      continue;
+    }
+
+    if (!isTTY) {
+      // THE PASTING AGENT HAS NO TTY EITHER (fix 1a, 2026-09-19 persona
+      // walk): OAuth needs a browser AND a terminal to wait on the redirect
+      // in, and `glytch init --yes` run BY a coding agent's own shell tool
+      // has neither. A personal token already on this machine skips OAuth
+      // entirely for Claude Code - the one agent whose CLI a bearer header
+      // was verified against (`claudeAddArgs` above) - registering it at
+      // LOCAL scope: it wins over the unauthenticated project entry and never lands in a committed file.
+      if (key === "claude" && token) {
+        const addArgs = claudeAddArgs(boardUrl, token, "local", serverKey);
+        let added;
+        try {
+          added = await exec(bin, addArgs, { env });
+        } catch (error) {
+          settle("fail", error instanceof Error ? error.message : String(error));
+          continue;
+        }
+        if (added?.ok) {
+          settle("ok", `registered at local scope with a personal access token (${bin} ${addArgs.slice(0, 6).join(" ")} ...)`);
+        } else {
+          settle("fail", lastStderrLine(added));
+        }
+        continue;
+      }
+      settle("warn", "skipped (no terminal)", `Run \`${command}\` from a terminal to connect it.`);
+      continue;
+    }
+
+    log(bold(`${label} is asking for a browser sign-in.`, options));
+    log(hint(command, options));
+    // A SPAWN THAT THROWS IS THIS AGENT'S FAIL ROW, NOT THE END OF `init`
+    // (2026-09-12 review, F4). `runInteractive` resolves for a child that ran
+    // and failed, but a spawn can throw outright - EACCES on a binary that is
+    // not executable, ENOENT for one deleted between the probe and here - and
+    // an uncaught throw took the whole command down through `main().catch`,
+    // losing the rows already painted above it and the agents after it.
+    let result;
+    try {
+      result = await interactive(bin, verb, { timeoutMs, env });
+    } catch (error) {
+      settle("fail", error instanceof Error ? error.message : String(error));
+      continue;
+    }
+    if (result?.ok) settle("ok", "connected");
+    else settle("fail", lastStderrLine(result));
+  }
+  return rows;
+}